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