source: rtems/cpukit/include/rtems/rtems/region.h @ e8e914b3

Last change on this file since e8e914b3 was e8e914b3, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 8, 2018 at 9:37:22 AM

rtems: Move internal structures to regiondata.h

Update #3598.

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