[ae68ff0] | 1 | @c |
---|
[1e524995] | 2 | @c COPYRIGHT (c) 1988-1998. |
---|
[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 | @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 | |
---|
| 27 | The region manager provides facilities to dynamically |
---|
| 28 | allocate memory in variable sized units. The directives |
---|
| 29 | provided 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 | |
---|
| 58 | A region makes up a physically contiguous memory |
---|
| 59 | space with user-defined boundaries from which variable-sized |
---|
| 60 | segments are dynamically allocated and deallocated. A segment |
---|
| 61 | is a variable size section of memory which is allocated in |
---|
| 62 | multiples of a user-defined page size. This page size is |
---|
| 63 | required to be a multiple of four greater than or equal to four. |
---|
| 64 | For example, if a request for a 350-byte segment is made in a |
---|
| 65 | region with 256-byte pages, then a 512-byte segment is allocated. |
---|
| 66 | |
---|
| 67 | Regions are organized as doubly linked chains of |
---|
| 68 | variable sized memory blocks. Memory requests are allocated |
---|
| 69 | using a first-fit algorithm. If available, the requester |
---|
| 70 | receives the number of bytes requested (rounded up to the next |
---|
| 71 | page size). RTEMS requires some overhead from the region's |
---|
| 72 | memory for each segment that is allocated. Therefore, an |
---|
| 73 | application should only modify the memory of a segment that has |
---|
| 74 | been obtained from the region. The application should NOT |
---|
| 75 | modify the memory outside of any obtained segments and within |
---|
| 76 | the region's boundaries while the region is currently active in |
---|
| 77 | the system. |
---|
| 78 | |
---|
| 79 | Upon return to the region, the free block is |
---|
| 80 | coalesced with its neighbors (if free) on both sides to produce |
---|
| 81 | the 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 | |
---|
| 88 | In general, an attribute set is built by a bitwise OR |
---|
| 89 | of the desired attribute components. The set of valid region |
---|
| 90 | attributes is provided in the following table: |
---|
| 91 | |
---|
| 92 | @itemize @bullet |
---|
[a3a7527] | 93 | @item @code{FIFO} - tasks wait by FIFO (default) |
---|
| 94 | @item @code{PRIORITY} - tasks wait by priority |
---|
[ae68ff0] | 95 | @end itemize |
---|
| 96 | |
---|
| 97 | Attribute values are specifically designed to be |
---|
| 98 | mutually exclusive, therefore bitwise OR and addition operations |
---|
| 99 | are equivalent as long as each attribute appears exactly once in |
---|
| 100 | the component list. An attribute listed as a default is not |
---|
| 101 | required to appear in the attribute list, although it is a good |
---|
| 102 | programming practice to specify default attributes. If all |
---|
[a94c5a5d] | 103 | defaults are desired, the attribute @code{DEFAULT_ATTRIBUTES} should be |
---|
[ae68ff0] | 104 | specified on this call. |
---|
| 105 | |
---|
| 106 | This example demonstrates the attribute_set parameter |
---|
| 107 | needed to create a region with the task priority waiting queue |
---|
| 108 | discipline. The attribute_set parameter to the region_create |
---|
[a3a7527] | 109 | directive should be @code{PRIORITY}. |
---|
[ae68ff0] | 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 | |
---|
| 116 | In general, an option is built by a bitwise OR of the |
---|
| 117 | desired option components. The set of valid options for the |
---|
| 118 | region_get_segment directive are listed in the following table: |
---|
| 119 | |
---|
| 120 | @itemize @bullet |
---|
[a94c5a5d] | 121 | @item @code{WAIT} - task will wait for semaphore (default) |
---|
| 122 | @item @code{NO_WAIT} - task should not wait |
---|
[ae68ff0] | 123 | @end itemize |
---|
| 124 | |
---|
| 125 | Option values are specifically designed to be |
---|
| 126 | mutually exclusive, therefore bitwise OR and addition operations |
---|
| 127 | are equivalent as long as each option appears exactly once in |
---|
| 128 | the component list. An option listed as a default is not |
---|
| 129 | required to appear in the option list, although it is a good |
---|
| 130 | programming practice to specify default options. If all |
---|
[a94c5a5d] | 131 | defaults are desired, the option @code{DEFAULT_OPTIONS} should be |
---|
[ae68ff0] | 132 | specified on this call. |
---|
| 133 | |
---|
| 134 | This example demonstrates the option parameter needed |
---|
| 135 | to poll for a segment. The option parameter passed to the |
---|
[a94c5a5d] | 136 | region_get_segment directive should be @code{NO_WAIT}. |
---|
[ae68ff0] | 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 | |
---|
| 159 | The region_create directive creates a region with the |
---|
| 160 | user-defined name. The user may select FIFO or task priority as |
---|
| 161 | the method for placing waiting tasks in the task wait queue. |
---|
| 162 | RTEMS allocates a Region Control Block (RNCB) from the RNCB free |
---|
| 163 | list to maintain the newly created region. RTEMS also generates |
---|
| 164 | a unique region ID which is returned to the calling task. |
---|
| 165 | |
---|
| 166 | It is not possible to calculate the exact number of |
---|
| 167 | bytes available to the user since RTEMS requires overhead for |
---|
| 168 | each segment allocated. For example, a region with one segment |
---|
| 169 | that is the size of the entire region has more available bytes |
---|
| 170 | than a region with two segments that collectively are the size |
---|
| 171 | of the entire region. This is because the region with one |
---|
| 172 | segment requires only the overhead for one segment, while the |
---|
| 173 | other region requires the overhead for two segments. |
---|
| 174 | |
---|
| 175 | Due to automatic coalescing, the number of segments |
---|
| 176 | in the region dynamically changes. Therefore, the total |
---|
| 177 | overhead 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 | |
---|
| 184 | When a region is created, RTEMS generates a unique |
---|
| 185 | region ID and assigns it to the created region until it is |
---|
| 186 | deleted. The region ID may be obtained by either of two |
---|
| 187 | methods. First, as the result of an invocation of the |
---|
| 188 | region_create directive, the region ID is stored in a user |
---|
| 189 | provided location. Second, the region ID may be obtained later |
---|
| 190 | using the region_ident directive. The region ID is used by |
---|
| 191 | other 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 | |
---|
| 198 | The region_extend directive may be used to add memory |
---|
| 199 | to an existing region. The caller specifies the size in bytes |
---|
| 200 | and starting address of the memory being added. |
---|
| 201 | |
---|
| 202 | NOTE: Please see the release notes or RTEMS source |
---|
| 203 | code for information regarding restrictions on the location of |
---|
| 204 | the memory being added in relation to memory already in the |
---|
| 205 | region. |
---|
| 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 | |
---|
| 212 | The region_get_segment directive attempts to acquire |
---|
| 213 | a segment from a specified region. If the region has enough |
---|
| 214 | available free memory, then a segment is returned successfully |
---|
| 215 | to the caller. When the segment cannot be allocated, one of the |
---|
| 216 | following situations applies: |
---|
| 217 | |
---|
| 218 | @itemize @bullet |
---|
| 219 | @item By default, the calling task will wait forever to acquire the segment. |
---|
| 220 | |
---|
[a94c5a5d] | 221 | @item Specifying the @code{NO_WAIT} option forces an immediate return |
---|
[ae68ff0] | 222 | with an error status code. |
---|
| 223 | |
---|
| 224 | @item Specifying a timeout limits the interval the task will |
---|
| 225 | wait before returning with an error status code. |
---|
| 226 | @end itemize |
---|
| 227 | |
---|
| 228 | If the task waits for the segment, then it is placed |
---|
| 229 | in the region's task wait queue in either FIFO or task priority |
---|
| 230 | order. All tasks waiting on a region are returned an error when |
---|
| 231 | the 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 | |
---|
| 238 | When a segment is returned to a region by the |
---|
| 239 | region_return_segment directive, it is merged with its |
---|
| 240 | unallocated neighbors to form the largest possible segment. The |
---|
| 241 | first task on the wait queue is examined to determine if its |
---|
| 242 | segment request can now be satisfied. If so, it is given a |
---|
| 243 | segment and unblocked. This process is repeated until the first |
---|
| 244 | task'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 | |
---|
| 251 | The region_get_segment_size directive returns the |
---|
| 252 | size in bytes of the specified segment. The size returned |
---|
| 253 | includes any "extra" memory included in the segment because of |
---|
| 254 | rounding 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 | |
---|
| 261 | A region can be removed from the system and returned |
---|
| 262 | to RTEMS with the region_delete directive. When a region is |
---|
| 263 | deleted, its control block is returned to the RNCB free list. A |
---|
| 264 | region with segments still allocated is not allowed to be |
---|
| 265 | deleted. Any task attempting to do so will be returned an |
---|
| 266 | error. As a result of this directive, all tasks blocked waiting |
---|
| 267 | to obtain a segment from the region will be readied and returned |
---|
| 268 | a 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 | |
---|
| 286 | This section details the region manager's directives. |
---|
| 287 | A subsection is dedicated to each of this manager's directives |
---|
| 288 | and describes the calling sequence, related constants, usage, |
---|
| 289 | and 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 | |
---|
[61389eac] | 299 | @ifset is-C |
---|
[ae68ff0] | 300 | @example |
---|
| 301 | rtems_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 |
---|
[61389eac] | 310 | @end ifset |
---|
| 311 | |
---|
| 312 | @ifset is-Ada |
---|
| 313 | @example |
---|
| 314 | procedure 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 |
---|
[ae68ff0] | 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 | |
---|
| 336 | This directive creates a region from a physically |
---|
| 337 | contiguous memory space which starts at starting_address and is |
---|
| 338 | length bytes long. Segments allocated from the region will be a |
---|
| 339 | multiple of page_size bytes in length. The assigned region id |
---|
| 340 | is returned in id. This region id is used as an argument to |
---|
| 341 | other region related directives to access the region. |
---|
| 342 | |
---|
| 343 | For control and maintenance of the region, RTEMS |
---|
| 344 | allocates and initializes an RNCB from the RNCB free pool. Thus |
---|
| 345 | memory from the region is not used to store the RNCB. However, |
---|
| 346 | some overhead within the region is required by RTEMS each time a |
---|
| 347 | segment is constructed in the region. |
---|
| 348 | |
---|
[a3a7527] | 349 | Specifying @code{PRIORITY} in attribute_set causes tasks |
---|
[ae68ff0] | 350 | waiting for a segment to be serviced according to task priority. |
---|
[a3a7527] | 351 | Specifying @code{FIFO} in attribute_set or selecting |
---|
[a94c5a5d] | 352 | @code{DEFAULT_ATTRIBUTES} will cause waiting tasks to be serviced in |
---|
[ae68ff0] | 353 | First In-First Out order. |
---|
| 354 | |
---|
| 355 | The starting_address parameter must be aligned on a |
---|
| 356 | four byte boundary. The page_size parameter must be a multiple |
---|
| 357 | of four greater than or equal to four. |
---|
| 358 | |
---|
| 359 | @subheading NOTES: |
---|
| 360 | |
---|
| 361 | This directive will not cause the calling task to be |
---|
| 362 | preempted. |
---|
| 363 | |
---|
| 364 | The following region attribute constants are defined |
---|
| 365 | by 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 | |
---|
[61389eac] | 380 | @ifset is-C |
---|
[ae68ff0] | 381 | @example |
---|
| 382 | rtems_status_code rtems_region_ident( |
---|
| 383 | rtems_name name, |
---|
| 384 | rtems_id *id |
---|
| 385 | ); |
---|
| 386 | @end example |
---|
[61389eac] | 387 | @end ifset |
---|
| 388 | |
---|
| 389 | @ifset is-Ada |
---|
| 390 | @example |
---|
| 391 | procedure 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 |
---|
[ae68ff0] | 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 | |
---|
| 406 | This directive obtains the region id associated with |
---|
| 407 | the region name to be acquired. If the region name is not |
---|
| 408 | unique, then the region id will match one of the regions with |
---|
| 409 | that name. However, this region id is not guaranteed to |
---|
| 410 | correspond to the desired region. The region id is used to |
---|
| 411 | access this region in other region manager directives. |
---|
| 412 | |
---|
| 413 | @subheading NOTES: |
---|
| 414 | |
---|
| 415 | This 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 | |
---|
[61389eac] | 425 | @ifset is-C |
---|
[ae68ff0] | 426 | @example |
---|
| 427 | rtems_status_code rtems_region_delete( |
---|
| 428 | rtems_id id |
---|
| 429 | ); |
---|
| 430 | @end example |
---|
[61389eac] | 431 | @end ifset |
---|
| 432 | |
---|
| 433 | @ifset is-Ada |
---|
| 434 | @example |
---|
| 435 | procedure Region_Delete ( |
---|
| 436 | ID : in RTEMS.ID; |
---|
| 437 | Result : out RTEMS.Status_Codes |
---|
| 438 | ); |
---|
| 439 | @end example |
---|
| 440 | @end ifset |
---|
[ae68ff0] | 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 | |
---|
| 450 | This directive deletes the region specified by id. |
---|
| 451 | The region cannot be deleted if any of its segments are still |
---|
| 452 | allocated. The RNCB for the deleted region is reclaimed by |
---|
| 453 | RTEMS. |
---|
| 454 | |
---|
| 455 | @subheading NOTES: |
---|
| 456 | |
---|
| 457 | This directive will not cause the calling task to be preempted. |
---|
| 458 | |
---|
| 459 | The calling task does not have to be the task that |
---|
| 460 | created the region. Any local task that knows the region id can |
---|
| 461 | delete 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 | |
---|
[61389eac] | 471 | @ifset is-C |
---|
[ae68ff0] | 472 | @example |
---|
| 473 | rtems_status_code rtems_region_extend( |
---|
| 474 | rtems_id id, |
---|
| 475 | void *starting_address, |
---|
| 476 | rtems_unsigned32 length |
---|
| 477 | ); |
---|
| 478 | @end example |
---|
[61389eac] | 479 | @end ifset |
---|
| 480 | |
---|
| 481 | @ifset is-Ada |
---|
| 482 | @example |
---|
| 483 | procedure 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 |
---|
[ae68ff0] | 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 | |
---|
| 500 | This directive adds the memory which starts at |
---|
| 501 | starting_address for length bytes to the region specified by id. |
---|
| 502 | |
---|
| 503 | @subheading NOTES: |
---|
| 504 | |
---|
| 505 | This directive will not cause the calling task to be preempted. |
---|
| 506 | |
---|
| 507 | The calling task does not have to be the task that |
---|
| 508 | created the region. Any local task that knows the region id can |
---|
| 509 | extend 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 | |
---|
[61389eac] | 519 | @ifset is-C |
---|
[ae68ff0] | 520 | @example |
---|
| 521 | rtems_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 |
---|
[61389eac] | 529 | @end ifset |
---|
| 530 | |
---|
| 531 | @ifset is-Ada |
---|
| 532 | @example |
---|
| 533 | procedure 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 |
---|
[ae68ff0] | 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 |
---|
| 549 | the 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 | |
---|
| 556 | This directive obtains a variable size segment from |
---|
| 557 | the region specified by id. The address of the allocated |
---|
[a94c5a5d] | 558 | segment is returned in segment. The @code{WAIT} and @code{NO_WAIT} components |
---|
[ae68ff0] | 559 | of the options parameter are used to specify whether the calling |
---|
| 560 | tasks wish to wait for a segment to become available or return |
---|
| 561 | immediately if no segment is available. For either option, if a |
---|
| 562 | sufficiently sized segment is available, then the segment is |
---|
| 563 | successfully acquired by returning immediately with the |
---|
[a94c5a5d] | 564 | @code{SUCCESSFUL} status code. |
---|
[ae68ff0] | 565 | |
---|
| 566 | If the calling task chooses to return immediately and |
---|
| 567 | a segment large enough is not available, then an error code |
---|
| 568 | indicating this fact is returned. If the calling task chooses |
---|
| 569 | to wait for the segment and a segment large enough is not |
---|
| 570 | available, then the calling task is placed on the region's |
---|
| 571 | segment wait queue and blocked. If the region was created with |
---|
[a3a7527] | 572 | the @priority{PRIORITY} option, then the calling task is inserted into the |
---|
[ae68ff0] | 573 | wait queue according to its priority. However, if the region |
---|
[a3a7527] | 574 | was created with the @priority{FIFO} option, then the calling task is |
---|
[ae68ff0] | 575 | placed at the rear of the wait queue. |
---|
| 576 | |
---|
| 577 | The timeout parameter specifies the maximum interval |
---|
| 578 | that a task is willing to wait to obtain a segment. If timeout |
---|
[a94c5a5d] | 579 | is set to @code{NO_TIMEOUT}, then the calling task will wait forever. |
---|
[ae68ff0] | 580 | |
---|
| 581 | @subheading NOTES: |
---|
| 582 | |
---|
| 583 | The actual length of the allocated segment may be |
---|
| 584 | larger than the requested size because a segment size is always |
---|
| 585 | a multiple of the region's page size. |
---|
| 586 | |
---|
| 587 | The following segment acquisition option constants |
---|
| 588 | are defined by RTEMS: |
---|
| 589 | |
---|
| 590 | @itemize @bullet |
---|
[a94c5a5d] | 591 | @item @code{WAIT} - task will wait for semaphore (default) |
---|
| 592 | @item @code{NO_WAIT} - task should not wait |
---|
[ae68ff0] | 593 | @end itemize |
---|
| 594 | |
---|
[1ca951ce] | 595 | A clock tick is required to support the timeout functionality of |
---|
| 596 | this directive. |
---|
| 597 | |
---|
[ae68ff0] | 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 | |
---|
[61389eac] | 606 | @ifset is-C |
---|
[ae68ff0] | 607 | @example |
---|
| 608 | rtems_status_code rtems_region_return_segment( |
---|
| 609 | rtems_id id, |
---|
| 610 | void *segment |
---|
| 611 | ); |
---|
| 612 | @end example |
---|
[61389eac] | 613 | @end ifset |
---|
| 614 | |
---|
| 615 | @ifset is-Ada |
---|
| 616 | @example |
---|
| 617 | procedure 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 |
---|
[ae68ff0] | 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 | |
---|
| 633 | This directive returns the segment specified by |
---|
| 634 | segment to the region specified by id. The returned segment is |
---|
| 635 | merged with its neighbors to form the largest possible segment. |
---|
| 636 | The first task on the wait queue is examined to determine if its |
---|
| 637 | segment request can now be satisfied. If so, it is given a |
---|
| 638 | segment and unblocked. This process is repeated until the first |
---|
| 639 | task's segment request cannot be satisfied. |
---|
| 640 | |
---|
| 641 | @subheading NOTES: |
---|
| 642 | |
---|
| 643 | This directive will cause the calling task to be |
---|
| 644 | preempted if one or more local tasks are waiting for a segment |
---|
| 645 | and 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 |
---|
| 651 | is 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 | |
---|
[61389eac] | 662 | @ifset is-C |
---|
[ae68ff0] | 663 | @example |
---|
| 664 | rtems_status_code rtems_region_get_segment_size( |
---|
| 665 | rtems_id id, |
---|
| 666 | void *segment, |
---|
| 667 | rtems_unsigned32 *size |
---|
| 668 | ); |
---|
| 669 | @end example |
---|
[61389eac] | 670 | @end ifset |
---|
| 671 | |
---|
| 672 | @ifset is-Ada |
---|
| 673 | @example |
---|
| 674 | procedure 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 |
---|
[ae68ff0] | 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 | |
---|
| 691 | This directive obtains the size in bytes of the specified segment. |
---|
| 692 | |
---|
| 693 | @subheading NOTES: |
---|
| 694 | |
---|
| 695 | The actual length of the allocated segment may be |
---|
| 696 | larger than the requested size because a segment size is always |
---|
| 697 | a multiple of the region's page size. |
---|
| 698 | |
---|