diff options
Diffstat (limited to '')
| -rw-r--r-- | ada_user/dual_ports_memory_manager.rst | 291 |
1 files changed, 0 insertions, 291 deletions
diff --git a/ada_user/dual_ports_memory_manager.rst b/ada_user/dual_ports_memory_manager.rst deleted file mode 100644 index 3888fec..0000000 --- a/ada_user/dual_ports_memory_manager.rst +++ /dev/null @@ -1,291 +0,0 @@ -Dual-Ported Memory Manager -########################## - -.. index:: ports -.. index:: dual ported memory - -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 - -Background -========== -.. index:: dual ported memory, definition -.. index:: external addresses, definition -.. index:: internal addresses, definition - -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. - -PORT_CREATE - Create a port ---------------------------- -.. index:: create a port - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Port_Create ( - Name : in RTEMS.Name; - Internal_Start : in RTEMS.Address; - External_Start : in RTEMS.Address; - Length : in RTEMS.Unsigned32; - ID : out RTEMS.ID; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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:** - -The internal_address and external_address parameters -must be on a four byte boundary. - -This directive will not cause the calling task to be -preempted. - -PORT_IDENT - Get ID of a port ------------------------------ -.. index:: get ID of a port -.. index:: obtain ID of a port - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Port_Ident ( - Name : in RTEMS.Name; - ID : out RTEMS.ID; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -PORT_DELETE - Delete a port ---------------------------- -.. index:: delete a port - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Port_Delete ( - ID : in RTEMS.ID; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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 will not cause the calling task to be -preempted. - -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. - -PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address ----------------------------------------------------------------- -.. index:: convert external to internal address - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Port_External_To_Internal ( - ID : in RTEMS.ID; - External : in RTEMS.Address; - Internal : out RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address ----------------------------------------------------------------- -.. index:: convert internal to external address - -**CALLING SEQUENCE:** - -.. code:: c - - procedure Port_Internal_To_External ( - ID : in RTEMS.ID; - Internal : in RTEMS.Address; - External : out RTEMS.Address; - Result : out RTEMS.Status_Codes - ); - -**DIRECTIVE STATUS CODES:** - -``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. - -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - |