RTEMS 4.8.1 On-Line Library

Region Manager REGION_GET_SEGMENT - Get segment from a region

RTEMS C User's Guide

14.4.5: REGION_GET_SEGMENT - Get segment from a region

CALLING SEQUENCE:

rtems_status_code rtems_region_get_segment(
  rtems_id         id,
  uint32_t         size,
  rtems_option     option_set,
  rtems_interval   timeout,
  void           **segment
);

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 C User's Guide