forked from Imagelibrary/rtems
387 lines
11 KiB
Perl
387 lines
11 KiB
Perl
@c
|
|
@c COPYRIGHT (c) 1996.
|
|
@c On-Line Applications Research Corporation (OAR).
|
|
@c All rights reserved.
|
|
@c
|
|
@c $Id$
|
|
@c
|
|
|
|
@ifinfo
|
|
@node Dual-Ported Memory Manager, Dual-Ported Memory Manager Introduction, REGION_GET_SEGMENT_SIZE - Obtain size of a segment, Top
|
|
@end ifinfo
|
|
@chapter Dual-Ported Memory Manager
|
|
@ifinfo
|
|
@menu
|
|
* Dual-Ported Memory Manager Introduction::
|
|
* Dual-Ported Memory Manager Background::
|
|
* Dual-Ported Memory Manager Operations::
|
|
* Dual-Ported Memory Manager Directives::
|
|
@end menu
|
|
@end ifinfo
|
|
|
|
@ifinfo
|
|
@node Dual-Ported Memory Manager Introduction, Dual-Ported Memory Manager Background, Dual-Ported Memory Manager, Dual-Ported Memory Manager
|
|
@end ifinfo
|
|
@section 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:
|
|
|
|
@itemize @bullet
|
|
@item @code{port_create} - Create a port
|
|
@item @code{port_ident} - Get ID of a port
|
|
@item @code{port_delete} - Delete a port
|
|
@item @code{port_external_to_internal} - Convert external to internal address
|
|
@item @code{port_internal_to_external} - Convert internal to external address
|
|
@end itemize
|
|
|
|
@ifinfo
|
|
@node Dual-Ported Memory Manager Background, Dual-Ported Memory Manager Operations, Dual-Ported Memory Manager Introduction, Dual-Ported Memory Manager
|
|
@end ifinfo
|
|
@section 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.
|
|
|
|
@ifinfo
|
|
@node Dual-Ported Memory Manager Operations, Creating a Port, Dual-Ported Memory Manager Background, Dual-Ported Memory Manager
|
|
@end ifinfo
|
|
@section Operations
|
|
@ifinfo
|
|
@menu
|
|
* Creating a Port::
|
|
* Obtaining Port IDs::
|
|
* Converting an Address::
|
|
* Deleting a DPMA Port::
|
|
@end menu
|
|
@end ifinfo
|
|
|
|
@ifinfo
|
|
@node Creating a Port, Obtaining Port IDs, Dual-Ported Memory Manager Operations, Dual-Ported Memory Manager Operations
|
|
@end ifinfo
|
|
@subsection Creating a Port
|
|
|
|
The 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.
|
|
|
|
@ifinfo
|
|
@node Obtaining Port IDs, Converting an Address, Creating a Port, Dual-Ported Memory Manager Operations
|
|
@end ifinfo
|
|
@subsection 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 port_create directive, the task
|
|
ID is stored in a user provided location. Second, the port ID
|
|
may be obtained later using the port_ident directive. The port
|
|
ID is used by other dual-ported memory manager directives to
|
|
access this port.
|
|
|
|
@ifinfo
|
|
@node Converting an Address, Deleting a DPMA Port, Obtaining Port IDs, Dual-Ported Memory Manager Operations
|
|
@end ifinfo
|
|
@subsection Converting an Address
|
|
|
|
The port_external_to_internal directive is used to
|
|
convert an address from external to internal representation for
|
|
the specified port. The 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.
|
|
|
|
@ifinfo
|
|
@node Deleting a DPMA Port, Dual-Ported Memory Manager Directives, Converting an Address, Dual-Ported Memory Manager Operations
|
|
@end ifinfo
|
|
@subsection Deleting a DPMA Port
|
|
|
|
A port can be removed from the system and returned to
|
|
RTEMS with the port_delete directive. When a port is deleted,
|
|
its control block is returned to the DPCB free list.
|
|
|
|
@ifinfo
|
|
@node Dual-Ported Memory Manager Directives, PORT_CREATE - Create a port, Deleting a DPMA Port, Dual-Ported Memory Manager
|
|
@end ifinfo
|
|
@section Directives
|
|
@ifinfo
|
|
@menu
|
|
* PORT_CREATE - Create a port::
|
|
* PORT_IDENT - Get ID of a port::
|
|
* PORT_DELETE - Delete a port::
|
|
* PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address::
|
|
* PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address::
|
|
@end menu
|
|
@end ifinfo
|
|
|
|
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.
|
|
|
|
@page
|
|
@ifinfo
|
|
@node PORT_CREATE - Create a port, PORT_IDENT - Get ID of a port, Dual-Ported Memory Manager Directives, Dual-Ported Memory Manager Directives
|
|
@end ifinfo
|
|
@subsection PORT_CREATE - Create a port
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@example
|
|
rtems_status_code rtems_port_create(
|
|
rtems_name name,
|
|
void *internal_start,
|
|
void *external_start,
|
|
rtems_unsigned32 length,
|
|
rtems_id *id
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
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
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{SUCCESSFUL} - port created successfully@*
|
|
@code{INVALID_NAME} - invalid task name@*
|
|
@code{INVALID_ADDRESS} - address not on four byte boundary@*
|
|
@code{TOO_MANY} - too many DP memory areas created
|
|
|
|
@subheading 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.
|
|
|
|
@subheading 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.
|
|
|
|
@page
|
|
@ifinfo
|
|
@node PORT_IDENT - Get ID of a port, PORT_DELETE - Delete a port, PORT_CREATE - Create a port, Dual-Ported Memory Manager Directives
|
|
@end ifinfo
|
|
@subsection PORT_IDENT - Get ID of a port
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@example
|
|
rtems_status_code rtems_port_ident(
|
|
rtems_name name,
|
|
rtems_id *id
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure Port_Ident (
|
|
Name : in RTEMS.Name;
|
|
ID : out RTEMS.ID;
|
|
Result : out RTEMS.Status_Codes
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{SUCCESSFUL} - port identified successfully@*
|
|
@code{INVALID_NAME} - port name not found
|
|
|
|
@subheading 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.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive will not cause the running task to be
|
|
preempted.
|
|
|
|
@page
|
|
@ifinfo
|
|
@node PORT_DELETE - Delete a port, PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, PORT_IDENT - Get ID of a port, Dual-Ported Memory Manager Directives
|
|
@end ifinfo
|
|
@subsection PORT_DELETE - Delete a port
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@example
|
|
rtems_status_code rtems_port_delete(
|
|
rtems_id id
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure Port_Delete (
|
|
ID : in RTEMS.ID;
|
|
Result : out RTEMS.Status_Codes
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{SUCCESSFUL} - port deleted successfully@*
|
|
@code{INVALID_ID} - invalid port id
|
|
|
|
@subheading 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.
|
|
|
|
@subheading 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.
|
|
|
|
@page
|
|
@ifinfo
|
|
@node PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, PORT_DELETE - Delete a port, Dual-Ported Memory Manager Directives
|
|
@end ifinfo
|
|
@subsection PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@example
|
|
rtems_status_code rtems_port_external_to_internal(
|
|
rtems_id id,
|
|
void *external,
|
|
void **internal
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure Port_External_To_Internal (
|
|
ID : in RTEMS.ID;
|
|
External : in RTEMS.Address;
|
|
Internal : out RTEMS.Address;
|
|
Result : out RTEMS.Status_Codes
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{SUCCESSFUL} - always successful
|
|
|
|
@subheading 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.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive is callable from an ISR.
|
|
|
|
This directive will not cause the calling task to be
|
|
preempted.
|
|
|
|
@page
|
|
@ifinfo
|
|
@node PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address, I/O Manager, PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address, Dual-Ported Memory Manager Directives
|
|
@end ifinfo
|
|
@subsection PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
|
|
|
|
@subheading CALLING SEQUENCE:
|
|
|
|
@ifset is-C
|
|
@example
|
|
rtems_status_code rtems_port_internal_to_external(
|
|
rtems_id id,
|
|
void *internal,
|
|
void **external
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@ifset is-Ada
|
|
@example
|
|
procedure Port_Internal_To_External (
|
|
ID : in RTEMS.ID;
|
|
Internal : in RTEMS.Address;
|
|
External : out RTEMS.Address;
|
|
Result : out RTEMS.Status_Codes
|
|
);
|
|
@end example
|
|
@end ifset
|
|
|
|
@subheading DIRECTIVE STATUS CODES:
|
|
@code{SUCCESSFUL} - always successful
|
|
|
|
@subheading 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.
|
|
|
|
@subheading NOTES:
|
|
|
|
This directive is callable from an ISR.
|
|
|
|
This directive will not cause the calling task to be
|
|
preempted.
|
|
|