c-user: Generate dual-ported memory manager docs

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.

2 files changed, 373 insertions, 170 deletions

diff --git a/c-user/dual-ported-memory/directives.rst b/c-user/dual-ported-memory/directives.rst
index fb21a4f..42cb875 100644
--- a/c-user/dual-ported-memory/directives.rst
+++ b/c-user/dual-ported-memory/directives.rst
@@ -1,229 +1,403 @@
 .. 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
+
+.. _DualPortedMemoryManagerDirectives:
+
 Directives
 ==========
 
-This section details the dual-ported memory 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 Dual-Ported Memory 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/dpmem/if/create
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_port_create()
 .. index:: create a port
-.. index:: rtems_port_create
-
-.. _rtems_port_create:
-
-PORT_CREATE - Create a port
----------------------------
-
-CALLING SEQUENCE:
-    .. code-block:: c
-
-        rtems_status_code rtems_port_create(
-            rtems_name  name,
-            void       *internal_start,
-            void       *external_start,
-            uint32_t    length,
-            rtems_id   *id
-        );
-
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
-
-     * - ``RTEMS_SUCCESSFUL``
-       - port created successfully
-     * - ``RTEMS_INVALID_NAME``
-       - invalid port name
-     * - ``RTEMS_INVALID_ADDRESS``
-       - address not on four byte boundary
-     * - ``RTEMS_INVALID_ADDRESS``
-       - ``id`` is NULL
-     * - ``RTEMS_TOO_MANY``
-       - too many DP memory areas created
-
-DESCRIPTION:
-    This directive creates a port which resides on the local node for the
-    specified DPMA.  The assigned port id is returned in id.  This port id is
-    used as an argument to other dual-ported memory manager directives to
-    convert addresses within this DPMA.
-
-    For control and maintenance of the port, RTEMS allocates and initializes an
-    DPCB from the DPCB free pool.  Thus memory from the dual-ported memory area
-    is not used to store the DPCB.
-
-NOTES:
-    This directive may cause the calling task to be preempted due to an
-    obtain and release of the object allocator mutex.
-
-    The internal_address and external_address parameters must be on a four byte
-    boundary.
+
+.. _InterfaceRtemsPortCreate:
+
+rtems_port_create()
+-------------------
+
+Creates a port.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    rtems_status_code rtems_port_create(
+      rtems_name name,
+      void      *internal_start,
+      void      *external_start,
+      uint32_t   length,
+      rtems_id  *id
+    );
+
+.. rubric:: PARAMETERS:
+
+``name``
+    This parameter is the object name of the port.
+
+``internal_start``
+    This parameter is the internal start address of the memory area.
+
+``external_start``
+    This parameter is the external start address of the memory area.
+
+``length``
+    This parameter is the length in bytes of the memory area.
+
+``id``
+    This parameter is the pointer to an object identifier variable.  When the
+    directive call is successful, the identifier of the created port will be
+    stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive creates a port which resides on the local node.  The port has
+the user-defined object name specified in ``name``.  The assigned object
+identifier is returned in ``id``.  This identifier is used to access the port
+with other dual-ported memory port related directives.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+    The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_NAME`
+    The ``name`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+    The ``id`` parameter was `NULL
+    <https://en.cppreference.com/w/c/types/NULL>`_.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+    The ``internal_start`` parameter was not properly aligned.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+    The ``external_start`` parameter was not properly aligned.
+
+:c:macro:`RTEMS_TOO_MANY`
+    There was no inactive object available to create a port.  The number of
+    port available to the application is configured through the
+    :ref:`CONFIGURE_MAXIMUM_PORTS` application configuration option.
+
+.. rubric:: NOTES:
+
+The ``internal_start`` and ``external_start`` parameters must be on a boundary
+defined by the target processor architecture.
+
+For control and maintenance of the port, RTEMS allocates a :term:`DPCB` from
+the local DPCB free pool and initializes it.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex.  This may
+  cause the calling task to be preempted.
+
+* The number of ports available to the application is configured through the
+  :ref:`CONFIGURE_MAXIMUM_PORTS` application configuration option.
+
+* Where the object class corresponding to the directive is configured to use
+  unlimited objects, the directive may allocate memory from the RTEMS
+  Workspace.
+
+.. Generated from spec:/rtems/dpmem/if/ident
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
+
+.. index:: rtems_port_ident()
+
+.. _InterfaceRtemsPortIdent:
+
+rtems_port_ident()
+------------------
+
+Identifies a port by the object name.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    rtems_status_code rtems_port_ident( rtems_name name, rtems_id *id );
+
+.. rubric:: PARAMETERS:
+
+``name``
+    This parameter is the object name to look up.
+
+``id``
+    This parameter is the pointer to an object identifier variable.  When the
+    directive call is successful, the object identifier of an object with the
+    specified name will be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive obtains a port identifier associated with the port name
+specified in ``name``.
 
