From 623a9a11e8b4daf2ccfba0a3cff23e5063453e75 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 20 Aug 2020 09:36:26 +0200 Subject: 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 | 23 +++ c-user/dual-ported-memory/directives.rst | 229 +++++++++++++++++++++ c-user/dual-ported-memory/index.rst | 16 ++ c-user/dual-ported-memory/introduction.rst | 20 ++ c-user/dual-ported-memory/operations.rst | 44 ++++ c-user/dual_ports_memory_manager.rst | 313 ----------------------------- c-user/index.rst | 2 +- 7 files changed, 333 insertions(+), 314 deletions(-) create mode 100644 c-user/dual-ported-memory/background.rst create mode 100644 c-user/dual-ported-memory/directives.rst create mode 100644 c-user/dual-ported-memory/index.rst create mode 100644 c-user/dual-ported-memory/introduction.rst create mode 100644 c-user/dual-ported-memory/operations.rst delete mode 100644 c-user/dual_ports_memory_manager.rst diff --git a/c-user/dual-ported-memory/background.rst b/c-user/dual-ported-memory/background.rst new file mode 100644 index 0000000..3b6301e --- /dev/null +++ b/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. diff --git a/c-user/dual-ported-memory/directives.rst b/c-user/dual-ported-memory/directives.rst new file mode 100644 index 0000000..fb21a4f --- /dev/null +++ b/c-user/dual-ported-memory/directives.rst @@ -0,0 +1,229 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + +Directives +========== + +This section details the dual-ported memory manager's directives. A subsection +is dedicated to each of this manager's directives and describes the calling +sequence, related constants, usage, and status codes. + +.. raw:: latex + + \clearpage + +.. index:: create a port +.. index:: rtems_port_create + +.. _rtems_port_create: + +PORT_CREATE - Create a port +--------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_port_create( + rtems_name name, + void *internal_start, + void *external_start, + uint32_t length, + rtems_id *id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - port created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid port name + * - ``RTEMS_INVALID_ADDRESS`` + - address not on four byte boundary + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_TOO_MANY`` + - too many DP memory areas created + +DESCRIPTION: + This directive creates a port which resides on the local node for the + specified DPMA. The assigned port id is returned in id. This port id is + used as an argument to other dual-ported memory manager directives to + convert addresses within this DPMA. + + For control and maintenance of the port, RTEMS allocates and initializes an + DPCB from the DPCB free pool. Thus memory from the dual-ported memory area + is not used to store the DPCB. + +NOTES: + This directive may cause the calling task to be preempted due to an + obtain and release of the object allocator mutex. + + The internal_address and external_address parameters must be on a four byte + boundary. + +.. raw:: latex + + \clearpage + +.. index:: get ID of a port +.. index:: obtain ID of a port +.. index:: rtems_port_ident + +.. _rtems_port_ident: + +PORT_IDENT - Get ID of a port +----------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_port_ident( + rtems_name name, + rtems_id *id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - port identified successfully + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_INVALID_NAME`` + - port name not found + +DESCRIPTION: + This directive obtains the port id associated with the specified name to be + acquired. If the port name is not unique, then the port id will match one + of the DPMAs with that name. However, this port id is not guaranteed to + correspond to the desired DPMA. The port id is used to access this DPMA in + other dual-ported memory area related directives. + +NOTES: + This directive will not cause the running task to be preempted. + +.. raw:: latex + + \clearpage + +.. index:: delete a port +.. index:: rtems_port_delete + +.. _rtems_port_delete: + +PORT_DELETE - Delete a port +--------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_port_delete( + rtems_id id + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - port deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid port id + +DESCRIPTION: + This directive deletes the dual-ported memory area specified by id. The + DPCB for the deleted dual-ported memory area is reclaimed by RTEMS. + +NOTES: + This directive may cause the calling task to be preempted due to an + obtain and release of the object allocator mutex. + + The calling task does not have to be the task that created the port. Any + local task that knows the port id can delete the port. + +.. raw:: latex + + \clearpage + +.. index:: convert external to internal address +.. index:: rtems_port_external_to_internal + +.. _rtems_port_external_to_internal: + +PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address +---------------------------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_port_external_to_internal( + rtems_id id, + void *external, + void **internal + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_INVALID_ADDRESS`` + - ``internal`` is NULL + * - ``RTEMS_SUCCESSFUL`` + - successful conversion + +DESCRIPTION: + This directive converts a dual-ported memory address from external to + internal representation for the specified port. If the given external + address is invalid for the specified port, then the internal address is set + to the given external address. + +NOTES: + This directive is callable from an ISR. + + This directive will not cause the calling task to be preempted. + +.. raw:: latex + + \clearpage + +.. index:: convert internal to external address +.. index:: rtems_port_internal_to_external + +.. _rtems_port_internal_to_external: + +PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address +---------------------------------------------------------------- + +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_port_internal_to_external( + rtems_id id, + void *internal, + void **external + ); + +DIRECTIVE STATUS CODES: + .. list-table:: + :class: rtems-table + + * - ``RTEMS_INVALID_ADDRESS`` + - ``external`` is NULL + * - ``RTEMS_SUCCESSFUL`` + - successful conversion + +DESCRIPTION: + This directive converts a dual-ported memory address from internal to + external representation so that it can be passed to owner of the DPMA + represented by the specified port. If the given internal address is an + invalid dual-ported address, then the external address is set to the given + internal address. + +NOTES: + This directive is callable from an ISR. + + This directive will not cause the calling task to be preempted. diff --git a/c-user/dual-ported-memory/index.rst b/c-user/dual-ported-memory/index.rst new file mode 100644 index 0000000..07628ce --- /dev/null +++ b/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 diff --git a/c-user/dual-ported-memory/introduction.rst b/c-user/dual-ported-memory/introduction.rst new file mode 100644 index 0000000..752a162 --- /dev/null +++ b/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` 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. diff --git a/c-user/dual_ports_memory_manager.rst b/c-user/dual_ports_memory_manager.rst deleted file mode 100644 index a8b7183..0000000 --- a/c-user/dual_ports_memory_manager.rst +++ /dev/null @@ -1,313 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. 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 -========== - -This section details the dual-ported memory manager's directives. A subsection -is dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. - -.. raw:: latex - - \clearpage - -.. index:: create a port -.. index:: rtems_port_create - -.. _rtems_port_create: - -PORT_CREATE - Create a port ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_create( - rtems_name name, - void *internal_start, - void *external_start, - uint32_t length, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - port created successfully - * - ``RTEMS_INVALID_NAME`` - - invalid port name - * - ``RTEMS_INVALID_ADDRESS`` - - address not on four byte boundary - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_TOO_MANY`` - - too many DP memory areas created - -DESCRIPTION: - This directive creates a port which resides on the local node for the - specified DPMA. The assigned port id is returned in id. This port id is - used as an argument to other dual-ported memory manager directives to - convert addresses within this DPMA. - - For control and maintenance of the port, RTEMS allocates and initializes an - DPCB from the DPCB free pool. Thus memory from the dual-ported memory area - is not used to store the DPCB. - -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. - - The internal_address and external_address parameters must be on a four byte - boundary. - -.. raw:: latex - - \clearpage - -.. index:: get ID of a port -.. index:: obtain ID of a port -.. index:: rtems_port_ident - -.. _rtems_port_ident: - -PORT_IDENT - Get ID of a port ------------------------------ - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_ident( - rtems_name name, - rtems_id *id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - port identified successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``id`` is NULL - * - ``RTEMS_INVALID_NAME`` - - port name not found - -DESCRIPTION: - This directive obtains the port id associated with the specified name to be - acquired. If the port name is not unique, then the port id will match one - of the DPMAs with that name. However, this port id is not guaranteed to - correspond to the desired DPMA. The port id is used to access this DPMA in - other dual-ported memory area related directives. - -NOTES: - This directive will not cause the running task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: delete a port -.. index:: rtems_port_delete - -.. _rtems_port_delete: - -PORT_DELETE - Delete a port ---------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_delete( - rtems_id id - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_SUCCESSFUL`` - - port deleted successfully - * - ``RTEMS_INVALID_ID`` - - invalid port id - -DESCRIPTION: - This directive deletes the dual-ported memory area specified by id. The - DPCB for the deleted dual-ported memory area is reclaimed by RTEMS. - -NOTES: - This directive may cause the calling task to be preempted due to an - obtain and release of the object allocator mutex. - - The calling task does not have to be the task that created the port. Any - local task that knows the port id can delete the port. - -.. raw:: latex - - \clearpage - -.. index:: convert external to internal address -.. index:: rtems_port_external_to_internal - -.. _rtems_port_external_to_internal: - -PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address ----------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_external_to_internal( - rtems_id id, - void *external, - void **internal - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_INVALID_ADDRESS`` - - ``internal`` is NULL - * - ``RTEMS_SUCCESSFUL`` - - successful conversion - -DESCRIPTION: - This directive converts a dual-ported memory address from external to - internal representation for the specified port. If the given external - address is invalid for the specified port, then the internal address is set - to the given external address. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the calling task to be preempted. - -.. raw:: latex - - \clearpage - -.. index:: convert internal to external address -.. index:: rtems_port_internal_to_external - -.. _rtems_port_internal_to_external: - -PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address ----------------------------------------------------------------- - -CALLING SEQUENCE: - .. code-block:: c - - rtems_status_code rtems_port_internal_to_external( - rtems_id id, - void *internal, - void **external - ); - -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - - * - ``RTEMS_INVALID_ADDRESS`` - - ``external`` is NULL - * - ``RTEMS_SUCCESSFUL`` - - successful conversion - -DESCRIPTION: - This directive converts a dual-ported memory address from internal to - external representation so that it can be passed to owner of the DPMA - represented by the specified port. If the given internal address is an - invalid dual-ported address, then the external address is set to the given - internal address. - -NOTES: - This directive is callable from an ISR. - - This directive will not cause the calling task to be preempted. diff --git a/c-user/index.rst b/c-user/index.rst index f4922da..51998bf 100644 --- a/c-user/index.rst +++ b/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 -- cgit v1.2.3