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

4.104.114.84.9
Last change on this file since f8892c9 was f8892c9, checked in by Joel Sherrill <joel.sherrill@…>, on May 6, 2004 at 7:21:50 PM

2004-05-06 Joel Sherrill <joel@…>

PR 618/rtems

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