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

4.104.114.84.95
Last change on this file since a3a7527 was a3a7527, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 27, 1998 at 1:04:02 PM

Attempting to add variable so that in C all constants start with RTEMS_
and all directives start with rtems_.

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