Region Manager. More...

Collaboration diagram for Regions:

Data Structures
struct	Region_Control
	The following records define the control block used to manage each region. More...
Defines
#define	RTEMS_REGION_EXTERN extern
	Instantiate RTEMS Region Data.
#define	_Region_Debug_Walk(_the_region, _source)
	_Region_Debug_Walk
Functions
void	_Region_Manager_initialization (void)
	_Region_Manager_initialization
rtems_status_code	rtems_region_create (rtems_name name, void starting_address, uintptr_t length, uintptr_t page_size, rtems_attribute attribute_set, rtems_id id)
	rtems_region_create
rtems_status_code	rtems_region_extend (rtems_id id, void *starting_address, uintptr_t length)
	RTEMS Extend Region.
rtems_status_code	rtems_region_ident (rtems_name name, rtems_id *id)
	RTEMS Region Name to Id.
rtems_status_code	rtems_region_get_information (rtems_id id, Heap_Information_block *the_info)
	RTEMS Get Region Information.
rtems_status_code	rtems_region_get_free_information (rtems_id id, Heap_Information_block *the_info)
	RTEMS Get Region Free Information.
rtems_status_code	rtems_region_delete (rtems_id id)
	RTEMS Delete Region.
rtems_status_code	rtems_region_get_segment (rtems_id id, uintptr_t size, rtems_option option_set, rtems_interval timeout, void **segment)
	RTEMS Get Region Segment.
rtems_status_code	rtems_region_get_segment_size (rtems_id id, void segment, uintptr_t size)
	RTEMS Get Region Segment Size.
rtems_status_code	rtems_region_return_segment (rtems_id id, void *segment)
	RTEMS Return Region Segment.
rtems_status_code	rtems_region_resize_segment (rtems_id id, void segment, uintptr_t size, uintptr_t old_size)
	Resize RTEMS Region Segment.
void	_Region_Process_queue (Region_Control *the_region)
	Process Region Queue.
RTEMS_INLINE_ROUTINE Region_Control *	_Region_Allocate (void)
	Region_Allocate.
RTEMS_INLINE_ROUTINE void	_Region_Free (Region_Control *the_region)
	Region_Free.
RTEMS_INLINE_ROUTINE Region_Control *	_Region_Get (Objects_Id id, Objects_Locations *location)
	Region_Get.
RTEMS_INLINE_ROUTINE void *	_Region_Allocate_segment (Region_Control *the_region, uintptr_t size)
	Region_Allocate_segment.
RTEMS_INLINE_ROUTINE bool	_Region_Free_segment (Region_Control the_region, void the_segment)
	Region_Free_segment.
RTEMS_INLINE_ROUTINE bool	_Region_Is_null (Region_Control *the_region)
	Region_Is_null.
Variables
RTEMS_REGION_EXTERN Objects_Information	_Region_Information
	The following defines the information control block used to manage this class of objects.

Detailed Description

Region Manager.

Macro Implementation from Region Manager.

This encapsulates functionality which XXX.

This include file contains all the constants and structures associated with the Region Manager. This manager provides facilities to dynamically allocate memory in variable sized units which are returned as segments.

Directives provided are:

create a region
get an ID of a region
delete a region
get a segment from a region
return a segment to a region

This file contains the macro implementation of the inlined routines from the Region Manager.

Define Documentation

#define _Region_Debug_Walk	(	_the_region,
		_source
	)

_Region_Debug_Walk

This routine is invoked to verify the integrity of a heap associated with the_region.

#define RTEMS_REGION_EXTERN extern

Instantiate RTEMS Region Data.

Region Manager -- Instantiate Data

This constant is defined to extern most of the time when using this header file. However by defining it to nothing, the data declared in this header file can be instantiated. This is done in a single per manager file.

Function Documentation

RTEMS_INLINE_ROUTINE Region_Control* _Region_Allocate ( void )

Region_Allocate.

This function allocates a region control block from the inactive chain of free region control blocks.

References _Objects_Allocate(), and _Region_Information.

RTEMS_INLINE_ROUTINE void* _Region_Allocate_segment	(	Region_Control *	the_region,
		uintptr_t	size
	)

Region_Allocate_segment.

This function attempts to allocate a segment from the_region. If successful, it returns the address of the allocated segment. Otherwise, it returns NULL.

References _Heap_Allocate().

RTEMS_INLINE_ROUTINE void _Region_Free ( Region_Control * the_region )

Region_Free.

This routine frees a region control block to the inactive chain of free region control blocks.

References _Objects_Free(), and _Region_Information.

RTEMS_INLINE_ROUTINE bool _Region_Free_segment	(	Region_Control *	the_region,
		void *	the_segment
	)

Region_Free_segment.

This function frees the_segment to the_region.

References _Heap_Free().

RTEMS_INLINE_ROUTINE Region_Control* _Region_Get	(	Objects_Id	id,
		Objects_Locations *	location
	)

Region_Get.

This function maps region IDs to region control blocks. If ID corresponds to a local region, then it returns the_region control pointer which maps to ID and location is set to OBJECTS_LOCAL. Otherwise, location is set to OBJECTS_ERROR and the_region is undefined.

References _Objects_Get_no_protection(), and _Region_Information.

RTEMS_INLINE_ROUTINE bool _Region_Is_null ( Region_Control * the_region )

Region_Is_null.

This function returns TRUE if the_region is NULL and FALSE otherwise.

void _Region_Manager_initialization ( void )

_Region_Manager_initialization

Region Manager

This routine performs the initialization necessary for this manager.

