From a4119a9f1ce98f753ac6b9cfa0a5555f7c6a7c5e Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 20 Aug 2020 10:00:14 +0200 Subject: c-user: Split up partition manager This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993. --- c-user/index.rst | 2 +- c-user/partition/background.rst | 50 ++++ c-user/partition/directives.rst | 349 ++++++++++++++++++++++++++++ c-user/partition/index.rst | 15 ++ c-user/partition/introduction.rst | 19 ++ c-user/partition/operations.rst | 55 +++++ c-user/partition_manager.rst | 469 -------------------------------------- 7 files changed, 489 insertions(+), 470 deletions(-) create mode 100644 c-user/partition/background.rst create mode 100644 c-user/partition/directives.rst create mode 100644 c-user/partition/index.rst create mode 100644 c-user/partition/introduction.rst create mode 100644 c-user/partition/operations.rst delete mode 100644 c-user/partition_manager.rst diff --git a/c-user/index.rst b/c-user/index.rst index 0febfc4..6de3f97 100644 --- a/c-user/index.rst +++ b/c-user/index.rst @@ -40,7 +40,7 @@ RTEMS Classic API Guide (|version|). message/index event/index signal_manager - partition_manager + partition/index region_manager dual-ported-memory/index io/index diff --git a/c-user/partition/background.rst b/c-user/partition/background.rst new file mode 100644 index 0000000..ce38fc7 --- /dev/null +++ b/c-user/partition/background.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Background +========== + +.. index:: partition, definition + +Partition Manager Definitions +----------------------------- + +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. + +.. index:: partition attribute set, building + +Building a Partition Attribute Set +---------------------------------- + +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: + +.. list-table:: + :class: rtems-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. diff --git a/c-user/partition/directives.rst b/c-user/partition/directives.rst new file mode 100644 index 0000000..f81c37f --- /dev/null +++ b/c-user/partition/directives.rst @@ -0,0 +1,349 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +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. + +.. raw:: latex + + \clearpage + +.. index:: create a partition +.. index:: rtems_partition_create + +.. _rtems_partition_create: + +PARTITION_CREATE - Create a partition +------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_partition_create( + rtems_name name, + void *starting_address, + uintptr_t length, + size_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`` + - ``starting_address`` is not on a pointer size 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`` is not an integral multiple of the pointer size + * - ``RTEMS_INVALID_SIZE`` + - ``buffer_size`` is less than two times the pointer size + * - ``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 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 the also the user data. For example, if the user + data contains some long double or vector data types, the partition buffer + area and the buffer size must take the alignment of these types into + account which is usually larger than the pointer alignment. A cache line + alignment may be also a factor. + + The ``buffer_size`` parameter must be an integral multiple of the pointer + size on the target architecture. 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. + +EXAMPLE: + .. code-block:: c + + #include + #include + + #include + + typedef struct { + char less; + short more; + } item; + + union { + item data; + rtems_chain_node node; + } items[ 13 ]; + + rtems_id create_partition(void) + { + rtems_id id; + rtems_status_code sc; + + sc = rtems_partition_create( + rtems_build_name( 'P', 'A', 'R', 'T' ), + items, + sizeof( items ), + sizeof( items[ 0 ] ), + RTEMS_DEFAULT_ATTRIBUTES, + &id + ); + assert(sc == RTEMS_SUCCESSFUL); + + return id; + } + +.. raw:: latex + + \clearpage + +.. index:: get ID of a partition +.. index:: obtain ID of a partition +.. index:: rtems_partition_ident + +.. _rtems_partition_ident: + +PARTITION_IDENT - Get ID of a partition +--------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_partition_ident( + rtems_name name, + uint32_t node, + rtems_id *id + ); + +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 + +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. + +.. raw:: latex + + \clearpage + +.. index:: delete a partition +.. index:: rtems_partition_delete + +.. _rtems_partition_delete: + +PARTITION_DELETE - Delete a partition +------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_partition_delete( + rtems_id id + ); + +DIRECTIVE STATUS CODES: + .. 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. + +NOTES: + This directive may cause the calling task to be preempted due to an + obtain and release of the object allocator mutex. + + 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. + +.. raw:: latex + + \clearpage + +.. index:: get buffer from partition +.. index:: obtain buffer from partition +.. index:: rtems_partition_get_buffer + +.. _rtems_partition_get_buffer: + +PARTITION_GET_BUFFER - Get buffer from a partition +-------------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_partition_get_buffer( + rtems_id id, + void **buffer + ); + +DIRECTIVE STATUS CODES: + .. 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. + +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. + +.. raw:: latex + + \clearpage + +.. index:: return buffer to partitition +.. index:: rtems_partition_return_buffer + +.. _rtems_partition_return_buffer: + +PARTITION_RETURN_BUFFER - Return buffer to a partition +------------------------------------------------------ + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_partition_return_buffer( + rtems_id id, + void *buffer + ); + +DIRECTIVE STATUS CODES: + .. 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. + +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. diff --git a/c-user/partition/index.rst b/c-user/partition/index.rst new file mode 100644 index 0000000..c8e7348 --- /dev/null +++ b/c-user/partition/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + +.. index:: partitions + +Partition Manager +***************** + +.. toctree:: + + introduction + background + operations + directives diff --git a/c-user/partition/introduction.rst b/c-user/partition/introduction.rst new file mode 100644 index 0000000..dd51d30 --- /dev/null +++ b/c-user/partition/introduction.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Introduction +============ + +The partition manager provides facilities to dynamically allocate memory in +fixed-size units. The directives provided by the partition manager are: + +- :ref:`rtems_partition_create` + +- :ref:`rtems_partition_ident` + +- :ref:`rtems_partition_delete` + +- :ref:`rtems_partition_get_buffer` + +- :ref:`rtems_partition_return_buffer` diff --git a/c-user/partition/operations.rst b/c-user/partition/operations.rst new file mode 100644 index 0000000..d0eff5b --- /dev/null +++ b/c-user/partition/operations.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +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. diff --git a/c-user/partition_manager.rst b/c-user/partition_manager.rst deleted file mode 100644 index bc30de2..0000000 --- a/c-user/partition_manager.rst +++ /dev/null @@ -1,469 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) - -.. index:: partitions - -Partition Manager -***************** - -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 -========== - -.. index:: partition, definition - -Partition Manager Definitions ------------------------------ - -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. - -.. index:: partition attribute set, building - -Building a Partition Attribute Set ----------------------------------- - -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: - -.. list-table:: - :class: rtems-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. - -.. raw:: latex - - \clearpage - -.. index:: create a partition -.. index:: rtems_partition_create - -.. _rtems_partition_create: - -PARTITION_CREATE - Create a partition -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_create( - rtems_name name, - void *starting_address, - uintptr_t length, - size_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`` - - ``starting_address`` is not on a pointer size 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`` is not an integral multiple of the pointer size - * - ``RTEMS_INVALID_SIZE`` - - ``buffer_size`` is less than two times the pointer size - * - ``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 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 the also the user data. For example, if the user - data contains some long double or vector data types, the partition buffer - area and the buffer size must take the alignment of these types into - account which is usually larger than the pointer alignment. A cache line - alignment may be also a factor. - - The ``buffer_size`` parameter must be an integral multiple of the pointer - size on the target architecture. 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. - -EXAMPLE: - .. code-block:: c - - #include - #include - - #include - - typedef struct { - char less; - short more; - } item; - - union { - item data; - rtems_chain_node node; - } items[ 13 ]; - - rtems_id create_partition(void) - { - rtems_id id; - rtems_status_code sc; - - sc = rtems_partition_create( - rtems_build_name( 'P', 'A', 'R', 'T' ), - items, - sizeof( items ), - sizeof( items[ 0 ] ), - RTEMS_DEFAULT_ATTRIBUTES, - &id - ); - assert(sc == RTEMS_SUCCESSFUL); - - return id; - } - -.. raw:: latex - - \clearpage - -.. index:: get ID of a partition -.. index:: obtain ID of a partition -.. index:: rtems_partition_ident - -.. _rtems_partition_ident: - -PARTITION_IDENT - Get ID of a partition ---------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_ident( - rtems_name name, - uint32_t node, - rtems_id *id - ); - -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 - -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. - -.. raw:: latex - - \clearpage - -.. index:: delete a partition -.. index:: rtems_partition_delete - -.. _rtems_partition_delete: - -PARTITION_DELETE - Delete a partition -------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. 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. - -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. - - 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. - -.. raw:: latex - - \clearpage - -.. index:: get buffer from partition -.. index:: obtain buffer from partition -.. index:: rtems_partition_get_buffer - -.. _rtems_partition_get_buffer: - -PARTITION_GET_BUFFER - Get buffer from a partition --------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_get_buffer( - rtems_id id, - void **buffer - ); - -DIRECTIVE STATUS CODES: - .. 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. - -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. - -.. raw:: latex - - \clearpage - -.. index:: return buffer to partitition -.. index:: rtems_partition_return_buffer - -.. _rtems_partition_return_buffer: - -PARTITION_RETURN_BUFFER - Return buffer to a partition ------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_partition_return_buffer( - rtems_id id, - void *buffer - ); - -DIRECTIVE STATUS CODES: - .. 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. - -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. -- cgit v1.2.3