[PATCH 2/2] c-user: Generate Partition Manager documentation
Gedare Bloom
gedare at rtems.org
Wed Nov 11 17:16:09 UTC 2020
These will be fine, with the manually edited warning fixed
On Mon, Nov 9, 2020 at 7:47 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> The manager 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. This
> header file was generated from the items by a script.
>
> Update #3993.
> ---
> c-user/partition/directives.rst | 647 +++++++++++++++++-------------
> c-user/partition/introduction.rst | 41 +-
> 2 files changed, 408 insertions(+), 280 deletions(-)
>
> diff --git a/c-user/partition/directives.rst b/c-user/partition/directives.rst
> index f81c37f..cd50671 100644
> --- a/c-user/partition/directives.rst
> +++ b/c-user/partition/directives.rst
> @@ -1,349 +1,450 @@
> .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
> .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
>
> +.. Do not manually edit this file. It 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 to an RTEMS mailing list or raise a bug report:
> +..
> +.. https://docs.rtems.org/branches/master/user/support/bugs.html
> +..
> +.. For information on updating and regenerating please refer to:
> +..
> +.. https://docs.rtems.org/branches/master/eng/req/howto.html
> +
> +.. _PartitionManagerDirectives:
> +
> Directives
> ==========
>
> -This section details the partition 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 Partition 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/part/if/create
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
>
> +.. index:: rtems_partition_create()
> .. index:: create a partition
> -.. index:: rtems_partition_create
> -
> -.. _rtems_partition_create:
> -
> -PARTITION_CREATE - Create a partition
> --------------------------------------
> -
> -CALLING SEQUENCE:
> - .. code-block:: c
> -
> - rtems_status_code rtems_partition_create(
> - rtems_name name,
> - void *starting_address,
> - uintptr_t length,
> - size_t buffer_size,
> - rtems_attribute attribute_set,
> - rtems_id *id
> - );
> -
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> -
> - * - ``RTEMS_SUCCESSFUL``
> - - partition created successfully
> - * - ``RTEMS_INVALID_NAME``
> - - invalid partition ``name``
> - * - ``RTEMS_TOO_MANY``
> - - too many partitions created
> - * - ``RTEMS_INVALID_ADDRESS``
> - - ``starting_address`` is not on a pointer size boundary
> - * - ``RTEMS_INVALID_ADDRESS``
> - - ``starting_address`` is NULL
> - * - ``RTEMS_INVALID_ADDRESS``
> - - ``id`` is NULL
> - * - ``RTEMS_INVALID_SIZE``
> - - ``length`` or ``buffer_size`` is 0
> - * - ``RTEMS_INVALID_SIZE``
> - - ``length`` is less than the ``buffer_size``
> - * - ``RTEMS_INVALID_SIZE``
> - - ``buffer_size`` is not an integral multiple of the pointer size
> - * - ``RTEMS_INVALID_SIZE``
> - - ``buffer_size`` is less than two times the pointer size
> - * - ``RTEMS_TOO_MANY``
> - - too many global objects
> -
> -DESCRIPTION:
> - This directive creates a partition of fixed size buffers from a physically
> - contiguous memory space which starts at starting_address and is length
> - bytes in size. Each allocated buffer is to be of ``buffer_size`` in bytes.
> - The assigned partition id is returned in ``id``. This partition id is used
> - to access the partition with other partition related directives. For
> - control and maintenance of the partition, RTEMS allocates a PTCB from the
> - local PTCB free pool and initializes it.
> -
> -NOTES:
> - This directive may cause the calling task to be preempted due to an
> - obtain and release of the object allocator mutex.
> -
> - The partition buffer area specified by the ``starting_address`` must be
> - properly aligned. It must be possible to directly store target
> - architecture pointers and the also the user data. For example, if the user
> - data contains some long double or vector data types, the partition buffer
> - area and the buffer size must take the alignment of these types into
> - account which is usually larger than the pointer alignment. A cache line
> - alignment may be also a factor.
> -
> - The ``buffer_size`` parameter must be an integral multiple of the pointer
> - size on the target architecture. Additionally, ``buffer_size`` must be
> - large enough to hold two pointers on the target architecture. This is
> - required for RTEMS to manage the buffers when they are free.
> -
> - Memory from the partition is not used by RTEMS to store the Partition
> - Control Block.
> -
> - The following partition attribute constants are defined by RTEMS:
> -
> - .. list-table::
> - :class: rtems-table
> -
> - * - ``RTEMS_LOCAL``
> - - local partition (default)
> - * - ``RTEMS_GLOBAL``
> - - global partition
> -
> - The PTCB for a global partition is allocated on the local node. The memory
> - space used for the partition must reside in shared memory. Partitions
> - should not be made global unless remote tasks must interact with the
> - partition. This is to avoid the overhead incurred by the creation of a
> - global partition. When a global partition is created, the partition's name
> - and id must be transmitted to every node in the system for insertion in the
> - local copy of the global object table.
> -
> - The total number of global objects, including partitions, is limited by the
> - maximum_global_objects field in the Configuration Table.
> -
> -EXAMPLE:
> - .. code-block:: c
> -
> - #include <rtems.h>
> - #include <rtems/chain.h>
> -
> - #include <assert.h>
> -
> - typedef struct {
> - char less;
> - short more;
> - } item;
> -
> - union {
> - item data;
> - rtems_chain_node node;
> - } items[ 13 ];
> -
> - rtems_id create_partition(void)
> - {
> - rtems_id id;
> - rtems_status_code sc;
> -
> - sc = rtems_partition_create(
> - rtems_build_name( 'P', 'A', 'R', 'T' ),
> - items,
> - sizeof( items ),
> - sizeof( items[ 0 ] ),
> - RTEMS_DEFAULT_ATTRIBUTES,
> - &id
> - );
> - assert(sc == RTEMS_SUCCESSFUL);
> -
> - return id;
> - }
> +
> +.. _InterfaceRtemsPartitionCreate:
> +
> +rtems_partition_create()
> +------------------------
> +
> +Creates a partition.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + rtems_status_code rtems_partition_create(
> + rtems_name name,
> + void *starting_address,
> + uintptr_t length,
> + size_t buffer_size,
> + rtems_attribute attribute_set,
> + rtems_id *id
> + );
> +
> +.. rubric:: PARAMETERS:
> +
> +``name``
> + This parameter is the name of the partition.
> +
> +``starting_address``
> + This parameter is the starting address of the buffer area used by the
> + partition.
> +
> +``length``
> + This parameter is the length in bytes of the buffer area used by the
> + partition.
> +
> +``buffer_size``
> + This parameter is the size in bytes of a buffer managed by the partition.
> +
> +``attribute_set``
> + This parameter is the attribute set of the partition.
> +
> +``id``
> + This parameter is the pointer to an object identifier variable. The
> + identifier of the created partition object will be stored in this variable,
> + in case of a successful operation.
> +
> +.. rubric:: DESCRIPTION:
> +
> +This directive creates a partition of fixed size buffers from a physically
> +contiguous memory space which starts at ``starting_address`` and is ``length``
> +bytes in size. Each allocated buffer is to be of ``buffer_size`` in bytes.
> +The assigned partition identifier is returned in ``id``. This partition
> +identifier is used to access the partition with other partition related
> +directives.
> +
> +The **attribute set** specified in ``attribute_set`` is built through a
> +*bitwise or* of the attribute constants described below. Attributes not
> +mentioned below are not evaluated by this directive and have no effect.
> +
> +The partition can have **local** or **global** scope in a multiprocessing
> +network (this attribute does not refer to SMP systems).
> +
> +* A **local** scope is the default and can be emphasized through the use of the
> + :c:macro:`RTEMS_LOCAL` attribute. A local partition can be only used by the
> + node which created it.
> +
> +* A **global** scope is established if the :c:macro:`RTEMS_GLOBAL` attribute is
> + set. The memory space used for the partition must reside in shared memory.
> + Setting the global attribute in a single node system has no effect.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_NAME`
> + The partition name was invalid.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``id`` parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_SIZE`
> + The ``length`` parameter was 0.
> +
> +:c:macro:`RTEMS_INVALID_SIZE`
> + The ``buffer_size`` parameter was 0.
> +
> +:c:macro:`RTEMS_INVALID_SIZE`
> + The ``length`` parameter was less than the ``buffer_size`` parameter.
> +
> +:c:macro:`RTEMS_INVALID_SIZE`
> + The ``buffer_size`` parameter was not an integral multiple of the pointer
> + size.
> +
> +:c:macro:`RTEMS_INVALID_SIZE`
> + The ``buffer_size`` parameter was less than two times the pointer size.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``starting_address`` parameter was not on a pointer size boundary.
> +
> +:c:macro:`RTEMS_TOO_MANY`
> + There was no inactive object available to create a new partition. The
> + number of partitions available to the application is configured through the
> + :ref:`CONFIGURE_MAXIMUM_PARTITIONS` configuration option.
> +
> +.. rubric:: NOTES:
> +
> +This directive may cause the calling task to be preempted due to an obtain and
> +release of the object allocator mutex.
> +
> +The partition buffer area specified by the ``starting_address`` must be
> +properly aligned. It must be possible to directly store target architecture
> +pointers and also the user data. For example, if the user data contains some
> +long double or vector data types, the partition buffer area and the buffer size
> +must take the alignment of these types into account which is usually larger
> +than the pointer alignment. A cache line alignment may be also a factor. Use
> +:c:macro:`RTEMS_PARTITION_ALIGNMENT` to specify the minimum alignment of a
> +partition buffer type.
> +
> +The ``buffer_size`` parameter must be an integral multiple of the pointer size
> +on the target architecture. Additionally, ``buffer_size`` must be large enough
> +to hold two pointers on the target architecture. This is required for RTEMS to
> +manage the buffers when they are free.
> +
> +For control and maintenance of the partition, RTEMS allocates a :term:`PTCB`
> +from the local PTCB free pool and initializes it. Memory from the partition
> +buffer area is not used by RTEMS to store the PTCB.
> +
> +The PTCB for a global partition is allocated on the local node. Partitions
> +should not be made global unless remote tasks must interact with the partition.
> +This is to avoid the overhead incurred by the creation of a global partition.
> +When a global partition is created, the partition's name and identifier must be
> +transmitted to every node in the system for insertion in the local copy of the
> +global object table.
> +
> +The total number of global objects, including partitions, is limited by the
> +value of the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
> +configuration option.
> +
> +.. Generated from spec:/rtems/part/if/ident
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
>
> +.. index:: rtems_partition_ident()
> .. index:: get ID of a partition
> .. index:: obtain ID of a partition
> -.. index:: rtems_partition_ident
>
> -.. _rtems_partition_ident:
> +.. _InterfaceRtemsPartitionIdent:
> +
> +rtems_partition_ident()
> +-----------------------
> +
> +Identifies a partition by the object name.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
>
> -PARTITION_IDENT - Get ID of a partition
> ----------------------------------------
> + rtems_status_code rtems_partition_ident(
> + rtems_name name,
> + uint32_t node,
> + rtems_id *id
> + );
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: PARAMETERS:
>
> - rtems_status_code rtems_partition_ident(
> - rtems_name name,
> - uint32_t node,
> - rtems_id *id
> - );
> +``name``
> + This parameter is the object name to look up.
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +``node``
> + This parameter is the node or node set to search for a matching object.
>
> - * - ``RTEMS_SUCCESSFUL``
> - - partition identified successfully
> - * - ``RTEMS_INVALID_ADDRESS``
> - - ``id`` is NULL
> - * - ``RTEMS_INVALID_NAME``
> - - partition name not found
> - * - ``RTEMS_INVALID_NODE``
> - - invalid node id
> +``id``
> + This parameter is the pointer to an object identifier variable. The object
> + identifier of an object with the specified name will be stored in this
> + variable, in case of a successful operation.
>
> -DESCRIPTION:
> - This directive obtains the partition id associated with the partition name.
> - If the partition name is not unique, then the partition id will match one
> - of the partitions with that name. However, this partition id is not
> - guaranteed to correspond to the desired partition. The partition id is
> - used with other partition related directives to access the partition.
> +.. rubric:: DESCRIPTION:
>
> -NOTES:
> - This directive will not cause the running task to be preempted.
> +This directive obtains a partition identifier associated with the partition
> +name specified in ``name``.
>
> - If node is ``RTEMS_SEARCH_ALL_NODES``, all nodes are searched with the
> - local node being searched first. All other nodes are searched with the
> - lowest numbered node searched first.
> +The node to search is specified in ``node``. It shall be
>
> - If node is a valid node number which does not represent the local node,
> - then only the partitions exported by the designated node are searched.
> +* a valid node number,
>
> - This directive does not generate activity on remote nodes. It accesses
> - only the local copy of the global object table.
> +* the constant :c:macro:`RTEMS_SEARCH_ALL_NODES` to search in all nodes,
> +
> +* the constant :c:macro:`RTEMS_SEARCH_LOCAL_NODE` to search in the local node
> + only, or
> +
> +* the constant :c:macro:`RTEMS_SEARCH_OTHER_NODES` to search in all nodes
> + except the local node.
> +
> +.. rubric:: RETURN VALUES:
> +
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
> +
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The id parameter was `NULL <https://en.cppreference.com/w/c/types/NULL>`_.
> +
> +:c:macro:`RTEMS_INVALID_NAME`
> + The name parameter was 0.
> +
> +:c:macro:`RTEMS_INVALID_NAME`
> + There was no object with the specified name on the specified nodes.
> +
> +:c:macro:`RTEMS_INVALID_NODE`
> + In multiprocessing configurations, the specified node was invalid.
> +
> +.. rubric:: NOTES:
> +
> +If the partition name is not unique, then the partition identifier will match
> +the first partition with that name in the search order. However, this
> +partition identifier is not guaranteed to correspond to the desired partition.
> +The partition identifier is used with other partition related directives to
> +access the partition.
> +
> +If node is :c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the
> +local node being searched first. All other nodes are searched with the lowest
> +numbered node searched first.
> +
> +If node is a valid node number which does not represent the local node, then
> +only the partitions exported by the designated node are searched.
> +
> +This directive does not generate activity on remote nodes. It accesses only
> +the local copy of the global object table.
> +
> +.. Generated from spec:/rtems/part/if/delete
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
>
> +.. index:: rtems_partition_delete()
> .. index:: delete a partition
> -.. index:: rtems_partition_delete
>
> -.. _rtems_partition_delete:
> +.. _InterfaceRtemsPartitionDelete:
> +
> +rtems_partition_delete()
> +------------------------
> +
> +Deletes the partition.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + rtems_status_code rtems_partition_delete( rtems_id id );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> + This parameter is the partition identifier.
> +
> +.. rubric:: DESCRIPTION:
>
> -PARTITION_DELETE - Delete a partition
> --------------------------------------
> +This directive deletes the partition specified by the id parameter. The
> +partition cannot be deleted if any of its buffers are still allocated. The
> +:term:`PTCB` for the deleted partition is reclaimed by RTEMS.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: RETURN VALUES:
>
> - rtems_status_code rtems_partition_delete(
> - rtems_id id
> - );
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no partition with the specified identifier.
>
> - * - ``RTEMS_SUCCESSFUL``
> - - partition deleted successfully
> - * - ``RTEMS_INVALID_ID``
> - - invalid partition id
> - * - ``RTEMS_RESOURCE_IN_USE``
> - - buffers still in use
> - * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT``
> - - cannot delete remote partition
> +:c:macro:`RTEMS_ILLEGAL_ON_REMOTE_OBJECT`
> + The partition resided on a remote node.
>
> -DESCRIPTION:
> - This directive deletes the partition specified by id. The partition cannot
> - be deleted if any of its buffers are still allocated. The PTCB for the
> - deleted partition is reclaimed by RTEMS.
> +:c:macro:`RTEMS_RESOURCE_IN_USE`
> + There were buffers of the partition still in use.
>
> -NOTES:
> - This directive may cause the calling task to be preempted due to an
> - obtain and release of the object allocator mutex.
> +.. rubric:: NOTES:
>
> - The calling task does not have to be the task that created the partition.
> - Any local task that knows the partition id can delete the partition.
> +This directive may cause the calling task to be preempted due to an obtain and
> +release of the object allocator mutex.
>
> - When a global partition is deleted, the partition id must be transmitted to
> - every node in the system for deletion from the local copy of the global
> - object table.
> +The calling task does not have to be the task that created the partition. Any
> +local task that knows the partition identifier can delete the partition.
>
> - The partition must reside on the local node, even if the partition was
> - created with the ``RTEMS_GLOBAL`` option.
> +When a global partition is deleted, the partition identifier must be
> +transmitted to every node in the system for deletion from the local copy of the
> +global object table.
> +
> +The partition must reside on the local node, even if the partition was created
> +with the :c:macro:`RTEMS_GLOBAL` attribute.
> +
> +.. Generated from spec:/rtems/part/if/get-buffer
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
>
> +.. index:: rtems_partition_get_buffer()
> .. index:: get buffer from partition
> .. index:: obtain buffer from partition
> -.. index:: rtems_partition_get_buffer
>
> -.. _rtems_partition_get_buffer:
> +.. _InterfaceRtemsPartitionGetBuffer:
> +
> +rtems_partition_get_buffer()
> +----------------------------
> +
> +Tries to get a buffer from the partition.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> + This parameter is the partition identifier.
> +
> +``buffer``
> + This parameter is the pointer to a buffer pointer variable. The pointer to
> + the allocated buffer will be stored in this variable, in case of a
> + successful operation.
> +
> +.. rubric:: DESCRIPTION:
>
> -PARTITION_GET_BUFFER - Get buffer from a partition
> ---------------------------------------------------
> +This directive allows a buffer to be obtained from the partition specified in
> +the ``id`` parameter. The address of the allocated buffer is returned through
> +the ``buffer`` parameter.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: RETURN VALUES:
>
> - rtems_status_code rtems_partition_get_buffer(
> - rtems_id id,
> - void **buffer
> - );
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no partition with the specified identifier.
>
> - * - ``RTEMS_SUCCESSFUL``
> - - buffer obtained successfully
> - * - ``RTEMS_INVALID_ADDRESS``
> - - ``buffer`` is NULL
> - * - ``RTEMS_INVALID_ID``
> - - invalid partition id
> - * - ``RTEMS_UNSATISFIED``
> - - all buffers are allocated
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The ``buffer`` parameter was `NULL
> + <https://en.cppreference.com/w/c/types/NULL>`_.
>
> -DESCRIPTION:
> - This directive allows a buffer to be obtained from the partition specified
> - in id. The address of the allocated buffer is returned in buffer.
> +:c:macro:`RTEMS_UNSATISFIED`
> + There was no free buffer available to allocate and return.
>
> -NOTES:
> - This directive will not cause the running task to be preempted.
> +.. rubric:: NOTES:
>
> - All buffers begin on a four byte boundary.
> +This directive will not cause the running task to be preempted.
>
> - A task cannot wait on a buffer to become available.
> +The buffer start alignment is determined by the memory area and buffer size
> +used to create the partition.
>
> - Getting a buffer from a global partition which does not reside on the local
> - node will generate a request telling the remote node to allocate a buffer
> - from the specified partition.
> +A task cannot wait on a buffer to become available.
> +
> +Getting a buffer from a global partition which does not reside on the local
> +node will generate a request telling the remote node to allocate a buffer from
> +the partition.
> +
> +.. Generated from spec:/rtems/part/if/return-buffer
>
> .. raw:: latex
>
> - \clearpage
> + \clearpage
> +
> +.. index:: rtems_partition_return_buffer()
> +.. index:: return buffer to partition
> +
> +.. _InterfaceRtemsPartitionReturnBuffer:
> +
> +rtems_partition_return_buffer()
> +-------------------------------
> +
> +Returns the buffer to the partition.
> +
> +.. rubric:: CALLING SEQUENCE:
> +
> +.. code-block:: c
> +
> + rtems_status_code rtems_partition_return_buffer( rtems_id id, void *buffer );
> +
> +.. rubric:: PARAMETERS:
> +
> +``id``
> + This parameter is the partition identifier.
>
> -.. index:: return buffer to partitition
> -.. index:: rtems_partition_return_buffer
> +``buffer``
> + This parameter is the pointer to the buffer to return.
>
> -.. _rtems_partition_return_buffer:
> +.. rubric:: DESCRIPTION:
>
> -PARTITION_RETURN_BUFFER - Return buffer to a partition
> -------------------------------------------------------
> +This directive returns the buffer specified by ``buffer`` to the partition
> +specified by ``id``.
>
> -CALLING SEQUENCE:
> - .. code-block:: c
> +.. rubric:: RETURN VALUES:
>
> - rtems_status_code rtems_partition_return_buffer(
> - rtems_id id,
> - void *buffer
> - );
> +:c:macro:`RTEMS_SUCCESSFUL`
> + The requested operation was successful.
>
> -DIRECTIVE STATUS CODES:
> - .. list-table::
> - :class: rtems-table
> +:c:macro:`RTEMS_INVALID_ID`
> + There was no partition with the specified identifier.
>
> - * - ``RTEMS_SUCCESSFUL``
> - - buffer returned successfully
> - * - ``RTEMS_INVALID_ADDRESS``
> - - ``buffer`` is NULL
> - * - ``RTEMS_INVALID_ID``
> - - invalid partition id
> - * - ``RTEMS_INVALID_ADDRESS``
> - - buffer address not in partition
> +:c:macro:`RTEMS_INVALID_ADDRESS`
> + The buffer referenced by ``buffer`` was not in the partition.
>
> -DESCRIPTION:
> - This directive returns the buffer specified by buffer to the partition
> - specified by id.
> +.. rubric:: NOTES:
>
> -NOTES:
> - This directive will not cause the running task to be preempted.
> +This directive will not cause the running task to be preempted.
>
> - Returning a buffer to a global partition which does not reside on the local
> - node will generate a request telling the remote node to return the buffer
> - to the specified partition.
> +Returning a buffer to a global partition which does not reside on the local
> +node will generate a request telling the remote node to return the buffer to
> +the partition.
>
> - Returning a buffer multiple times is an error. It will corrupt the
> - internal state of the partition.
> +Returning a buffer multiple times is an error. It will corrupt the internal
> +state of the partition.
> diff --git a/c-user/partition/introduction.rst b/c-user/partition/introduction.rst
> index dd51d30..4cfa9ac 100644
> --- a/c-user/partition/introduction.rst
> +++ b/c-user/partition/introduction.rst
> @@ -1,19 +1,46 @@
> .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
> .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
>
> +.. Do not manually edit this file. It 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 to an RTEMS mailing list or raise a bug report:
> +..
> +.. https://docs.rtems.org/branches/master/user/support/bugs.html
> +..
> +.. For information on updating and regenerating please refer to:
> +..
> +.. https://docs.rtems.org/branches/master/eng/req/howto.html
> +
> +.. Generated from spec:/rtems/part/if/group
> +
> +.. _PartitionManagerIntroduction:
> +
> Introduction
> ============
>
> -The partition manager provides facilities to dynamically allocate memory in
> -fixed-size units. The directives provided by the partition manager are:
> +.. The following list was generated from:
> +.. spec:/rtems/part/if/create
> +.. spec:/rtems/part/if/ident
> +.. spec:/rtems/part/if/delete
> +.. spec:/rtems/part/if/get-buffer
> +.. spec:/rtems/part/if/return-buffer
> +
> +The Partition Manager provides facilities to dynamically allocate memory in
> +fixed-size units. The directives provided by the Partition Manager are:
>
> -- :ref:`rtems_partition_create`
> +* :ref:`InterfaceRtemsPartitionCreate` - Creates a partition.
>
> -- :ref:`rtems_partition_ident`
> +* :ref:`InterfaceRtemsPartitionIdent` - Identifies a partition by the object
> + name.
>
> -- :ref:`rtems_partition_delete`
> +* :ref:`InterfaceRtemsPartitionDelete` - Deletes the partition.
>
> -- :ref:`rtems_partition_get_buffer`
> +* :ref:`InterfaceRtemsPartitionGetBuffer` - Tries to get a buffer from the
> + partition.
>
> -- :ref:`rtems_partition_return_buffer`
> +* :ref:`InterfaceRtemsPartitionReturnBuffer` - Returns the buffer to the
> + partition.
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list