[PATCH] c-user: Clarify partition manager documentation

Gedare Bloom gedare at rtems.org
Tue Feb 2 16:10:15 UTC 2021


On Tue, Feb 2, 2021 at 7:13 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> Unify the wording across similar directives of other managers.  Add
> "CONSTRAINTS" section.
>
> Update #3993.
> ---
>  c-user/partition/directives.rst   | 167 ++++++++++++++++++++++--------
>  c-user/partition/introduction.rst |   2 +-
>  2 files changed, 124 insertions(+), 45 deletions(-)
>
> diff --git a/c-user/partition/directives.rst
> b/c-user/partition/directives.rst
> index ae3e921..bc8f2c8 100644
> --- a/c-user/partition/directives.rst
> +++ b/c-user/partition/directives.rst
> @@ -1,6 +1,6 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de
> )
> +.. 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
> @@ -59,7 +59,7 @@ Creates a partition.
>  .. rubric:: PARAMETERS:
>
>  ``name``
> -    This parameter is the name of the partition.
> +    This parameter is the object name of the partition.
>
>  ``starting_address``
>      This parameter is the starting address of the buffer area used by the
> @@ -77,29 +77,36 @@ Creates a 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.
> +    identifier of the created partition 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 object identifier is returned in ``id``.  This identifier is
> used
> -to access the partition with other partition related directives.
> +The partition as the user-defined object name specified in ``name``.  The
>
The "as" is strange although it may be correct if you mean "Use the
partition as" but since the language parsing is awkward. Or did you mean
"has"?


> +assigned object identifier is returned in ``id``.  This 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
> +*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 partition has a local or global **scope** in a multiprocessing network
> +(this attribute does not refer to SMP systems).  The scope is selected by
> the

+mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`
> +attributes.
> +
> +* 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
> +* 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.
>
> @@ -109,7 +116,7 @@ network (this attribute does not refer to SMP systems).
>      The requested operation was successful.
>
>  :c:macro:`RTEMS_INVALID_NAME`
> -    The partition name was invalid.
> +    The ``name`` parameter was invalid.
>
>  :c:macro:`RTEMS_INVALID_ADDRESS`
>      The ``id`` parameter was `NULL
> @@ -135,14 +142,18 @@ network (this attribute does not refer to SMP
> systems).
>      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.
> +    There was no inactive object available to create a partition.  The
> number
> +    of partitions available to the application is configured through the
> +    :ref:`CONFIGURE_MAXIMUM_PARTITIONS` application configuration option.
>
> -.. rubric:: NOTES:
> +:c:macro:`RTEMS_TOO_MANY`
> +    In multiprocessing configurations, there was no inactive global object
> +    available to create a global semaphore.  The number of global objects
> +    available to the application is configured through the
> +    :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration
> +    option.
>
> -This directive may cause the calling task to be preempted due to an
> obtain and
> -release of the object allocator mutex.
> +.. rubric:: NOTES:
>
>  The partition buffer area specified by the ``starting_address`` must be
>  properly aligned.  It must be possible to directly store target
> architecture
> @@ -169,9 +180,27 @@ 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.
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* The directive may obtain and release the object allocator mutex.  This
> may
> +  cause the calling task to be preempted.
> +
> +* The directive may be called from within device driver initialization
> context.
> +
> +* The directive may be called from within task context.
> +
> +* The number of partitions available to the application is configured
> through
> +  the :ref:`CONFIGURE_MAXIMUM_PARTITIONS` 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.
> +
> +* The number of global objects available to the application is configured
> +  through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
> +  configuration option.
>
>
I like this, but it made me also think whether it makes sense and would be
possible to provide a separate section for Configuration notes/constraints?
Some constraints are 'hard'/system constraints, but others are
'soft'/application (configuration) constraints. Maybe lumping them together
doesn't matter too much. This is already a great improvement over the
previous way.


