source: rtems/cpukit/include/rtems/rtems/support.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: 12.2 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @brief This header file defines support services of the 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/support/if/header */
53
54#ifndef _RTEMS_RTEMS_SUPPORT_H
55#define _RTEMS_RTEMS_SUPPORT_H
56
57#include <stdbool.h>
58#include <stddef.h>
59#include <stdint.h>
60#include <rtems/config.h>
61#include <rtems/rtems/types.h>
62#include <rtems/score/heapinfo.h>
63
64#ifdef __cplusplus
65extern "C" {
66#endif
67
68/* Generated from spec:/rtems/support/if/group */
69
70/**
71 * @defgroup RTEMSAPIClassicSupport Support Services
72 *
73 * @ingroup RTEMSAPIClassic
74 *
75 * @brief Items of this group should move to other groups.
76 */
77
78/* Generated from spec:/rtems/support/if/is-name-valid */
79
80/**
81 * @ingroup RTEMSAPIClassicSupport
82 *
83 * @brief Checks if the object name is valid.
84 *
85 * @param name is the object name to check.
86 *
87 * @return Returns true, if the object name is valid, otherwise false.
88 *
89 * @par Constraints
90 * @parblock
91 * The following constraints apply to this directive:
92 *
93 * * The directive may be called from within any runtime context.
94 *
95 * * The directive will not cause the calling task to be preempted.
96 * @endparblock
97 */
98static inline bool rtems_is_name_valid( rtems_name name )
99{
100  return name != 0;
101}
102
103/* Generated from spec:/rtems/support/if/microseconds-to-ticks */
104
105/**
106 * @ingroup RTEMSAPIClassicSupport
107 *
108 * @brief Gets the number of clock ticks for the microseconds value.
109 *
110 * @param _us is the microseconds value to convert to clock ticks.
111 *
112 * @return Returns the number of clock ticks for the specified microseconds
113 *   value.
114 *
115 * @par Notes
116 * The number of clock ticks per second is defined by the
117 * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option.
118 *
119 * @par Constraints
120 * @parblock
121 * The following constraints apply to this directive:
122 *
123 * * The directive may be called from within any runtime context.
124 *
125 * * The directive will not cause the calling task to be preempted.
126 * @endparblock
127 */
128#define RTEMS_MICROSECONDS_TO_TICKS( _us ) \
129  ( ( _us ) / rtems_configuration_get_microseconds_per_tick() )
130
131/* Generated from spec:/rtems/support/if/milliseconds-to-microseconds */
132
133/**
134 * @ingroup RTEMSAPIClassicSupport
135 *
136 * @brief Gets the number of microseconds for the milliseconds value.
137 *
138 * @param _ms is the milliseconds value to convert to microseconds.
139 *
140 * @return Returns the number of microseconds for the milliseconds value.
141 *
142 * @par Constraints
143 * @parblock
144 * The following constraints apply to this directive:
145 *
146 * * The directive is implemented by a macro and may be called from within
147 *   C/C++ constant expressions.  In addition, a function implementation of the
148 *   directive exists for bindings to other programming languages.
149 *
150 * * The directive will not cause the calling task to be preempted.
151 * @endparblock
152 */
153#define RTEMS_MILLISECONDS_TO_MICROSECONDS( _ms ) ( ( _ms ) * 1000UL )
154
155/* Generated from spec:/rtems/support/if/milliseconds-to-ticks */
156
157/**
158 * @ingroup RTEMSAPIClassicSupport
159 *
160 * @brief Gets the number of clock ticks for the milliseconds value.
161 *
162 * @param _ms is the milliseconds value to convert to clock ticks.
163 *
164 * @return Returns the number of clock ticks for the milliseconds value.
165 *
166 * @par Notes
167 * The number of clock ticks per second is defined by the
168 * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option.
169 *
170 * @par Constraints
171 * @parblock
172 * The following constraints apply to this directive:
173 *
174 * * The directive may be called from within any runtime context.
175 *
176 * * The directive will not cause the calling task to be preempted.
177 * @endparblock
178 */
179#define RTEMS_MILLISECONDS_TO_TICKS( _ms ) \
180  RTEMS_MICROSECONDS_TO_TICKS( RTEMS_MILLISECONDS_TO_MICROSECONDS( _ms ) )
181
182/* Generated from spec:/rtems/support/if/name-to-characters */
183
184/**
185 * @ingroup RTEMSAPIClassicSupport
186 *
187 * @brief Breaks the object name into the four component characters.
188 *
189 * @param name is the object name to break into four component characters.
190 *
191 * @param[out] c1 is the first character of the object name.
192 *
193 * @param[out] c2 is the second character of the object name.
194 *
195 * @param[out] c3 is the third character of the object name.
196 *
197 * @param[out] c4 is the fourth character of the object name.
198 *
199 * @par Constraints
200 * @parblock
201 * The following constraints apply to this directive:
202 *
203 * * The directive may be called from within any runtime context.
204 *
205 * * The directive will not cause the calling task to be preempted.
206 * @endparblock
207 */
208static inline void rtems_name_to_characters(
209  rtems_name name,
210  char      *c1,
211  char      *c2,
212  char      *c3,
213  char      *c4
214)
215{
216  *c1 = (char) ( ( ( name ) >> 24 ) & 0xff );
217  *c2 = (char) ( ( ( name ) >> 16 ) & 0xff );
218  *c3 = (char) ( ( ( name ) >> 8 ) & 0xff );
219  *c4 = (char) ( ( name ) & 0xff );
220}
221
222/* Generated from spec:/rtems/support/if/workspace-allocate */
223
224/**
225 * @ingroup RTEMSAPIClassicSupport
226 *
227 * @brief Allocates a memory area from the RTEMS Workspace.
228 *
229 * @param bytes is the number of bytes to allocated.
230 *
231 * @param[out] pointer is the pointer to a ``void`` pointer object.  When the
232 *   directive call is successful, the begin address of the allocated memory
233 *   area will be stored in this object.
234 *
235 * @return Returns true, if the allocation was successful, otherwise false.
236 *
237 * @par Notes
238 * This directive is intended to be used by tests of the RTEMS test suites.
239 *
240 * @par Constraints
241 * @parblock
242 * The following constraints apply to this directive:
243 *
244 * * The directive may be called from within device driver initialization
245 *   context.
246 *
247 * * The directive may be called from within task context.
248 *
249 * * The directive may obtain and release the object allocator mutex.  This may
250 *   cause the calling task to be preempted.
251 * @endparblock
252 */
253bool rtems_workspace_allocate( size_t bytes, void **pointer );
254
255/* Generated from spec:/rtems/support/if/workspace-free */
256
257/**
258 * @ingroup RTEMSAPIClassicSupport
259 *
260 * @brief Frees the memory area allocated from the RTEMS Workspace.
261 *
262 * @param pointer is the begin address of the memory area to free.
263 *
264 * @return Returns true, if freeing the memory area was successful, otherwise
265 *   false.
266 *
267 * @par Constraints
268 * @parblock
269 * The following constraints apply to this directive:
270 *
271 * * The directive may be called from within device driver initialization
272 *   context.
273 *
274 * * The directive may be called from within task context.
275 *
276 * * The directive may obtain and release the object allocator mutex.  This may
277 *   cause the calling task to be preempted.
278 * @endparblock
279 */
280bool rtems_workspace_free( void *pointer );
281
282/* Generated from spec:/rtems/support/if/workspace-get-information */
283
284/**
285 * @ingroup RTEMSAPIClassicSupport
286 *
287 * @brief Gets information about the RTEMS Workspace.
288 *
289 * @param[out] the_info is the pointer to a Heap_Information_block object.
290 *   When the directive call is successful, the heap information will be stored
291 *   in this object.
292 *
293 * @return Returns true, if getting the information was successful, otherwise
294 *   false.
295 *
296 * @par Constraints
297 * @parblock
298 * The following constraints apply to this directive:
299 *
300 * * The directive may be called from within device driver initialization
301 *   context.
302 *
303 * * The directive may be called from within task context.
304 *
305 * * The directive may obtain and release the object allocator mutex.  This may
306 *   cause the calling task to be preempted.
307 * @endparblock
308 */
309bool rtems_workspace_get_information( Heap_Information_block *the_info );
310
311/* Generated from spec:/rtems/support/if/workspace-greedy-allocate */
312
313/**
314 * @ingroup RTEMSAPIClassicSupport
315 *
316 * @brief Greedy allocates that empties the RTEMS Workspace.
317 *
318 * @param block_sizes is the array of block sizes.
319 *
320 * @param block_count is the block count.
321 *
322 * Afterwards the heap has at most ``block_count`` allocatable blocks of sizes
323 * specified by ``block_sizes``.  The ``block_sizes`` must point to an array
324 * with ``block_count`` members.  All other blocks are used.
325 *
326 * @return The returned pointer value may be used to free the greedy allocation
327 *   by calling rtems_workspace_greedy_free().
328 */
329void *rtems_workspace_greedy_allocate(
330  const uintptr_t *block_sizes,
331  size_t           block_count
332);
333
334/* Generated from spec:/rtems/support/if/workspace-greedy-allocate-all-except-largest */
335
336/**
337 * @ingroup RTEMSAPIClassicSupport
338 *
339 * @brief Greedy allocates all blocks of the RTEMS Workspace except the largest
340 *   free block.
341 *
342 * @param allocatable_size is the remaining allocatable size.
343 *
344 * Afterwards the heap has at most one allocatable block.  This block is the
345 * largest free block if it exists.  The allocatable size of this block is
346 * stored in ``allocatable_size``.  All other blocks are used.
347 *
348 * @return The returned pointer value may be used to free the greedy allocation
349 *   by calling rtems_workspace_greedy_free().
350 *
351 * @par Notes
352 * This directive is intended to be used by tests of the RTEMS test suites.
353 *
354 * @par Constraints
355 * @parblock
356 * The following constraints apply to this directive:
357 *
358 * * The directive may be called from within device driver initialization
359 *   context.
360 *
361 * * The directive may be called from within task context.
362 *
363 * * The directive may obtain and release the object allocator mutex.  This may
364 *   cause the calling task to be preempted.
365 * @endparblock
366 */
367void *rtems_workspace_greedy_allocate_all_except_largest(
368  uintptr_t *allocatable_size
369);
370
371/* Generated from spec:/rtems/support/if/workspace-greedy-free */
372
373/**
374 * @ingroup RTEMSAPIClassicSupport
375 *
376 * @brief Frees space of a greedy allocation to the RTEMS Workspace.
377 *
378 * @param opaque is the pointer value returned by
379 *   rtems_workspace_greedy_allocate() or
380 *   rtems_workspace_greedy_allocate_all_except_largest().
381 *
382 * @par Notes
383 * This directive is intended to be used by tests of the RTEMS test suites.
384 *
385 * @par Constraints
386 * @parblock
387 * The following constraints apply to this directive:
388 *
389 * * The directive may be called from within device driver initialization
390 *   context.
391 *
392 * * The directive may be called from within task context.
393 *
394 * * The directive may obtain and release the object allocator mutex.  This may
395 *   cause the calling task to be preempted.
396 * @endparblock
397 */
398void rtems_workspace_greedy_free( void *opaque );
399
400#ifdef __cplusplus
401}
402#endif
403
404#endif /* _RTEMS_RTEMS_SUPPORT_H */
Note: See TracBrowser for help on using the repository browser.