/** * @file * * @ingroup ClassicRegion * * @brief Classic Region Manager API */ /* 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 #include #include #include #ifdef __cplusplus extern "C" { #endif /** * @defgroup ClassicRegion Regions * * @ingroup ClassicRTEMS * * This encapsulates functionality related to the Classic API Region * Manager. */ /**@{*/ /** * @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 */