wiki:GCI/Documentation/ClassicAPIRequirements

Version 2 (modified by Gedare Bloom, on Sep 12, 2018 at 7:29:15 PM) (diff)

--

Classic API Requirements Documents

This task is part of the RTEMS project's effort to reduce certification costs by easing requirements traceability. As we want our developers to spend more time on adding technical value (instead of updating duplicate documentation), we will want to merge as much of this documentation as possible.

We have several existing classic API documents and converting each into chapter into reStructuredText will provide a baseline which is easier for further automated processing and updates. The focus will be on the final versions of the RTEID and ORKID specifications.

We expect approximately 30 tasks in this category for the first round. There can be followup tasks sets to further refine them.

Directions for Students

Classic API Requirements Document (Phase I Deliverables)

The deliverable is a .rst

Classic API Requirements Document (Phase I Method)

  1. Copy the contents of the file into an RST editor
  2. Format the .rst to match the example and the original pdf
  3. Limit line length to 80 characters
  4. If the numbering is
    1. like 3, chapter-level, use ===== to underline,
    2. like 3.5, section-level, use --- to underline
    3. like 3.5.7, subsection-level, use C Rempel? (talk?) to underline
  5. Separate paragraphs with a blank line
  6. Use tables to format the Completion Status
  7. use linux-style line endings
  8. Look for spelling errors
  9. use on items that are supposed to be code
  10. Upload to melange, ask the mentor to review the .rst

Classic API Requirements Document (Phase I Example)

.. contents:: Table of Contents
.. section-numbering::

NODES==  ==


Nodes are the building bricks of ORKID systems, referenced by a node identifier
and containing a single set of ORKID data structures. Nodes will typically
contain a single CPU, but multi-CPU nodes are equally possible.

Specifying how nodes are created and configured is outside the scope of this
standard. However, certain basic operations for node handling will be needed in
all ORKID implementations and are defined in the following sections.

NODE_IDENT
----------------
Obtain the identifier of a node with a given name.

  * Synopsis**

``node_ident( name, nid )``

  * Input Parameters**

``name: string``
   user defined node name

  * Output Parameters**

``nid: node_id``
   system defined node identifier

  * Literal Values**

``name = WHO_AM_I``
   returns nid of calling task

  * Completion Status**
==  =============== ========================================

``OK``                 ``node_ident`` successful
``ILLEGAL_USE``        ``node_ident`` not callable from ISR
``INVALID_PARAMETER``  a parameter refers to an invalid address
``NAME_NOT_FOUND``     no node with this name==  =============== ========================================


  * Description**

This operation returns the node identifier for the node with the given name. 
No assumption is made on how this identifier is obtained. If there is more 
than one mode with the same name in the system, then the ``nid`` of the first
one found is returned.

  1. Requirements (Outdated Binary Format):
    1. ftp://ftp.rtems.com/pub/rtems/people/joel/RTEID-ORKID/ORKID-2.1/merged/ORKID-2_1-p1-p108.docx
  2. ftp://ftp.rtems.com/pub/rtems/people/joel/RTEID-ORKID/RTEID-2.1/merged/RTEID-2_1-p1-p116.doc
  3. User's Guide (Unmaintainable Textual Format):
    1. http://rtems.org/onlinedocs/doc-current/share/rtems/html/c_user/index.html
    2. http://rtems.org/onlinedocs/doc-current/share/rtems/html/shell/index.html
  4. Doxygen API (Maintainable Textual Format): http://www.rtems.org/onlinedocs/doxygen/cpukit/html/modules.html

TBD: identify unified textual format

Directions for Mentors

  1. Verify the .rst renders in the RST editor
  2. Verify the format matches the example
  3. Look for optica