summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSebastian Huber <sebastian.huber@embedded-brains.de>2020-06-01 12:49:49 +0200
committerSebastian Huber <sebastian.huber@embedded-brains.de>2020-06-01 13:00:41 +0200
commit9b269adc6c1ab6847c40dd533ca2e0151151c3f7 (patch)
treec430a07e5fa972705045ade7b61c9f38119e18f1
parent459326c2b9a829852782170deed0e5876c1258f5 (diff)
downloadrtems-docs-master.tar.bz2
eng: Add interface specification how-toHEADmaster
Update #3715.
-rw-r--r--eng/req/howto.rst88
-rw-r--r--eng/req/index.rst1
2 files changed, 89 insertions, 0 deletions
diff --git a/eng/req/howto.rst b/eng/req/howto.rst
new file mode 100644
index 0000000..de9b145
--- /dev/null
+++ b/eng/req/howto.rst
@@ -0,0 +1,88 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+How-To
+======
+
+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
diff --git a/eng/req/index.rst b/eng/req/index.rst
index fbda0b8..f0d11b3 100644
--- a/eng/req/index.rst
+++ b/eng/req/index.rst
@@ -89,3 +89,4 @@ All procedures should be based on a peer review principles.
traceability
management
tooling
+ howto