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