On Tue, Feb 2, 2021 at 7:13 AM Sebastian Huber < sebastian.hu...@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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
