diff options
Diffstat (limited to 'c-user/partition_manager.rst')
| -rw-r--r-- | c-user/partition_manager.rst | 428 |
1 files changed, 212 insertions, 216 deletions
diff --git a/c-user/partition_manager.rst b/c-user/partition_manager.rst index 1de5fc1..f3d0a92 100644 --- a/c-user/partition_manager.rst +++ b/c-user/partition_manager.rst @@ -129,99 +129,103 @@ 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. +.. raw:: latex + + \clearpage + .. _rtems_partition_create: PARTITION_CREATE - Create a partition ------------------------------------- .. index:: create a partition - -**CALLING SEQUENCE:** - .. index:: rtems_partition_create -.. code-block:: 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:** - -.. 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. - -**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: - -.. list-table:: - :class: rtems-table - - * - ``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. +CALLING SEQUENCE: + .. code-block:: 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: + .. 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. + +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: + + .. list-table:: + :class: rtems-table + + * - ``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. + +.. raw:: latex + + \clearpage .. _rtems_partition_ident: @@ -229,104 +233,102 @@ 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-block:: c - - rtems_status_code rtems_partition_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); +CALLING SEQUENCE: + .. code-block:: c -**DIRECTIVE STATUS CODES:** + rtems_status_code rtems_partition_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); -.. list-table:: - :class: rtems-table +DIRECTIVE STATUS CODES: + .. 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 + * - ``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:** +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. -**NOTES:** + 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. -This directive will not cause the running task to be preempted. + 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 ``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. + This directive does not generate activity on remote nodes. It accesses + only the local copy of the global object table. -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. +.. raw:: latex -This directive does not generate activity on remote nodes. It accesses only -the local copy of the global object table. + \clearpage .. _rtems_partition_delete: PARTITION_DELETE - Delete a partition ------------------------------------- .. index:: delete a partition - -**CALLING SEQUENCE:** - .. index:: rtems_partition_delete -.. code-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_partition_delete( - rtems_id id - ); + rtems_status_code rtems_partition_delete( + rtems_id id + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 + * - ``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:** +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. -**NOTES:** + 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. -This directive will not cause the calling task to be preempted. + 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 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 partition must reside on the local node, even if the partition was + created with the ``RTEMS_GLOBAL`` option. -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. +.. raw:: latex -The partition must reside on the local node, even if the partition was created -with the ``RTEMS_GLOBAL`` option. + \clearpage .. _rtems_partition_get_buffer: @@ -334,92 +336,86 @@ 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-block:: c +CALLING SEQUENCE: + .. code-block:: c - rtems_status_code rtems_partition_get_buffer( - rtems_id id, - void **buffer - ); + rtems_status_code rtems_partition_get_buffer( + rtems_id id, + void **buffer + ); -**DIRECTIVE STATUS CODES:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -.. 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 + * - ``RTEMS_SUCCESSFUL`` + - buffer obtained successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``buffer`` is NULL + * - ``RTEMS_INVALID_ID`` + - invalid partition id + * - ``RTEMS_UNSATISFIED`` + - all buffers are allocated -**DESCRIPTION:** +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. -**NOTES:** + All buffers begin on a four byte boundary. -This directive will not cause the running task to be preempted. + A task cannot wait on a buffer to become available. -All buffers begin on a four byte boundary. + 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. -A task cannot wait on a buffer to become available. +.. raw:: latex -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. + \clearpage .. _rtems_partition_return_buffer: PARTITION_RETURN_BUFFER - Return buffer to a partition ------------------------------------------------------ .. index:: return buffer to partitition - -**CALLING SEQUENCE:** - .. index:: rtems_partition_return_buffer -.. code-block:: c - - rtems_status_code rtems_partition_return_buffer( - rtems_id id, - void *buffer - ); - -**DIRECTIVE STATUS CODES:** - -.. list-table:: - :class: rtems-table +CALLING SEQUENCE: + .. code-block:: c - * - ``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 + rtems_status_code rtems_partition_return_buffer( + rtems_id id, + void *buffer + ); -**DESCRIPTION:** +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table -This directive returns the buffer specified by buffer to the partition -specified by id. + * - ``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 -**NOTES:** +DESCRIPTION: + This directive returns the buffer specified by buffer to the partition + specified by id. -This directive will not cause the running task to be preempted. +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 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. + Returning a buffer multiple times is an error. It will corrupt the + internal state of the partition. |