| /* --COPYRIGHT--,ESD |
| * Copyright (c) 2008 Texas Instruments. All rights reserved. |
| * This program and the accompanying materials are made available under the |
| * terms of the Eclipse Public License v1.0 and Eclipse Distribution License |
| * v. 1.0 which accompanies this distribution. The Eclipse Public License is |
| * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse |
| * Distribution License is available at |
| * http://www.eclipse.org/org/documents/edl-v10.php. |
| * |
| * Contributors: |
| * Texas Instruments - initial implementation |
| * --/COPYRIGHT--*/ |
| /* |
| * ======== Memory.xdc ======== |
| */ |
| |
| /*! |
| * ======== Memory ======== |
| * Static and run-time memory manager |
| * |
| * All memory allocations are performed either by |
| * `{@link #staticPlace Memory.staticPlace()}` at build time or through |
| * `{@link #alloc Memory_alloc()}` (or its varients `Memory_calloc()`, |
| * `Memory_valloc()`, etc.) at run-time. |
| * |
| * Run-time memory management is performed by modules that |
| * implement the `{@link xdc.runtime.IHeap}` interface. The `Memory` module |
| * itself simply provides a common interface for any variety of system and |
| * application specific memory management policies implemented by `IHeap` |
| * modules; for example, `{@link HeadStd}` and `{@link HeadMin}`. |
| * |
| * Heap instances are created statically or dynamically via heap specific |
| * create functions and these instances are then passed as an input |
| * parameter to the `Memory` calls that have a |
| * `{@link xdc.runtime.IHeap#Handle}` parameter. |
| */ |
| @DirectCall |
| module Memory { |
| |
| /*! |
| * ======== Q_BLOCKING ======== |
| * Blocking quality |
| * |
| * `{@link xdc.runtime.IHeap}`s with this "quality" may cause the |
| * calling thread to block; i.e., suspend execution until another thread |
| * leaves the gate. |
| */ |
| const Int Q_BLOCKING = 1; |
| |
| /*! |
| * ======== Size ======== |
| * Type to be used to specify heap buffer sizes |
| */ |
| typedef UArg Size; |
| |
| /*! |
| * ======== Stats ======== |
| * Memory heap statistics |
| * |
| * This structure defines generic statistics that must be supplied |
| * by each module that implements the `{@link xdc.runtime.IHeap}` |
| * interface. |
| * |
| * @field(totalSize) total size (in MADUs) of heap. |
| * @field(totalFreeSize) current size (in MADUs) of free memory in |
| * the heap |
| * @field(largestFreeSize) current largest contiguous free block |
| * (in MADUs) |
| */ |
| struct Stats { |
| Size totalSize; |
| Size totalFreeSize; |
| Size largestFreeSize; |
| }; |
| |
| /*! @_nodoc */ |
| @XmlDtd |
| metaonly struct Module_View { |
| SizeT maxDefaultTypeAlignment; |
| }; |
| |
| /*! |
| * ======== defaultHeapInstance ======== |
| * The default heap. |
| * |
| * If no heap is specified in the `Memory` module's methods (i.e. |
| * heap == `NULL`) `defaultHeapInstance` is used. If |
| * `defaultHeapInstance` is not set (or set to `null`), a |
| * `{@link xdc.runtime.HeapStd}` heap instance is created and assigned |
| * to this configuration parameter. The size of the heap is determined |
| * by the `{@link #xdc.runtime.HeapStd.HEAP_MAX}` parameter. |
| * |
| * By default, all modules are configured with a `null` instance heap. |
| * Instances created by modules with a `null` instance heap are |
| * allocated from the `defaultHeapInstance` heap. |
| */ |
| config IHeap.Handle defaultHeapInstance; |
| |
| /*! |
| * ======== defaultHeapSize ======== |
| * The size (in target MADUs) of the `defaultHeapInstance`. |
| * |
| * This parameters is used when the `{@link #defaultHeapInstance}` |
| * is not configured. |
| */ |
| metaonly config int defaultHeapSize = 0x1000; |
| |
| /*! |
| * ======== alloc ======== |
| * Allocate a block of memory from a heap. |
| * |
| * @param(heap) heap from which the memory is allocated |
| * |
| * The `heap` is created by a module that implements |
| * the `{@link xdc.runtime.IHeap}` interface. |
| * If `heap` is `NULL`, the |
| * `{@link #defaultHeapInstance}` is used. |
| * |
| * @param(size) requested memory block size (in MADUs) |
| * @param(align) alignment (in MADUs) of the block of memory |
| * |
| * A value of 0 denotes maximum default type alignment. |
| * |
| * @param(eb) pointer to error block |
| * |
| * @a(returns) |
| * If the allocation was successful, `Memory_alloc()` returns non-`NULL` |
| * pointer to the allocated and uninitialized block; otherwise it returns |
| * `NULL` and the error block will indicate the cause of the error. |
| */ |
| Ptr alloc(IHeap.Handle heap, SizeT size, SizeT align, Error.Block *eb); |
| |
| /*! |
| * ======== calloc ======== |
| * Allocate a block of memory from a heap and zero out the contents. |
| * |
| * @param(heap) heap from which the memory is allocated |
| * |
| * The `heap` is created by a module that implements |
| * the `{@link xdc.runtime.IHeap}` interface. |
| * If `heap` is `NULL`, the |
| * `{@link #defaultHeapInstance}` is used. |
| * |
| * @param(size) requested memory block size (in MADUs) |
| * @param(align) alignment (in MADUs) of the block of memory |
| * |
| * A value of 0 denotes maximum default type alignment. |
| * |
| * @param(eb) pointer to error block |
| * |
| * @a(returns) |
| * If the allocation was successful, `Memory_calloc()` returns non-`NULL` |
| * pointer to the allocated and initialized block; otherwise it returns |
| * `NULL` and the error block will indicate the cause of the error. |
| */ |
| Ptr calloc(IHeap.Handle heap, SizeT size, SizeT align, Error.Block *eb); |
| |
| /*! |
| * ======== free ======== |
| * Frees the space if the heap manager offers such functionality. |
| * |
| * @param(heap) heap that the block of memory will be freed back to. |
| * |
| * The `heap` is created by a module that implements |
| * the `{@link xdc.runtime.IHeap}` interface. |
| * If `heap` is `NULL`, the |
| * `{@link #defaultHeapInstance}` is used. |
| * |
| * @param(block) block of memory to free back to the heap |
| * @param(size) size (in MADUs) of the block of memory to free. |
| * |
| */ |
| Void free(IHeap.Handle heap, Ptr block, SizeT size); |
| |
| /*! |
| * ======== getStats ======== |
| * Obtain statistics from a heap. |
| * |
| * @param(heap) the heap to get the statistics from |
| * |
| * The `heap` is created by a module that implements |
| * the `{@link xdc.runtime.IHeap}` interface. |
| * If `heap` is `NULL`, the |
| * `{@link #defaultHeapInstance}` is used. |
| * |
| * @param(stats) the output buffer for the returned statistics |
| */ |
| Void getStats(IHeap.Handle heap, Stats *stats); |
| |
| /*! |
| * ======== query ======== |
| * Test for a particular `{@link xdc.runtime.IHeap}` quality. |
| * |
| * There currently is only one quality, namely `{@link #Q_BLOCKING}`. |
| * |
| * @param(heap) the heap to query |
| * |
| * The `heap` is created by a module that implements |
| * the `{@link xdc.runtime.IHeap}` interface. If `heap` |
| * is `NULL`, the `{@link #defaultHeapInstance}` |
| * is queried |
| * |
| * @param(qual) quality to test |
| * |
| * For example: `{@link #Q_BLOCKING}`. |
| * |
| * @a(returns) |
| * If `heap` has the `qual` quality, this method returns `TRUE`, |
| * otherwise it returns `FALSE`. |
| */ |
| Bool query(IHeap.Handle heap, Int qual); |
| |
| /*! |
| * ======== getMaxDefaultTypeAlignMeta ======== |
| * Return the largest alignment required by the target |
| * |
| * This method scans the standard base types supported by the current |
| * configuration's target |
| * (`{@link xdc.cfg.Program#build Program.build.target}`) and returns |
| * the largest alignment required for these types. |
| * |
| * @a(returns) Returns target-specific alignment in MADUs. |
| * |
| * @see xdc.bld.ITarget#stdTypes |
| */ |
| metaonly SizeT getMaxDefaultTypeAlignMeta(); |
| |
| /*! |
| * ======== getMaxDefaultTypeAlign ======== |
| * Return the largest alignment required by the target |
| * |
| * `getMaxDefaultTypeAlign` returns the largest alignment |
| * required for all the standard base types supported by the current |
| * configuration's target |
| * (`{@link xdc.cfg.Program#build Program.build.target}`) |
| * |
| * This is the runtime version of the |
| * `{@link #getMaxDefaultTypeAlignMeta}` function. |
| * |
| * @a(returns) Returns target-specific alignment in MADUs. |
| * |
| * @see #getMaxDefaultTypeAlignMeta |
| */ |
| SizeT getMaxDefaultTypeAlign(); |
| |
| /*! |
| * ======== staticPlace ======== |
| * Statically places buffers. |
| * |
| * This function places the object specified by `obj` into the specified |
| * memory section. The section string is a target-specific name that is |
| * interpreted by the underlying target tool-chain. In the case of TI |
| * tool-chains, this section can be a subsection (e.g. |
| * ".data:someSection"). |
| * |
| * The amount of memory that is created for `obj` is dependent on its |
| * size and the value of the property `length`. The length (number |
| * of elements in an array) is set before the `staticPlace()` is called. |
| * For example, setting `obj.length = 5;` before calling `staticPlace()`, |
| * will create `5 * sizeof (obj)` MADUs of memory. |
| * |
| * If 0 is specified for the alignment, the allocated buffer is aligned |
| * as determined by the target toolchain. For instance, if `obj` is an |
| * array of structs that have only 16-bit integers, the alignment would |
| * be on a 16-bit boundary. |
| * |
| * All non-zero alignments must be a power of 2. Not all targets support |
| * directives that allow one to specify alignment. The readonly config |
| * parameter |
| * `{@link xdc.cfg.Program#build Program.build.target.alignDirectiveSupported}` |
| * can be used to determine if the target supports alignment directives. |
| * |
| * @param(obj) object to place |
| * |
| * This object always has the `length` property; `obj.length` |
| * determines the size of the allocated buffer for `obj` |
| * |
| * @param(align) the alignment required by `obj` |
| * |
| * @param(section) section name to contain `obj` |
| * |
| * This parameter names the section where `obj` will be placed. If |
| * this parameter is `null`, no explicit placement is done. |
| * |
| * @a(returns) |
| * Returns `false` if the alignment request cannot be honored. The `obj` |
| * is still placed regardless of the return code. |
| */ |
| metaonly Bool staticPlace(any obj, SizeT align, String section); |
| |
| /*! |
| * ======== valloc ======== |
| * Allocate a block of memory from a heap and initialize the contents |
| * to the value specified. |
| * |
| * @param(heap) heap from which the memory is allocated |
| * |
| * The `heap` is created by a module that implements |
| * the `{@link xdc.runtime.IHeap}` interface. |
| * If `heap` is `NULL`, the |
| * `{@link #defaultHeapInstance}` is used. |
| * |
| * @param(size) requested memory block size (in MADUs) |
| * @param(align) alignment (in MADUs) of the block of memory |
| * |
| * A value of 0 denotes maximum default type alignment. |
| * |
| * @param(value) value to initialize the contents of the block |
| * @param(eb) pointer to error block |
| * |
| * @a(returns) |
| * If the allocation was successful, `Memory_valloc()` returns non-`NULL` |
| * pointer to the allocated and initialized block; otherwise it returns |
| * `NULL` and the error block will indicate the cause of the error. |
| */ |
| Ptr valloc(IHeap.Handle heap, SizeT size, SizeT align, Char value, |
| Error.Block *eb); |
| |
| internal: |
| |
| proxy HeapProxy inherits IHeap; |
| |
| struct Module_State { |
| SizeT maxDefaultTypeAlign; |
| } |
| } |
