RTEMS 4.7.1 On-Line Library

Region Manager REGION_GET_SEGMENT - Get segment from a region

RTEMS Ada User's Guide

14.4.5: REGION_GET_SEGMENT - Get segment from a region

CALLING SEQUENCE:

procedure Region_Get_Segment (
   ID         : in     RTEMS.ID;
   Size       : in     RTEMS.Unsigned32;
   Option_Set : in     RTEMS.Option;
   Timeout    : in     RTEMS.Interval;
   Segment    :    out RTEMS.Address;
   Result     :    out RTEMS.Status_Codes
);

DIRECTIVE STATUS CODES:

RTEMS.SUCCESSFUL - segment obtained successfully
RTEMS.INVALID_ADDRESS - segment is NULL
RTEMS.INVALID_ID - invalid region id
RTEMS.INVALID_SIZE - request is for zero bytes or exceeds the size of maximum segment which is possible for this region
RTEMS.UNSATISFIED - segment of requested size not available
RTEMS.TIMEOUT - timed out waiting for segment
RTEMS.OBJECT_WAS_DELETED - semaphore deleted while waiting

DESCRIPTION:

This directive obtains a variable size segment from the region specified by id. The address of the allocated segment is returned in segment. The RTEMS.WAIT and RTEMS.NO_WAIT components of the options parameter are used to specify whether the calling tasks wish to wait for a segment to become available or return immediately if no segment is available. For either option, if a sufficiently sized segment is available, then the segment is successfully acquired by returning immediately with the RTEMS.SUCCESSFUL status code.

If the calling task chooses to return immediately and a segment large enough is not available, then an error code indicating this fact is returned. If the calling task chooses to wait for the segment and a segment large enough is not available, then the calling task is placed on the region's segment wait queue and blocked. If the region was created with the RTEMS.PRIORITY option, then the calling task is inserted into the wait queue according to its priority. However, if the region was created with the RTEMS.FIFO option, then the calling task is placed at the rear of the wait queue.

The timeout parameter specifies the maximum interval that a task is willing to wait to obtain a segment. If timeout is set to RTEMS.NO_TIMEOUT, then the calling task will wait forever.

NOTES:

The actual length of the allocated segment may be larger than the requested size because a segment size is always a multiple of the region's page size.

The following segment acquisition option constants are defined by RTEMS:

RTEMS.WAIT - task will wait for semaphore (default)
RTEMS.NO_WAIT - task should not wait

A clock tick is required to support the timeout functionality of this directive.

RTEMS Ada User's Guide