1 | /* |
---|
2 | * COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org> |
---|
3 | * |
---|
4 | * The license and distribution terms for this file may be |
---|
5 | * found in the file LICENSE in this distribution or at |
---|
6 | * http://www.rtems.org/license/LICENSE. |
---|
7 | */ |
---|
8 | /** |
---|
9 | * @file |
---|
10 | * |
---|
11 | * @ingroup rtems_rtl |
---|
12 | * |
---|
13 | * @brief RTEMS Run-Time Linker Allocator |
---|
14 | */ |
---|
15 | |
---|
16 | #if !defined (_RTEMS_RTL_ALLOCATOR_H_) |
---|
17 | #define _RTEMS_RTL_ALLOCATOR_H_ |
---|
18 | |
---|
19 | #include <stdbool.h> |
---|
20 | |
---|
21 | #include "rtl-indirect-ptr.h" |
---|
22 | |
---|
23 | #ifdef __cplusplus |
---|
24 | extern "C" { |
---|
25 | #endif /* __cplusplus */ |
---|
26 | |
---|
27 | /** |
---|
28 | * Define the types of allocation the loader requires. |
---|
29 | * |
---|
30 | * @note It is best to use the object tag for general memory allocation and to |
---|
31 | * leave the tags with specific access properties to the module data |
---|
32 | */ |
---|
33 | enum rtems_rtl_alloc_tags_e { |
---|
34 | RTEMS_RTL_ALLOC_OBJECT, /**< A generic memory object. */ |
---|
35 | RTEMS_RTL_ALLOC_SYMBOL, /**< Memory used for symbols. */ |
---|
36 | RTEMS_RTL_ALLOC_EXTERNAL, /**< Memory used for external symbols. */ |
---|
37 | RTEMS_RTL_ALLOC_READ, /**< The memory is read only. */ |
---|
38 | RTEMS_RTL_ALLOC_READ_WRITE, /**< The memory is read and write. */ |
---|
39 | RTEMS_RTL_ALLOC_READ_EXEC /**< The memory is read and executable. */ |
---|
40 | }; |
---|
41 | |
---|
42 | /** |
---|
43 | * The allocator tag type. |
---|
44 | */ |
---|
45 | typedef enum rtems_rtl_alloc_tags_e rtems_rtl_alloc_tag_t; |
---|
46 | |
---|
47 | /** |
---|
48 | * The number of tags. |
---|
49 | */ |
---|
50 | #define RTEMS_RTL_ALLOC_TAGS ((size_t) (RTEMS_RTL_ALLOC_READ_EXEC + 1)) |
---|
51 | |
---|
52 | /** |
---|
53 | * Allocator handler handles all RTL allocations. It can be hooked and |
---|
54 | * overridded for customised allocation schemes or memory maps. |
---|
55 | * |
---|
56 | * @param allocation If true the request is to allocate memory else free. |
---|
57 | * @param tag The type of allocation request. |
---|
58 | * @param address Pointer to the memory address. If an allocation the value is |
---|
59 | * unspecific on entry and the allocated address or NULL on |
---|
60 | * exit. The NULL value means the allocation failed. If a delete |
---|
61 | * or free request the memory address is the block to free. A |
---|
62 | * free request of NULL is silently ignored. |
---|
63 | * @param size The size of the allocation if an allocation request and |
---|
64 | * not used if deleting or freeing a previous allocation. |
---|
65 | */ |
---|
66 | typedef void (*rtems_rtl_allocator_t)(bool allocate, |
---|
67 | rtems_rtl_alloc_tag_t tag, |
---|
68 | void** address, |
---|
69 | size_t size); |
---|
70 | |
---|
71 | /** |
---|
72 | * The allocator data. |
---|
73 | */ |
---|
74 | struct rtems_rtl_alloc_data_s { |
---|
75 | /**< The memory allocator handler. */ |
---|
76 | rtems_rtl_allocator_t allocator; |
---|
77 | /**< The indirect pointer chains. */ |
---|
78 | rtems_chain_control indirects[RTEMS_RTL_ALLOC_TAGS]; |
---|
79 | }; |
---|
80 | |
---|
81 | typedef struct rtems_rtl_alloc_data_s rtems_rtl_alloc_data_t; |
---|
82 | |
---|
83 | /** |
---|
84 | * Initialise the allocate data. |
---|
85 | * |
---|
86 | * @param data The data to initialise. |
---|
87 | */ |
---|
88 | void rtems_rtl_alloc_initialise (rtems_rtl_alloc_data_t* data); |
---|
89 | |
---|
90 | /** |
---|
91 | * The Runtime Loader allocator new allocates new memory and optionally clear |
---|
92 | * the memory if requested. |
---|
93 | * |
---|
94 | * @param tag The type of allocation request. |
---|
95 | * @param size The size of the allocation. |
---|
96 | * @param zero If true the memory is cleared. |
---|
97 | * @return void* The memory address or NULL is not memory available. |
---|
98 | */ |
---|
99 | void* rtems_rtl_alloc_new (rtems_rtl_alloc_tag_t tag, size_t size, bool zero); |
---|
100 | |
---|
101 | /** |
---|
102 | * The Runtime Loader allocator delete deletes allocated memory. |
---|
103 | * |
---|
104 | * @param tag The type of allocation request. |
---|
105 | * @param address The memory address to delete. A NULL is ignored. |
---|
106 | */ |
---|
107 | void rtems_rtl_alloc_del (rtems_rtl_alloc_tag_t tag, void* address); |
---|
108 | |
---|
109 | /** |
---|
110 | * Hook the Runtime Loader allocatior. A handler can call the previous handler |
---|
111 | * in the chain to use it for specific tags. The default handler uses the |
---|
112 | * system heap. Do not unhook your handler if memory it allocates has not been |
---|
113 | * returned. |
---|
114 | * |
---|
115 | * @param handler The handler to use as the allocator. |
---|
116 | * @return rtems_rtl_alloc_handler_t The previous handler. |
---|
117 | */ |
---|
118 | rtems_rtl_allocator_t rtems_rtl_alloc_hook (rtems_rtl_allocator_t handler); |
---|
119 | |
---|
120 | /** |
---|
121 | * Allocate memory to an indirect handle. |
---|
122 | * |
---|
123 | * @param tag The type of allocation request. |
---|
124 | * @param handle The handle to allocate the memory to. |
---|
125 | * @param size The size of the allocation. |
---|
126 | */ |
---|
127 | void rtems_rtl_alloc_indirect_new (rtems_rtl_alloc_tag_t tag, |
---|
128 | rtems_rtl_ptr_t* handle, |
---|
129 | size_t size); |
---|
130 | |
---|
131 | /** |
---|
132 | * Free memory from an indirect handle. |
---|
133 | * |
---|
134 | * @param tag The type of allocation request. |
---|
135 | * @param handle The handle to free the memory from. |
---|
136 | */ |
---|
137 | void rtems_rtl_alloc_indirect_del (rtems_rtl_alloc_tag_t tag, |
---|
138 | rtems_rtl_ptr_t* handle); |
---|
139 | |
---|
140 | /** |
---|
141 | * Allocate the memory for a module given the size of the text, const, data and |
---|
142 | * bss sections. If any part of the allocation fails the no memory is |
---|
143 | * allocated. |
---|
144 | * |
---|
145 | * @param text_base Pointer to the text base pointer. |
---|
146 | * @param text_size The size of the read/exec section. |
---|
147 | * @param const_base Pointer to the const base pointer. |
---|
148 | * @param const_size The size of the read only section. |
---|
149 | * @param data_base Pointer to the data base pointer. |
---|
150 | * @param data_size The size of the read/write secton. |
---|
151 | * @param bss_base Pointer to the bss base pointer. |
---|
152 | * @param bss_size The size of the read/write. |
---|
153 | * @retval true The memory has been allocated. |
---|
154 | * @retval false The allocation of memory has failed. |
---|
155 | */ |
---|
156 | bool rtems_rtl_alloc_module_new (void** text_base, size_t text_size, |
---|
157 | void** const_base, size_t const_size, |
---|
158 | void** data_base, size_t data_size, |
---|
159 | void** bss_base, size_t bss_size); |
---|
160 | |
---|
161 | /** |
---|
162 | * Free the memory allocated to a module. |
---|
163 | * |
---|
164 | * @param text_base Pointer to the text base pointer. |
---|
165 | * @param const_base Pointer to the const base pointer. |
---|
166 | * @param data_base Pointer to the data base pointer. |
---|
167 | * @param bss_base Pointer to the bss base pointer. |
---|
168 | */ |
---|
169 | void rtems_rtl_alloc_module_del (void** text_base, void** const_base, |
---|
170 | void** data_base, void** bss_base); |
---|
171 | |
---|
172 | #ifdef __cplusplus |
---|
173 | } |
---|
174 | #endif /* __cplusplus */ |
---|
175 | |
---|
176 | #endif |
---|