diff options
Diffstat (limited to 'c_user/dual_ports_memory_manager.rst')
| -rw-r--r-- | c_user/dual_ports_memory_manager.rst | 273 |
1 files changed, 143 insertions, 130 deletions
diff --git a/c_user/dual_ports_memory_manager.rst b/c_user/dual_ports_memory_manager.rst index 5dd59a5..6088ece 100644 --- a/c_user/dual_ports_memory_manager.rst +++ b/c_user/dual_ports_memory_manager.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Dual-Ported Memory Manager ########################## @@ -7,20 +11,19 @@ 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: +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_create_ - Create a port -- ``rtems_port_ident`` - Get ID of a port +- rtems_port_ident_ - Get ID of a port -- ``rtems_port_delete`` - Delete a port +- rtems_port_delete_ - Delete a port -- ``rtems_port_external_to_internal`` - Convert external to internal address +- rtems_port_external_to_internal_ - Convert external to internal address -- ``rtems_port_internal_to_external`` - Convert internal to external address +- rtems_port_internal_to_external_ - Convert internal to external address Background ========== @@ -28,21 +31,18 @@ Background .. 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 +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. +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 ========== @@ -50,54 +50,49 @@ 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. +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. +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. +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. +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. +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. + +.. _rtems_port_create: PORT_CREATE - Create a port --------------------------- @@ -110,41 +105,48 @@ PORT_CREATE - Create a port .. code:: c rtems_status_code rtems_port_create( - rtems_name name, - void \*internal_start, - void \*external_start, - uint32_t length, - rtems_id \*id + rtems_name name, + void *internal_start, + void *external_start, + uint32_t length, + rtems_id *id ); **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 +.. 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 +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. +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. +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. +This directive will not cause the calling task to be preempted. + +.. _rtems_port_ident: PORT_IDENT - Get ID of a port ----------------------------- @@ -158,29 +160,35 @@ PORT_IDENT - Get ID of a port .. code:: c rtems_status_code rtems_port_ident( - rtems_name name, - rtems_id \*id + rtems_name name, + rtems_id \*id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - port identified successfully -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_INVALID_NAME`` - port name not found +.. 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 +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. +This directive will not cause the running task to be preempted. + +.. _rtems_port_delete: PORT_DELETE - Delete a port --------------------------- @@ -193,28 +201,32 @@ PORT_DELETE - Delete a port .. code:: c rtems_status_code rtems_port_delete( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - port deleted successfully -``RTEMS_INVALID_ID`` - invalid port id +.. 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. +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. +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. -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. +.. _rtems_port_external_to_internal: PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address ---------------------------------------------------------------- @@ -227,30 +239,35 @@ PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address .. code:: c rtems_status_code rtems_port_external_to_internal( - rtems_id id, - void \*external, - void \**internal + rtems_id id, + void *external, + void **internal ); **DIRECTIVE STATUS CODES:** -``RTEMS_INVALID_ADDRESS`` - ``internal`` is NULL -``RTEMS_SUCCESSFUL`` - successful conversion +.. 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. +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. +This directive will not cause the calling task to be preempted. + +.. _rtems_port_internal_to_external: PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address ---------------------------------------------------------------- @@ -263,34 +280,30 @@ PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address .. code:: c rtems_status_code rtems_port_internal_to_external( - rtems_id id, - void \*internal, - void \**external + rtems_id id, + void *internal, + void **external ); **DIRECTIVE STATUS CODES:** -``RTEMS_INVALID_ADDRESS`` - ``external`` is NULL -``RTEMS_SUCCESSFUL`` - successful conversion +.. 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. +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. - +This directive will not cause the calling task to be preempted. |