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