rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-15 14:27:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

c-user: Clarify partition manager documentation

Browse Source 
Unify the wording across similar directives of other managers.  Add
"CONSTRAINTS" section.

Update #3993.
This commit is contained in:
Sebastian Huber 2021-01-15 06:37:22 +01:00
parent 95e2f933cb
commit 66c9808db0
2 changed files with 121 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

165
c-user/partition/directives.rst
View File

@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0 .. 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) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
.. This file is part of the RTEMS quality process and was automatically .. This file is part of the RTEMS quality process and was automatically
@ -59,7 +59,7 @@ Creates a partition.
.. rubric:: PARAMETERS: .. rubric:: PARAMETERS:
``name`` ``name``
This parameter is the name of the partition. This parameter is the object name of the partition.
``starting_address`` ``starting_address``
This parameter is the starting address of the buffer area used by the This parameter is the starting address of the buffer area used by the
@ -77,29 +77,36 @@ Creates a partition.
``id`` ``id``
This parameter is the pointer to an object identifier variable. The This parameter is the pointer to an object identifier variable. The
identifier of the created partition object will be stored in this variable, identifier of the created partition will be stored in this variable, in
in case of a successful operation. case of a successful operation.
.. rubric:: DESCRIPTION: .. rubric:: DESCRIPTION:
This directive creates a partition of fixed size buffers from a physically This directive creates a partition of fixed size buffers from a physically
contiguous memory space which starts at ``starting_address`` and is ``length`` 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. 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 The partition has the user-defined object name specified in ``name``. The
to access the partition with other partition related directives. 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 The **attribute set** specified in ``attribute_set`` is built through a
*bitwise or* of the attribute constants described below. Attributes not *bitwise or* of the attribute constants described below. Not all combinations
mentioned below are not evaluated by this directive and have no effect. 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 can have **local** or **global** scope in a multiprocessing The partition has a local or global **scope** in a multiprocessing network
network (this attribute does not refer to SMP systems). (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 * 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 :c:macro:`RTEMS_LOCAL` attribute. A local partition can be only used by the
node which created it. 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. 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. 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. The requested operation was successful.
:c:macro:`RTEMS_INVALID_NAME` :c:macro:`RTEMS_INVALID_NAME`
The partition name was invalid. The ``name`` parameter was invalid.
:c:macro:`RTEMS_INVALID_ADDRESS` :c:macro:`RTEMS_INVALID_ADDRESS`
The ``id`` parameter was `NULL The ``id`` parameter was `NULL
@ -135,15 +142,19 @@ network (this attribute does not refer to SMP systems).
The ``starting_address`` parameter was not on a pointer size boundary. The ``starting_address`` parameter was not on a pointer size boundary.
:c:macro:`RTEMS_TOO_MANY` :c:macro:`RTEMS_TOO_MANY`
There was no inactive object available to create a new partition. The There was no inactive object available to create a partition. The number
number of partitions available to the application is configured through the of partitions available to the application is configured through the
:ref:`CONFIGURE_MAXIMUM_PARTITIONS` configuration option. :ref:`CONFIGURE_MAXIMUM_PARTITIONS` application configuration option.
: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.
.. rubric:: NOTES: .. 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 buffer area specified by the ``starting_address`` must be The partition buffer area specified by the ``starting_address`` must be
properly aligned. It must be possible to directly store target architecture properly aligned. It must be possible to directly store target architecture
pointers and also the user data. For example, if the user data contains some pointers and also the user data. For example, if the user data contains some
@ -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 transmitted to every node in the system for insertion in the local copy of the
global object table. global object table.
The total number of global objects, including partitions, is limited by the .. rubric:: CONSTRAINTS:
value of the :ref:`CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS` application
configuration option. The following constraints apply to this directive:
* The directive may be called from within device driver initialization context.
* The directive may be called from within task context.
* The directive may obtain and release the object allocator mutex. This may
cause the calling task to be preempted.
* 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 .. 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 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 the first partition with that name in the search order. However, this
partition identifier is not guaranteed to correspond to the desired partition. 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 The objects are searched from lowest to the highest index. If ``node`` is
local node being searched first. All other nodes are searched with the lowest :c:macro:`RTEMS_SEARCH_ALL_NODES`, all nodes are searched with the local node
numbered node searched first. 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 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. 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 This directive does not generate activity on remote nodes. It accesses only
the local copy of the global object table. 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 .. Generated from spec:/rtems/part/if/delete
.. raw:: latex .. raw:: latex
@ -295,8 +334,7 @@ Deletes the partition.
.. rubric:: DESCRIPTION: .. rubric:: DESCRIPTION:
This directive deletes the partition specified by the ``id`` parameter. The This directive deletes the partition specified by ``id``.
partition cannot be deleted if any of its buffers are still allocated.
.. rubric:: RETURN VALUES: .. rubric:: RETURN VALUES:
@ -314,14 +352,10 @@ partition cannot be deleted if any of its buffers are still allocated.
.. rubric:: NOTES: .. rubric:: NOTES:
This directive may cause the calling task to be preempted due to an obtain and The partition cannot be deleted if any of its buffers are still allocated.
release of the object allocator mutex.
The :term:`PTCB` for the deleted partition is reclaimed by RTEMS. 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 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 transmitted to every node in the system for deletion from the local copy of the
global object table. global object table.
@ -329,6 +363,23 @@ global object table.
The partition must reside on the local node, even if the partition was created The partition must reside on the local node, even if the partition was created
with the :c:macro:`RTEMS_GLOBAL` attribute. with the :c:macro:`RTEMS_GLOBAL` attribute.
.. rubric:: CONSTRAINTS:
The following constraints apply to this directive:
* The directive may be called from within device driver initialization context.
* The directive may be called from within task context.
* 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.
* 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 .. Generated from spec:/rtems/part/if/get-buffer
.. raw:: latex .. raw:: latex
@ -364,9 +415,9 @@ Tries to get a buffer from the partition.
.. rubric:: DESCRIPTION: .. rubric:: DESCRIPTION:
This directive allows a buffer to be obtained from the partition specified in This directive allows a buffer to be obtained from the partition specified by
the ``id`` parameter. The address of the allocated buffer is returned through ``id``. The address of the allocated buffer is returned through the ``buffer``
the ``buffer`` parameter. parameter.
.. rubric:: RETURN VALUES: .. rubric:: RETURN VALUES:
@ -385,8 +436,6 @@ the ``buffer`` parameter.
.. rubric:: NOTES: .. 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 The buffer start alignment is determined by the memory area and buffer size
used to create the partition. 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 node will generate a request telling the remote node to allocate a buffer from
the partition. 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 .. Generated from spec:/rtems/part/if/return-buffer
.. raw:: latex .. raw:: latex
@ -444,11 +509,21 @@ specified by ``id``.
.. rubric:: NOTES: .. rubric:: NOTES:
This directive will not cause the running task to be preempted.
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 Returning a buffer multiple times is an error. It will corrupt the internal
state of the partition. 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.

2
c-user/partition/introduction.rst
View File

@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0 .. 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) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
.. This file is part of the RTEMS quality process and was automatically .. This file is part of the RTEMS quality process and was automatically