source: rtems/cpukit/include/rtems/rtems/region.h @ b3d3186d

Last change on this file since b3d3186d was b3d3186d, checked in by Sebastian Huber <sebastian.huber@…>, on Jun 24, 2020 at 5:10:06 AM

rtems: Generate <rtems/rtems/region.h>

Change license to BSD-2-Clause according to file histories and
documentation re-licensing agreement.

Update #3899.
Update #3993.

  • Property mode set to 100644
File size: 25.3 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @brief This header file defines the Region 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/region/if/header */
53
54#ifndef _RTEMS_RTEMS_REGION_H
55#define _RTEMS_RTEMS_REGION_H
56
57#include <stdint.h>
58#include <rtems/rtems/attr.h>
59#include <rtems/rtems/options.h>
60#include <rtems/rtems/status.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/region/if/group */
69
70/**
71 * @defgroup RTEMSAPIClassicRegion Region Manager
72 *
73 * @ingroup RTEMSAPIClassic
74 *
75 * @brief The Region Manager provides facilities to dynamically allocate memory
76 *   in variable sized units.
77 */
78
79/* Generated from spec:/rtems/region/if/get-segment-size */
80
81/**
82 * @ingroup RTEMSAPIClassicRegion
83 *
84 * @brief Gets the size of the region segment.
85 *
86 * @param id is the region identifier.
87 *
88 * @param segment is the begin address of the segment.
89 *
90 * @param[out] size is the pointer to a uintptr_t variable.  When the directive
91 *   call is successful, the size of the segment in bytes will be stored in
92 *   this variable.
93 *
94 * This directive obtains the size in bytes of the segment specified by
95 * ``segment`` of the region specified by ``id`` in ``size``.
96 *
97 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
98 *
99 * @retval ::RTEMS_INVALID_ADDRESS The ``segment`` parameter was NULL.
100 *
101 * @retval ::RTEMS_INVALID_ADDRESS The ``size`` parameter was NULL.
102 *
103 * @retval ::RTEMS_INVALID_ID There was no region associated with the
104 *   identifier specified by ``id``.
105 *
106 * @retval ::RTEMS_INVALID_ADDRESS The segment was not within the region.
107 *
108 * @par Notes
109 * The actual length of the allocated segment may be larger than the requested
110 * size because a segment size is always a multiple of the region's page size.
111 *
112 * @par Constraints
113 * @parblock
114 * The following constraints apply to this directive:
115 *
116 * * The directive may be called from within device driver initialization
117 *   context.
118 *
119 * * The directive may be called from within task context.
120 *
121 * * The directive may obtain and release the object allocator mutex.  This may
122 *   cause the calling task to be preempted.
123 * @endparblock
124 */
125rtems_status_code rtems_region_get_segment_size(
126  rtems_id   id,
127  void      *segment,
128  uintptr_t *size
129);
130
131/* Generated from spec:/rtems/region/if/create */
132
133/**
134 * @ingroup RTEMSAPIClassicRegion
135 *
136 * @brief Creates a region.
137 *
138 * @param name is the object name of the region.
139 *
140 * @param starting_address is the starting address of the memory area managed
141 *   by the region.
142 *
143 * @param length is the length in bytes of the memory area managed by the
144 *   region.
145 *
146 * @param page_size is the alignment of the starting address and length of each
147 *   allocated segment of the region.
148 *
149 * @param attribute_set is the attribute set of the region.
150 *
151 * @param[out] id is the pointer to an object identifier variable.  When the
152 *   directive call is successful, the identifier of the created region will be
153 *   stored in this variable.
154 *
155 * This directive creates a region which resides on the local node.  The region
156 * has the user-defined object name specified in ``name``.  The assigned object
157 * identifier is returned in ``id``.  This identifier is used to access the
158 * region with other region related directives.
159 *
160 * The region manages the **contiguous memory area** which starts at
161 * ``starting_address`` and is ``length`` bytes long.  The memory area shall be
162 * large enough to contain some internal region administration data.
163 *
164 * The **starting address** and **length of segments** allocated from the
165 * region will be an integral multiple of ``page_size``.  The specified page
166 * size will be aligned to an implementation-dependent minimum alignment if
167 * necessary.
168 *
169 * The **attribute set** specified in ``attribute_set`` is built through a
170 * *bitwise or* of the attribute constants described below.  Not all
171 * combinations of attributes are allowed.  Some attributes are mutually
172 * exclusive.  If mutually exclusive attributes are combined, the behaviour is
173 * undefined.  Attributes not mentioned below are not evaluated by this
174 * directive and have no effect.  Default attributes can be selected by using
175 * the #RTEMS_DEFAULT_ATTRIBUTES constant.
176 *
177 * The **task wait queue discipline** is selected by the mutually exclusive
178 * #RTEMS_FIFO and #RTEMS_PRIORITY attributes. The discipline defines the order
179 * in which tasks wait for allocatable segments on a currently empty region.
180 *
181 * * The **FIFO discipline** is the default and can be emphasized through use
182 *   of the #RTEMS_FIFO attribute.
183 *
184 * * The **priority discipline** is selected by the #RTEMS_PRIORITY attribute.
185 *
186 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
187 *
188 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
189 *
190 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
191 *
192 * @retval ::RTEMS_INVALID_ADDRESS The ``starting_address`` parameter was NULL.
193 *
194 * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
195 *   region.  The number of regions available to the application is configured
196 *   through the #CONFIGURE_MAXIMUM_REGIONS application configuration option.
197 *
198 * @retval ::RTEMS_INVALID_SIZE The ``page_size`` parameter was invalid.
199 *
200 * @retval ::RTEMS_INVALID_SIZE The memory area specified in
201 *   ``starting_address`` and ``length`` was too small.
202 *
203 * @par Notes
204 * For control and maintenance of the region, RTEMS allocates a RNCB from the
205 * local RNCB free pool and initializes it.
206 *
207 * @par Constraints
208 * @parblock
209 * The following constraints apply to this directive:
210 *
211 * * The directive may be called from within device driver initialization
212 *   context.
213 *
214 * * The directive may be called from within task context.
215 *
216 * * The directive may obtain and release the object allocator mutex.  This may
217 *   cause the calling task to be preempted.
218 *
219 * * The number of regions available to the application is configured through
220 *   the #CONFIGURE_MAXIMUM_REGIONS application configuration option.
221 *
222 * * Where the object class corresponding to the directive is configured to use
223 *   unlimited objects, the directive may allocate memory from the RTEMS
224 *   Workspace.
225 * @endparblock
226 */
227rtems_status_code rtems_region_create(
228  rtems_name      name,
229  void           *starting_address,
230  uintptr_t       length,
231  uintptr_t       page_size,
232  rtems_attribute attribute_set,
233  rtems_id       *id
234);
235
236/* Generated from spec:/rtems/region/if/ident */
237
238/**
239 * @ingroup RTEMSAPIClassicRegion
240 *
241 * @brief Identifies a region by the object name.
242 *
243 * @param name is the object name to look up.
244 *
245 * @param[out] id is the pointer to an object identifier variable.  When the
246 *   directive call is successful, the object identifier of an object with the
247 *   specified name will be stored in this variable.
248 *
249 * This directive obtains a region identifier associated with the region name
250 * specified in ``name``.
251 *
252 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
253 *
254 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
255 *
256 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
257 *
258 * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
259 *   the local node.
260 *
261 * @par Notes
262 * @parblock
263 * If the region name is not unique, then the region identifier will match the
264 * first region with that name in the search order.  However, this region
265 * identifier is not guaranteed to correspond to the desired region.
266 *
267 * The objects are searched from lowest to the highest index.  Only the local
268 * node is searched.
269 *
270 * The region identifier is used with other region related directives to access
271 * the region.
272 * @endparblock
273 *
274 * @par Constraints
275 * @parblock
276 * The following constraints apply to this directive:
277 *
278 * * The directive may be called from within any runtime context.
279 *
280 * * The directive will not cause the calling task to be preempted.
281 * @endparblock
282 */
283rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id );
284
285/* Generated from spec:/rtems/region/if/delete */
286
287/**
288 * @ingroup RTEMSAPIClassicRegion
289 *
290 * @brief Deletes the region.
291 *
292 * @param id is the region identifier.
293 *
294 * This directive deletes the region specified by ``id``.
295 *
296 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
297 *
298 * @retval ::RTEMS_INVALID_ID There was no region associated with the
299 *   identifier specified by ``id``.
300 *
301 * @retval ::RTEMS_RESOURCE_IN_USE There were segments of the region still in
302 *   use.
303 *
304 * @par Notes
305 * @parblock
306 * The region cannot be deleted if any of its segments are still allocated.
307 *
308 * The RNCB for the deleted region is reclaimed by RTEMS.
309 * @endparblock
310 *
311 * @par Constraints
312 * @parblock
313 * The following constraints apply to this directive:
314 *
315 * * The directive may be called from within device driver initialization
316 *   context.
317 *
318 * * The directive may be called from within task context.
319 *
320 * * The directive may obtain and release the object allocator mutex.  This may
321 *   cause the calling task to be preempted.
322 *
323 * * The calling task does not have to be the task that created the object.
324 *   Any local task that knows the object identifier can delete the object.
325 *
326 * * Where the object class corresponding to the directive is configured to use
327 *   unlimited objects, the directive may free memory to the RTEMS Workspace.
328 * @endparblock
329 */
330rtems_status_code rtems_region_delete( rtems_id id );
331
332/* Generated from spec:/rtems/region/if/extend */
333
334/**
335 * @ingroup RTEMSAPIClassicRegion
336 *
337 * @brief Extends the region.
338 *
339 * @param id is the region identifier.
340 *
341 * @param starting_address is the starting address of the memory area to extend
342 *   the region.
343 *
344 * @param length is the length in bytes of the memory area to extend the
345 *   region.
346 *
347 * This directive adds the memory area which starts at ``starting_address`` for
348 * ``length`` bytes to the region specified by ``id``.
349 *
350 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
351 *
352 * @retval ::RTEMS_INVALID_ADDRESS The ``starting_address`` parameter was NULL.
353 *
354 * @retval ::RTEMS_INVALID_ID There was no region associated with the
355 *   identifier specified by ``id``.
356 *
357 * @retval ::RTEMS_INVALID_ADDRESS The memory area specified by
358 *   ``starting_address`` and ``length`` was insufficient to extend the heap.
359 *
360 * @par Notes
361 * There are no alignment requirements for the memory area.  The memory area
362 * must be big enough to contain some maintenance blocks.  It must not overlap
363 * parts of the current heap memory areas.  Disconnected memory areas added to
364 * the heap will lead to used blocks which cover the gaps.  Extending with an
365 * inappropriate memory area will corrupt the heap resulting in undefined
366 * behaviour.
367 *
368 * @par Constraints
369 * @parblock
370 * The following constraints apply to this directive:
371 *
372 * * The directive may be called from within device driver initialization
373 *   context.
374 *
375 * * The directive may be called from within task context.
376 *
377 * * The directive may obtain and release the object allocator mutex.  This may
378 *   cause the calling task to be preempted.
379 * @endparblock
380 */
381rtems_status_code rtems_region_extend(
382  rtems_id  id,
383  void     *starting_address,
384  uintptr_t length
385);
386
387/* Generated from spec:/rtems/region/if/get-segment */
388
389/**
390 * @ingroup RTEMSAPIClassicRegion
391 *
392 * @brief Gets a segment from the region.
393 *
394 * @param id is the region identifier.
395 *
396 * @param size is the size in bytes of the segment to allocate.
397 *
398 * @param option_set is the option set.
399 *
400 * @param timeout is the timeout in clock ticks if the #RTEMS_WAIT option is
401 *   set.  Use #RTEMS_NO_TIMEOUT to wait potentially forever.
402 *
403 * @param segment is the pointer to a void pointer variable.  When the
404 *   directive call is successful, the begin address of the allocated segment
405 *   will be stored in this variable.
406 *
407 * This directive gets a segment from the region specified by ``id``.
408 *
409 * The **option set** specified in ``option_set`` is built through a *bitwise
410 * or* of the option constants described below.  Not all combinations of
411 * options are allowed.  Some options are mutually exclusive.  If mutually
412 * exclusive options are combined, the behaviour is undefined.  Options not
413 * mentioned below are not evaluated by this directive and have no effect.
414 * Default options can be selected by using the #RTEMS_DEFAULT_OPTIONS
415 * constant.
416 *
417 * The calling task can **wait** or **try to get** a segment from the region
418 * according to the mutually exclusive #RTEMS_WAIT and #RTEMS_NO_WAIT options.
419 *
420 * * **Waiting to get** a segment from the region is the default and can be
421 *   emphasized through the use of the #RTEMS_WAIT option. The ``timeout``
422 *   parameter defines how long the calling task is willing to wait.  Use
423 *   #RTEMS_NO_TIMEOUT to wait potentially forever, otherwise set a timeout
424 *   interval in clock ticks.
425 *
426 * * **Trying to get** a segment from the region is selected by the
427 *   #RTEMS_NO_WAIT option.  If this option is defined, then the ``timeout``
428 *   parameter is ignored.  When a segment from the region cannot be
429 *   immediately allocated, then the ::RTEMS_UNSATISFIED status is returned.
430 *
431 * With either #RTEMS_WAIT or #RTEMS_NO_WAIT if there is a segment of the
432 * requested size is available, then it is returned in ``segment`` and this
433 * directive returns immediately with the ::RTEMS_SUCCESSFUL status code.
434 *
435 * If the calling task chooses to return immediately and the region has no
436 * segment of the requested size available, then the directive returns
437 * immediately with the ::RTEMS_UNSATISFIED status code.  If the calling task
438 * chooses to wait for a segment, then the calling task is placed on the region
439 * wait queue and blocked.  If the region was created with the #RTEMS_PRIORITY
440 * option specified, then the calling task is inserted into the wait queue
441 * according to its priority.  But, if the region was created with the
442 * #RTEMS_FIFO option specified, then the calling task is placed at the rear of
443 * the wait queue.
444 *
445 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
446 *
447 * @retval ::RTEMS_INVALID_ADDRESS The ``segment`` parameter was NULL.
448 *
449 * @retval ::RTEMS_INVALID_SIZE The ``size`` parameter was zero.
450 *
451 * @retval ::RTEMS_INVALID_ID There was no region associated with the
452 *   identifier specified by ``id``.
453 *
454 * @retval ::RTEMS_INVALID_SIZE The ``size`` parameter exceeded the maximum
455 *   segment size which is possible for the region.
456 *
457 * @retval ::RTEMS_UNSATISFIED The region had no segment of the requested size
458 *   immediately available.
459 *
460 * @retval ::RTEMS_TIMEOUT The timeout happened while the calling task was
461 *   waiting to get a segment from the region.
462 *
463 * @par Notes
464 * The actual length of the allocated segment may be larger than the requested
465 * size because a segment size is always a multiple of the region's page size.
466 *
467 * @par Constraints
468 * @parblock
469 * The following constraints apply to this directive:
470 *
471 * * The directive may be called from within device driver initialization
472 *   context.
473 *
474 * * The directive may be called from within task context.
475 *
476 * * The directive may obtain and release the object allocator mutex.  This may
477 *   cause the calling task to be preempted.
478 *
479 * * When the request cannot be immediately satisfied and the #RTEMS_WAIT
480 *   option is set, the calling task blocks at some point during the directive
481 *   call.
482 *
483 * * The timeout functionality of the directive requires a clock tick.
484 * @endparblock
485 */
486rtems_status_code rtems_region_get_segment(
487  rtems_id       id,
488  uintptr_t      size,
489  rtems_option   option_set,
490  rtems_interval timeout,
491  void         **segment
492);
493
494/* Generated from spec:/rtems/region/if/return-segment */
495
496/**
497 * @ingroup RTEMSAPIClassicRegion
498 *
499 * @brief Returns the segment to the region.
500 *
501 * @param id is the region identifier.
502 *
503 * @param segment is the begin address of the segment to return.
504 *
505 * This directive returns the segment specified by ``segment`` to the region
506 * specified by ``id``.  The returned segment is merged with its neighbors to
507 * form the largest possible segment.  The first task on the wait queue is
508 * examined to determine if its segment request can now be satisfied.  If so,
509 * it is given a segment and unblocked.  This process is repeated until the
510 * first task's segment request cannot be satisfied.
511 *
512 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
513 *
514 * @retval ::RTEMS_INVALID_ID There was no region associated with the
515 *   identifier specified by ``id``.
516 *
517 * @retval ::RTEMS_INVALID_ADDRESS The segment was not within the region.
518 *
519 * @par Notes
520 * @parblock
521 * This directive will cause the calling task to be preempted if one or more
522 * local tasks are waiting for a segment and the following conditions exist:
523 *
524 * * A waiting task has a higher priority than the calling task.
525 *
526 * * The size of the segment required by the waiting task is less than or equal
527 *   to the size of the segment returned.
528 * @endparblock
529 *
530 * @par Constraints
531 * @parblock
532 * The following constraints apply to this directive:
533 *
534 * * The directive may be called from within device driver initialization
535 *   context.
536 *
537 * * The directive may be called from within task context.
538 *
539 * * The directive may unblock a task.  This may cause the calling task to be
540 *   preempted.
541 *
542 * * The directive may obtain and release the object allocator mutex.  This may
543 *   cause the calling task to be preempted.
544 * @endparblock
545 */
546rtems_status_code rtems_region_return_segment( rtems_id id, void *segment );
547
548/* Generated from spec:/rtems/region/if/resize-segment */
549
550/**
551 * @ingroup RTEMSAPIClassicRegion
552 *
553 * @brief Changes the size of the segment.
554 *
555 * @param id is the region identifier.
556 *
557 * @param segment is the begin address of the segment to resize.
558 *
559 * @param size is the requested new size of the segment.
560 *
561 * @param[out] old_size is the pointer to an uintptr_t variable.  When the
562 *   directive call is successful, the old size of the segment will be stored
563 *   in this variable.
564 *
565 * This directive is used to increase or decrease the size of the ``segment``
566 * of the region specified by ``id``.  When increasing the size of a segment,
567 * it is possible that there is no memory available contiguous to the segment.
568 * In this case, the request is unsatisfied.
569 *
570 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
571 *
572 * @retval ::RTEMS_INVALID_ADDRESS The ``old_size`` parameter was NULL.
573 *
574 * @retval ::RTEMS_INVALID_ID There was no region associated with the
575 *   identifier specified by ``id``.
576 *
577 * @retval ::RTEMS_INVALID_ADDRESS The segment was not within the region.
578 *
579 * @retval ::RTEMS_UNSATISFIED The region was unable to resize the segment.
580 *
581 * @par Notes
582 * If an attempt to increase the size of a segment fails, then the application
583 * may want to allocate a new segment of the desired size, copy the contents of
584 * the original segment to the new, larger segment and then return the original
585 * segment.
586 *
587 * @par Constraints
588 * @parblock
589 * The following constraints apply to this directive:
590 *
591 * * The directive may be called from within device driver initialization
592 *   context.
593 *
594 * * The directive may be called from within task context.
595 *
596 * * The directive may obtain and release the object allocator mutex.  This may
597 *   cause the calling task to be preempted.
598 * @endparblock
599 */
600rtems_status_code rtems_region_resize_segment(
601  rtems_id   id,
602  void      *segment,
603  uintptr_t  size,
604  uintptr_t *old_size
605);
606
607/* Generated from spec:/rtems/region/if/get-information */
608
609/**
610 * @ingroup RTEMSAPIClassicRegion
611 *
612 * @brief Gets the region information.
613 *
614 * @param id is the region identifier.
615 *
616 * @param[out] the_info is the pointer to a Heap_Information_block variable.
617 *   When the directive call is successful, the information of the region will
618 *   be stored in this variable.
619 *
620 * This directive is used to obtain information about the used and free memory
621 * in the region specified by ``id``. This is a snapshot at the time of the
622 * call. The information will be returned in the structure pointed to by
623 * ``the_info``.
624 *
625 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
626 *
627 * @retval ::RTEMS_INVALID_ADDRESS The ``the_info`` parameter was NULL.
628 *
629 * @retval ::RTEMS_INVALID_ID There was no region associated with the
630 *   identifier specified by ``id``.
631 *
632 * @par Notes
633 * @parblock
634 * This is primarily intended as a mechanism to obtain a diagnostic
635 * information. This method forms am O(n) scan of the free and an O(n) scan of
636 * the used blocks in the region to calculate the information provided. Given
637 * that the execution time is driven by the number of used and free blocks, it
638 * can take a non-deterministic time to execute.
639 *
640 * To get only the free information of the region use
641 * rtems_region_get_free_information().
642 * @endparblock
643 *
644 * @par Constraints
645 * @parblock
646 * The following constraints apply to this directive:
647 *
648 * * The directive may be called from within device driver initialization
649 *   context.
650 *
651 * * The directive may be called from within task context.
652 *
653 * * The directive may obtain and release the object allocator mutex.  This may
654 *   cause the calling task to be preempted.
655 * @endparblock
656 */
657rtems_status_code rtems_region_get_information(
658  rtems_id                id,
659  Heap_Information_block *the_info
660);
661
662/* Generated from spec:/rtems/region/if/get-free-information */
663
664/**
665 * @ingroup RTEMSAPIClassicRegion
666 *
667 * @brief Gets the region free information.
668 *
669 * @param id is the region identifier.
670 *
671 * @param[out] the_info is the pointer to a Heap_Information_block variable.
672 *   When the directive call is successful, the free information of the region
673 *   will be stored in this variable.
674 *
675 * This directive is used to obtain information about the free memory in the
676 * region specified by ``id``. This is a snapshot at the time of the call. The
677 * information will be returned in the structure pointed to by ``the_info``.
678 *
679 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
680 *
681 * @retval ::RTEMS_INVALID_ADDRESS The ``the_info`` parameter was NULL.
682 *
683 * @retval ::RTEMS_INVALID_ID There was no region associated with the
684 *   identifier specified by ``id``.
685 *
686 * @par Notes
687 * @parblock
688 * This directive uses the same structure to return information as the
689 * rtems_region_get_information() directive but does not fill in the used
690 * information.
691 *
692 * This is primarily intended as a mechanism to obtain a diagnostic
693 * information. This method forms am O(n) scan of the free in the region to
694 * calculate the information provided. Given that the execution time is driven
695 * by the number of used and free blocks, it can take a non-deterministic time
696 * to execute. Typically, there are many used blocks and a much smaller number
697 * of used blocks making a call to this directive less expensive than a call to
698 * rtems_region_get_information().
699 * @endparblock
700 *
701 * @par Constraints
702 * @parblock
703 * The following constraints apply to this directive:
704 *
705 * * The directive may be called from within device driver initialization
706 *   context.
707 *
708 * * The directive may be called from within task context.
709 *
710 * * The directive may obtain and release the object allocator mutex.  This may
711 *   cause the calling task to be preempted.
712 * @endparblock
713 */
714rtems_status_code rtems_region_get_free_information(
715  rtems_id                id,
716  Heap_Information_block *the_info
717);
718
719#ifdef __cplusplus
720}
721#endif
722
723#endif /* _RTEMS_RTEMS_REGION_H */
Note: See TracBrowser for help on using the repository browser.