diff options
Diffstat (limited to 'c_user/partition_manager.rst')
| -rw-r--r-- | c_user/partition_manager.rst | 429 |
1 files changed, 231 insertions, 198 deletions
diff --git a/c_user/partition_manager.rst b/c_user/partition_manager.rst index 8ea18d3..0e08ab8 100644 --- a/c_user/partition_manager.rst +++ b/c_user/partition_manager.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Partition Manager ################# @@ -6,19 +10,18 @@ Partition Manager Introduction ============ -The partition manager provides facilities to -dynamically allocate memory in fixed-size units. The directives -provided by the partition manager are: +The partition manager provides facilities to dynamically allocate memory in +fixed-size units. The directives provided by the partition manager are: -- ``rtems_partition_create`` - Create a partition +- rtems_partition_create_ - Create a partition -- ``rtems_partition_ident`` - Get ID of a partition +- rtems_partition_ident_ - Get ID of a partition -- ``rtems_partition_delete`` - Delete a partition +- rtems_partition_delete_ - Delete a partition -- ``rtems_partition_get_buffer`` - Get buffer from a partition +- rtems_partition_get_buffer_ - Get buffer from a partition -- ``rtems_partition_return_buffer`` - Return buffer to a partition +- rtems_partition_return_buffer_ - Return buffer to a partition Background ========== @@ -27,41 +30,43 @@ Partition Manager Definitions ----------------------------- .. index:: partition, definition -A partition is a physically contiguous memory area -divided into fixed-size buffers that can be dynamically -allocated and deallocated... index:: buffers, definition +A partition is a physically contiguous memory area divided into fixed-size +buffers that can be dynamically allocated and deallocated. -Partitions are managed and maintained as a list of -buffers. Buffers are obtained from the front of the partition's -free buffer chain and returned to the rear of the same chain. -When a buffer is on the free buffer chain, RTEMS uses two -pointers of memory from each buffer as the free buffer chain. -When a buffer is allocated, the entire buffer is available for application use. -Therefore, modifying memory that is outside of an allocated -buffer could destroy the free buffer chain or the contents of an -adjacent allocated buffer. +.. index:: buffers, definition + +Partitions are managed and maintained as a list of buffers. Buffers are +obtained from the front of the partition's free buffer chain and returned to +the rear of the same chain. When a buffer is on the free buffer chain, RTEMS +uses two pointers of memory from each buffer as the free buffer chain. When a +buffer is allocated, the entire buffer is available for application use. +Therefore, modifying memory that is outside of an allocated buffer could +destroy the free buffer chain or the contents of an adjacent allocated buffer. Building a Partition Attribute Set ---------------------------------- .. index:: partition attribute set, building -In general, an attribute set is built by a bitwise OR -of the desired attribute components. The set of valid partition -attributes is provided in the following table: +In general, an attribute set is built by a bitwise OR of the desired attribute +components. The set of valid partition attributes is provided in the following +table: -- ``RTEMS_LOCAL`` - local partition (default) +.. list-table:: + :class: rtems-table -- ``RTEMS_GLOBAL`` - global partition + * - ``RTEMS_LOCAL`` + - local partition (default) + * - ``RTEMS_GLOBAL`` + - global partition -Attribute values are specifically designed to be -mutually exclusive, therefore bitwise OR and addition operations -are equivalent as long as each attribute appears exactly once in -the component list. An attribute listed as a default is not -required to appear in the attribute list, although it is a good -programming practice to specify default attributes. If all -defaults are desired, the attribute``RTEMS_DEFAULT_ATTRIBUTES`` should be -specified on this call. The attribute_set parameter should be``RTEMS_GLOBAL`` to indicate that the partition -is to be known globally. +Attribute values are specifically designed to be mutually exclusive, therefore +bitwise OR and addition operations are equivalent as long as each attribute +appears exactly once in the component list. An attribute listed as a default +is not required to appear in the attribute list, although it is a good +programming practice to specify default attributes. If all defaults are +desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this +call. The attribute_set parameter should be ``RTEMS_GLOBAL`` to indicate that +the partition is to be known globally. Operations ========== @@ -69,62 +74,60 @@ Operations Creating a Partition -------------------- -The ``rtems_partition_create`` directive creates a partition -with a user-specified name. The partition's name, starting -address, length and buffer size are all specified to the``rtems_partition_create`` directive. -RTEMS allocates a Partition Control -Block (PTCB) from the PTCB free list. This data structure is -used by RTEMS to manage the newly created partition. The number -of buffers in the partition is calculated based upon the -specified partition length and buffer size. If successful,the -unique partition ID is returned to the calling task. +The ``rtems_partition_create`` directive creates a partition with a +user-specified name. The partition's name, starting address, length and buffer +size are all specified to the ``rtems_partition_create`` directive. RTEMS +allocates a Partition Control Block (PTCB) from the PTCB free list. This data +structure is used by RTEMS to manage the newly created partition. The number +of buffers in the partition is calculated based upon the specified partition +length and buffer size. If successful,the unique partition ID is returned to +the calling task. Obtaining Partition IDs ----------------------- -When a partition is created, RTEMS generates a unique -partition ID and assigned it to the created partition until it -is deleted. The partition ID may be obtained by either of two -methods. First, as the result of an invocation of the``rtems_partition_create`` directive, the partition -ID is stored in a user provided location. Second, the partition -ID may be obtained later using the ``rtems_partition_ident`` -directive. The partition ID is used by other partition manager directives -to access this partition. +When a partition is created, RTEMS generates a unique partition ID and assigned +it to the created partition until it is deleted. The partition ID may be +obtained by either of two methods. First, as the result of an invocation of +the ``rtems_partition_create`` directive, the partition ID is stored in a user +provided location. Second, the partition ID may be obtained later using the +``rtems_partition_ident`` directive. The partition ID is used by other +partition manager directives to access this partition. Acquiring a Buffer ------------------ -A buffer can be obtained by calling the``rtems_partition_get_buffer`` directive. -If a buffer is available, then -it is returned immediately with a successful return code. -Otherwise, an unsuccessful return code is returned immediately -to the caller. Tasks cannot block to wait for a buffer to -become available. +A buffer can be obtained by calling the ``rtems_partition_get_buffer`` +directive. If a buffer is available, then it is returned immediately with a +successful return code. Otherwise, an unsuccessful return code is returned +immediately to the caller. Tasks cannot block to wait for a buffer to become +available. Releasing a Buffer ------------------ -Buffers are returned to a partition's free buffer -chain with the ``rtems_partition_return_buffer`` directive. This -directive returns an error status code if the returned buffer -was not previously allocated from this partition. +Buffers are returned to a partition's free buffer chain with the +``rtems_partition_return_buffer`` directive. This directive returns an error +status code if the returned buffer was not previously allocated from this +partition. Deleting a Partition -------------------- -The ``rtems_partition_delete`` directive allows a partition to -be removed and returned to RTEMS. When a partition is deleted, -the PTCB for that partition is returned to the PTCB free list. -A partition with buffers still allocated cannot be deleted. Any -task attempting to do so will be returned an error status code. +The ``rtems_partition_delete`` directive allows a partition to be removed and +returned to RTEMS. When a partition is deleted, the PTCB for that partition is +returned to the PTCB free list. A partition with buffers still allocated +cannot be deleted. Any task attempting to do so will be returned an error +status code. Directives ========== -This section details the partition manager's -directives. A subsection is dedicated to each of this manager's -directives and describes the calling sequence, related -constants, usage, and status codes. +This section details the partition manager's directives. A subsection is +dedicated to each of this manager's directives and describes the calling +sequence, related constants, usage, and status codes. + +.. _rtems_partition_create: PARTITION_CREATE - Create a partition ------------------------------------- @@ -137,75 +140,88 @@ PARTITION_CREATE - Create a partition .. code:: c rtems_status_code rtems_partition_create( - rtems_name name, - void \*starting_address, - uint32_t length, - uint32_t buffer_size, - rtems_attribute attribute_set, - rtems_id \*id + rtems_name name, + void *starting_address, + uint32_t length, + uint32_t buffer_size, + rtems_attribute attribute_set, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - partition created successfully -``RTEMS_INVALID_NAME`` - invalid partition name -``RTEMS_TOO_MANY`` - too many partitions created -``RTEMS_INVALID_ADDRESS`` - address not on four byte boundary -``RTEMS_INVALID_ADDRESS`` - ``starting_address`` is NULL -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_INVALID_SIZE`` - length or buffer size is 0 -``RTEMS_INVALID_SIZE`` - length is less than the buffer size -``RTEMS_INVALID_SIZE`` - buffer size not a multiple of 4 -``RTEMS_MP_NOT_CONFIGURED`` - multiprocessing not configured -``RTEMS_TOO_MANY`` - too many global objects +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - partition created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid partition name + * - ``RTEMS_TOO_MANY`` + - too many partitions created + * - ``RTEMS_INVALID_ADDRESS`` + - address not on four byte boundary + * - ``RTEMS_INVALID_ADDRESS`` + - ``starting_address`` is NULL + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_SIZE`` + - length or buffer size is 0 + * - ``RTEMS_INVALID_SIZE`` + - length is less than the buffer size + * - ``RTEMS_INVALID_SIZE`` + - buffer size not a multiple of 4 + * - ``RTEMS_MP_NOT_CONFIGURED`` + - multiprocessing not configured + * - ``RTEMS_TOO_MANY`` + - too many global objects **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 -partition id is returned in ``id``. This partition id is used to -access the partition with other partition related directives. -For control and maintenance of the partition, RTEMS allocates a -PTCB from the local PTCB free pool and initializes it. +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 partition id is returned in ``id``. This partition id is used to +access the partition with other partition related directives. For control and +maintenance of the partition, RTEMS allocates a PTCB from the local PTCB free +pool and initializes it. **NOTES:** -This directive will not cause the calling task to be -preempted. +This directive will not cause the calling task to be preempted. -The ``starting_address`` must be properly aligned for the -target architecture. +The ``starting_address`` must be properly aligned for the target architecture. -The ``buffer_size`` parameter must be a multiple of -the CPU alignment factor. Additionally, ``buffer_size`` -must be large enough to hold two pointers on the target -architecture. This is required for RTEMS to manage the -buffers when they are free. +The ``buffer_size`` parameter must be a multiple of the CPU alignment factor. +Additionally, ``buffer_size`` must be large enough to hold two pointers on the +target architecture. This is required for RTEMS to manage the buffers when +they are free. -Memory from the partition is not used by RTEMS to -store the Partition Control Block. +Memory from the partition is not used by RTEMS to store the Partition Control +Block. -The following partition attribute constants are -defined by RTEMS: +The following partition attribute constants are defined by RTEMS: -- ``RTEMS_LOCAL`` - local partition (default) +.. list-table:: + :class: rtems-table -- ``RTEMS_GLOBAL`` - global partition + * - ``RTEMS_LOCAL`` + - local partition (default) + * - ``RTEMS_GLOBAL`` + - global partition -The PTCB for a global partition is allocated on the -local node. The memory space used for the partition must reside -in shared memory. Partitions should not be made global unless -remote tasks must interact with the partition. This is to avoid -the overhead incurred by the creation of a global partition. -When a global partition is created, the partition's name and id -must be transmitted to every node in the system for insertion in -the local copy of the global object table. +The PTCB for a global partition is allocated on the local node. The memory +space used for the partition must reside in shared memory. Partitions should +not be made global unless remote tasks must interact with the partition. This +is to avoid the overhead incurred by the creation of a global partition. When +a global partition is created, the partition's name and id 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 maximum_global_objects field in -the Configuration Table. +The total number of global objects, including partitions, is limited by the +maximum_global_objects field in the Configuration Table. + +.. _rtems_partition_ident: PARTITION_IDENT - Get ID of a partition --------------------------------------- @@ -219,43 +235,48 @@ PARTITION_IDENT - Get ID of a partition .. code:: c rtems_status_code rtems_partition_ident( - rtems_name name, - uint32_t node, - rtems_id \*id + rtems_name name, + uint32_t node, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - partition identified successfully -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_INVALID_NAME`` - partition name not found -``RTEMS_INVALID_NODE`` - invalid node id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - partition identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - partition name not found + * - ``RTEMS_INVALID_NODE`` + - invalid node id **DESCRIPTION:** -This directive obtains the partition id associated -with the partition name. If the partition name is not unique, -then the partition id will match one of the partitions with that -name. However, this partition id is not guaranteed to -correspond to the desired partition. The partition id is used -with other partition related directives to access the partition. +This directive obtains the partition id associated with the partition name. If +the partition name is not unique, then the partition id will match one of the +partitions with that name. However, this partition id is not guaranteed to +correspond to the desired partition. The partition id is used with other +partition related directives to access the partition. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. -If node is ``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. +If node is ``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. -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. +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. -This directive does not generate activity on remote -nodes. It accesses only the local copy of the global object -table. +This directive does not generate activity on remote nodes. It accesses only +the local copy of the global object table. + +.. _rtems_partition_delete: PARTITION_DELETE - Delete a partition ------------------------------------- @@ -268,38 +289,44 @@ PARTITION_DELETE - Delete a partition .. code:: c rtems_status_code rtems_partition_delete( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - partition deleted successfully -``RTEMS_INVALID_ID`` - invalid partition id -``RTEMS_RESOURCE_IN_USE`` - buffers still in use -``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` - cannot delete remote partition +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - partition deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid partition id + * - ``RTEMS_RESOURCE_IN_USE`` + - buffers still in use + * - ``RTEMS_ILLEGAL_ON_REMOTE_OBJECT`` + - cannot delete remote partition **DESCRIPTION:** -This directive deletes the partition specified by id. -The partition cannot be deleted if any of its buffers are still -allocated. The PTCB for the deleted partition is reclaimed by -RTEMS. +This directive deletes the partition specified by id. The partition cannot be +deleted if any of its buffers are still allocated. The PTCB for the deleted +partition is reclaimed by RTEMS. **NOTES:** -This directive will not cause the calling task to be -preempted. +This directive will not cause the calling task to be preempted. -The calling task does not have to be the task that -created the partition. Any local task that knows the partition -id can delete the partition. +The calling task does not have to be the task that created the partition. Any +local task that knows the partition id can delete the partition. -When a global partition is deleted, the partition id -must be transmitted to every node in the system for deletion -from the local copy of the global object table. +When a global partition is deleted, the partition id must be transmitted to +every node in the system for deletion from the local copy of the global object +table. + +The partition must reside on the local node, even if the partition was created +with the ``RTEMS_GLOBAL`` option. -The partition must reside on the local node, even if -the partition was created with the ``RTEMS_GLOBAL`` option. +.. _rtems_partition_get_buffer: PARTITION_GET_BUFFER - Get buffer from a partition -------------------------------------------------- @@ -313,35 +340,42 @@ PARTITION_GET_BUFFER - Get buffer from a partition .. code:: c rtems_status_code rtems_partition_get_buffer( - rtems_id id, - void \**buffer + rtems_id id, + void **buffer ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - buffer obtained successfully -``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL -``RTEMS_INVALID_ID`` - invalid partition id -``RTEMS_UNSATISFIED`` - all buffers are allocated +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - buffer obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid partition id + * - ``RTEMS_UNSATISFIED`` + - all buffers are allocated **DESCRIPTION:** -This directive allows a buffer to be obtained from -the partition specified in id. The address of the allocated -buffer is returned in buffer. +This directive allows a buffer to be obtained from the partition specified +in id. The address of the allocated buffer is returned in buffer. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. All buffers begin on a four byte boundary. A task cannot wait on a buffer to become available. -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 specified partition. +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 specified partition. + +.. _rtems_partition_return_buffer: PARTITION_RETURN_BUFFER - Return buffer to a partition ------------------------------------------------------ @@ -354,37 +388,36 @@ PARTITION_RETURN_BUFFER - Return buffer to a partition .. code:: c rtems_status_code rtems_partition_return_buffer( - rtems_id id, - void \*buffer + rtems_id id, + void *buffer ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - buffer returned successfully -``RTEMS_INVALID_ADDRESS`` - ``buffer`` is NULL -``RTEMS_INVALID_ID`` - invalid partition id -``RTEMS_INVALID_ADDRESS`` - buffer address not in partition +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - buffer returned successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid partition id + * - ``RTEMS_INVALID_ADDRESS`` + - buffer address not in partition **DESCRIPTION:** -This directive returns the buffer specified by buffer -to the partition specified by id. +This directive returns the buffer specified by buffer to the partition +specified by id. **NOTES:** -This directive will not cause the running task to be -preempted. +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 specified 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 specified partition. Returning a buffer multiple times is an error. It will corrupt the internal state of the partition. - -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - |