c-user: Split up partition manager

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

Update #3993.

1 files changed, 55 insertions, 0 deletions

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.