source: rtems-docs/c-user/dual_ports_memory_manager.rst @ c2ee227

5
Last change on this file since c2ee227 was 3384994, checked in by Chris Johns <chrisj@…>, on 11/13/17 at 02:25:18

Clean up sphinx warnings.

  • Fix minor formatting issues.
  • Fix reference the gloassary TLS using ':term:'.
  • Make sure nothing is between an anchor and the heading where ':ref:' references the anchor. This meant moving all the recently added '.. index::' entries.

Update #3232.
Update #3229.

  • Property mode set to 100644
File size: 9.2 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. COMMENT: COPYRIGHT (c) 1988-2008.
4.. COMMENT: On-Line Applications Research Corporation (OAR).
5.. COMMENT: All rights reserved.
6
7.. index:: ports
8.. index:: dual ported memory
9
10Dual-Ported Memory Manager
11**************************
12
13Introduction
14============
15
16The dual-ported memory manager provides a mechanism for converting addresses
17between internal and external representations for multiple dual-ported memory
18areas (DPMA).  The directives provided by the dual-ported memory manager are:
19
20- rtems_port_create_ - Create a port
21
22- rtems_port_ident_ - Get ID of a port
23
24- rtems_port_delete_ - Delete a port
25
26- rtems_port_external_to_internal_ - Convert external to internal address
27
28- rtems_port_internal_to_external_ - Convert internal to external address
29
30.. index:: dual ported memory, definition
31.. index:: external addresses, definition
32.. index:: internal addresses, definition
33
34Background
35==========
36
37A dual-ported memory area (DPMA) is an contiguous block of RAM owned by a
38particular processor but which can be accessed by other processors in the
39system.  The owner accesses the memory using internal addresses, while other
40processors must use external addresses.  RTEMS defines a port as a particular
41mapping of internal and external addresses.
42
43There are two system configurations in which dual-ported memory is commonly
44found.  The first is tightly-coupled multiprocessor computer systems where the
45dual-ported memory is shared between all nodes and is used for inter-node
46communication.  The second configuration is computer systems with intelligent
47peripheral controllers.  These controllers typically utilize the DPMA for
48high-performance data transfers.
49
50Operations
51==========
52
53Creating a Port
54---------------
55
56The ``rtems_port_create`` directive creates a port into a DPMA with the
57user-defined name.  The user specifies the association between internal and
58external representations for the port being created.  RTEMS allocates a
59Dual-Ported Memory Control Block (DPCB) from the DPCB free list to maintain the
60newly created DPMA.  RTEMS also generates a unique dual-ported memory port ID
61which is returned to the calling task.  RTEMS does not initialize the
62dual-ported memory area or access any memory within it.
63
64Obtaining Port IDs
65------------------
66
67When a port is created, RTEMS generates a unique port ID and assigns it to the
68created port until it is deleted.  The port ID may be obtained by either of two
69methods.  First, as the result of an invocation of the``rtems_port_create``
70directive, the task ID is stored in a user provided location.  Second, the port
71ID may be obtained later using the ``rtems_port_ident`` directive.  The port ID
72is used by other dual-ported memory manager directives to access this port.
73
74Converting an Address
75---------------------
76
77The ``rtems_port_external_to_internal`` directive is used to convert an address
78from external to internal representation for the specified port.  The
79``rtems_port_internal_to_external`` directive is used to convert an address
80from internal to external representation for the specified port.  If an attempt
81is made to convert an address which lies outside the specified DPMA, then the
82address to be converted will be returned.
83
84Deleting a DPMA Port
85--------------------
86
87A port can be removed from the system and returned to RTEMS with the
88``rtems_port_delete`` directive.  When a port is deleted, its control block is
89returned to the DPCB free list.
90
91Directives
92==========
93
94This section details the dual-ported memory manager's directives.  A subsection
95is dedicated to each of this manager's directives and describes the calling
96sequence, related constants, usage, and status codes.
97
98.. raw:: latex
99
100   \clearpage
101
102.. index:: create a port
103.. index:: rtems_port_create
104
105.. _rtems_port_create:
106
107PORT_CREATE - Create a port
108---------------------------
109
110CALLING SEQUENCE:
111    .. code-block:: c
112
113        rtems_status_code rtems_port_create(
114            rtems_name  name,
115            void       *internal_start,
116            void       *external_start,
117            uint32_t    length,
118            rtems_id   *id
119        );
120
121DIRECTIVE STATUS CODES:
122    .. list-table::
123     :class: rtems-table
124
125     * - ``RTEMS_SUCCESSFUL``
126       - port created successfully
127     * - ``RTEMS_INVALID_NAME``
128       - invalid port name
129     * - ``RTEMS_INVALID_ADDRESS``
130       - address not on four byte boundary
131     * - ``RTEMS_INVALID_ADDRESS``
132       - ``id`` is NULL
133     * - ``RTEMS_TOO_MANY``
134       - too many DP memory areas created
135
136DESCRIPTION:
137    This directive creates a port which resides on the local node for the
138    specified DPMA.  The assigned port id is returned in id.  This port id is
139    used as an argument to other dual-ported memory manager directives to
140    convert addresses within this DPMA.
141
142    For control and maintenance of the port, RTEMS allocates and initializes an
143    DPCB from the DPCB free pool.  Thus memory from the dual-ported memory area
144    is not used to store the DPCB.
145
146NOTES:
147    The internal_address and external_address parameters must be on a four byte
148    boundary.
149
150    This directive will not cause the calling task to be preempted.
151
152.. raw:: latex
153
154   \clearpage
155
156.. index:: get ID of a port
157.. index:: obtain ID of a port
158.. index:: rtems_port_ident
159
160.. _rtems_port_ident:
161
162PORT_IDENT - Get ID of a port
163-----------------------------
164
165CALLING SEQUENCE:
166    .. code-block:: c
167
168        rtems_status_code rtems_port_ident(
169            rtems_name  name,
170            rtems_id   *id
171        );
172
173DIRECTIVE STATUS CODES:
174    .. list-table::
175     :class: rtems-table
176
177     * - ``RTEMS_SUCCESSFUL``
178       - port identified successfully
179     * - ``RTEMS_INVALID_ADDRESS``
180       - ``id`` is NULL
181     * - ``RTEMS_INVALID_NAME``
182       - port name not found
183
184DESCRIPTION:
185    This directive obtains the port id associated with the specified name to be
186    acquired.  If the port name is not unique, then the port id will match one
187    of the DPMAs with that name.  However, this port id is not guaranteed to
188    correspond to the desired DPMA.  The port id is used to access this DPMA in
189    other dual-ported memory area related directives.
190
191NOTES:
192    This directive will not cause the running task to be preempted.
193
194.. raw:: latex
195
196   \clearpage
197
198.. index:: delete a port
199.. index:: rtems_port_delete
200
201.. _rtems_port_delete:
202
203PORT_DELETE - Delete a port
204---------------------------
205
206CALLING SEQUENCE:
207    .. code-block:: c
208
209        rtems_status_code rtems_port_delete(
210            rtems_id id
211        );
212
213DIRECTIVE STATUS CODES:
214    .. list-table::
215     :class: rtems-table
216
217     * - ``RTEMS_SUCCESSFUL``
218       - port deleted successfully
219     * - ``RTEMS_INVALID_ID``
220       - invalid port id
221
222DESCRIPTION:
223    This directive deletes the dual-ported memory area specified by id.  The
224    DPCB for the deleted dual-ported memory area is reclaimed by RTEMS.
225
226NOTES:
227    This directive will not cause the calling task to be preempted.
228
229    The calling task does not have to be the task that created the port.  Any
230    local task that knows the port id can delete the port.
231
232.. raw:: latex
233
234   \clearpage
235
236.. index:: convert external to internal address
237.. index:: rtems_port_external_to_internal
238
239.. _rtems_port_external_to_internal:
240
241PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
242----------------------------------------------------------------
243
244CALLING SEQUENCE:
245    .. code-block:: c
246
247        rtems_status_code rtems_port_external_to_internal(
248            rtems_id   id,
249            void      *external,
250            void     **internal
251        );
252
253DIRECTIVE STATUS CODES:
254    .. list-table::
255     :class: rtems-table
256
257     * - ``RTEMS_INVALID_ADDRESS``
258       - ``internal`` is NULL
259     * - ``RTEMS_SUCCESSFUL``
260       - successful conversion
261
262DESCRIPTION:
263    This directive converts a dual-ported memory address from external to
264    internal representation for the specified port.  If the given external
265    address is invalid for the specified port, then the internal address is set
266    to the given external address.
267
268NOTES:
269    This directive is callable from an ISR.
270
271    This directive will not cause the calling task to be preempted.
272
273.. raw:: latex
274
275   \clearpage
276
277.. index:: convert internal to external address
278.. index:: rtems_port_internal_to_external
279
280.. _rtems_port_internal_to_external:
281
282PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
283----------------------------------------------------------------
284
285CALLING SEQUENCE:
286    .. code-block:: c
287
288        rtems_status_code rtems_port_internal_to_external(
289            rtems_id   id,
290            void      *internal,
291            void     **external
292        );
293
294DIRECTIVE STATUS CODES:
295    .. list-table::
296     :class: rtems-table
297
298     * - ``RTEMS_INVALID_ADDRESS``
299       - ``external`` is NULL
300     * - ``RTEMS_SUCCESSFUL``
301       - successful conversion
302
303DESCRIPTION:
304    This directive converts a dual-ported memory address from internal to
305    external representation so that it can be passed to owner of the DPMA
306    represented by the specified port.  If the given internal address is an
307    invalid dual-ported address, then the external address is set to the given
308    internal address.
309
310NOTES:
311    This directive is callable from an ISR.
312
313    This directive will not cause the calling task to be preempted.
Note: See TracBrowser for help on using the repository browser.