[PATCH] c-user: Clarify partition manager documentation
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Feb 2 14:13:09 UTC 2021
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
+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.
.. 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
More information about the devel
mailing list