From fd6dc8c8de4dbc7ecf8a82a597cd5b43476fc8e3 Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sun, 17 Jan 2016 19:19:43 -0500 Subject: Split document into seperate files by section. --- c_user/partition_manager.rst | 390 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 390 insertions(+) create mode 100644 c_user/partition_manager.rst (limited to 'c_user/partition_manager.rst') diff --git a/c_user/partition_manager.rst b/c_user/partition_manager.rst new file mode 100644 index 0000000..c411a13 --- /dev/null +++ b/c_user/partition_manager.rst @@ -0,0 +1,390 @@ +Partition Manager +################# + +.. index:: partitions + +Introduction +============ + +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_ident`` - Get ID of a partition + +- ``rtems_partition_delete`` - Delete a partition + +- ``rtems_partition_get_buffer`` - Get buffer from a partition + +- ``rtems_partition_return_buffer`` - Return buffer to a partition + +Background +========== + +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 + +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: + +- ``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. + +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. + +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. + +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. + +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. + +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. + +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. + +PARTITION_CREATE - Create a partition +------------------------------------- +.. index:: create a partition + +**CALLING SEQUENCE:** + +.. index:: rtems_partition_create + +.. 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 + ); + +**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 + +**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. + +**NOTES:** + +This directive will not cause the calling task to be +preempted. + +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. + +Memory from the partition is not used by RTEMS to +store the Partition Control Block. + +The following partition attribute constants are +defined by RTEMS: + +- ``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 total number of global objects, including +partitions, is limited by the maximum_global_objects field in +the Configuration Table. + +PARTITION_IDENT - Get ID of a partition +--------------------------------------- +.. index:: get ID of a partition +.. index:: obtain ID of a partition + +**CALLING SEQUENCE:** + +.. index:: rtems_partition_ident + +.. code:: c + + rtems_status_code rtems_partition_ident( + 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 + +**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. + +**NOTES:** + +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 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. + +PARTITION_DELETE - Delete a partition +------------------------------------- +.. index:: delete a partition + +**CALLING SEQUENCE:** + +.. index:: rtems_partition_delete + +.. code:: c + + rtems_status_code rtems_partition_delete( + 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 + +**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. + +**NOTES:** + +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. + +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. + +PARTITION_GET_BUFFER - Get buffer from a partition +-------------------------------------------------- +.. index:: get buffer from partition +.. index:: obtain buffer from partition + +**CALLING SEQUENCE:** + +.. index:: rtems_partition_get_buffer + +.. code:: c + + rtems_status_code rtems_partition_get_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 + +**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. + +**NOTES:** + +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. + +PARTITION_RETURN_BUFFER - Return buffer to a partition +------------------------------------------------------ +.. index:: return buffer to partitition + +**CALLING SEQUENCE:** + +.. index:: rtems_partition_return_buffer + +.. code:: c + + rtems_status_code rtems_partition_return_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 + +**DESCRIPTION:** + +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. + +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. + -- cgit v1.2.3