RTEMS 4.6.99.3 On-Line Library

Region Manager REGION_CREATE - Create a region

RTEMS C User's Guide

14.4.1: REGION_CREATE - Create a region

CALLING SEQUENCE:

rtems_status_code rtems_region_create(
  rtems_name        name,
  void             *starting_address,
  rtems_unsigned32  length,
  rtems_unsigned32  page_size,
  rtems_attribute   attribute_set,
  rtems_id         *id
);

DIRECTIVE STATUS CODES:

RTEMS_SUCCESSFUL - region created successfully
RTEMS_INVALID_NAME - invalid task name
RTEMS_INVALID_ADDRESS - id is NULL
RTEMS_INVALID_ADDRESS - starting_address is NULL
RTEMS_INVALID_ADDRESS - address not on four byte boundary
RTEMS_TOO_MANY - too many regions created
RTEMS_INVALID_SIZE - invalid page size

DESCRIPTION:

This directive creates a region from a physically contiguous memory space which starts at starting_address and is length bytes long. Segments allocated from the region will be a multiple of page_size bytes in length. The assigned region id is returned in id. This region id is used as an argument to other region related directives to access the region.

For control and maintenance of the region, RTEMS allocates and initializes an RNCB from the RNCB free pool. Thus memory from the region is not used to store the RNCB. However, some overhead within the region is required by RTEMS each time a segment is constructed in the region.

Specifying RTEMS_PRIORITY in attribute_set causes tasks waiting for a segment to be serviced according to task priority. Specifying RTEMS_FIFO in attribute_set or selecting RTEMS_DEFAULT_ATTRIBUTES will cause waiting tasks to be serviced in First In-First Out order.

The starting_address parameter must be aligned on a four byte boundary. The page_size parameter must be a multiple of four greater than or equal to four.

NOTES:

This directive will not cause the calling task to be preempted.

The following region attribute constants are defined by RTEMS:

RTEMS_FIFO - tasks wait by FIFO (default)
RTEMS_PRIORITY - tasks wait by priority

RTEMS C User's Guide