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     *  ======== 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     *  @(#) xdc.runtime; 2, 1, 0,0; 7-26-2016 11:46:15; /db/ztree/library/trees/xdc/xdc-B21/src/packages/
   331     */
   332