[PATCH 8/8] c-user: Generate dual-ported memory manager docs
Gedare Bloom
gedare at rtems.org
Wed Apr 21 15:28:51 UTC 2021
On Wed, Apr 21, 2021 at 7:50 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> 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.
> ---
> c-user/dual-ported-memory/directives.rst | 500 ++++++++++++++-------
> c-user/dual-ported-memory/introduction.rst | 43 +-
> 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..d701a2b 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 ``length`` parameter was `NULL
id?
everything else looks ok
> + <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.
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list