.. 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 Application Configuration Options --------------------------------- The application configuration options and groups are maintained by specification items in the directory :file:`spec/if/acfg`. Application configuration options are grouped by :ref:`SpecTypeApplicationConfigurationGroupItemType` items which should be stored in files using the :file:`spec/if/acfg/group-*.yml` pattern. Each application configuration option shall link to exactly one group item with the :ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole`. There are four application option item types available which cover all existing options: * The *feature enable options* let the application enable a feature option. If the option is not defined, then the feature is simply not available or active. There should be no feature-specific code linked to the application if the option is not defined. Examples are options which enable a device driver like ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``. These options are specified by :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` items. * The *feature options* let the application enable a specific feature option. If the option is not defined, then a default feature option is used. Regardless whether the option is defined or not defined, feature-specific code may be linked to the application. Examples are options which disable a feature if the option is defined such as ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` and options which provide a stub implementation of a feature by default and a full implementation if the option is defined such as ``CONFIGURE_IMFS_ENABLE_MKFIFO``. These options are specified by :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` items. * The *integer value options* let the application define a specific value for a system parameter. If the option is not defined, then a default value is used for the system parameter. Examples are options which define the maximum count of objects available for application use such as ``CONFIGURE_MAXIMUM_TASKS``. These options are specified by :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items. * The *initializer options* let the application define a specific initializer for a system parameter. If the option is not defined, then a default setting is used for the system parameter. An example option of this type is ``CONFIGURE_INITIAL_EXTENSIONS``. These options are specified by :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items. Sphinx documentation sources and header files with Doxygen markup are generated from the specification items. The descriptions in the items shall use a restricted Sphinx formatting. Emphasis via one asterisk ("*"), strong emphasis via two asterisk ("**"), code samples via blockquotes ("``"), code blocks (".. code-block:: c") and lists are allowed. References to interface items are also allowed, for example "${appl-needs-clock-driver:/name}" and "${../rtems/tasks/create:/name}". References to other parts of the documentation are possible, however, they are currently provided by hard-coded tables in :file:`rtemsspec/applconfig.py`. Modify an Existing Group ^^^^^^^^^^^^^^^^^^^^^^^^ Search for the group by its section header and edit the specification item file. For example: .. code-block:: none $ grep -rl "name: General System Configuration" spec/if/acfg spec/if/acfg/group-general.yml $ vi spec/if/acfg/group-general.yml Modify an Existing Option ^^^^^^^^^^^^^^^^^^^^^^^^^ Search for the option by its C preprocessor define name and edit the specification item file. For example: .. code-block:: none $ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/if/acfg spec/if/acfg/appl-needs-clock-driver.yml $ vi spec/if/acfg/appl-needs-clock-driver.yml Add a New Group ^^^^^^^^^^^^^^^ Let ``new`` be the UID name part of the new group. Create the file :file:`spec/if/acfg/group-new.yml` and provide all attributes for an :ref:`SpecTypeApplicationConfigurationGroupItemType` item. For example: .. code-block:: none $ vi spec/if/acfg/group-new.yml Add a New Option ^^^^^^^^^^^^^^^^ Let ``my-new-option`` be the UID name of the option. Create the file :file:`if/acfg/my-new-option.yml` and provide all attributes for an appropriate refinement of :ref:`SpecTypeApplicationConfigurationOptionItemType`. For example: .. code-block:: none $ vi spec/if/acfg/my-new-option.yml Generate Content after Changes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once you are done with the modifications of an existing item or the creation of a new item, the changes need to be propagated to generated source files. This is done by the :file:`spec2modules.py` script. Before you call this script, make sure the Git submodules are up-to-date. .. code-block:: none $ ./spec2dmodules.py The script modifies or creates source files in :file:`modules/rtems` and :file:`modules/rtems-docs`. Create patch sets for these changes just as if these were work done by a human and follow the normal patch review process described in the *RTEMS User Manual*. When the changes are integrated, update the Git submodules and check in the changed items. 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:`spec2modules.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