>  .. Generated from spec:/rtems/part/if/ident
>
> @@ -253,12 +282,11 @@ The node to search is specified in ``node``.  It
> shall be
>  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.
> +The objects are searched from lowest to the highest index.  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 from lowest to the
> highest
> +node number.
>
>  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.
> @@ -266,6 +294,17 @@ 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.
>
> +The partition identifier is used with other partition related directives
> to
> +access the partition.
> +
> +.. 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/part/if/delete
>
>  .. raw:: latex
> @@ -295,8 +334,7 @@ Deletes the partition.
>
>  .. rubric:: DESCRIPTION:
>
> -This directive deletes the partition specified by the ``id`` parameter.
> The
> -partition cannot be deleted if any of its buffers are still allocated.
> +This directive deletes the partition specified by ``id``.
>
>  .. rubric:: RETURN VALUES:
>
> @@ -314,14 +352,10 @@ partition cannot be deleted if any of its buffers
> are still allocated.
>
>  .. 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 cannot be deleted if any of its buffers are still allocated.
>
>  The :term:`PTCB` for the deleted partition is reclaimed by RTEMS.
>
> -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.
> -
>  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.
> @@ -329,6 +363,23 @@ global object table.
>  The partition must reside on the local node, even if the partition was
> created
>  with the :c:macro:`RTEMS_GLOBAL` attribute.
>
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* 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.
> +
> +* The directive may be called from within device driver initialization
> context.
> +
> +* The directive may be called from within task context.
> +
> +* 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/part/if/get-buffer
>
>  .. raw:: latex
> @@ -364,9 +415,9 @@ Tries to get a buffer from the partition.
>
>  .. rubric:: DESCRIPTION:
>
> -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.
> +This directive allows a buffer to be obtained from the partition
> specified by
> +``id``.  The address of the allocated buffer is returned through the
> ``buffer``
> +parameter.
>
>  .. rubric:: RETURN VALUES:
>
> @@ -385,8 +436,6 @@ the ``buffer`` parameter.
>
>  .. rubric:: NOTES:
>
> -This directive will not cause the running task to be preempted.
> -
>  The buffer start alignment is determined by the memory area and buffer
> size
>  used to create the partition.
>
> @@ -396,6 +445,22 @@ 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.
>
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* When the directive operates on a local object, the directive may be
> called
> +  from within interrupt context.
> +
> +* The directive may be called from within task context.
> +
> +* When the directive operates on a local object, the directive will not
> cause
> +  the calling task to be preempted.
> +
> +* When the directive operates on a remote object, the directive sends a
> message
> +  to the remote node and waits for a reply.  This will preempt the calling
> +  task.
> +
>  .. Generated from spec:/rtems/part/if/return-buffer
>
>  .. raw:: latex
> @@ -444,11 +509,25 @@ specified by ``id``.
>
>  .. rubric:: NOTES:
>
> -This directive will not cause the running task to be preempted.
> +Returning a buffer multiple times is an error.  It will corrupt the
> internal
> +state of the 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.
> +.. rubric:: CONSTRAINTS:
> +
> +The following constraints apply to this directive:
> +
> +* When the directive operates on a local object, the directive may be
> called
> +  from within interrupt context.
> +
> +* The directive may be called from within task context.
> +
> +* When the directive operates on a local object, the directive will not
> cause
> +  the calling task to be preempted.
> +
> +* When the directive operates on a remote object, the directive sends a
> message
> +  to the remote node and waits for a reply.  This will preempt the calling
> +  task.
> diff --git a/c-user/partition/introduction.rst
> b/c-user/partition/introduction.rst
> index 8cc33e1..2798658 100644
> --- a/c-user/partition/introduction.rst
> +++ b/c-user/partition/introduction.rst
> @@ -1,6 +1,6 @@
>  .. SPDX-License-Identifier: CC-BY-SA-4.0
>
> -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de
> )
> +.. 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
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20210202/c4d8b48d/attachment-0001.html>


More information about the devel mailing list