<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Feb 2, 2021 at 7:13 AM Sebastian Huber <<a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-brains.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Unify the wording across similar directives of other managers. Add<br>
"CONSTRAINTS" section.<br>
<br>
Update #3993.<br>
---<br>
c-user/partition/directives.rst | 167 ++++++++++++++++++++++--------<br>
c-user/partition/introduction.rst | 2 +-<br>
2 files changed, 124 insertions(+), 45 deletions(-)<br>
<br>
diff --git a/c-user/partition/directives.rst b/c-user/partition/directives.rst<br>
index ae3e921..bc8f2c8 100644<br>
--- a/c-user/partition/directives.rst<br>
+++ b/c-user/partition/directives.rst<br>
@@ -1,6 +1,6 @@<br>
.. SPDX-License-Identifier: CC-BY-SA-4.0<br>
<br>
-.. Copyright (C) 2020 embedded brains GmbH (<a href="http://www.embedded-brains.de" rel="noreferrer" target="_blank">http://www.embedded-brains.de</a>)<br>
+.. Copyright (C) 2020, 2021 embedded brains GmbH (<a href="http://www.embedded-brains.de" rel="noreferrer" target="_blank">http://www.embedded-brains.de</a>)<br>
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)<br>
<br>
.. This file is part of the RTEMS quality process and was automatically<br>
@@ -59,7 +59,7 @@ Creates a partition.<br>
.. rubric:: PARAMETERS:<br>
<br>
``name``<br>
- This parameter is the name of the partition.<br>
+ This parameter is the object name of the partition.<br>
<br>
``starting_address``<br>
This parameter is the starting address of the buffer area used by the<br>
@@ -77,29 +77,36 @@ Creates a partition.<br>
<br>
``id``<br>
This parameter is the pointer to an object identifier variable. The<br>
- identifier of the created partition object will be stored in this variable,<br>
- in case of a successful operation.<br>
+ identifier of the created partition will be stored in this variable, in<br>
+ case of a successful operation.<br>
<br>
.. rubric:: DESCRIPTION:<br>
<br>
This directive creates a partition of fixed size buffers from a physically<br>
contiguous memory space which starts at ``starting_address`` and is ``length``<br>
bytes in size. Each allocated buffer is to be of ``buffer_size`` in bytes.<br>
-The assigned object identifier is returned in ``id``. This identifier is used<br>
-to access the partition with other partition related directives.<br>
+The partition as the user-defined object name specified in ``name``. The<br></blockquote><div>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"? </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+assigned object identifier is returned in ``id``. This identifier is used to<br>
+access the partition with other partition related directives.<br>
<br>
The **attribute set** specified in ``attribute_set`` is built through a<br>
-*bitwise or* of the attribute constants described below. Attributes not<br>
-mentioned below are not evaluated by this directive and have no effect.<br>
-<br>
-The partition can have **local** or **global** scope in a multiprocessing<br>
-network (this attribute does not refer to SMP systems).<br>
-<br>
-* A **local** scope is the default and can be emphasized through the use of the<br>
+*bitwise or* of the attribute constants described below. Not all combinations<br>
+of attributes are allowed. Some attributes are mutually exclusive. If<br>
+mutually exclusive attributes are combined, the behaviour is undefined.<br>
+Attributes not mentioned below are not evaluated by this directive and have no<br>
+effect. Default attributes can be selected by using the<br>
+:c:macro:`RTEMS_DEFAULT_ATTRIBUTES` constant.<br>
+<br>
+The partition has a local or global **scope** in a multiprocessing network<br>
+(this attribute does not refer to SMP systems). The scope is selected by the</blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
+mutually exclusive :c:macro:`RTEMS_LOCAL` and :c:macro:`RTEMS_GLOBAL`<br>
+attributes.<br>
+<br>
+* A **local scope** is the default and can be emphasized through the use of the<br>
:c:macro:`RTEMS_LOCAL` attribute. A local partition can be only used by the<br>
node which created it.<br>
<br>
-* A **global** scope is established if the :c:macro:`RTEMS_GLOBAL` attribute is<br>
+* A **global scope** is established if the :c:macro:`RTEMS_GLOBAL` attribute is<br>
set. The memory space used for the partition must reside in shared memory.<br>
Setting the global attribute in a single node system has no effect.<br>
<br>
@@ -109,7 +116,7 @@ network (this attribute does not refer to SMP systems).<br>
The requested operation was successful.<br>
<br>
:c:macro:`RTEMS_INVALID_NAME`<br>
- The partition name was invalid.<br>
+ The ``name`` parameter was invalid.<br>
<br>
:c:macro:`RTEMS_INVALID_ADDRESS`<br>
The ``id`` parameter was `NULL<br>
@@ -135,14 +142,18 @@ network (this attribute does not refer to SMP systems).<br>
The ``starting_address`` parameter was not on a pointer size boundary.<br>
<br>
:c:macro:`RTEMS_TOO_MANY`<br>
- There was no inactive object available to create a new partition. The<br>
- number of partitions available to the application is configured through the<br>
- :ref:`CONFIGURE_MAXIMUM_PARTITIONS` configuration option.<br>
+ There was no inactive object available to create a partition. The number<br>
+ of partitions available to the application is configured through the<br>
+ :ref:`CONFIGURE_MAXIMUM_PARTITIONS` application configuration option.<br>
<br>
-.. rubric:: NOTES:<br>
+:c:macro:`RTEMS_TOO_MANY`<br>
+ In multiprocessing configurations, there was no inactive global object<br>
+ available to create a global semaphore. The number of global objects<br>
+ available to the application is configured through the<br>
+ :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application configuration<br>
+ option.<br>
<br>
-This directive may cause the calling task to be preempted due to an obtain and<br>
-release of the object allocator mutex.<br>
+.. rubric:: NOTES:<br>
<br>
The partition buffer area specified by the ``starting_address`` must be<br>
properly aligned. It must be possible to directly store target architecture<br>
@@ -169,9 +180,27 @@ When a global partition is created, the partition's name and identifier must be<br>
transmitted to every node in the system for insertion in the local copy of the<br>
global object table.<br>
<br>
-The total number of global objects, including partitions, is limited by the<br>
-value of the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application<br>
-configuration option.<br>
+.. rubric:: CONSTRAINTS:<br>
+<br>
+The following constraints apply to this directive:<br>
+<br>
+* The directive may obtain and release the object allocator mutex. This may<br>
+ cause the calling task to be preempted.<br>
+<br>
+* The directive may be called from within device driver initialization context.<br>
+<br>
+* The directive may be called from within task context.<br>
+<br>
+* The number of partitions available to the application is configured through<br>
+ the :ref:`CONFIGURE_MAXIMUM_PARTITIONS` application configuration option.<br>
+<br>
+* Where the object class corresponding to the directive is configured to use<br>
+ unlimited objects, the directive may allocate memory from the RTEMS<br>
+ Workspace.<br>
+<br>
+* The number of global objects available to the application is configured<br>
+ through the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application<br>
+ configuration option.<br>
<br></blockquote><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
.. Generated from spec:/rtems/part/if/ident<br>
<br>
@@ -253,12 +282,11 @@ The node to search is specified in ``node``. It shall be<br>
If the partition name is not unique, then the partition identifier will match<br>
the first partition with that name in the search order. However, this<br>
partition identifier is not guaranteed to correspond to the desired partition.<br>
-The partition identifier is used with other partition related directives to<br>
-access the partition.<br>
<br>
-If node is :c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the<br>
-local node being searched first. All other nodes are searched with the lowest<br>
-numbered node searched first.<br>
+The objects are searched from lowest to the highest index. If ``node`` is<br>
+:c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node<br>
+being searched first. All other nodes are searched from lowest to the highest<br>
+node number.<br>
<br>
If node is a valid node number which does not represent the local node, then<br>
only the partitions exported by the designated node are searched.<br>
@@ -266,6 +294,17 @@ only the partitions exported by the designated node are searched.<br>
This directive does not generate activity on remote nodes. It accesses only<br>
the local copy of the global object table.<br>
<br>
+The partition identifier is used with other partition related directives to<br>
+access the partition.<br>
+<br>
+.. rubric:: CONSTRAINTS:<br>
+<br>
+The following constraints apply to this directive:<br>
+<br>
+* The directive may be called from within any runtime context.<br>
+<br>
+* The directive will not cause the calling task to be preempted.<br>
+<br>
.. Generated from spec:/rtems/part/if/delete<br>
<br>
.. raw:: latex<br>
@@ -295,8 +334,7 @@ Deletes the partition.<br>
<br>
.. rubric:: DESCRIPTION:<br>
<br>
-This directive deletes the partition specified by the ``id`` parameter. The<br>
-partition cannot be deleted if any of its buffers are still allocated.<br>
+This directive deletes the partition specified by ``id``.<br>
<br>
.. rubric:: RETURN VALUES:<br>
<br>
@@ -314,14 +352,10 @@ partition cannot be deleted if any of its buffers are still allocated.<br>
<br>
.. rubric:: NOTES:<br>
<br>
-This directive may cause the calling task to be preempted due to an obtain and<br>
-release of the object allocator mutex.<br>
+The partition cannot be deleted if any of its buffers are still allocated.<br>
<br>
The :term:`PTCB` for the deleted partition is reclaimed by RTEMS.<br>
<br>
-The calling task does not have to be the task that created the partition. Any<br>
-local task that knows the partition identifier can delete the partition.<br>
-<br>
When a global partition is deleted, the partition identifier must be<br>
transmitted to every node in the system for deletion from the local copy of the<br>
global object table.<br>
@@ -329,6 +363,23 @@ global object table.<br>
The partition must reside on the local node, even if the partition was created<br>
with the :c:macro:`RTEMS_GLOBAL` attribute.<br>
<br>
+.. rubric:: CONSTRAINTS:<br>
+<br>
+The following constraints apply to this directive:<br>
+<br>
+* The directive may obtain and release the object allocator mutex. This may<br>
+ cause the calling task to be preempted.<br>
+<br>
+* The calling task does not have to be the task that created the object. Any<br>
+ local task that knows the object identifier can delete the object.<br>
+<br>
+* The directive may be called from within device driver initialization context.<br>
+<br>
+* The directive may be called from within task context.<br>
+<br>
+* Where the object class corresponding to the directive is configured to use<br>
+ unlimited objects, the directive may free memory to the RTEMS Workspace.<br>
+<br>
.. Generated from spec:/rtems/part/if/get-buffer<br>
<br>
.. raw:: latex<br>
@@ -364,9 +415,9 @@ Tries to get a buffer from the partition.<br>
<br>
.. rubric:: DESCRIPTION:<br>
<br>
-This directive allows a buffer to be obtained from the partition specified in<br>
-the ``id`` parameter. The address of the allocated buffer is returned through<br>
-the ``buffer`` parameter.<br>
+This directive allows a buffer to be obtained from the partition specified by<br>
+``id``. The address of the allocated buffer is returned through the ``buffer``<br>
+parameter.<br>
<br>
.. rubric:: RETURN VALUES:<br>
<br>
@@ -385,8 +436,6 @@ the ``buffer`` parameter.<br>
<br>
.. rubric:: NOTES:<br>
<br>
-This directive will not cause the running task to be preempted.<br>
-<br>
The buffer start alignment is determined by the memory area and buffer size<br>
used to create the partition.<br>
<br>
@@ -396,6 +445,22 @@ Getting a buffer from a global partition which does not reside on the local<br>
node will generate a request telling the remote node to allocate a buffer from<br>
the partition.<br>
<br>
+.. rubric:: CONSTRAINTS:<br>
+<br>
+The following constraints apply to this directive:<br>
+<br>
+* When the directive operates on a local object, the directive may be called<br>
+ from within interrupt context.<br>
+<br>
+* The directive may be called from within task context.<br>
+<br>
+* When the directive operates on a local object, the directive will not cause<br>
+ the calling task to be preempted.<br>
+<br>
+* When the directive operates on a remote object, the directive sends a message<br>
+ to the remote node and waits for a reply. This will preempt the calling<br>
+ task.<br>
+<br>
.. Generated from spec:/rtems/part/if/return-buffer<br>
<br>
.. raw:: latex<br>
@@ -444,11 +509,25 @@ specified by ``id``.<br>
<br>
.. rubric:: NOTES:<br>
<br>
-This directive will not cause the running task to be preempted.<br>
+Returning a buffer multiple times is an error. It will corrupt the internal<br>
+state of the partition.<br>
<br>
Returning a buffer to a global partition which does not reside on the local<br>
node will generate a request telling the remote node to return the buffer to<br>
the partition.<br>
<br>
-Returning a buffer multiple times is an error. It will corrupt the internal<br>
-state of the partition.<br>
+.. rubric:: CONSTRAINTS:<br>
+<br>
+The following constraints apply to this directive:<br>
+<br>
+* When the directive operates on a local object, the directive may be called<br>
+ from within interrupt context.<br>
+<br>
+* The directive may be called from within task context.<br>
+<br>
+* When the directive operates on a local object, the directive will not cause<br>
+ the calling task to be preempted.<br>
+<br>
+* When the directive operates on a remote object, the directive sends a message<br>
+ to the remote node and waits for a reply. This will preempt the calling<br>
+ task.<br>
diff --git a/c-user/partition/introduction.rst b/c-user/partition/introduction.rst<br>
index 8cc33e1..2798658 100644<br>
--- a/c-user/partition/introduction.rst<br>
+++ b/c-user/partition/introduction.rst<br>
@@ -1,6 +1,6 @@<br>
.. SPDX-License-Identifier: CC-BY-SA-4.0<br>
<br>
-.. Copyright (C) 2020 embedded brains GmbH (<a href="http://www.embedded-brains.de" rel="noreferrer" target="_blank">http://www.embedded-brains.de</a>)<br>
+.. Copyright (C) 2020, 2021 embedded brains GmbH (<a href="http://www.embedded-brains.de" rel="noreferrer" target="_blank">http://www.embedded-brains.de</a>)<br>
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)<br>
<br>
.. This file is part of the RTEMS quality process and was automatically<br>
-- <br>
2.26.2<br>
<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div>