5.6. How-To

5.6.1. Getting Started

The RTEMS specification items and qualification tools are work in progress and not fully integrated in the RTEMS Project. The first step to work with the RTEMS specification and the corresponding tools is a clone of the following repository:

git clone git://git.rtems.org/sebh/rtems-qual.git
git submodule init
git submodule update

The tools need a virtual Python 3 environment. To set it up use:

cd rtems-qual
make env

Each time you want to use one of the tools, you have to activate the environment in your shell:

cd rtems-qual
. env/bin/activate

5.6.2. Glossary Specification

The glossary of terms for the RTEMS Project is defined by Glossary Term Item Type items in the 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 spec/glossary/magicpower.yml for the term magic power.

Use ${uid:/attribute} substitutions to reference other parts of the specification.

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:

...
term: MP
...
text: |
  This term is an acronym for Magic Power.
...

Once you are done with the glossary items, run the script spec2doc.py to generate the derived documentation content. Send patches for the generated documentation and the specification to the Developers Mailing List and follow the normal patch review process.

5.6.3. Interface Specification

5.6.3.1. Specify an API Header File

The RTEMS API header files are specified under spec:/if/rtems/*. Create a subdirectory with a corresponding name for the API, for example in spec/if/rtems/foo for the foo API. In this new subdirectory place an Interface Header File Item Type item named header.yml (spec/if/rtems/foo/header.yml) and populate it with the required attributes.

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

5.6.3.2. Specify an API Element

Figure out the corresponding header file item. If it does not exist, see Specify an API Header File. Place a specialization of an Interface Item Type item into the directory of the header file item, for example spec/if/rtems/foo/bar.yml for the 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 Interface Unspecified Item Type 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 Interface Forward Declaration Item Type item.

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