-.. index:: get ID of a port
-.. index:: obtain ID of a port
-.. index:: rtems_port_ident
+.. rubric:: RETURN VALUES:
 
-.. _rtems_port_ident:
+:c:macro:`RTEMS_SUCCESSFUL`
+    The requested operation was successful.
 
-PORT_IDENT - Get ID of a port
------------------------------
+:c:macro:`RTEMS_INVALID_ADDRESS`
+    The ``id`` parameter was `NULL
+    <https://en.cppreference.com/w/c/types/NULL>`_.
 
-CALLING SEQUENCE:
-    .. code-block:: c
+:c:macro:`RTEMS_INVALID_NAME`
+    The ``name`` parameter was 0.
 
-        rtems_status_code rtems_port_ident(
-            rtems_name  name,
-            rtems_id   *id
-        );
+:c:macro:`RTEMS_INVALID_NAME`
+    There was no object with the specified name on the local node.
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+.. rubric:: NOTES:
 
-     * - ``RTEMS_SUCCESSFUL``
-       - port identified successfully
-     * - ``RTEMS_INVALID_ADDRESS``
-       - ``id`` is NULL
-     * - ``RTEMS_INVALID_NAME``
-       - port name not found
+If the port name is not unique, then the port identifier will match the first
+port with that name in the search order.  However, this port identifier is not
+guaranteed to correspond to the desired port.
 
-DESCRIPTION:
-    This directive obtains the port id associated with the specified name to be
-    acquired.  If the port name is not unique, then the port id will match one
-    of the DPMAs with that name.  However, this port id is not guaranteed to
-    correspond to the desired DPMA.  The port id is used to access this DPMA in
-    other dual-ported memory area related directives.
+The objects are searched from lowest to the highest index.  Only the local node
+is searched.
 
-NOTES:
-    This directive will not cause the running task to be preempted.
+The port identifier is used with other dual-ported memory related directives to
+access the port.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/dpmem/if/delete
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_port_delete()
 .. index:: delete a port
-.. index:: rtems_port_delete
 
-.. _rtems_port_delete:
+.. _InterfaceRtemsPortDelete:
+
+rtems_port_delete()
+-------------------
+
+Deletes the port.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    rtems_status_code rtems_port_delete( rtems_id id );
+
+.. rubric:: PARAMETERS:
+
+``id``
+    This parameter is the port identifier.
 
-PORT_DELETE - Delete a port
----------------------------
+.. rubric:: DESCRIPTION:
 
-CALLING SEQUENCE:
-    .. code-block:: c
+This directive deletes the port specified by ``id``.
 
-        rtems_status_code rtems_port_delete(
-            rtems_id id
-        );
+.. rubric:: RETURN VALUES:
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+:c:macro:`RTEMS_SUCCESSFUL`
+    The requested operation was successful.
 
-     * - ``RTEMS_SUCCESSFUL``
-       - port deleted successfully
-     * - ``RTEMS_INVALID_ID``
-       - invalid port id
+:c:macro:`RTEMS_INVALID_ID`
+    There was no port associated with the identifier specified by ``id``.
 
