source: rtems/doc/user/region.t @ b86eb32e

4.9
Last change on this file since b86eb32e was b86eb32e, checked in by Joel Sherrill <joel.sherrill@…>, on 12/12/08 at 14:48:49

2008-12-12 Joel Sherrill <joel.sherrill@…>

  • user/region.t: Malloc Family is not implemented in termios of Region Manager after 4.7. Correct documentation.
  • Property mode set to 100644
File size: 22.6 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Region Manager
10
11@cindex regions
12
13@section Introduction
14
15The region manager provides facilities to dynamically
16allocate memory in variable sized units.  The directives
17provided by the region manager are:
18
19@itemize @bullet
20@item @code{@value{DIRPREFIX}region_create} - Create a region
21@item @code{@value{DIRPREFIX}region_ident} - Get ID of a region
22@item @code{@value{DIRPREFIX}region_delete} - Delete a region
23@item @code{@value{DIRPREFIX}region_extend} - Add memory to a region
24@item @code{@value{DIRPREFIX}region_get_segment} - Get segment from a region
25@item @code{@value{DIRPREFIX}region_return_segment} - Return segment to a region
26@item @code{@value{DIRPREFIX}region_get_segment_size} - Obtain size of a segment
27@item @code{@value{DIRPREFIX}region_resize_segment} - Change size of a segment
28@end itemize
29
30@section Background
31
32@subsection Region Manager Definitions
33
34@cindex region, definition
35@cindex segment, definition
36
37A region makes up a physically contiguous memory
38space with user-defined boundaries from which variable-sized
39segments are dynamically allocated and deallocated.  A segment
40is a variable size section of memory which is allocated in
41multiples of a user-defined page size.  This page size is
42required to be a multiple of four greater than or equal to four.
43For example, if a request for a 350-byte segment is made in a
44region with 256-byte pages, then a 512-byte segment is allocated.
45
46Regions are organized as doubly linked chains of
47variable sized memory blocks.  Memory requests are allocated
48using a first-fit algorithm.  If available, the requester
49receives the number of bytes requested (rounded up to the next
50page size).  RTEMS requires some overhead from the region's
51memory for each segment that is allocated.  Therefore, an
52application should only modify the memory of a segment that has
53been obtained from the region.  The application should NOT
54modify the memory outside of any obtained segments and within
55the region's boundaries while the region is currently active in
56the system.
57
58Upon return to the region, the free block is
59coalesced with its neighbors (if free) on both sides to produce
60the largest possible unused block.
61
62@subsection Building an Attribute Set
63
64@cindex region attribute set, building
65
66In general, an attribute set is built by a bitwise OR
67of the desired attribute components.  The set of valid region
68attributes is provided in the following table:
69
70@itemize @bullet
71@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
72@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
73@end itemize
74
75Attribute values are specifically designed to be
76mutually exclusive, therefore bitwise OR and addition operations
77are equivalent as long as each attribute appears exactly once in
78the component list.  An attribute listed as a default is not
79required to appear in the attribute list, although it is a good
80programming practice to specify default attributes.  If all
81defaults are desired, the attribute
82@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
83specified on this call.
84
85This example demonstrates the attribute_set parameter
86needed to create a region with the task priority waiting queue
87discipline.  The attribute_set parameter to the
88@code{@value{DIRPREFIX}region_create}
89directive should be @code{@value{RPREFIX}PRIORITY}.
90
91@subsection Building an Option Set
92
93In general, an option is built by a bitwise OR of the
94desired option components.  The set of valid options for the
95@code{@value{DIRPREFIX}region_get_segment} directive are
96listed in the following table:
97
98@itemize @bullet
99@item @code{@value{RPREFIX}WAIT} - task will wait for segment (default)
100@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
101@end itemize
102
103Option values are specifically designed to be
104mutually exclusive, therefore bitwise OR and addition operations
105are equivalent as long as each option appears exactly once in
106the component list.  An option listed as a default is not
107required to appear in the option list, although it is a good
108programming practice to specify default options.  If all
109defaults are desired, the option
110@code{@value{RPREFIX}DEFAULT_OPTIONS} should be
111specified on this call.
112
113This example demonstrates the option parameter needed
114to poll for a segment.  The option parameter passed to the
115@code{@value{DIRPREFIX}region_get_segment} directive should
116be @code{@value{RPREFIX}NO_WAIT}.
117
118@section Operations
119
120@subsection Creating a Region
121
122The @code{@value{DIRPREFIX}region_create} directive creates a region with the
123user-defined name.  The user may select FIFO or task priority as
124the method for placing waiting tasks in the task wait queue.
125RTEMS allocates a Region Control Block (RNCB) from the RNCB free
126list to maintain the newly created region.  RTEMS also generates
127a unique region ID which is returned to the calling task.
128
129It is not possible to calculate the exact number of
130bytes available to the user since RTEMS requires overhead for
131each segment allocated.  For example, a region with one segment
132that is the size of the entire region has more available bytes
133than a region with two segments that collectively are the size
134of the entire region.  This is because the region with one
135segment requires only the overhead for one segment, while the
136other region requires the overhead for two segments.
137
138Due to automatic coalescing, the number of segments
139in the region dynamically changes.  Therefore, the total
140overhead required by RTEMS dynamically changes.
141
142@subsection Obtaining Region IDs
143
144When a region is created, RTEMS generates a unique
145region ID and assigns it to the created region until it is
146deleted.  The region ID may be obtained by either of two
147methods.  First, as the result of an invocation of the
148@code{@value{DIRPREFIX}region_create} directive,
149the region ID is stored in a user
150provided location.  Second, the region ID may be obtained later
151using the @code{@value{DIRPREFIX}region_ident} directive. 
152The region ID is used by other region manager directives to
153access this region.
154
155@subsection Adding Memory to a Region
156
157The @code{@value{DIRPREFIX}region_extend} directive may be used to add memory
158to an existing region.  The caller specifies the size in bytes
159and starting address of the memory being added.
160
161NOTE:  Please see the release notes or RTEMS source
162code for information regarding restrictions on the location of
163the memory being added in relation to memory already in the
164region.
165
166@subsection Acquiring a Segment
167
168The @code{@value{DIRPREFIX}region_get_segment} directive attempts to acquire
169a segment from a specified region.  If the region has enough
170available free memory, then a segment is returned successfully
171to the caller.  When the segment cannot be allocated, one of the
172following situations applies:
173
174@itemize @bullet
175@item By default, the calling task will wait forever to acquire the segment.
176
177@item Specifying the @code{@value{RPREFIX}NO_WAIT} option forces
178an immediate return with an error status code.
179
180@item Specifying a timeout limits the interval the task will
181wait before returning with an error status code.
182@end itemize
183
184If the task waits for the segment, then it is placed
185in the region's task wait queue in either FIFO or task priority
186order.  All tasks waiting on a region are returned an error when
187the message queue is deleted.
188
189@subsection Releasing a Segment
190
191When a segment is returned to a region by the
192@code{@value{DIRPREFIX}region_return_segment} directive, it is merged with its
193unallocated neighbors to form the largest possible segment.  The
194first task on the wait queue is examined to determine if its
195segment request can now be satisfied.  If so, it is given a
196segment and unblocked.  This process is repeated until the first
197task's segment request cannot be satisfied.
198
199@subsection Obtaining the Size of a Segment
200
201The @code{@value{DIRPREFIX}region_get_segment_size} directive returns the
202size in bytes of the specified segment.  The size returned
203includes any "extra" memory included in the segment because of
204rounding up to a page size boundary.
205
206@subsection Changing the Size of a Segment
207
208The @code{@value{DIRPREFIX}region_resize_segment} directive is used
209to change the size in bytes of the specified segment.  The size may be
210increased or decreased.  When increasing the size of a segment, it is
211possible that the request cannot be satisfied.  This directive provides
212functionality similar to the @code{realloc()} function in the Standard
213C Library.
214
215@subsection Deleting a Region
216
217A region can be removed from the system and returned
218to RTEMS with the @code{@value{DIRPREFIX}region_delete}
219directive.  When a region is
220deleted, its control block is returned to the RNCB free list.  A
221region with segments still allocated is not allowed to be
222deleted.  Any task attempting to do so will be returned an
223error.  As a result of this directive, all tasks blocked waiting
224to obtain a segment from the region will be readied and returned
225a status code which indicates that the region was deleted.
226
227@section Directives
228
229This section details the region manager's directives.
230A subsection is dedicated to each of this manager's directives
231and describes the calling sequence, related constants, usage,
232and status codes.
233
234@c
235@c
236@c
237@page
238@subsection REGION_CREATE - Create a region
239
240@cindex create a region
241
242@subheading CALLING SEQUENCE:
243
244@ifset is-C
245@findex rtems_region_create
246@example
247rtems_status_code rtems_region_create(
248  rtems_name       name,
249  void            *starting_address,
250  uint32_t         length,
251  uint32_t         page_size,
252  rtems_attribute  attribute_set,
253  rtems_id        *id
254);
255@end example
256@end ifset
257
258@ifset is-Ada
259@example
260procedure Region_Create (
261   Name             : in     RTEMS.Name;
262   Starting_Address : in     RTEMS.Address;
263   Length           : in     RTEMS.Unsigned32;
264   Page_Size        : in     RTEMS.Unsigned32;
265   Attribute_Set    : in     RTEMS.Attribute;
266   ID               :    out RTEMS.ID;
267   Result           :    out RTEMS.Status_Codes
268);
269@end example
270@end ifset
271
272@subheading DIRECTIVE STATUS CODES:
273
274@code{@value{RPREFIX}SUCCESSFUL} - region created successfully@*
275@code{@value{RPREFIX}INVALID_NAME} - invalid region name@*
276@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
277@code{@value{RPREFIX}INVALID_ADDRESS} - @code{starting_address} is NULL@*
278@code{@value{RPREFIX}INVALID_ADDRESS} - address not on four byte boundary@*
279@code{@value{RPREFIX}TOO_MANY} - too many regions created@*
280@code{@value{RPREFIX}INVALID_SIZE} - invalid page size
281
282@subheading DESCRIPTION:
283
284This directive creates a region from a physically
285contiguous memory space which starts at starting_address and is
286length bytes long.  Segments allocated from the region will be a
287multiple of page_size bytes in length.  The assigned region id
288is returned in id.  This region id is used as an argument to
289other region related directives to access the region.
290
291For control and maintenance of the region, RTEMS
292allocates and initializes an RNCB from the RNCB free pool.  Thus
293memory from the region is not used to store the RNCB.  However,
294some overhead within the region is required by RTEMS each time a
295segment is constructed in the region.
296
297Specifying @code{@value{RPREFIX}PRIORITY} in attribute_set causes tasks
298waiting for a segment to be serviced according to task priority.
299Specifying @code{@value{RPREFIX}FIFO} in attribute_set or selecting
300@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} will cause waiting tasks to
301be serviced in First In-First Out order.
302
303The @code{starting_address} parameter must be aligned on a
304four byte boundary.  The @code{page_size} parameter must be a multiple
305of four greater than or equal to eight.
306
307@subheading NOTES:
308
309This directive will not cause the calling task to be
310preempted.
311
312The following region attribute constants are defined
313by RTEMS:
314
315@itemize @bullet
316@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
317@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
318@end itemize
319
320@c
321@c
322@c
323@page
324@subsection REGION_IDENT - Get ID of a region
325
326@cindex get ID of a region
327@cindex obtain ID of a region
328
329@subheading CALLING SEQUENCE:
330
331@ifset is-C
332@findex rtems_region_ident
333@example
334rtems_status_code rtems_region_ident(
335  rtems_name  name,
336  rtems_id   *id
337);
338@end example
339@end ifset
340
341@ifset is-Ada
342@example
343procedure Region_Ident (
344   Name   : in     RTEMS.Name;
345   ID     :    out RTEMS.ID;
346   Result :    out RTEMS.Status_Codes
347);
348@end example
349@end ifset
350
351@subheading DIRECTIVE STATUS CODES:
352
353@code{@value{RPREFIX}SUCCESSFUL} - region identified successfully@*
354@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
355@code{@value{RPREFIX}INVALID_NAME} - region name not found
356
357@subheading DESCRIPTION:
358
359This directive obtains the region id associated with
360the region name to be acquired.  If the region name is not
361unique, then the region id will match one of the regions with
362that name.  However, this region id is not guaranteed to
363correspond to the desired region.  The region id is used to
364access this region in other region manager directives.
365
366@subheading NOTES:
367
368This directive will not cause the running task to be preempted.
369
370@c
371@c
372@c
373@page
374@subsection REGION_DELETE - Delete a region
375
376@cindex delete a region
377
378@subheading CALLING SEQUENCE:
379
380@ifset is-C
381@findex rtems_region_delete
382@example
383rtems_status_code rtems_region_delete(
384  rtems_id id
385);
386@end example
387@end ifset
388
389@ifset is-Ada
390@example
391procedure Region_Delete (
392   ID     : in     RTEMS.ID;
393   Result :    out RTEMS.Status_Codes
394);
395@end example
396@end ifset
397
398@subheading DIRECTIVE STATUS CODES:
399
400@code{@value{RPREFIX}SUCCESSFUL} - region deleted successfully@*
401@code{@value{RPREFIX}INVALID_ID} - invalid region id@*
402@code{@value{RPREFIX}RESOURCE_IN_USE} - segments still in use
403
404@subheading DESCRIPTION:
405
406This directive deletes the region specified by id.
407The region cannot be deleted if any of its segments are still
408allocated.  The RNCB for the deleted region is reclaimed by
409RTEMS.
410
411@subheading NOTES:
412
413This directive will not cause the calling task to be preempted.
414
415The calling task does not have to be the task that
416created the region.  Any local task that knows the region id can
417delete the region.
418
419@c
420@c
421@c
422@page
423@subsection REGION_EXTEND - Add memory to a region
424
425@cindex add memory to a region
426@cindex region, add memory
427
428@subheading CALLING SEQUENCE:
429
430@ifset is-C
431@findex rtems_region_extend
432@example
433rtems_status_code rtems_region_extend(
434  rtems_id  id,
435  void     *starting_address,
436  uint32_t  length
437);
438@end example
439@end ifset
440
441@ifset is-Ada
442@example
443procedure Region_Extend (
444   ID               : in     RTEMS.ID;
445   Starting_Address : in     RTEMS.Address;
446   Length           : in     RTEMS.Unsigned32;
447   Result           :    out RTEMS.Status_Codes
448);
449@end example
450@end ifset
451
452@subheading DIRECTIVE STATUS CODES:
453
454@code{@value{RPREFIX}SUCCESSFUL} - region extended successfully@*
455@code{@value{RPREFIX}INVALID_ADDRESS} - @code{starting_address} is NULL@*
456@code{@value{RPREFIX}INVALID_ID} - invalid region id@*
457@code{@value{RPREFIX}INVALID_ADDRESS} - invalid address of area to add
458
459@subheading DESCRIPTION:
460
461This directive adds the memory which starts at
462starting_address for length bytes to the region specified by id.
463
464@subheading NOTES:
465
466This directive will not cause the calling task to be preempted.
467
468The calling task does not have to be the task that
469created the region.  Any local task that knows the region id can
470extend the region.
471
472@c
473@c
474@c
475@page
476@subsection REGION_GET_SEGMENT - Get segment from a region
477
478@cindex get segment from region
479
480@subheading CALLING SEQUENCE:
481
482@ifset is-C
483@findex rtems_region_get_segment
484@example
485rtems_status_code rtems_region_get_segment(
486  rtems_id         id,
487  uint32_t         size,
488  rtems_option     option_set,
489  rtems_interval   timeout,
490  void           **segment
491);
492@end example
493@end ifset
494
495@ifset is-Ada
496@example
497procedure Region_Get_Segment (
498   ID         : in     RTEMS.ID;
499   Size       : in     RTEMS.Unsigned32;
500   Option_Set : in     RTEMS.Option;
501   Timeout    : in     RTEMS.Interval;
502   Segment    :    out RTEMS.Address;
503   Result     :    out RTEMS.Status_Codes
504);
505@end example
506@end ifset
507
508@subheading DIRECTIVE STATUS CODES:
509
510@code{@value{RPREFIX}SUCCESSFUL} - segment obtained successfully@*
511@code{@value{RPREFIX}INVALID_ADDRESS} - @code{segment} is NULL@*
512@code{@value{RPREFIX}INVALID_ID} - invalid region id@*
513@code{@value{RPREFIX}INVALID_SIZE} - request is for zero bytes or exceeds
514the size of maximum segment which is possible for this region@*
515@code{@value{RPREFIX}UNSATISFIED} - segment of requested size not available@*
516@code{@value{RPREFIX}TIMEOUT} - timed out waiting for segment@*
517@code{@value{RPREFIX}OBJECT_WAS_DELETED} - semaphore deleted while waiting
518
519@subheading DESCRIPTION:
520
521This directive obtains a variable size segment from
522the region specified by id.  The address of the allocated
523segment is returned in segment.  The @code{@value{RPREFIX}WAIT}
524and @code{@value{RPREFIX}NO_WAIT} components
525of the options parameter are used to specify whether the calling
526tasks wish to wait for a segment to become available or return
527immediately if no segment is available.  For either option, if a
528sufficiently sized segment is available, then the segment is
529successfully acquired by returning immediately with  the
530@code{@value{RPREFIX}SUCCESSFUL} status code.
531
532If the calling task chooses to return immediately and
533a segment large enough is not available, then an error code
534indicating this fact is returned.  If the calling task chooses
535to wait for the segment and a segment large enough is not
536available, then the calling task is placed on the region's
537segment wait queue and blocked.  If the region was created with
538the @code{@value{RPREFIX}PRIORITY} option, then the calling
539task is inserted into the
540wait queue according to its priority.  However, if the region
541was created with the @code{@value{RPREFIX}FIFO} option, then the calling
542task is placed at the rear of the wait queue.
543
544The timeout parameter specifies the maximum interval
545that a task is willing to wait to obtain a segment.  If timeout
546is set to @code{@value{RPREFIX}NO_TIMEOUT}, then the
547calling task will wait forever.
548
549@subheading NOTES:
550
551The actual length of the allocated segment may be
552larger than the requested size because a segment size is always
553a multiple of the region's page size.
554
555The following segment acquisition option constants
556are defined by RTEMS:
557
558@itemize @bullet
559@item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default)
560@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
561@end itemize
562
563A clock tick is required to support the timeout functionality of
564this directive.
565
566@c
567@c
568@c
569@page
570@subsection REGION_RETURN_SEGMENT - Return segment to a region
571
572@cindex return segment to region
573
574@subheading CALLING SEQUENCE:
575
576@ifset is-C
577@findex rtems_region_return_segment
578@example
579rtems_status_code rtems_region_return_segment(
580  rtems_id  id,
581  void     *segment
582);
583@end example
584@end ifset
585
586@ifset is-Ada
587@example
588procedure Region_Return_Segment (
589   ID      : in     RTEMS.ID;
590   Segment : in     RTEMS.Address;
591   Result  :    out RTEMS.Status_Codes
592);
593@end example
594@end ifset
595
596@subheading DIRECTIVE STATUS CODES:
597
598@code{@value{RPREFIX}SUCCESSFUL} - segment returned successfully@*
599@code{@value{RPREFIX}INVALID_ADDRESS} - @code{segment} is NULL@*
600@code{@value{RPREFIX}INVALID_ID} - invalid region id@*
601@code{@value{RPREFIX}INVALID_ADDRESS} - segment address not in region
602
603@subheading DESCRIPTION:
604
605This directive returns the segment specified by
606segment to the region specified by id.  The returned segment is
607merged with its neighbors to form the largest possible segment.
608The first task on the wait queue is examined to determine if its
609segment request can now be satisfied.  If so, it is given a
610segment and unblocked.  This process is repeated until the first
611task's segment request cannot be satisfied.
612
613@subheading NOTES:
614
615This directive will cause the calling task to be
616preempted if one or more local tasks are waiting for a segment
617and the following conditions exist:
618
619@itemize @bullet
620@item a waiting task has a higher priority than the calling task
621
622@item the size of the segment required by the waiting task
623is less than or equal to the size of the segment returned.
624@end itemize
625
626@c
627@c
628@c
629@page
630@subsection REGION_GET_SEGMENT_SIZE - Obtain size of a segment
631
632@cindex get size of segment
633
634@subheading CALLING SEQUENCE:
635
636@ifset is-C
637@findex rtems_region_get_segment_size
638@example
639rtems_status_code rtems_region_get_segment_size(
640  rtems_id  id,
641  void     *segment,
642  size_t   *size
643);
644@end example
645@end ifset
646
647@ifset is-Ada
648@example
649procedure Region_Get_Segment_Size (
650   ID         : in     RTEMS.ID;
651   Segment    : in     RTEMS.Address;
652   Size       :    out RTEMS.Unsigned32;
653   Result     :    out RTEMS.Status_Codes
654);
655@end example
656@end ifset
657
658@subheading DIRECTIVE STATUS CODES:
659
660@code{@value{RPREFIX}SUCCESSFUL} - segment obtained successfully@*
661@code{@value{RPREFIX}INVALID_ADDRESS} - @code{segment} is NULL@*
662@code{@value{RPREFIX}INVALID_ADDRESS} - @code{size} is NULL@*
663@code{@value{RPREFIX}INVALID_ID} - invalid region id@*
664@code{@value{RPREFIX}INVALID_ADDRESS} - segment address not in region
665
666@subheading DESCRIPTION:
667
668This directive obtains the size in bytes of the specified segment.
669
670@subheading NOTES:
671
672The actual length of the allocated segment may be
673larger than the requested size because a segment size is always
674a multiple of the region's page size.
675
676@c
677@c
678@c
679@page
680@subsection REGION_RESIZE_SEGMENT - Change size of a segment
681
682@cindex resize segment
683
684@subheading CALLING SEQUENCE:
685
686@ifset is-C
687@findex rtems_region_resize_segment
688@example
689rtems_status_code rtems_region_resize_segment(
690  rtems_id     id,
691  void        *segment,
692  size_t       size,
693  size_t      *old_size
694);
695@end example
696@end ifset
697
698@ifset is-Ada
699@example
700procedure Region_Resize_Segment (
701   ID         : in     RTEMS.ID;
702   Segment    : in     RTEMS.Address;
703   Size       : in     RTEMS.Unsigned32;
704   Old_Size   :    out RTEMS.Unsigned32;
705   Result     :    out RTEMS.Status_Codes
706);
707@end example
708@end ifset
709
710@subheading DIRECTIVE STATUS CODES:
711
712@code{@value{RPREFIX}SUCCESSFUL} - segment obtained successfully@*
713@code{@value{RPREFIX}INVALID_ADDRESS} - @code{segment} is NULL@*
714@code{@value{RPREFIX}INVALID_ADDRESS} - @code{old_size} is NULL@*
715@code{@value{RPREFIX}INVALID_ID} - invalid region id@*
716@code{@value{RPREFIX}INVALID_ADDRESS} - segment address not in region
717@code{@value{RPREFIX}UNSATISFIED} - unable to make segment larger
718
719@subheading DESCRIPTION:
720
721This directive is used to increase or decrease the size of
722a segment.  When increasing the size of a segment, it
723is possible that there is not memory available contiguous
724to the segment.  In this case, the request is unsatisfied.
725
726@subheading NOTES:
727
728If an attempt to increase the size of a segment fails, then
729the application may want to allocate a new segment of the desired
730size, copy the contents of the original segment to the new, larger
731segment and then return the original segment.
732
Note: See TracBrowser for help on using the repository browser.