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