void _Region_Process_queue ( Region_Control * the_region )

Process Region Queue.

This is a helper routine which is invoked any time memory is freed. It looks at the set of waiting tasks and attempts to satisfy all outstanding requests.

Parameters:

[in] the_region is the the region

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

rtems_region_create

Region Manager

This routine implements the rtems_region_create directive. The region will have the name name. The memory area managed by the region is of length bytes and starts at starting_address. The memory area will be divided into as many allocatable units of page_size bytes as possible. The attribute_set determines which thread queue discipline is used by the region. It returns the id of the created region in ID.

rtems_status_code rtems_region_delete ( rtems_id id )

RTEMS Delete Region.

This routine implements the rtems_region_delete directive. The region indicated by ID is deleted, provided that none of its segments are still allocated.

Parameters:

[in] id is the region id

Return values:

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

rtems_status_code rtems_region_extend	(	rtems_id	id,
		void *	starting_address,
		uintptr_t	length
	)

RTEMS Extend Region.

This routine implements the rtems_region_extend directive. The region will have the name name. The memory area managed by the region will be attempted to be grown by length bytes using the memory starting at starting_address.

Parameters:

[in]	id	is the id of region to grow
[in]	starting_address	starting address of memory area for extension
[in]	length	is the physical length in bytes to grow the region

Return values:

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

rtems_status_code rtems_region_get_free_information	(	rtems_id	id,
		Heap_Information_block *	the_info
	)

RTEMS Get Region Free Information.

This routine implements the rtems_region_get_free_information directive. This directive returns information about the free blocks in the heap associated with this region. Information about the used blocks will be returned as zero.

Parameters:

[in]	id	is the region id
[in]	the_info	is the pointer to region information block

Return values:

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error. If successful, the the_info will be filled in with the region information block.

rtems_status_code rtems_region_get_information	(	rtems_id	id,
		Heap_Information_block *	the_info
	)

RTEMS Get Region Information.

This routine implements the rtems_region_get_information directive. This directive returns information about the heap associated with this region.

Parameters:

[in]	id	is the region id
[in]	the_info	is the pointer to region information block

Return values:

RTEMS_SUCCESSFUL if successful or error code if unsuccessful and *id filled with the region information block

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

RTEMS Get Region Segment.

This routine implements the rtems_region_get_segment directive. It attempts to allocate a segment from the region associated with id. If a segment of the requested size size can be allocated, its address is returned in segment. If no segment is available, then the task may return immediately or block waiting for a segment with an optional timeout of timeout clock ticks. Whether the task blocks or returns immediately is based on the no_wait option in the option_set.

Parameters:

[in]	id	is the region id
[in]	size	is the segment size in bytes
[in]	option_set	is the wait option
[in]	timeout	is the number of ticks to wait (0 means wait forever)
[in]	segment	is the pointer to segment address

Return values:

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error. If successful, the segment will be filled in with the segment address.

rtems_status_code rtems_region_get_segment_size	(	rtems_id	id,
		void *	segment,
		uintptr_t *	size
	)

RTEMS Get Region Segment Size.

This routine implements the rtems_region_get_segment_size directive. It returns the size in bytes of the specified user memory area.

Parameters:

[in]	id	is the region id
[in]	segment	is the segment address
[in]	size	is the pointer to segment size in bytes

Return values:

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error. If successful, the size will be filled in with the segment size in bytes.

rtems_status_code rtems_region_ident	(	rtems_name	name,
		rtems_id *	id
	)

RTEMS Region Name to Id.

This routine implements the rtems_region_ident directive. This directive returns the region ID associated with name. If more than one region is named name, then the region to which the ID belongs is arbitrary.

Parameters:

[in]	name	is the user defined region name
[in]	id	is the pointer to region id

Return values:

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error. If successful, the id will be filled in with the region id.

rtems_status_code rtems_region_resize_segment	(	rtems_id	id,
		void *	segment,
		uintptr_t	size,
		uintptr_t *	old_size
	)

Resize RTEMS Region Segment.

This routine implements the rtems_region_resize_segment directive. It tries to resize segment in the region associated with 'id' to the new size 'size' in place. The first 'size' or old size bytes of the segment (whatever is less) are guaranteed to remain unmodified. The segment must have been previously allocated from the same region. If resizing the segment results in enough memory being available to satisfy the rtems_region_get_segment of the first blocked task, then that task and as many subsequent tasks as possible will be unblocked with their requests satisfied.

Parameters:

[in]	id	is the region id
[in]	segment	is the pointer to segment address
[in]	size	is the new required size

Return values:

RTEMS_SUCCESSFUL if operation successful, RTEMS_UNSATISFIED if the the segment can't be resized in place or any other code at failure

Note:: On RTEMS_SUCCESSFUL or RTEMS_UNSATISFIED exit it returns into the 'old_size' the old size in bytes of the user memory area of the specified segment.

rtems_status_code rtems_region_return_segment	(	rtems_id	id,
		void *	segment
	)

RTEMS Return Region Segment.

This routine implements the rtems_region_return_segment directive. It frees the segment to the region associated with ID. The segment must have been previously allocated from the same region. If freeing the segment results in enough memory being available to satisfy the rtems_region_get_segment of the first blocked task, then that task and as many subsequent tasks as possible will be unblocked with their requests satisfied.

Parameters:

[in]	id	is the region id
[in]	segment	is the pointer to segment address

Return values:

RTEMS_SUCCESSFUL if successful or error code if unsuccessful

Data Structures

Defines

Functions

Variables

Detailed Description

Define Documentation

Function Documentation