1 2 3 4 5 6 7 8 9 10 11 12
13 14 15
16
17 /*!
18 * ======== Memory ========
19 * Static and run-time memory manager
20 *
21 * All memory allocations are executed via `staticPlace()` at the
22 * config time or through `Memory_alloc()` (or `Memory_calloc()` or
23 * `Memory_valloc()`) at run-time.
24 *
25 * The actual memory management is performed by modules that
26 * implement `{@link xdc.runtime.IHeap}`. Heap instances are created
27 * statically or dynamically via the heap specific create functions and
28 * these instances are then passed as input parameters to the `Memory`
29 * calls with `{@link xdc.runtime.IHeap#Handle}` parameters.
30 */
31 module Memory {
32
33 /*!
34 * ======== Q_BLOCKING ========
35 * Blocking quality
36 *
37 * `{@link xdc.runtime.IHeap}`s with this "quality" may cause the
38 * calling thread to block; i.e., suspend execution until another thread
39 * leaves the gate.
40 */
41 const Int Q_BLOCKING = 1;
42
43 /*!
44 * ======== Size ========
45 * Type to be used to specify heap buffer sizes
46 */
47 typedef UArg Size;
48
49 /*!
50 * ======== Stats ========
51 * Memory heap statistics
52 *
53 * This structure defines generic statistics that must be supplied
54 * by each module that implements the `{@link xdc.runtime.IHeap}`
55 * interface.
56 *
57 * @field(totalSize) total size (in MADUs) of heap.
58 * @field(totalFreeSize) current size (in MADUs) of free memory in
59 * the heap
60 * @field(largestFreeSize) current largest contiguous free block
61 * (in MADUs)
62 */
63 struct Stats {
64 Size totalSize;
65 Size totalFreeSize;
66 Size largestFreeSize;
67 }
68
69 /*! @_nodoc */
70 @XmlDtd
71 metaonly struct Module_View {
72 SizeT maxDefaultTypeAlignment;
73 };
74
75 /*!
76 * ======== defaultHeapInstance ========
77 * The default heap.
78 *
79 * If no heap is specified in the `Memory` module's methods (i.e.
80 * heap == `NULL`) `defaultHeapInstance` is used. If
81 * `defaultHeapInstance` is not set (or set to `null`), a
82 * `{@link xdc.runtime.HeapStd}` heap instance is created and assigned
83 * to this configuration parameter. The size of the heap is determined
84 * by the `{@link #defaultHeapSize}` parameter.
85 *
86 * By default, all modules are configured with a `null` instance heap.
87 * Instances created by modules with a `null` instance heap are
88 * allocated from the `defaultHeapInstance` heap.
89 */
90 config IHeap.Handle defaultHeapInstance;
91
92 /*!
93 * ======== defaultHeapSize ========
94 * The size (in target MADUs) of the `defaultHeapInstance`.
95 *
96 * This parameters is used when the `{@link #defaultHeapInstance}`
97 * is not configured.
98 */
99 metaonly config int defaultHeapSize = 0x1000;
100
101 /*!
102 * ======== alloc ========
103 * Allocate a block of memory from a heap.
104 *
105 * @param(heap) heap from which the memory is allocated
106 *
107 * The `heap` is created by a module that implements
108 * the `{@link xdc.runtime.IHeap}` interface.
109 * If `heap` is `NULL`, the
110 * `{@link #defaultHeapInstance}` is used.
111 *
112 * @param(size) requested memory block size (in MADUs)
113 * @param(align) alignment (in MADUs) of the block of memory
114 *
115 * A value of 0 denotes maximum default type alignment.
116 *
117 * @param(eb) pointer to error block
118 *
119 * @a(returns)
120 * If the allocation was successful, `Memory_alloc()` returns non-`NULL`
121 * pointer to the allocated and uninitialized block; otherwise it returns
122 * `NULL` and the error block will indicate the cause of the error.
123 */
124 Ptr alloc(IHeap.Handle heap, SizeT size, SizeT align, Error.Block *eb);
125
126 /*!
127 * ======== calloc ========
128 * Allocate a block of memory from a heap and zero out the contents.
129 *
130 * @param(heap) heap from which the memory is allocated
131 *
132 * The `heap` is created by a module that implements
133 * the `{@link xdc.runtime.IHeap}` interface.
134 * If `heap` is `NULL`, the
135 * `{@link #defaultHeapInstance}` is used.
136 *
137 * @param(size) requested memory block size (in MADUs)
138 * @param(align) alignment (in MADUs) of the block of memory
139 *
140 * A value of 0 denotes maximum default type alignment.
141 *
142 * @param(eb) pointer to error block
143 *
144 * @a(returns)
145 * If the allocation was successful, `Memory_calloc()` returns non-`NULL`
146 * pointer to the allocated and initialized block; otherwise it returns
147 * `NULL` and the error block will indicate the cause of the error.
148 */
149 Ptr calloc(IHeap.Handle heap, SizeT size, SizeT align, Error.Block *eb);
150
151 /*!
152 * ======== free ========
153 * Frees the space if the heap manager offers such functionality.
154 *
155 * @param(heap) heap that the block of memory will be freed back to.
156 *
157 * The `heap` is created by a module that implements
158 * the `{@link xdc.runtime.IHeap}` interface.
159 * If `heap` is `NULL`, the
160 * `{@link #defaultHeapInstance}` is used.
161 *
162 * @param(block) block of memory to free back to the heap
163 * @param(size) size (in MADUs) of the block of memory to free.
164 *
165 */
166 Void free(IHeap.Handle heap, Ptr block, SizeT size);
167
168 /*!
169 * ======== getStats ========
170 * Obtain statistics from a heap.
171 *
172 * @param(heap) the heap to get the statistics from
173 *
174 * The `heap` is created by a module that implements
175 * the `{@link xdc.runtime.IHeap}` interface.
176 * If `heap` is `NULL`, the
177 * `{@link #defaultHeapInstance}` is used.
178 *
179 * @param(stats) the output buffer for the returned statistics
180 */
181 Void getStats(IHeap.Handle heap, Stats *stats);
182
183 /*!
184 * ======== query ========
185 * Test for a particular `{@link xdc.runtime.IHeap}` quality.
186 *
187 * There currently is only one quality, namely `{@link #Q_BLOCKING}`.
188 *
189 * @param(heap) the heap to query
190 *
191 * The `heap` is created by a module that implements
192 * the `{@link xdc.runtime.IHeap}` interface. If `heap`
193 * is `NULL`, the `{@link #defaultHeapInstance}`
194 * is queried
195 *
196 * @param(qual) quality to test
197 *
198 * For example: `{@link #Q_BLOCKING}`.
199 *
200 * @a(returns)
201 * If `heap` has the `qual` quality, this method returns `TRUE`,
202 * otherwise it returns `FALSE`.
203 */
204 Bool query(IHeap.Handle heap, Int qual);
205
206 /*!
207 * ======== getMaxDefaultTypeAlignMeta ========
208 * Return the largest alignment required by the target
209 *
210 * This method scans the standard base types supported by the current
211 * configuration's target
212 * (`{@link xdc.cfg.Program#build Program.build.target}`) and returns
213 * the largest alignment required for these types.
214 *
215 * @a(returns) Returns target-specific alignment in MADUs.
216 *
217 * @see xdc.bld.ITarget#stdTypes
218 */
219 metaonly SizeT getMaxDefaultTypeAlignMeta();
220
221 /*!
222 * ======== getMaxDefaultTypeAlign ========
223 * Return the largest alignment required by the target
224 *
225 * `getMaxDefaultTypeAlign` returns the largest alignment
226 * required for all the standard base types supported by the current
227 * configuration's target
228 * (`{@link xdc.cfg.Program#build Program.build.target}`)
229 *
230 * This is the runtime version of the
231 * `{@link #getMaxDefaultTypeAlignMeta}` function.
232 *
233 * @a(returns) Returns target-specific alignment in MADUs.
234 *
235 * @see #getMaxDefaultTypeAlignMeta
236 */
237 SizeT getMaxDefaultTypeAlign();
238
239 /*!
240 * ======== staticPlace ========
241 * Statically places buffers.
242 *
243 * This function places the object specified by `obj` into the specified
244 * memory section. The section string is a target-specific name that is
245 * interpreted by the underlying target tool-chain. In the case of TI
246 * tool-chains, this section can be a subsection (e.g.
247 * ".data:someSection").
248 *
249 * The amount of memory that is created for `obj` is dependent on its
250 * size and the value of the property `length`. The length (number
251 * of elements in an array) is set before the `staticPlace()` is called.
252 * For example, setting `obj.length = 5;` before calling `staticPlace()`,
253 * will create `5 * sizeof (obj)` MADUs of memory.
254 *
255 * If 0 is specified for the alignment, the allocated buffer is aligned
256 * as determined by the target toolchain. For instance, if `obj` is an
257 * array of structs that have only 16-bit integers, the alignment would
258 * be on a 16-bit boundary.
259 *
260 * All non-zero alignments must be a power of 2. Not all targets support
261 * directives that allow one to specify alignment. The readonly config
262 * parameter
263 * `{@link xdc.cfg.Program#build Program.build.target.alignDirectiveSupported}`
264 * can be used to determine if the target supports alignment directives.
265 *
266 * @param(obj) object to place
267 *
268 * This object always has the `length` property; `obj.length`
269 * determines the size of the allocated buffer for `obj`
270 *
271 * @param(align) the alignment required by `obj`
272 *
273 * @param(section) section name to contain `obj`
274 *
275 * This parameter names the section where `obj` will be placed. If
276 * this parameter is `null`, no explicit placement is done.
277 *
278 * @a(returns)
279 * Returns `false` if the alignment request cannot be honored. The `obj`
280 * is still placed regardless of the return code.
281 */
282 metaonly Bool staticPlace(any obj, SizeT align, String section);
283
284 /*!
285 * ======== valloc ========
286 * Allocate a block of memory from a heap and initialize the contents
287 * to the value specified.
288 *
289 * @param(heap) heap from which the memory is allocated
290 *
291 * The `heap` is created by a module that implements
292 * the `{@link xdc.runtime.IHeap}` interface.
293 * If `heap` is `NULL`, the
294 * `{@link #defaultHeapInstance}` is used.
295 *
296 * @param(size) requested memory block size (in MADUs)
297 * @param(align) alignment (in MADUs) of the block of memory
298 *
299 * A value of 0 denotes maximum default type alignment.
300 *
301 * @param(value) value to initialize the contents of the block
302 * @param(eb) pointer to error block
303 *
304 * @a(returns)
305 * If the allocation was successful, `Memory_valloc()` returns non-`NULL`
306 * pointer to the allocated and initialized block; otherwise it returns
307 * `NULL` and the error block will indicate the cause of the error.
308 */
309 Ptr valloc(IHeap.Handle heap, SizeT size, SizeT align, Char value,
310 Error.Block *eb);
311
312 internal:
313
314 proxy HeapProxy inherits IHeap;
315
316 struct Module_State {
317 SizeT maxDefaultTypeAlign;
318 }
319 }
320 321 322
323