rtems_status_code rtems_region_get_segment( rtems_id id, uint32_t size, rtems_option option_set, rtems_interval timeout, void **segment );
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
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.
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.
Copyright © 1988-2004 OAR Corporation