[4b487363] | 1 | /** |
---|
| 2 | * @file rtems/rtems/region.h |
---|
[067a96a] | 3 | * |
---|
[61b8e9f] | 4 | * @defgroup ClassicRegion Regions |
---|
[f1eb368d] | 5 | * |
---|
[61b8e9f] | 6 | * @ingroup ClassicRTEMS |
---|
| 7 | * @brief Region Manager |
---|
[ac7d5ef0] | 8 | * |
---|
[61b8e9f] | 9 | * This include file contains all the constants and structures associated |
---|
| 10 | * with the Region Manager. This manager provides facilities to dynamically |
---|
| 11 | * allocate memory in variable sized units which are returned as segments. |
---|
[ac7d5ef0] | 12 | * |
---|
[61b8e9f] | 13 | * Directives provided are: |
---|
| 14 | * |
---|
| 15 | * - create a region |
---|
| 16 | * - get an ID of a region |
---|
| 17 | * - delete a region |
---|
| 18 | * - get a segment from a region |
---|
| 19 | * - return a segment to a region |
---|
[067a96a] | 20 | */ |
---|
| 21 | |
---|
[651e3aa] | 22 | /* COPYRIGHT (c) 1989-2013. |
---|
[61b8e9f] | 23 | * On-Line Applications Research Corporation (OAR). |
---|
[ac7d5ef0] | 24 | * |
---|
[61b8e9f] | 25 | * The license and distribution terms for this file may be |
---|
| 26 | * found in the file LICENSE in this distribution or at |
---|
[c499856] | 27 | * http://www.rtems.org/license/LICENSE. |
---|
[ac7d5ef0] | 28 | */ |
---|
| 29 | |
---|
[092f142a] | 30 | #ifndef _RTEMS_RTEMS_REGION_H |
---|
| 31 | #define _RTEMS_RTEMS_REGION_H |
---|
[ac7d5ef0] | 32 | |
---|
[3a4ae6c] | 33 | #include <rtems/rtems/attr.h> |
---|
[6f1384c] | 34 | #include <rtems/rtems/options.h> |
---|
| 35 | #include <rtems/rtems/status.h> |
---|
[3a4ae6c] | 36 | #include <rtems/rtems/types.h> |
---|
[f6c7c57d] | 37 | #include <rtems/score/heap.h> |
---|
[a112364] | 38 | #include <rtems/score/threadq.h> |
---|
[f6c7c57d] | 39 | |
---|
| 40 | #ifdef __cplusplus |
---|
| 41 | extern "C" { |
---|
| 42 | #endif |
---|
[ac7d5ef0] | 43 | |
---|
[067a96a] | 44 | /** |
---|
[c85ab23] | 45 | * @defgroup ClassicRegion Regions |
---|
| 46 | * |
---|
| 47 | * @ingroup ClassicRTEMS |
---|
[067a96a] | 48 | * |
---|
[651e3aa] | 49 | * This encapsulates functionality related to the Classic API Region |
---|
| 50 | * Manager. |
---|
[067a96a] | 51 | */ |
---|
| 52 | /**@{*/ |
---|
| 53 | |
---|
| 54 | /** |
---|
[ac7d5ef0] | 55 | * The following records define the control block used to manage |
---|
| 56 | * each region. |
---|
| 57 | */ |
---|
| 58 | |
---|
| 59 | typedef struct { |
---|
| 60 | Objects_Control Object; |
---|
[e65f596] | 61 | Thread_queue_Control Wait_queue; /* waiting threads */ |
---|
[1e1a91ed] | 62 | const Thread_queue_Operations *wait_operations; |
---|
[dea3eccb] | 63 | uintptr_t maximum_segment_size; /* in bytes */ |
---|
[ac7d5ef0] | 64 | rtems_attribute attribute_set; |
---|
| 65 | Heap_Control Memory; |
---|
| 66 | } Region_Control; |
---|
| 67 | |
---|
[067a96a] | 68 | /** |
---|
| 69 | * @brief rtems_region_create |
---|
[ac7d5ef0] | 70 | * |
---|
[4efe1955] | 71 | * Region Manager |
---|
| 72 | * |
---|
[ac7d5ef0] | 73 | * This routine implements the rtems_region_create directive. The |
---|
| 74 | * region will have the name name. The memory area managed by |
---|
| 75 | * the region is of length bytes and starts at starting_address. |
---|
| 76 | * The memory area will be divided into as many allocatable units of |
---|
| 77 | * page_size bytes as possible. The attribute_set determines which |
---|
| 78 | * thread queue discipline is used by the region. It returns the |
---|
| 79 | * id of the created region in ID. |
---|
| 80 | */ |
---|
| 81 | rtems_status_code rtems_region_create( |
---|
[3235ad9] | 82 | rtems_name name, |
---|
[ac7d5ef0] | 83 | void *starting_address, |
---|
[dea3eccb] | 84 | uintptr_t length, |
---|
| 85 | uintptr_t page_size, |
---|
| 86 | rtems_attribute attribute_set, |
---|
[d3b72ca3] | 87 | rtems_id *id |
---|
[ac7d5ef0] | 88 | ); |
---|
| 89 | |
---|
[067a96a] | 90 | /** |
---|
[61b8e9f] | 91 | * @brief RTEMS Extend Region |
---|
[ac7d5ef0] | 92 | * |
---|
[61b8e9f] | 93 | * This routine implements the rtems_region_extend directive. The |
---|
| 94 | * region will have the name name. The memory area managed by |
---|
| 95 | * the region will be attempted to be grown by length bytes using |
---|
| 96 | * the memory starting at starting_address. |
---|
[f1eb368d] | 97 | * |
---|
[61b8e9f] | 98 | * @param[in] id is the id of region to grow |
---|
| 99 | * @param[in] starting_address starting address of memory area for extension |
---|
| 100 | * @param[in] length is the physical length in bytes to grow the region |
---|
[f1eb368d] | 101 | * |
---|
[61b8e9f] | 102 | * @retval This method returns RTEMS_SUCCESSFUL if there was not an |
---|
| 103 | * error. Otherwise, a status code is returned indicating the |
---|
| 104 | * source of the error. |
---|
[ac7d5ef0] | 105 | */ |
---|
| 106 | rtems_status_code rtems_region_extend( |
---|
[d3b72ca3] | 107 | rtems_id id, |
---|
[ac7d5ef0] | 108 | void *starting_address, |
---|
[dea3eccb] | 109 | uintptr_t length |
---|
[ac7d5ef0] | 110 | ); |
---|
| 111 | |
---|
[067a96a] | 112 | /** |
---|
[61b8e9f] | 113 | * @brief RTEMS Region Name to Id |
---|
[ac7d5ef0] | 114 | * |
---|
[61b8e9f] | 115 | * This routine implements the rtems_region_ident directive. |
---|
| 116 | * This directive returns the region ID associated with name. |
---|
| 117 | * If more than one region is named name, then the region |
---|
| 118 | * to which the ID belongs is arbitrary. |
---|
[f1eb368d] | 119 | * |
---|
[61b8e9f] | 120 | * @param[in] name is the user defined region name |
---|
| 121 | * @param[in] id is the pointer to region id |
---|
[f1eb368d] | 122 | * |
---|
[61b8e9f] | 123 | * @retval This method returns RTEMS_SUCCESSFUL if there was not an |
---|
| 124 | * error. Otherwise, a status code is returned indicating the |
---|
| 125 | * source of the error. If successful, the id will |
---|
| 126 | * be filled in with the region id. |
---|
[ac7d5ef0] | 127 | */ |
---|
| 128 | rtems_status_code rtems_region_ident( |
---|
[3235ad9] | 129 | rtems_name name, |
---|
[d3b72ca3] | 130 | rtems_id *id |
---|
[ac7d5ef0] | 131 | ); |
---|
| 132 | |
---|
[067a96a] | 133 | /** |
---|
[61b8e9f] | 134 | * @brief RTEMS Get Region Information |
---|
[b541e1f] | 135 | * |
---|
[61b8e9f] | 136 | * This routine implements the rtems_region_get_information directive. |
---|
| 137 | * This directive returns information about the heap associated with |
---|
| 138 | * this region. |
---|
[4efe1955] | 139 | * |
---|
[61b8e9f] | 140 | * @param[in] id is the region id |
---|
| 141 | * @param[in] the_info is the pointer to region information block |
---|
[4efe1955] | 142 | * |
---|
[61b8e9f] | 143 | * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and |
---|
| 144 | * *id filled with the region information block |
---|
[b541e1f] | 145 | */ |
---|
| 146 | rtems_status_code rtems_region_get_information( |
---|
[d3b72ca3] | 147 | rtems_id id, |
---|
[b541e1f] | 148 | Heap_Information_block *the_info |
---|
| 149 | ); |
---|
| 150 | |
---|
[067a96a] | 151 | /** |
---|
[61b8e9f] | 152 | * @brief RTEMS Get Region Free Information |
---|
[9b3f187] | 153 | * |
---|
[61b8e9f] | 154 | * This routine implements the rtems_region_get_free_information directive. |
---|
| 155 | * This directive returns information about the free blocks in the |
---|
| 156 | * heap associated with this region. Information about the used blocks |
---|
| 157 | * will be returned as zero. |
---|
[f1eb368d] | 158 | * |
---|
[61b8e9f] | 159 | * @param[in] id is the region id |
---|
| 160 | * @param[in] the_info is the pointer to region information block |
---|
[f1eb368d] | 161 | * |
---|
[61b8e9f] | 162 | * @retval This method returns RTEMS_SUCCESSFUL if there was not an |
---|
| 163 | * error. Otherwise, a status code is returned indicating the |
---|
| 164 | * source of the error. If successful, the the_info will |
---|
| 165 | * be filled in with the region information block. |
---|
[9b3f187] | 166 | */ |
---|
| 167 | rtems_status_code rtems_region_get_free_information( |
---|
[d3b72ca3] | 168 | rtems_id id, |
---|
[9b3f187] | 169 | Heap_Information_block *the_info |
---|
| 170 | ); |
---|
| 171 | |
---|
[067a96a] | 172 | /** |
---|
[61b8e9f] | 173 | * @brief RTEMS Delete Region |
---|
[ac7d5ef0] | 174 | * |
---|
[61b8e9f] | 175 | * This routine implements the rtems_region_delete directive. The |
---|
| 176 | * region indicated by ID is deleted, provided that none of its segments are |
---|
| 177 | * still allocated. |
---|
[f1eb368d] | 178 | * |
---|
[61b8e9f] | 179 | * @param[in] id is the region id |
---|
[f1eb368d] | 180 | * |
---|
[61b8e9f] | 181 | * @retval This method returns RTEMS_SUCCESSFUL if there was not an |
---|
| 182 | * error. Otherwise, a status code is returned indicating the |
---|
| 183 | * source of the error. |
---|
[ac7d5ef0] | 184 | */ |
---|
| 185 | rtems_status_code rtems_region_delete( |
---|
[d3b72ca3] | 186 | rtems_id id |
---|
[ac7d5ef0] | 187 | ); |
---|
| 188 | |
---|
[067a96a] | 189 | /** |
---|
[61b8e9f] | 190 | * @brief RTEMS Get Region Segment |
---|
| 191 | * |
---|
| 192 | * This routine implements the rtems_region_get_segment directive. It |
---|
| 193 | * attempts to allocate a segment from the region associated with @a id. |
---|
| 194 | * If a segment of the requested @a size size can be allocated, its address |
---|
| 195 | * is returned in @a segment. If no segment is available, then the task |
---|
| 196 | * may return immediately or block waiting for a segment with an optional |
---|
| 197 | * timeout of @a timeout clock ticks. Whether the task blocks or returns |
---|
| 198 | * immediately is based on the no_wait option in the @a option_set. |
---|
| 199 | * |
---|
| 200 | * @param[in] id is the region id |
---|
| 201 | * @param[in] size is the segment size in bytes |
---|
| 202 | * @param[in] option_set is the wait option |
---|
| 203 | * @param[in] timeout is the number of ticks to wait (0 means wait forever) |
---|
| 204 | * @param[in] segment is the pointer to segment address |
---|
| 205 | * |
---|
| 206 | * @retval This method returns RTEMS_SUCCESSFUL if there was not an |
---|
| 207 | * error. Otherwise, a status code is returned indicating the |
---|
| 208 | * source of the error. If successful, the segment will |
---|
| 209 | * be filled in with the segment address. |
---|
[ac7d5ef0] | 210 | */ |
---|
| 211 | rtems_status_code rtems_region_get_segment( |
---|
[d3b72ca3] | 212 | rtems_id id, |
---|
[dea3eccb] | 213 | uintptr_t size, |
---|
[3a4ae6c] | 214 | rtems_option option_set, |
---|
| 215 | rtems_interval timeout, |
---|
[dea3eccb] | 216 | void **segment |
---|
[ac7d5ef0] | 217 | ); |
---|
| 218 | |
---|
[067a96a] | 219 | /** |
---|
[61b8e9f] | 220 | * @brief RTEMS Get Region Segment Size |
---|
[ac7d5ef0] | 221 | * |
---|
[61b8e9f] | 222 | * This routine implements the rtems_region_get_segment_size directive. It |
---|
| 223 | * returns the size in bytes of the specified user memory area. |
---|
[f1eb368d] | 224 | * |
---|
[61b8e9f] | 225 | * @param[in] id is the region id |
---|
| 226 | * @param[in] segment is the segment address |
---|
| 227 | * @param[in] size is the pointer to segment size in bytes |
---|
[f1eb368d] | 228 | * |
---|
[61b8e9f] | 229 | * @retval This method returns RTEMS_SUCCESSFUL if there was not an |
---|
| 230 | * error. Otherwise, a status code is returned indicating the |
---|
| 231 | * source of the error. If successful, the size will |
---|
| 232 | * be filled in with the segment size in bytes. |
---|
[ac7d5ef0] | 233 | */ |
---|
| 234 | rtems_status_code rtems_region_get_segment_size( |
---|
[d3b72ca3] | 235 | rtems_id id, |
---|
[ac7d5ef0] | 236 | void *segment, |
---|
[dea3eccb] | 237 | uintptr_t *size |
---|
[ac7d5ef0] | 238 | ); |
---|
| 239 | |
---|
[067a96a] | 240 | /** |
---|
[61b8e9f] | 241 | * @brief RTEMS Return Region Segment |
---|
[ac7d5ef0] | 242 | * |
---|
[61b8e9f] | 243 | * This routine implements the rtems_region_return_segment directive. It |
---|
| 244 | * frees the segment to the region associated with ID. The segment must |
---|
| 245 | * have been previously allocated from the same region. If freeing the |
---|
| 246 | * segment results in enough memory being available to satisfy the |
---|
| 247 | * rtems_region_get_segment of the first blocked task, then that task and as |
---|
| 248 | * many subsequent tasks as possible will be unblocked with their requests |
---|
| 249 | * satisfied. |
---|
[f1eb368d] | 250 | * |
---|
[61b8e9f] | 251 | * @param[in] id is the region id |
---|
| 252 | * @param[in] segment is the pointer to segment address |
---|
[f1eb368d] | 253 | * |
---|
[61b8e9f] | 254 | * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful |
---|
[ac7d5ef0] | 255 | */ |
---|
| 256 | rtems_status_code rtems_region_return_segment( |
---|
[d3b72ca3] | 257 | rtems_id id, |
---|
[ac7d5ef0] | 258 | void *segment |
---|
| 259 | ); |
---|
| 260 | |
---|
[067a96a] | 261 | /** |
---|
[61b8e9f] | 262 | * @brief Resize RTEMS Region Segment |
---|
| 263 | * |
---|
| 264 | * This routine implements the rtems_region_resize_segment directive. It |
---|
| 265 | * tries to resize segment in the region associated with 'id' to the new size |
---|
| 266 | * 'size' in place. The first 'size' or old size bytes of the segment |
---|
| 267 | * (whatever is less) are guaranteed to remain unmodified. The segment must |
---|
| 268 | * have been previously allocated from the same region. If resizing the |
---|
| 269 | * segment results in enough memory being available to satisfy the |
---|
| 270 | * rtems_region_get_segment of the first blocked task, then that task and as |
---|
| 271 | * many subsequent tasks as possible will be unblocked with their requests |
---|
| 272 | * satisfied. |
---|
| 273 | * |
---|
| 274 | * @param[in] id is the region id |
---|
[e858f70] | 275 | * @param[in] segment is the pointer to segment address |
---|
[61b8e9f] | 276 | * @param[in] size is the new required size |
---|
| 277 | * @retval RTEMS_SUCCESSFUL if operation successful, RTEMS_UNSATISFIED if the |
---|
| 278 | * the segment can't be resized in place or any other code at failure |
---|
| 279 | * |
---|
| 280 | * @note On RTEMS_SUCCESSFUL or RTEMS_UNSATISFIED exit it returns into the |
---|
| 281 | * 'old_size' the old size in bytes of the user memory area of the |
---|
| 282 | * specified segment. |
---|
[80f2885b] | 283 | */ |
---|
| 284 | rtems_status_code rtems_region_resize_segment( |
---|
[d3b72ca3] | 285 | rtems_id id, |
---|
[80f2885b] | 286 | void *segment, |
---|
[dea3eccb] | 287 | uintptr_t size, |
---|
| 288 | uintptr_t *old_size |
---|
[80f2885b] | 289 | ); |
---|
| 290 | |
---|
[f6c7c57d] | 291 | /**@}*/ |
---|
[ac7d5ef0] | 292 | |
---|
| 293 | #ifdef __cplusplus |
---|
| 294 | } |
---|
| 295 | #endif |
---|
| 296 | |
---|
| 297 | #endif |
---|
| 298 | /* end of include file */ |
---|