-DESCRIPTION:
-    This directive deletes the dual-ported memory area specified by id.  The
-    DPCB for the deleted dual-ported memory area is reclaimed by RTEMS.
+.. rubric:: NOTES:
 
-NOTES:
-    This directive may cause the calling task to be preempted due to an
-    obtain and release of the object allocator mutex.
+The :term:`DPCB` for the deleted port is reclaimed by RTEMS.
 
-    The calling task does not have to be the task that created the port.  Any
-    local task that knows the port id can delete the port.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive may obtain and release the object allocator mutex.  This may
+  cause the calling task to be preempted.
+
+* The calling task does not have to be the task that created the object.  Any
+  local task that knows the object identifier can delete the object.
+
+* Where the object class corresponding to the directive is configured to use
+  unlimited objects, the directive may free memory to the RTEMS Workspace.
+
+.. Generated from spec:/rtems/dpmem/if/external-to-internal
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_port_external_to_internal()
 .. index:: convert external to internal address
-.. index:: rtems_port_external_to_internal
 
-.. _rtems_port_external_to_internal:
+.. _InterfaceRtemsPortExternalToInternal:
+
+rtems_port_external_to_internal()
+---------------------------------
+
+Converts the external address to the internal address.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
 
-PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
-----------------------------------------------------------------
+    rtems_status_code rtems_port_external_to_internal(
+      rtems_id id,
+      void    *external,
+      void   **internal
+    );
 
-CALLING SEQUENCE:
-    .. code-block:: c
+.. rubric:: PARAMETERS:
 
-        rtems_status_code rtems_port_external_to_internal(
-            rtems_id   id,
-            void      *external,
-            void     **internal
-        );
+``id``
+    This parameter is the port identifier.
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+``external``
+    This parameter is the external address to convert.
 
-     * - ``RTEMS_INVALID_ADDRESS``
-       - ``internal`` is NULL
-     * - ``RTEMS_SUCCESSFUL``
-       - successful conversion
+``internal``
+    This parameter is the pointer to a pointer variable.  When the directive
+    call is successful, the external address associated with the internal
+    address will be stored in this variable.
 
-DESCRIPTION:
-    This directive converts a dual-ported memory address from external to
-    internal representation for the specified port.  If the given external
-    address is invalid for the specified port, then the internal address is set
-    to the given external address.
+.. rubric:: DESCRIPTION:
 
-NOTES:
-    This directive is callable from an ISR.
+This directive converts a dual-ported memory address from external to internal
+representation for the specified port.  If the given external address is
+invalid for the specified port, then the internal address is set to the given
+external address.
 
-    This directive will not cause the calling task to be preempted.
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+    The requested operation was successful.
+
+:c:macro:`RTEMS_INVALID_NAME`
+    The ``id`` parameter was invalid.
+
+:c:macro:`RTEMS_INVALID_ADDRESS`
+    The ``internal`` parameter was `NULL
+    <https://en.cppreference.com/w/c/types/NULL>`_.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within interrupt context.
+
+* The directive may be called from within device driver initialization context.
+
+* The directive may be called from within task context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/dpmem/if/internal-to-external
 
 .. raw:: latex
 
-   \clearpage
+    \clearpage
 
+.. index:: rtems_port_internal_to_external()
 .. index:: convert internal to external address
-.. index:: rtems_port_internal_to_external
 
