mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-15 02:16:41 +08:00
c-user: Clarify partition manager documentation
Unify the wording across similar directives of other managers. Add "CONSTRAINTS" section. Update #3993.
This commit is contained in:
Sebastian Huber
parent
95e2f933cb
commit
66c9808db0
@ -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 has 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.
|
||||
*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 can have **local** or **global** scope in a multiprocessing
|
||||
network (this attribute does not refer to SMP systems).
|
||||
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
|
||||
* 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,15 +142,19 @@ 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.
|
||||
|
||||
: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:
|
||||
|
||||
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
|
||||
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
|
||||
@ -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 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
|
||||
|
||||
@ -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 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
|
||||
|
||||
.. 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,21 @@ specified by ``id``.
|
||||
|
||||
.. 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
|
||||
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.
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user