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