source: rtems/cpukit/include/rtems/rtems/region.h @ 2afb22b

5
Last change on this file since 2afb22b was 2afb22b, checked in by Chris Johns <chrisj@…>, on Dec 23, 2017 at 7:18:56 AM

Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step. It
copied header files from arbitrary locations into the build tree. The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

  • The make preinstall step itself needs time and disk space.
  • Errors in header files show up in the build tree copy. This makes it hard for editors to open the right file to fix the error.
  • There is no clear relationship between source and build tree header files. This makes an audit of the build process difficult.
  • The visibility of all header files in the build tree makes it difficult to enforce API barriers. For example it is discouraged to use BSP-specifics in the cpukit.
  • An introduction of a new build system is difficult.
  • Include paths specified by the -B option are system headers. This may suppress warnings.
  • The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step. All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc. Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

  • cpukit/include
  • cpukit/score/cpu/@RTEMS_CPU@/include
  • cpukit/libnetworking

The new BSP include directories are:

  • bsps/include
  • bsps/@RTEMS_CPU@/include
  • bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed. The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

  • Property mode set to 100644
File size: 9.5 KB
Line 
1/**
2 * @file rtems/rtems/region.h
3 *
4 * @defgroup ClassicRegion Regions
5 *
6 * @ingroup ClassicRTEMS
7 * @brief Region Manager
8 *
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.
12 *
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
20 */
21
22/* COPYRIGHT (c) 1989-2013.
23 * On-Line Applications Research Corporation (OAR).
24 *
25 * The license and distribution terms for this file may be
26 * found in the file LICENSE in this distribution or at
27 * http://www.rtems.org/license/LICENSE.
28 */
29
30#ifndef _RTEMS_RTEMS_REGION_H
31#define _RTEMS_RTEMS_REGION_H
32
33#include <rtems/rtems/attr.h>
34#include <rtems/rtems/options.h>
35#include <rtems/rtems/status.h>
36#include <rtems/rtems/types.h>
37#include <rtems/score/heap.h>
38#include <rtems/score/threadq.h>
39
40#ifdef __cplusplus
41extern "C" {
42#endif
43
44/**
45 *  @defgroup ClassicRegion Regions
46 *
47 *  @ingroup ClassicRTEMS
48 *
49 *  This encapsulates functionality related to the Classic API Region
50 *  Manager.
51 */
52/**@{*/
53
54/**
55 *  The following records define the control block used to manage
56 *  each region.
57 */
58
59typedef struct {
60  Objects_Control       Object;
61  Thread_queue_Control  Wait_queue;            /* waiting threads        */
62  const Thread_queue_Operations *wait_operations;
63  uintptr_t             maximum_segment_size;  /* in bytes               */
64  rtems_attribute       attribute_set;
65  Heap_Control          Memory;
66}  Region_Control;
67
68/**
69 *  @brief rtems_region_create
70 *
71 *  Region Manager
72 *
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 */
81rtems_status_code rtems_region_create(
82  rtems_name          name,
83  void               *starting_address,
84  uintptr_t           length,
85  uintptr_t           page_size,
86  rtems_attribute     attribute_set,
87  rtems_id           *id
88);
89
90/**
91 * @brief RTEMS Extend Region
92 *
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.
97 *
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
101 *
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.
105 */
106rtems_status_code rtems_region_extend(
107  rtems_id            id,
108  void               *starting_address,
109  uintptr_t           length
110);
111
112/**
113 * @brief RTEMS Region Name to Id
114 *
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.
119 *
120 * @param[in] name is the user defined region name
121 * @param[in] id is the pointer to region id
122 *
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.
127 */
128rtems_status_code rtems_region_ident(
129  rtems_name    name,
130  rtems_id     *id
131);
132
133/**
134 * @brief RTEMS Get Region Information
135 *
136 * This routine implements the rtems_region_get_information directive.
137 * This directive returns information about the heap associated with
138 * this region.
139 *
140 * @param[in] id is the region id
141 * @param[in] the_info is the pointer to region information block
142 *
143 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
144 * *id filled with the region information block
145 */
146rtems_status_code rtems_region_get_information(
147  rtems_id                id,
148  Heap_Information_block *the_info
149);
150
151/**
152 * @brief RTEMS Get Region Free Information
153 *
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.
158 *
159 * @param[in] id is the region id
160 * @param[in] the_info is the pointer to region information block
161 *
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.
166 */
167rtems_status_code rtems_region_get_free_information(
168  rtems_id                id,
169  Heap_Information_block *the_info
170);
171
172/**
173 * @brief RTEMS Delete Region
174 *
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.
178 *
179 * @param[in] id is the region id
180 *
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.
184 */
185rtems_status_code rtems_region_delete(
186  rtems_id   id
187);
188
189/**
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.
210 */
211rtems_status_code rtems_region_get_segment(
212  rtems_id           id,
213  uintptr_t          size,
214  rtems_option       option_set,
215  rtems_interval     timeout,
216  void             **segment
217);
218
219/**
220 * @brief RTEMS Get Region Segment Size
221 *
222 * This routine implements the rtems_region_get_segment_size directive. It
223 * returns the size in bytes of the specified user memory area.
224 *
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
228 *
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.
233 */
234rtems_status_code rtems_region_get_segment_size(
235  rtems_id           id,
236  void              *segment,
237  uintptr_t         *size
238);
239
240/**
241 * @brief RTEMS Return Region Segment
242 *
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.
250 *
251 * @param[in] id is the region id
252 * @param[in] segment is the pointer to segment address
253 *
254 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
255 */
256rtems_status_code rtems_region_return_segment(
257  rtems_id    id,
258  void       *segment
259);
260
261/**
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
275 * @param[in] segment is the pointer to segment address
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.
283 */
284rtems_status_code rtems_region_resize_segment(
285  rtems_id    id,
286  void       *segment,
287  uintptr_t   size,
288  uintptr_t  *old_size
289);
290
291/**@}*/
292
293#ifdef __cplusplus
294}
295#endif
296
297#endif
298/* end of include file */
Note: See TracBrowser for help on using the repository browser.