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