c-user: Split up dual-ported memory manager

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

Update #3993.

1 files changed, 44 insertions, 0 deletions

diff --git a/c-user/dual-ported-memory/operations.rst b/c-user/dual-ported-memory/operations.rst
new file mode 100644
index 0000000..15efb36
--- /dev/null
+++ b/c-user/dual-ported-memory/operations.rst
@@ -0,0 +1,44 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Creating a Port
+---------------
+
+The ``rtems_port_create`` directive creates a port into a DPMA with the
+user-defined name.  The user specifies the association between internal and
+external representations for the port being created.  RTEMS allocates a
+Dual-Ported Memory Control Block (DPCB) from the DPCB free list to maintain the
+newly created DPMA.  RTEMS also generates a unique dual-ported memory port ID
+which is returned to the calling task.  RTEMS does not initialize the
+dual-ported memory area or access any memory within it.
+
+Obtaining Port IDs
+------------------
+
+When a port is created, RTEMS generates a unique port ID and assigns it to the
+created port until it is deleted.  The port ID may be obtained by either of two
+methods.  First, as the result of an invocation of the``rtems_port_create``
+directive, the task ID is stored in a user provided location.  Second, the port
+ID may be obtained later using the ``rtems_port_ident`` directive.  The port ID
+is used by other dual-ported memory manager directives to access this port.
+
+Converting an Address
+---------------------
+
+The ``rtems_port_external_to_internal`` directive is used to convert an address
+from external to internal representation for the specified port.  The
+``rtems_port_internal_to_external`` directive is used to convert an address
+from internal to external representation for the specified port.  If an attempt
+is made to convert an address which lies outside the specified DPMA, then the
+address to be converted will be returned.
+
+Deleting a DPMA Port
+--------------------
+
+A port can be removed from the system and returned to RTEMS with the
+``rtems_port_delete`` directive.  When a port is deleted, its control block is
+returned to the DPCB free list.