/* region.h * * 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 * * COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994. * On-Line Applications Research Corporation (OAR). * All rights assigned to U.S. Government, 1994. * * This material may be reproduced by or for the U.S. Government pursuant * to the copyright license under the clause at DFARS 252.227-7013. This * notice must appear in all copies of this file and its derivatives. * * $Id$ */ #ifndef __RTEMS_REGION_h #define __RTEMS_REGION_h #ifdef __cplusplus extern "C" { #endif #include #include #include #include #include #include /* * The following records define the control block used to manage * each region. */ typedef struct { Objects_Control Object; Thread_queue_Control Wait_queue; /* waiting threads */ void *starting_address; /* physical start addr */ unsigned32 length; /* physical length(bytes) */ unsigned32 page_size; /* in bytes */ unsigned32 maximum_segment_size; /* in bytes */ rtems_attribute attribute_set; unsigned32 number_of_used_blocks; /* blocks allocated */ Heap_Control Memory; } Region_Control; /* * The following defines the information control block used to * manage this class of objects. */ EXTERN Objects_Information _Region_Information; /* * _Region_Manager_initialization * * DESCRIPTION: * * This routine performs the initialization necessary for this manager. */ void _Region_Manager_initialization( unsigned32 maximum_regions ); /* * rtems_region_create * * DESCRIPTION: * * 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_create( rtems_name name, void *starting_address, unsigned32 length, unsigned32 page_size, rtems_attribute attribute_set, Objects_Id *id ); /* * rtems_region_extend * * DESCRIPTION: * * 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. */ rtems_status_code rtems_region_extend( Objects_Id id, void *starting_address, unsigned32 length ); /* * rtems_region_ident * * DESCRIPTION: * * 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. */ rtems_status_code rtems_region_ident( rtems_name name, Objects_Id *id ); /* * rtems_region_delete * * DESCRIPTION: * * This routine implements the rtems_region_delete directive. The * region indicated by ID is deleted. */ rtems_status_code rtems_region_delete( Objects_Id id ); /* * rtems_region_get_segment * * DESCRIPTION: * * 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 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. */ rtems_status_code rtems_region_get_segment( Objects_Id id, unsigned32 size, rtems_option option_set, rtems_interval timeout, void **segment ); /* * rtems_region_get_segment_size * * DESCRIPTION: * * This routine implements the rtems_region_get_segment_size directive. It * returns the size in bytes of the specified user memory area. */ rtems_status_code rtems_region_get_segment_size( Objects_Id id, void *segment, unsigned32 *size ); /* * rtems_region_return_segment * * DESCRIPTION: * * 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. */ rtems_status_code rtems_region_return_segment( Objects_Id id, void *segment ); /* * _Region_Allocate * * DESCRIPTION: * * This function allocates a region control block from * the inactive chain of free region control blocks. */ STATIC INLINE Region_Control *_Region_Allocate( void ); /* * _Region_Free * * DESCRIPTION: * * This routine frees a region control block to the * inactive chain of free region control blocks. */ STATIC INLINE void _Region_Free ( Region_Control *the_region ); /* * _Region_Get * * DESCRIPTION: * * 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. */ STATIC INLINE Region_Control *_Region_Get ( Objects_Id id, Objects_Locations *location ); /* * _Region_Allocate_segment * * DESCRIPTION: * * This function attempts to allocate a segment from the_region. * If successful, it returns the address of the allocated segment. * Otherwise, it returns NULL. */ STATIC INLINE void *_Region_Allocate_segment ( Region_Control *the_region, unsigned32 size ); /* * _Region_Free_segment * * DESCRIPTION: * * This function frees the_segment to the_region. */ STATIC INLINE boolean _Region_Free_segment ( Region_Control *the_region, void *the_segment ); /* * _Region_Is_null * * DESCRIPTION: * * This function returns TRUE if the_region is NULL and FALSE otherwise. */ STATIC INLINE boolean _Region_Is_null ( Region_Control *the_region ); #include #include /* * _Region_Debug_Walk * * DESCRIPTION: * * This routine is invoked to verify the integrity of a heap associated * with the_region. */ #ifdef RTEMS_DEBUG #define _Region_Debug_Walk( _the_region, _source ) \ do { \ if ( _Debug_Is_enabled( RTEMS_DEBUG_REGION ) ) \ _Heap_Walk( &(_the_region)->Memory, _source, FALSE ); \ } while ( 0 ) #else #define _Region_Debug_Walk( _the_region, _source ) #endif #ifdef __cplusplus } #endif #endif /* end of include file */