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.

c-user/dual-ported-memory/background.rst

@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+.. index:: dual ported memory, definition
+.. index:: external addresses, definition
+.. index:: internal addresses, definition
+
+Background
+==========
+
+A dual-ported memory area (DPMA) is an contiguous block of RAM owned by a
+particular processor but which can be accessed by other processors in the
+system.  The owner accesses the memory using internal addresses, while other
+processors must use external addresses.  RTEMS defines a port as a particular
+mapping of internal and external addresses.
+
+There are two system configurations in which dual-ported memory is commonly
+found.  The first is tightly-coupled multiprocessor computer systems where the
+dual-ported memory is shared between all nodes and is used for inter-node
+communication.  The second configuration is computer systems with intelligent
+peripheral controllers.  These controllers typically utilize the DPMA for
+high-performance data transfers.

c-user/dual-ported-memory/directives.rst

@@ -2,90 +2,6 @@
 
 .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 
-.. index:: ports
-.. index:: dual ported memory
-
-Dual-Ported Memory Manager
-**************************
-
-Introduction
-============
-
-The dual-ported memory manager provides a mechanism for converting addresses
-between internal and external representations for multiple dual-ported memory
-areas (DPMA).  The directives provided by the dual-ported memory manager are:
-
-- rtems_port_create_ - Create a port
-
-- rtems_port_ident_ - Get ID of a port
-
-- rtems_port_delete_ - Delete a port
-
-- rtems_port_external_to_internal_ - Convert external to internal address
-
-- rtems_port_internal_to_external_ - Convert internal to external address
-
-.. index:: dual ported memory, definition
-.. index:: external addresses, definition
-.. index:: internal addresses, definition
-
-Background
-==========
-
-A dual-ported memory area (DPMA) is an contiguous block of RAM owned by a
-particular processor but which can be accessed by other processors in the
-system.  The owner accesses the memory using internal addresses, while other
-processors must use external addresses.  RTEMS defines a port as a particular
-mapping of internal and external addresses.
-
-There are two system configurations in which dual-ported memory is commonly
-found.  The first is tightly-coupled multiprocessor computer systems where the
-dual-ported memory is shared between all nodes and is used for inter-node
-communication.  The second configuration is computer systems with intelligent
-peripheral controllers.  These controllers typically utilize the DPMA for
-high-performance data transfers.
-
-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.
-
 Directives
 ==========
 

c-user/dual-ported-memory/index.rst

@@ -0,0 +1,16 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: ports
+.. index:: dual ported memory
+
+Dual-Ported Memory Manager
+**************************
+
+.. toctree::
+
+    introduction
+    background
+    operations
+    directives

c-user/dual-ported-memory/introduction.rst

@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+The dual-ported memory manager provides a mechanism for converting addresses
+between internal and external representations for multiple dual-ported memory
+areas (DPMA).  The directives provided by the dual-ported memory manager are:
+
+- :ref:`rtems_port_create`
+
+- :ref:`rtems_port_ident`
+
+- :ref:`rtems_port_delete`
+
+- :ref:`rtems_port_external_to_internal`
+
+- :ref:`rtems_port_internal_to_external`

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.

c-user/index.rst

@@ -42,7 +42,7 @@ RTEMS Classic API Guide (|version|).
 	signal_manager
 	partition_manager
 	region_manager
-	dual_ports_memory_manager
+	dual-ported-memory/index
 	io_manager
 	fatal_error
 	board_support_packages