c-user: Split up partition manager

This makes it easier to automatically generate parts of the manager
documentation in the future.

Update #3993.

6 files changed, 140 insertions, 121 deletions

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
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.