/**
* @file rtems/rtems/region.h
*
* @defgroup ClassicRegion Regions
*
* @ingroup ClassicRTEMS
* @brief Region Manager
*
* 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-2013.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
* found in the file LICENSE in this distribution or at
* http://www.rtems.org/license/LICENSE.
*/
#ifndef _RTEMS_RTEMS_REGION_H
#define _RTEMS_RTEMS_REGION_H
#include <rtems/rtems/attr.h>
#include <rtems/rtems/options.h>
#include <rtems/rtems/status.h>
#include <rtems/rtems/types.h>
#include <rtems/score/heap.h>
#include <rtems/score/threadq.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup ClassicRegion Regions
*
* @ingroup ClassicRTEMS
*
* This encapsulates functionality related to the Classic API Region
* Manager.
*/
/**@{*/
/**
* The following records define the control block used to manage
* each region.
*/
typedef struct {
Objects_Control Object;
Thread_queue_Control Wait_queue; /* waiting threads */
const Thread_queue_Operations *wait_operations;
uintptr_t maximum_segment_size; /* in bytes */
rtems_attribute attribute_set;
Heap_Control Memory;
} Region_Control;
/**
* @brief 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_create(
rtems_name name,
void *starting_address,
uintptr_t length,
uintptr_t page_size,
rtems_attribute attribute_set,
rtems_id *id
);
/**
* @brief 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.
*
* @param[in] id is the id of region to grow
* @param[in] starting_address starting address of memory area for extension
* @param[in] length is the physical length in bytes to grow the region
*
* @retval 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
);
/**
* @brief 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.
*
* @param[in] name is the user defined region name
* @param[in] id is the pointer to region id
*
* @retval 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_ident(
rtems_name name,
rtems_id *id
);
/**
* @brief RTEMS Get Region Information
*
* This routine implements the rtems_region_get_information directive.
* This directive returns information about the heap associated with
* this region.
*
* @param[in] id is the region id
* @param[in] the_info is the pointer to region information block
*
* @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
* *id filled with the region information block
*/
rtems_status_code rtems_region_get_information(
rtems_id id,
Heap_Information_block *the_info
);
/**
* @brief 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.
*
* @param[in] id is the region id
* @param[in] the_info is the pointer to region information block
*
* @retval 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_free_information(
rtems_id id,
Heap_Information_block *the_info
);
/**
* @brief 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.
*
* @param[in] id is the region id
*
* @retval 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_delete(
rtems_id id
);
/**
* @brief RTEMS Get Region Segment
*
* This routine implements the rtems_region_get_segment directive. It
* attempts to allocate a segment from the region associated with @a id.
* If a segment of the requested @a size size can be allocated, its address
* is returned in @a segment. If no segment is available, then the task
* may return immediately or block waiting for a segment with an optional
* timeout of @a timeout clock ticks. Whether the task blocks or returns
* immediately is based on the no_wait option in the @a option_set.
*
* @param[in] id is the region id
* @param[in] size is the segment size in bytes
* @param[in] option_set is the wait option
* @param[in] timeout is the number of ticks to wait (0 means wait forever)
* @param[in] segment is the pointer to segment address
*
* @retval 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(
rtems_id id,
uintptr_t size,
rtems_option option_set,
rtems_interval timeout,
void **segment
);
/**
* @brief 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.
*
* @param[in] id is the region id
* @param[in] segment is the segment address
* @param[in] size is the pointer to segment size in bytes
*
* @retval 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_get_segment_size(
rtems_id id,
void *segment,
uintptr_t *size
);
/**
* @brief 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.
*
* @param[in] id is the region id
* @param[in] segment is the pointer to segment address
*
* @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
*/
rtems_status_code rtems_region_return_segment(
rtems_id id,
void *segment
);
/**
* @brief 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.
*
* @param[in] id is the region id
* @param[in] segment is the pointer to segment address
* @param[in] size is the new required size
* @retval 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_resize_segment(
rtems_id id,
void *segment,
uintptr_t size,
uintptr_t *old_size
);
/**@}*/
#ifdef __cplusplus
}
#endif
#endif
/* end of include file */