-.. _rtems_port_internal_to_external:
+.. _InterfaceRtemsPortInternalToExternal:
+
+rtems_port_internal_to_external()
+---------------------------------
+
+Converts the internal address to the external address.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+    rtems_status_code rtems_port_internal_to_external(
+      rtems_id id,
+      void    *internal,
+      void   **external
+    );
+
+.. rubric:: PARAMETERS:
+
+``id``
+    This parameter is the port identifier.
+
+``internal``
+    This parameter is the internal address to convert.
+
+``external``
+    This parameter is the pointer to a pointer variable.  When the directive
+    call is successful, the external address associated with the internal
+    address will be stored in this variable.
+
+.. rubric:: DESCRIPTION:
+
+This directive converts a dual-ported memory address from internal to external
+representation so that it can be passed to owner of the DPMA represented by the
+specified port.  If the given internal address is an invalid dual-ported
+address, then the external address is set to the given internal address.
+
+.. rubric:: RETURN VALUES:
+
+:c:macro:`RTEMS_SUCCESSFUL`
+    The requested operation was successful.
 
-PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
-----------------------------------------------------------------
+:c:macro:`RTEMS_INVALID_NAME`
+    The ``id`` parameter was invalid.
 
-CALLING SEQUENCE:
-    .. code-block:: c
+:c:macro:`RTEMS_INVALID_ADDRESS`
+    The ``external`` parameter was `NULL
+    <https://en.cppreference.com/w/c/types/NULL>`_.
 
-        rtems_status_code rtems_port_internal_to_external(
-            rtems_id   id,
-            void      *internal,
-            void     **external
-        );
+.. rubric:: CONSTRAINTS:
 
-DIRECTIVE STATUS CODES:
-    .. list-table::
-     :class: rtems-table
+The following constraints apply to this directive:
 
-     * - ``RTEMS_INVALID_ADDRESS``
-       - ``external`` is NULL
-     * - ``RTEMS_SUCCESSFUL``
-       - successful conversion
+* The directive may be called from within interrupt context.
 
-DESCRIPTION:
-    This directive converts a dual-ported memory address from internal to
-    external representation so that it can be passed to owner of the DPMA
-    represented by the specified port.  If the given internal address is an
-    invalid dual-ported address, then the external address is set to the given
-    internal address.
+* The directive may be called from within device driver initialization context.
 
-NOTES:
-    This directive is callable from an ISR.
+* The directive may be called from within task context.
 
-    This directive will not cause the calling task to be preempted.
+* The directive will not cause the calling task to be preempted.
diff --git a/c-user/dual-ported-memory/introduction.rst b/c-user/dual-ported-memory/introduction.rst
index 752a162..fd7cc8e 100644
--- a/c-user/dual-ported-memory/introduction.rst
+++ b/c-user/dual-ported-memory/introduction.rst
@@ -1,20 +1,49 @@
 .. 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
+
+.. Generated from spec:/rtems/dpmem/if/group
+
+.. _DualPortedMemoryManagerIntroduction:
+
 Introduction
 ============
 
-The dual-ported memory manager provides a mechanism for converting addresses
+.. The following list was generated from:
+.. spec:/rtems/dpmem/if/create
+.. spec:/rtems/dpmem/if/ident
+.. spec:/rtems/dpmem/if/delete
+.. spec:/rtems/dpmem/if/external-to-internal
+.. spec:/rtems/dpmem/if/internal-to-external
+
+The Dual-Ported Memory Manager provides a mechanism for converting addresses
 between internal and external representations for multiple dual-ported memory
-areas (DPMA).  The directives provided by the dual-ported memory manager are:
+areas (DPMA). The directives provided by the Dual-Ported Memory Manager are:
 
-- :ref:`rtems_port_create`
+* :ref:`InterfaceRtemsPortCreate` - Creates a port.
 
-- :ref:`rtems_port_ident`
+* :ref:`InterfaceRtemsPortIdent` - Identifies a port by the object name.
 
-- :ref:`rtems_port_delete`
+* :ref:`InterfaceRtemsPortDelete` - Deletes the port.
 
-- :ref:`rtems_port_external_to_internal`
+* :ref:`InterfaceRtemsPortExternalToInternal` - Converts the external address
+  to the internal address.
 
-- :ref:`rtems_port_internal_to_external`
+* :ref:`InterfaceRtemsPortInternalToExternal` - Converts the internal address
+  to the external address.