18.3. Operations

18.3.1. Creating a Region

The rtems_region_create directive creates a region with the user-defined name. The user may select FIFO or task priority as the method for placing waiting tasks in the task wait queue. RTEMS allocates a Region Control Block (RNCB) from the RNCB free list to maintain the newly created region. RTEMS also generates a unique region ID which is returned to the calling task.

It is not possible to calculate the exact number of bytes available to the user since RTEMS requires overhead for each segment allocated. For example, a region with one segment that is the size of the entire region has more available bytes than a region with two segments that collectively are the size of the entire region. This is because the region with one segment requires only the overhead for one segment, while the other region requires the overhead for two segments.

Due to automatic coalescing, the number of segments in the region dynamically changes. Therefore, the total overhead required by RTEMS dynamically changes.

18.3.2. Obtaining Region IDs

When a region is created, RTEMS generates a unique region ID and assigns it to the created region until it is deleted. The region ID may be obtained by either of two methods. First, as the result of an invocation of the rtems_region_create directive, the region ID is stored in a user provided location. Second, the region ID may be obtained later using the rtems_region_ident directive. The region ID is used by other region manager directives to access this region.

18.3.3. Adding Memory to a Region

The rtems_region_extend directive may be used to add memory to an existing region. The caller specifies the size in bytes and starting address of the memory being added.

18.3.4. Acquiring a Segment

The rtems_region_get_segment directive attempts to acquire a segment from a specified region. If the region has enough available free memory, then a segment is returned successfully to the caller. When the segment cannot be allocated, one of the following situations applies:

  • By default, the calling task will wait forever to acquire the segment.

  • Specifying the RTEMS_NO_WAIT option forces an immediate return with an error status code.

  • Specifying a timeout limits the interval the task will wait before returning with an error status code.

If the task waits for the segment, then it is placed in the region’s task wait queue in either FIFO or task priority order. All tasks waiting on a region are returned an error when the message queue is deleted.

18.3.5. Releasing a Segment

When a segment is returned to a region by the rtems_region_return_segment directive, it is merged with its unallocated neighbors to form the largest possible segment. The first task on the wait queue is examined to determine if its segment request can now be satisfied. If so, it is given a segment and unblocked. This process is repeated until the first task’s segment request cannot be satisfied.

18.3.6. Obtaining the Size of a Segment

The rtems_region_get_segment_size directive returns the size in bytes of the specified segment. The size returned includes any “extra” memory included in the segment because of rounding up to a page size boundary.

18.3.7. Changing the Size of a Segment

The rtems_region_resize_segment directive is used to change the size in bytes of the specified segment. The size may be increased or decreased. When increasing the size of a segment, it is possible that the request cannot be satisfied. This directive provides functionality similar to the realloc() function in the Standard C Library.

18.3.8. Deleting a Region

A region can be removed from the system and returned to RTEMS with the rtems_region_delete directive. When a region is deleted, its control block is returned to the RNCB free list. A region with segments still allocated is not allowed to be deleted. Any task attempting to do so will be returned an error. As a result of this directive, all tasks blocked waiting to obtain a segment from the region will be readied and returned a status code which indicates that the region was deleted.