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