blob: c539563396c6f4c315ce888c596bf61bdcaa4f05 (
plain) (
tree)
|
|
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
How-To
======
Getting Started
---------------
The RTEMS specification items and qualification tools are work in progress. The
first step to work with the RTEMS specification and the corresponding tools is a
clone of the following repository:
.. code-block:: none
git clone git://git.rtems.org/rtems-central.git
git submodule init
git submodule update
The tools need a virtual Python 3 environment. To set it up use:
.. code-block:: none
cd rtems-central
make env
Each time you want to use one of the tools, you have to activate the
environment in your shell:
.. code-block:: none
cd rtems-central
. env/bin/activate
Glossary Specification
----------------------
The glossary of terms for the RTEMS Project is defined by
:ref:`SpecTypeGlossaryTermItemType` items in the :file:`spec/glossary`
directory. For a new glossary term add a glossary item to this directory. As
the file name use the term in lower case with all white space and special
characters removed or replaced by alphanumeric characters, for example
:file:`spec/glossary/magicpower.yml` for the term `magic power`.
Use ``${uid:/attribute}`` substitutions to reference other parts of the
specification.
.. code-block:: yaml
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
glossary-type: term
links:
- role: glossary-member
uid: ../glossary-general
term: magic power
text: |
Magic power enables a caller to create magic objects using a
${magicwand:/term}.
type: glossary
Define acronyms with the phrase `This term is an acronym for *.` in the
``text`` attribute:
.. code-block:: yaml
...
term: MP
...
text: |
This term is an acronym for Magic Power.
...
Once you are done with the glossary items, run the script :file:`spec2doc.py`
to generate the derived documentation content. Send patches for the generated
documentation and the specification to the :r:list:`devel` and follow the
normal patch review process.
Interface Specification
-----------------------
.. _ReqEngAddAPIHeaderFile:
Specify an API Header File
^^^^^^^^^^^^^^^^^^^^^^^^^^
The RTEMS :term:`API` header files are specified under ``spec:/if/rtems/*``.
Create a subdirectory with a corresponding name for the API, for example in
:file:`spec/if/rtems/foo` for the `foo` API. In this new subdirectory place an
:ref:`SpecTypeInterfaceHeaderFileItemType` item named :file:`header.yml`
(:file:`spec/if/rtems/foo/header.yml`) and populate it with the required
attributes.
.. code-block:: yaml
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
interface-type: header-file
links:
- role: interface-placement
uid: /if/domains/api
path: rtems/rtems/foo.h
prefix: cpukit/include
type: interface
Specify an API Element
^^^^^^^^^^^^^^^^^^^^^^
Figure out the corresponding header file item. If it does not exist, see
:ref:`ReqEngAddAPIHeaderFile`. Place a specialization of an
:ref:`SpecTypeInterfaceItemType` item into the directory of the header file
item, for example :file:`spec/if/rtems/foo/bar.yml` for the :c:func:`bar`
function. Add the required attributes for the new interface item. Do not hard
code interface names which are used to define the new interface. Use
``${uid-of-interface-item:/name}`` instead. If the referenced interface is
specified in the same directory, then use a relative UID. Using interface
references creates implicit dependencies and helps the header file generator to
resolve the interface dependencies and header file includes for you. Use
:ref:`SpecTypeInterfaceUnspecifiedItemType` items for interface dependencies to
other domains such as the C language, the compiler, the implementation, or
user-provided defines. To avoid cyclic dependencies between types you may use
an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item.
.. code-block:: yaml
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: Tries to create a magic object and returns it.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
body: null
params:
- ${magic-wand:/name} ${.:/params[0]/name}
return: ${magic-type:/name} *
variants: []
description: |
The magic object is created out of nothing with the help of a magic wand.
enabled-by: true
interface-type: function
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: /groups/api/classic/foo
name: bar
notes: null
params:
- description: is the magic wand.
dir: null
name: magic_wand
return:
return: Otherwise, the magic object is returned.
return-values:
- description: The caller did not have enough magic power.
value: ${/if/c/null}
type: interface
|