source: rtems/cpukit/include/rtems/rtems/dpmem.h @ 6abdd89

Last change on this file since 6abdd89 was 6abdd89, checked in by Sebastian Huber <sebastian.huber@…>, on Jun 14, 2021 at 7:57:51 AM

Use a common phrase for pointer parameters

Mention the type of the pointer in the parameter description. Use the
more general term "object" instead of "variable".

Update #3993.

  • Property mode set to 100644
File size: 11.1 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @brief This header file defines the Dual-Ported Memory Manager API.
7 */
8
9/*
10 * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
11 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 * 1. Redistributions of source code must retain the above copyright
17 *    notice, this list of conditions and the following disclaimer.
18 * 2. Redistributions in binary form must reproduce the above copyright
19 *    notice, this list of conditions and the following disclaimer in the
20 *    documentation and/or other materials provided with the distribution.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
26 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 * POSSIBILITY OF SUCH DAMAGE.
33 */
34
35/*
36 * This file is part of the RTEMS quality process and was automatically
37 * generated.  If you find something that needs to be fixed or
38 * worded better please post a report or patch to an RTEMS mailing list
39 * or raise a bug report:
40 *
41 * https://www.rtems.org/bugs.html
42 *
43 * For information on updating and regenerating please refer to the How-To
44 * section in the Software Requirements Engineering chapter of the
45 * RTEMS Software Engineering manual.  The manual is provided as a part of
46 * a release.  For development sources please refer to the online
47 * documentation at:
48 *
49 * https://docs.rtems.org
50 */
51
52/* Generated from spec:/rtems/dpmem/if/header */
53
54#ifndef _RTEMS_RTEMS_DPMEM_H
55#define _RTEMS_RTEMS_DPMEM_H
56
57#include <stdint.h>
58#include <rtems/rtems/status.h>
59#include <rtems/rtems/types.h>
60
61#ifdef __cplusplus
62extern "C" {
63#endif
64
65/* Generated from spec:/rtems/dpmem/if/group */
66
67/**
68 * @defgroup RTEMSAPIClassicDPMem Dual-Ported Memory Manager
69 *
70 * @ingroup RTEMSAPIClassic
71 *
72 * @brief The Dual-Ported Memory Manager provides a mechanism for converting
73 *   addresses between internal and external representations for multiple
74 *   dual-ported memory areas (DPMA).
75 */
76
77/* Generated from spec:/rtems/dpmem/if/create */
78
79/**
80 * @ingroup RTEMSAPIClassicDPMem
81 *
82 * @brief Creates a port.
83 *
84 * @param name is the object name of the port.
85 *
86 * @param internal_start is the internal start address of the memory area.
87 *
88 * @param external_start is the external start address of the memory area.
89 *
90 * @param length is the length in bytes of the memory area.
91 *
92 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
93 *   call is successful, the identifier of the created port will be stored in
94 *   this object.
95 *
96 * This directive creates a port which resides on the local node.  The port has
97 * the user-defined object name specified in ``name``.  The assigned object
98 * identifier is returned in ``id``.  This identifier is used to access the
99 * port with other dual-ported memory port related directives.
100 *
101 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
102 *
103 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
104 *
105 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
106 *
107 * @retval ::RTEMS_INVALID_ADDRESS The ``internal_start`` parameter was not
108 *   properly aligned.
109 *
110 * @retval ::RTEMS_INVALID_ADDRESS The ``external_start`` parameter was not
111 *   properly aligned.
112 *
113 * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
114 *   port.  The number of port available to the application is configured
115 *   through the #CONFIGURE_MAXIMUM_PORTS application configuration option.
116 *
117 * @par Notes
118 * @parblock
119 * The ``internal_start`` and ``external_start`` parameters must be on a
120 * boundary defined by the target processor architecture.
121 *
122 * For control and maintenance of the port, RTEMS allocates a DPCB from the
123 * local DPCB free pool and initializes it.
124 * @endparblock
125 *
126 * @par Constraints
127 * @parblock
128 * The following constraints apply to this directive:
129 *
130 * * The directive may be called from within device driver initialization
131 *   context.
132 *
133 * * The directive may be called from within task context.
134 *
135 * * The directive may obtain and release the object allocator mutex.  This may
136 *   cause the calling task to be preempted.
137 *
138 * * The number of ports available to the application is configured through the
139 *   #CONFIGURE_MAXIMUM_PORTS application configuration option.
140 *
141 * * Where the object class corresponding to the directive is configured to use
142 *   unlimited objects, the directive may allocate memory from the RTEMS
143 *   Workspace.
144 * @endparblock
145 */
146rtems_status_code rtems_port_create(
147  rtems_name name,
148  void      *internal_start,
149  void      *external_start,
150  uint32_t   length,
151  rtems_id  *id
152);
153
154/* Generated from spec:/rtems/dpmem/if/ident */
155
156/**
157 * @ingroup RTEMSAPIClassicDPMem
158 *
159 * @brief Identifies a port by the object name.
160 *
161 * @param name is the object name to look up.
162 *
163 * @param[out] id is the pointer to an ::rtems_id object.  When the directive
164 *   call is successful, the object identifier of an object with the specified
165 *   name will be stored in this object.
166 *
167 * This directive obtains a port identifier associated with the port name
168 * specified in ``name``.
169 *
170 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
171 *
172 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
173 *
174 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
175 *
176 * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
177 *   the local node.
178 *
179 * @par Notes
180 * @parblock
181 * If the port name is not unique, then the port identifier will match the
182 * first port with that name in the search order.  However, this port
183 * identifier is not guaranteed to correspond to the desired port.
184 *
185 * The objects are searched from lowest to the highest index.  Only the local
186 * node is searched.
187 *
188 * The port identifier is used with other dual-ported memory related directives
189 * to access the port.
190 * @endparblock
191 *
192 * @par Constraints
193 * @parblock
194 * The following constraints apply to this directive:
195 *
196 * * The directive may be called from within any runtime context.
197 *
198 * * The directive will not cause the calling task to be preempted.
199 * @endparblock
200 */
201rtems_status_code rtems_port_ident( rtems_name name, rtems_id *id );
202
203/* Generated from spec:/rtems/dpmem/if/delete */
204
205/**
206 * @ingroup RTEMSAPIClassicDPMem
207 *
208 * @brief Deletes the port.
209 *
210 * @param id is the port identifier.
211 *
212 * This directive deletes the port specified by ``id``.
213 *
214 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
215 *
216 * @retval ::RTEMS_INVALID_ID There was no port associated with the identifier
217 *   specified by ``id``.
218 *
219 * @par Notes
220 * The DPCB for the deleted port is reclaimed by RTEMS.
221 *
222 * @par Constraints
223 * @parblock
224 * The following constraints apply to this directive:
225 *
226 * * The directive may be called from within device driver initialization
227 *   context.
228 *
229 * * The directive may be called from within task context.
230 *
231 * * The directive may obtain and release the object allocator mutex.  This may
232 *   cause the calling task to be preempted.
233 *
234 * * The calling task does not have to be the task that created the object.
235 *   Any local task that knows the object identifier can delete the object.
236 *
237 * * Where the object class corresponding to the directive is configured to use
238 *   unlimited objects, the directive may free memory to the RTEMS Workspace.
239 * @endparblock
240 */
241rtems_status_code rtems_port_delete( rtems_id id );
242
243/* Generated from spec:/rtems/dpmem/if/external-to-internal */
244
245/**
246 * @ingroup RTEMSAPIClassicDPMem
247 *
248 * @brief Converts the external address to the internal address.
249 *
250 * @param id is the port identifier.
251 *
252 * @param external is the external address to convert.
253 *
254 * @param[out] internal is the pointer to a ``void`` pointer object.  When the
255 *   directive call is successful, the external address associated with the
256 *   internal address will be stored in this object.
257 *
258 * This directive converts a dual-ported memory address from external to
259 * internal representation for the specified port.  If the given external
260 * address is invalid for the specified port, then the internal address is set
261 * to the given external address.
262 *
263 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
264 *
265 * @retval ::RTEMS_INVALID_NAME The ``id`` parameter was invalid.
266 *
267 * @retval ::RTEMS_INVALID_ADDRESS The ``internal`` parameter was NULL.
268 *
269 * @par Constraints
270 * @parblock
271 * The following constraints apply to this directive:
272 *
273 * * The directive may be called from within interrupt context.
274 *
275 * * The directive may be called from within device driver initialization
276 *   context.
277 *
278 * * The directive may be called from within task context.
279 *
280 * * The directive will not cause the calling task to be preempted.
281 * @endparblock
282 */
283rtems_status_code rtems_port_external_to_internal(
284  rtems_id id,
285  void    *external,
286  void   **internal
287);
288
289/* Generated from spec:/rtems/dpmem/if/internal-to-external */
290
291/**
292 * @ingroup RTEMSAPIClassicDPMem
293 *
294 * @brief Converts the internal address to the external address.
295 *
296 * @param id is the port identifier.
297 *
298 * @param internal is the internal address to convert.
299 *
300 * @param[out] external is the pointer to a ``void`` pointer object.  When the
301 *   directive call is successful, the external address associated with the
302 *   internal address will be stored in this object.
303 *
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 *
310 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
311 *
312 * @retval ::RTEMS_INVALID_NAME The ``id`` parameter was invalid.
313 *
314 * @retval ::RTEMS_INVALID_ADDRESS The ``external`` parameter was NULL.
315 *
316 * @par Constraints
317 * @parblock
318 * The following constraints apply to this directive:
319 *
320 * * The directive may be called from within interrupt context.
321 *
322 * * The directive may be called from within device driver initialization
323 *   context.
324 *
325 * * The directive may be called from within task context.
326 *
327 * * The directive will not cause the calling task to be preempted.
328 * @endparblock
329 */
330rtems_status_code rtems_port_internal_to_external(
331  rtems_id id,
332  void    *internal,
333  void   **external
334);
335
336#ifdef __cplusplus
337}
338#endif
339
340#endif /* _RTEMS_RTEMS_DPMEM_H */
Note: See TracBrowser for help on using the repository browser.