Re: [PATCH] c-user: Generate region manager documentation
On Tue, Apr 27, 2021 at 12:03 PM Sebastian Huber wrote: > > The documentation is a consolidation of the comments in Doxygen markup > and the documentation sources in Sphinx markup. The documentation was > transfered to interface specification items. The documentation source > files were generated from the items by a script. > > Update #3993. > --- > Here is the updated document for review: > > https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf > > c-user/region/directives.rst | 1269 > c-user/region/introduction.rst | 58 +- > 2 files changed, 857 insertions(+), 470 deletions(-) > > diff --git a/c-user/region/directives.rst b/c-user/region/directives.rst > index be994f6..3ec06cd 100644 > --- a/c-user/region/directives.rst > +++ b/c-user/region/directives.rst > @@ -1,561 +1,914 @@ > .. SPDX-License-Identifier: CC-BY-SA-4.0 > > +.. Copyright (C) 2020, 2021 embedded brains GmbH > (http://www.embedded-brains.de) > .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) > > +.. This file is part of the RTEMS quality process and was automatically > +.. generated. If you find something that needs to be fixed or > +.. worded better please post a report or patch to an RTEMS mailing list > +.. or raise a bug report: > +.. > +.. https://www.rtems.org/bugs.html > +.. > +.. For information on updating and regenerating please refer to the How-To > +.. section in the Software Requirements Engineering chapter of the > +.. RTEMS Software Engineering manual. The manual is provided as a part of > +.. a release. For development sources please refer to the online > +.. documentation at: > +.. > +.. https://docs.rtems.org > + > +.. _RegionManagerDirectives: > + > Directives > == > > -This section details the region manager's directives. A subsection is > -dedicated to each of this manager's directives and describes the calling > -sequence, related constants, usage, and status codes. > +This section details the directives of the Region Manager. A subsection is > +dedicated to each of this manager's directives and lists the calling > sequence, > +parameters, description, return values, and notes of the directive. > + > +.. Generated from spec:/rtems/region/if/create > > .. raw:: latex > > - \clearpage > +\clearpage > > +.. index:: rtems_region_create() > .. index:: create a region > > -.. _rtems_region_create: > +.. _InterfaceRtemsRegionCreate: > > -REGION_CREATE - Create a region > > +rtems_region_create() > +- > + > +Creates a region. > + > +.. rubric:: CALLING SEQUENCE: > + > +.. code-block:: c > + > +rtems_status_code rtems_region_create( > + rtems_name name, > + void *starting_address, > + uintptr_t length, > + uintptr_t page_size, > + rtems_attribute attribute_set, > + rtems_id *id > +); > + > +.. rubric:: PARAMETERS: > + > +``name`` > +This parameter is the object name of the region. > + > +``starting_address`` > +This parameter is the starting address of the memory area managed by the > +region. > + > +``length`` > +This parameter is the length in bytes of the memory area managed by the > +region. > + > +``page_size`` > +This parameter is the alignment of the starting address and length of > each > +allocated segment of the region. > + > +``attribute_set`` > +This parameter is the attribute set of the region. > + > +``id`` > +This parameter is the pointer to an object identifier variable. When the > +directive call is successful, the identifier of the created region will > be > +stored in this variable. > + > +.. rubric:: DESCRIPTION: > + > +This directive creates a region which resides on the local node. The region > +has the user-defined object name specified in ``name``. The assigned object > +identifier is returned in ``id``. This identifier is used to access the > region > +with other region related directives. > + > +The region manages the **contiguous memory area** which starts at > +``starting_address`` and is ``length`` bytes long. The memory area shall be > +large enough to contain some internal region administration data. > + > +The **starting address** and **length of segments** allocated from the region > +will be an integral multiple of ``page_size``. The specified page size will > be > +aligned to an implementation-dependent minimum alignment if necessary. > + > +The **attribute set** specified in ``attribute_set`` is built through a > +*bitwise or* of the attribute constants described below. Not all > combinations > +of attributes are allowed. Some attributes are mutually exclusive. If > +mutually exclusive attributes are combined, the behaviour is undefined. > +Attributes not mentioned below are not evaluated by this directive and have > no > +effect. Default attributes can be selected by using the >
[PATCH] c-user: Generate region manager documentation
The documentation is a consolidation of the comments in Doxygen markup and the documentation sources in Sphinx markup. The documentation was transfered to interface specification items. The documentation source files were generated from the items by a script. Update #3993. --- Here is the updated document for review: https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf c-user/region/directives.rst | 1269 c-user/region/introduction.rst | 58 +- 2 files changed, 857 insertions(+), 470 deletions(-) diff --git a/c-user/region/directives.rst b/c-user/region/directives.rst index be994f6..3ec06cd 100644 --- a/c-user/region/directives.rst +++ b/c-user/region/directives.rst @@ -1,561 +1,914 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _RegionManagerDirectives: + Directives == -This section details the region manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. +This section details the directives of the Region Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/region/if/create .. raw:: latex - \clearpage +\clearpage +.. index:: rtems_region_create() .. index:: create a region -.. _rtems_region_create: +.. _InterfaceRtemsRegionCreate: -REGION_CREATE - Create a region +rtems_region_create() +- + +Creates a region. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + +rtems_status_code rtems_region_create( + rtems_name name, + void *starting_address, + uintptr_t length, + uintptr_t page_size, + rtems_attribute attribute_set, + rtems_id *id +); + +.. rubric:: PARAMETERS: + +``name`` +This parameter is the object name of the region. + +``starting_address`` +This parameter is the starting address of the memory area managed by the +region. + +``length`` +This parameter is the length in bytes of the memory area managed by the +region. + +``page_size`` +This parameter is the alignment of the starting address and length of each +allocated segment of the region. + +``attribute_set`` +This parameter is the attribute set of the region. + +``id`` +This parameter is the pointer to an object identifier variable. When the +directive call is successful, the identifier of the created region will be +stored in this variable. + +.. rubric:: DESCRIPTION: + +This directive creates a region which resides on the local node. The region +has the user-defined object name specified in ``name``. The assigned object +identifier is returned in ``id``. This identifier is used to access the region +with other region related directives. + +The region manages the **contiguous memory area** which starts at +``starting_address`` and is ``length`` bytes long. The memory area shall be +large enough to contain some internal region administration data. + +The **starting address** and **length of segments** allocated from the region +will be an integral multiple of ``page_size``. The specified page size will be +aligned to an implementation-dependent minimum alignment if necessary. + +The **attribute set** specified in ``attribute_set`` is built through a +*bitwise or* of the attribute constants described below. Not all combinations +of attributes are allowed. Some attributes are mutually exclusive. If +mutually exclusive attributes are combined, the behaviour is undefined. +Attributes not mentioned below are not evaluated by this directive and have no +effect. Default attributes can be selected by using the +:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant. + +The **task wait queue discipline** is selected by the mutually exclusive +:c:macro:`RTEMS_FIFO` and :c:macro:`RTEMS_PRIORITY` attributes. The discipline +defines the order in which tasks wait for allocatable segments on a currently +empty region. + +* The **FIFO discipline** is the default and can be
