[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