[PATCH v2 09/16] c-user: Split up partition manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:01:03 UTC 2020
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 ++++++++
.../directives.rst} | 120 ------------------
c-user/partition/index.rst | 15 +++
c-user/partition/introduction.rst | 19 +++
c-user/partition/operations.rst | 55 ++++++++
6 files changed, 140 insertions(+), 121 deletions(-)
create mode 100644 c-user/partition/background.rst
rename c-user/{partition_manager.rst => partition/directives.rst} (70%)
create mode 100644 c-user/partition/index.rst
create mode 100644 c-user/partition/introduction.rst
create mode 100644 c-user/partition/operations.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_manager.rst b/c-user/partition/directives.rst
similarity index 70%
rename from c-user/partition_manager.rst
rename to c-user/partition/directives.rst
index bc30de2..f81c37f 100644
--- a/c-user/partition_manager.rst
+++ b/c-user/partition/directives.rst
@@ -2,126 +2,6 @@
.. 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
==========
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.
--
2.26.2
More information about the devel
mailing list