summaryrefslogtreecommitdiffstats
path: root/c-user/region_manager.rst
blob: 70cf31d6576c8d062db9e209ae01f55bb1224fbb (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
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
.. 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.

Region Manager
**************

.. index:: regions

Introduction
============

The region manager provides facilities to dynamically allocate memory in
variable sized units.  The directives provided by the region manager are:

- rtems_region_create_ - Create a region

- rtems_region_ident_ - Get ID of a region

- rtems_region_delete_ - Delete a region

- rtems_region_extend_ - Add memory to a region

- rtems_region_get_segment_ - Get segment from a region

- rtems_region_return_segment_ - Return segment to a region

- rtems_region_get_segment_size_ - Obtain size of a segment

- rtems_region_resize_segment_ - Change size of a segment

Background
==========

Region Manager Definitions
--------------------------
.. index:: region, definition
.. index:: segment, definition

A region makes up a physically contiguous memory space with user-defined
boundaries from which variable-sized segments are dynamically allocated and
deallocated.  A segment is a variable size section of memory which is allocated
in multiples of a user-defined page size.  This page size is required to be a
multiple of four greater than or equal to four.  For example, if a request for
a 350-byte segment is made in a region with 256-byte pages, then a 512-byte
segment is allocated.

Regions are organized as doubly linked chains of variable sized memory blocks.
Memory requests are allocated using a first-fit algorithm.  If available, the
requester receives the number of bytes requested (rounded up to the next page
size).  RTEMS requires some overhead from the region's memory for each segment
that is allocated.  Therefore, an application should only modify the memory of
a segment that has been obtained from the region.  The application should NOT
modify the memory outside of any obtained segments and within the region's
boundaries while the region is currently active in the system.

Upon return to the region, the free block is coalesced with its neighbors (if
free) on both sides to produce the largest possible unused block.

Building an Attribute Set
-------------------------
.. index:: region attribute set, building

In general, an attribute set is built by a bitwise OR of the desired attribute
components.  The set of valid region attributes is provided in the following
table:

.. list-table::
 :class: rtems-table

 * - ``RTEMS_FIFO``
   - tasks wait by FIFO (default)
 * - ``RTEMS_PRIORITY``
   - tasks wait by priority

Attribute values are specifically designed to be mutually exclusive, therefore
bitwise OR and addition operations are equivalent as long as each attribute
appears exactly once in the component list.  An attribute listed as a default
is not required to appear in the attribute list, although it is a good
programming practice to specify default attributes.  If all defaults are
desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this
call.

This example demonstrates the attribute_set parameter needed to create a region
with the task priority waiting queue discipline.  The attribute_set parameter
to the ``rtems_region_create`` directive should be ``RTEMS_PRIORITY``.

Building an Option Set
----------------------

In general, an option is built by a bitwise OR of the desired option
components.  The set of valid options for the ``rtems_region_get_segment``
directive are listed in the following table:

.. list-table::
 :class: rtems-table

 * - ``RTEMS_WAIT``
   - task will wait for segment (default)
 * - ``RTEMS_NO_WAIT``
   - task should not wait

Option values are specifically designed to be mutually exclusive, therefore
bitwise OR and addition operations are equivalent as long as each option
appears exactly once in the component list.  An option listed as a default is
not required to appear in the option list, although it is a good programming
practice to specify default options.  If all defaults are desired, the
option ``RTEMS_DEFAULT_OPTIONS`` should be specified on this call.

This example demonstrates the option parameter needed to poll for a segment.
The option parameter passed to the ``rtems_region_get_segment`` directive
should be ``RTEMS_NO_WAIT``.

Operations
==========

Creating a Region
-----------------

The ``rtems_region_create`` directive creates a region with the user-defined
name.  The user may select FIFO or task priority as the method for placing
waiting tasks in the task wait queue.  RTEMS allocates a Region Control Block
(RNCB) from the RNCB free list to maintain the newly created region.  RTEMS
also generates a unique region ID which is returned to the calling task.

It is not possible to calculate the exact number of bytes available to the user
since RTEMS requires overhead for each segment allocated.  For example, a
region with one segment that is the size of the entire region has more
available bytes than a region with two segments that collectively are the size
of the entire region.  This is because the region with one segment requires
only the overhead for one segment, while the other region requires the overhead
for two segments.

Due to automatic coalescing, the number of segments in the region dynamically
changes.  Therefore, the total overhead required by RTEMS dynamically changes.

Obtaining Region IDs
--------------------

When a region is created, RTEMS generates a unique region ID and assigns it to
the created region until it is deleted.  The region ID may be obtained by
either of two methods.  First, as the result of an invocation of the
``rtems_region_create`` directive, the region ID is stored in a user provided
location.  Second, the region ID may be obtained later using the
``rtems_region_ident`` directive.  The region ID is used by other region
manager directives to access this region.

Adding Memory to a Region
-------------------------

The ``rtems_region_extend`` directive may be used to add memory to an existing
region.  The caller specifies the size in bytes and starting address of the
memory being added.

Acquiring a Segment
-------------------

The ``rtems_region_get_segment`` directive attempts to acquire a segment from a
specified region.  If the region has enough available free memory, then a
segment is returned successfully to the caller.  When the segment cannot be
allocated, one of the following situations applies:

- By default, the calling task will wait forever to acquire the segment.

- Specifying the ``RTEMS_NO_WAIT`` option forces an immediate return with an
  error status code.

- Specifying a timeout limits the interval the task will wait before returning
  with an error status code.

If the task waits for the segment, then it is placed in the region's task wait
queue in either FIFO or task priority order.  All tasks waiting on a region are
returned an error when the message queue is deleted.

Releasing a Segment
-------------------

When a segment is returned to a region by the ``rtems_region_return_segment``
directive, it is merged with its unallocated neighbors to form the largest
possible segment.  The first task on the wait queue is examined to determine if
its segment request can now be satisfied.  If so, it is given a segment and
unblocked.  This process is repeated until the first task's segment request
cannot be satisfied.

Obtaining the Size of a Segment
-------------------------------

The ``rtems_region_get_segment_size`` directive returns the size in bytes of
the specified segment.  The size returned includes any "extra" memory included
in the segment because of rounding up to a page size boundary.

Changing the Size of a Segment
------------------------------

The ``rtems_region_resize_segment`` directive is used to change the size in
bytes of the specified segment.  The size may be increased or decreased.  When
increasing the size of a segment, it is possible that the request cannot be
satisfied.  This directive provides functionality similar to the ``realloc()``
function in the Standard C Library.

Deleting a Region
-----------------

A region can be removed from the system and returned to RTEMS with the
``rtems_region_delete`` directive.  When a region is deleted, its control block
is returned to the RNCB free list.  A region with segments still allocated is
not allowed to be deleted.  Any task attempting to do so will be returned an
error.  As a result of this directive, all tasks blocked waiting to obtain a
segment from the region will be readied and returned a status code which
indicates that the region was deleted.

Directives
==========

This section details the region 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_region_create:

REGION_CREATE - Create a region
-------------------------------
.. index:: create a region
CALLING SEQUENCE:
    .. code-block:: c

        rtems_status_code rtems_region_create(
          rtems_name       name,
          void            *starting_address,
          uintptr_t        length,
          uintptr_t        page_size,
          rtems_attribute  attribute_set,
          rtems_id        *id
        );

DIRECTIVE STATUS CODES:
    .. list-table::
     :class: rtems-table

     * - ``RTEMS_SUCCESSFUL``
       - region created successfully
     * - ``RTEMS_INVALID_NAME``
       - invalid region name
     * - ``RTEMS_INVALID_ADDRESS``
       - ``id`` is NULL
     * - ``RTEMS_INVALID_ADDRESS``
       - ``starting_address`` is NULL
     * - ``RTEMS_INVALID_ADDRESS``
       - address not on four byte boundary
     * - ``RTEMS_TOO_MANY``
       - too many regions created
     * - ``RTEMS_INVALID_SIZE``
       - invalid page size

DESCRIPTION:
    This directive creates a region from a physically contiguous memory space
    which starts at starting_address and is length bytes long.  Segments
    allocated from the region will be a multiple of page_size bytes in length.
    The assigned region id is returned in id.  This region id is used as an
    argument to other region related directives to access the region.

    For control and maintenance of the region, RTEMS allocates and initializes
    an RNCB from the RNCB free pool.  Thus memory from the region is not used
    to store the RNCB.  However, some overhead within the region is required by
    RTEMS each time a segment is constructed in the region.

    Specifying ``RTEMS_PRIORITY`` in attribute_set causes tasks waiting for a
    segment to be serviced according to task priority.  Specifying
    ``RTEMS_FIFO`` in attribute_set or selecting ``RTEMS_DEFAULT_ATTRIBUTES``
    will cause waiting tasks to be serviced in First In-First Out order.

    The ``starting_address`` parameter must be aligned on a four byte boundary.
    The ``page_size`` parameter must be a multiple of four greater than or
    equal to eight.

NOTES:
    This directive will obtain the allocator mutex and may cause the calling
    task to be preempted.

    The following region attribute constants are defined by RTEMS:

    .. list-table::
     :class: rtems-table

     * - ``RTEMS_FIFO``
       - tasks wait by FIFO (default)
     * - ``RTEMS_PRIORITY``
       - tasks wait by priority

.. raw:: latex

   \clearpage

.. _rtems_region_ident:

REGION_IDENT - Get ID of a region
---------------------------------
.. index:: get ID of a region
.. index:: obtain ID of a region
.. index:: rtems_region_ident

CALLING SEQUENCE:
    .. code-block:: c

        rtems_status_code rtems_region_ident(
          rtems_name  name,
          rtems_id   *id
        );

DIRECTIVE STATUS CODES:
    .. list-table::
     :class: rtems-table

     * - ``RTEMS_SUCCESSFUL``
       - region identified successfully
     * - ``RTEMS_INVALID_ADDRESS``
       - ``id`` is NULL
     * - ``RTEMS_INVALID_NAME``
       - region name not found

DESCRIPTION:

    This directive obtains the region id associated with the region name to be
    acquired.  If the region name is not unique, then the region id will match
    one of the regions with that name.  However, this region id is not
    guaranteed to correspond to the desired region.  The region id is used to
    access this region in other region manager directives.

NOTES:
    This directive will not cause the running task to be preempted.

.. raw:: latex

   \clearpage

.. _rtems_region_delete:

REGION_DELETE - Delete a region
-------------------------------
.. index:: delete a region
.. index:: rtems_region_delete

CALLING SEQUENCE:
    .. code-block:: c

        rtems_status_code rtems_region_delete(
          rtems_id id
        );

DIRECTIVE STATUS CODES:
    .. list-table::
     :class: rtems-table

     * - ``RTEMS_SUCCESSFUL``
       - region deleted successfully
     * - ``RTEMS_INVALID_ID``
       - invalid region id
     * - ``RTEMS_RESOURCE_IN_USE``
       - segments still in use

DESCRIPTION:
    This directive deletes the region specified by id.  The region cannot be
    deleted if any of its segments are still allocated.  The RNCB for the
    deleted region is reclaimed by RTEMS.

NOTES:
    This directive will obtain the allocator mutex and may cause the calling
    task to be preempted.

    The calling task does not have to be the task that created the region.  Any
    local task that knows the region id can delete the region.

.. raw:: latex

   \clearpage

.. _rtems_region_extend:

REGION_EXTEND - Add memory to a region
--------------------------------------
.. index:: add memory to a region
.. index:: region, add memory
.. index:: rtems_region_extend

CALLING SEQUENCE:
    .. code-block:: c

        rtems_status_code rtems_region_extend(
          rtems_id   id,
          void      *starting_address,
          uintptr_t  length
        );

DIRECTIVE STATUS CODES:
    .. list-table::
     :class: rtems-table

     * - ``RTEMS_SUCCESSFUL``
       - region extended successfully
     * - ``RTEMS_INVALID_ADDRESS``
       - ``starting_address`` is NULL
     * - ``RTEMS_INVALID_ID``
       - invalid region id
     * - ``RTEMS_INVALID_ADDRESS``
       - invalid address of area to add

DESCRIPTION:
    This directive adds the memory area which starts at
    :c:data:`starting_address` for :c:data:`length` bytes to the region
    specified by :c:data:`id`.

    There are no alignment requirements for the memory area.  The memory area
    must be big enough to contain some maintenance blocks.  It must not overlap
    parts of the current heap memory areas.  Disconnected memory areas added to
    the heap will lead to used blocks which cover the gaps.  Extending with an
    inappropriate memory area will corrupt the heap resulting in undefined
    behaviour.

NOTES:
    This directive will obtain the allocator mutex and may cause the calling
    task to be preempted.

    The calling task does not have to be the task that created the region.  Any
    local task that knows the region identifier can extend the region.

.. raw:: latex

   \clearpage

.. _rtems_region_get_segment:

REGION_GET_SEGMENT - Get segment from a region
----------------------------------------------
.. index:: get segment from region
.. index:: rtems_region_get_segment

CALLING SEQUENCE:
    .. code-block:: c

        rtems_status_code rtems_region_get_segment(
          rtems_id         id,
          uintptr_t        size,
          rtems_option     option_set,
          rtems_interval   timeout,
          void           **segment
        );

DIRECTIVE STATUS CODES:
    .. list-table::
     :class: rtems-table

     * - ``RTEMS_SUCCESSFUL``
       - segment obtained successfully
     * - ``RTEMS_INVALID_ADDRESS``
       - ``segment`` is NULL
     * - ``RTEMS_INVALID_ID``
       - invalid region id
     * - ``RTEMS_INVALID_SIZE``
       - request is for zero bytes or exceeds the size of maximum segment which is
         possible for this region
     * - ``RTEMS_UNSATISFIED``
       - segment of requested size not available
     * - ``RTEMS_TIMEOUT``
       - timed out waiting for segment
     * - ``RTEMS_OBJECT_WAS_DELETED``
       - region deleted while waiting

DESCRIPTION:
    This directive obtains a variable size segment from the region specified by
    ``id``.  The address of the allocated segment is returned in segment.  The
    ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` components of the options parameter
    are used to specify whether the calling tasks wish to wait for a segment to
    become available or return immediately if no segment is available.  For
    either option, if a sufficiently sized segment is available, then the
    segment is successfully acquired by returning immediately with the
    ``RTEMS_SUCCESSFUL`` status code.

    If the calling task chooses to return immediately and a segment large
    enough is not available, then an error code indicating this fact is
    returned.  If the calling task chooses to wait for the segment and a
    segment large enough is not available, then the calling task is placed on
    the region's segment wait queue and blocked.  If the region was created
    with the ``RTEMS_PRIORITY`` option, then the calling task is inserted into
    the wait queue according to its priority.  However, if the region was
    created with the ``RTEMS_FIFO`` option, then the calling task is placed at
    the rear of the wait queue.

    The timeout parameter specifies the maximum interval that a task is willing
    to wait to obtain a segment.  If timeout is set to ``RTEMS_NO_TIMEOUT``,
    then the calling task will wait forever.

NOTES:
    This directive will obtain the allocator mutex and may cause the calling
    task to be preempted.

    The actual length of the allocated segment may be larger than the requested
    size because a segment size is always a multiple of the region's page size.

    The following segment acquisition option constants are defined by RTEMS:

    .. list-table::
     :class: rtems-table

     * - ``RTEMS_WAIT``
       - task will wait for segment (default)
     * - ``RTEMS_NO_WAIT``
       - task should not wait

    A clock tick is required to support the timeout functionality of this
    directive.

.. raw:: latex

   \clearpage

.. _rtems_region_return_segment:

REGION_RETURN_SEGMENT - Return segment to a region
--------------------------------------------------
.. index:: return segment to region
.. index:: rtems_region_return_segment

CALLING SEQUENCE:
    .. code-block:: c

        rtems_status_code rtems_region_return_segment(
          rtems_id  id,
          void     *segment
        );

DIRECTIVE STATUS CODES:
    .. list-table::
     :class: rtems-table

     * - ``RTEMS_SUCCESSFUL``
       - segment returned successfully
     * - ``RTEMS_INVALID_ADDRESS``
       - ``segment`` is NULL
     * - ``RTEMS_INVALID_ID``
       - invalid region id
     * - ``RTEMS_INVALID_ADDRESS``
       - segment address not in region

DESCRIPTION:
    This directive returns the segment specified by segment to the region
    specified by id.  The returned segment is merged with its neighbors to form
    the largest possible segment.  The first task on the wait queue is examined
    to determine if its segment request can now be satisfied.  If so, it is
    given a segment and unblocked.  This process is repeated until the first
    task's segment request cannot be satisfied.

NOTES:
    This directive will cause the calling task to be preempted if one or more
    local tasks are waiting for a segment and the following conditions exist:

    - a waiting task has a higher priority than the calling task

    - the size of the segment required by the waiting task is less than or
      equal to the size of the segment returned.

.. raw:: latex

   \clearpage

.. _rtems_region_get_segment_size:

REGION_GET_SEGMENT_SIZE - Obtain size of a segment
--------------------------------------------------
.. index:: get size of segment
.. index:: rtems_region_get_segment_size

CALLING SEQUENCE:
    .. code-block:: c

        rtems_status_code rtems_region_get_segment_size(
          rtems_id   id,
          void      *segment,
          uintptr_t *size
        );

DIRECTIVE STATUS CODES:
    .. list-table::
     :class: rtems-table

     * - ``RTEMS_SUCCESSFUL``
       - segment obtained successfully
     * - ``RTEMS_INVALID_ADDRESS``
       - ``segment`` is NULL
     * - ``RTEMS_INVALID_ADDRESS``
       - ``size`` is NULL
     * - ``RTEMS_INVALID_ID``
       - invalid region id
     * - ``RTEMS_INVALID_ADDRESS``
       - segment address not in region

DESCRIPTION:
    This directive obtains the size in bytes of the specified segment.

NOTES:
    The actual length of the allocated segment may be larger than the requested
    size because a segment size is always a multiple of the region's page size.

.. raw:: latex

   \clearpage

.. _rtems_region_resize_segment:

REGION_RESIZE_SEGMENT - Change size of a segment
------------------------------------------------
.. index:: resize segment
.. index:: rtems_region_resize_segment

CALLING SEQUENCE:
    .. code-block:: c

        rtems_status_code rtems_region_resize_segment(
          rtems_id   id,
          void      *segment,
          uintptr_t  new_size,
          uintptr_t *old_size
        );

DIRECTIVE STATUS CODES:
    .. list-table::
     :class: rtems-table

     * - ``RTEMS_SUCCESSFUL``
       - segment obtained successfully
     * - ``RTEMS_INVALID_ADDRESS``
       - ``segment`` is NULL
     * - ``RTEMS_INVALID_ADDRESS``
       - ``old_size`` is NULL
     * - ``RTEMS_INVALID_ID``
       - invalid region id
     * - ``RTEMS_INVALID_ADDRESS``
       - segment address not in region
     * - ``RTEMS_UNSATISFIED``
       - unable to make segment larger

DESCRIPTION:
    This directive is used to increase or decrease the size of a segment.  When
    increasing the size of a segment, it is possible that there is not memory
    available contiguous to the segment.  In this case, the request is
    unsatisfied.

NOTES:
    This directive will obtain the allocator mutex and may cause the calling
    task to be preempted.

    If an attempt to increase the size of a segment fails, then the application
    may want to allocate a new segment of the desired size, copy the contents
    of the original segment to the new, larger segment and then return the
    original segment.