summaryrefslogtreecommitdiffstats
path: root/c-user/dual_ports_memory_manager.rst
blob: 18b58089ea74ef9fbc7db339a56bbe733d0c969c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
.. comment SPDX-License-Identifier: CC-BY-SA-4.0

.. COMMENT: COPYRIGHT (c) 1988-2008.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

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.

.. raw:: latex

   \clearpage

.. _rtems_port_create:

PORT_CREATE - Create a port
---------------------------
.. index:: create a port
.. index:: rtems_port_create

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:
    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.

.. raw:: latex

   \clearpage

.. _rtems_port_ident:

PORT_IDENT - Get ID of a port
-----------------------------
.. index:: get ID of a port
.. index:: obtain ID of a port
.. index:: rtems_port_ident

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

.. _rtems_port_delete:

PORT_DELETE - Delete a port
---------------------------
.. index:: delete a port
.. index:: rtems_port_delete

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 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.

.. raw:: latex

   \clearpage

.. _rtems_port_external_to_internal:

PORT_EXTERNAL_TO_INTERNAL - Convert external to internal address
----------------------------------------------------------------
.. index:: convert external to internal address
.. index:: rtems_port_external_to_internal

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

.. _rtems_port_internal_to_external:

PORT_INTERNAL_TO_EXTERNAL - Convert internal to external address
----------------------------------------------------------------
.. index:: convert internal to external address
.. index:: rtems_port_internal_to_external

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.