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     *  ======== HeapMin.xdc ========
    15     */
    16    
    17    import xdc.rov.ViewInfo;
    18    
    19    /*!
    20     *  ======== HeapMin ========
    21     *  Growth-only based heap implementation.
    22     *
    23     *  `HeapMin` is a minimal footprint heap implementation. This module is 
    24     *  is designed for applications that only create module instances and
    25     *  generally only allocate memory at runtime, but never delete created
    26     *  instances or free memory explicitly.
    27     *  
    28     *  For configuration-time `HeapMin.create`, the heap is aligned to 
    29     *  `{@link Memory#getMaxDefaultTypeAlignMeta()}` for those targets that support
    30     *  static alignment. For targets that do not support static alignment, the
    31     *  buffer alignment is undefined.
    32     *
    33     *  When calling `{@link #create()}` at runtime, the client 
    34     *  is responsible for aligning the buffer.
    35     */
    36    @RomConsts
    37    
    38    module HeapMin inherits xdc.runtime.IHeap {
    39    
    40        /*! @_nodoc */
    41        @XmlDtd
    42        metaonly struct BasicView {
    43            String          label;
    44            Ptr             buffer;
    45            Memory.Size     remainSize;
    46            Memory.Size     startSize;
    47        }
    48    
    49        /*! @_nodoc */
    50        @Facet
    51        metaonly config ViewInfo.Instance rovViewInfo =
    52            ViewInfo.create({
    53                viewMap: [
    54                [
    55                    'Basic',
    56                    {
    57                        type: ViewInfo.INSTANCE,
    58                        viewInitFxn: 'viewInitBasic',
    59                        structName: 'BasicView'
    60                    }
    61                ],
    62                ]
    63            });
    64        
    65        /*!
    66         *  ======== A_zeroSize ========
    67         *  Assert that the `{@link #size}` is non-zero on the create
    68         */     
    69        config Assert.Id A_zeroSize  =
    70            {msg: "HeapMin_create cannot have a zero size value"};
    71            
    72        /*! 
    73         *  ======== E_freeError ========
    74         *  Error raised if `{@link #free()}` is called.
    75         *
    76         *  This error is only raised if a `{@link #free()}`
    77         *  is called and `{@link #freeError}` is true.
    78         */
    79        config Error.Id E_freeError = {
    80            msg: "free() invalid in growth-only HeapMin"
    81        };
    82    
    83        /*!
    84         *  ======== freeError ========
    85         *  Flag to control whether `{@link #E_freeError}` is enabled.
    86         * 
    87         *  If true, a `{@link #E_freeError}` error occurs when trying 
    88         *  to free a buffer. 
    89         *
    90         *  If false, no error occurs and the `{@link #free()}` does nothing.
    91         */
    92        config Bool freeError = true;
    93    
    94    instance:
    95    
    96        /*!
    97         *  ======== align ========
    98         *  Alignment of the buffer being managed by this heap instance.
    99         *
   100         *  In the static HeapMin.create() call, the buffer allocated for the
   101         *  HeapMin instance will have the alignment specified by this parameter
   102         *  on targets that support static alignment.
   103         *
   104         *  In the dynamic case, the client must supply the buffer, so it is the
   105         *  client's responsibility to manage the buffer's alignment, and there is
   106         *  no 'align' parameter.
   107         *
   108         *  The specified `align` parameter must be a power of 2.
   109         *
   110         *  The default alignment of zero causes the buffer to get aligned using
   111         *  {@link Memory#getMaxDefaultTypeAlignMeta()}.
   112         */
   113        metaonly config SizeT align;
   114    
   115        /*!
   116         *  ======== create ========
   117         *  Create a `HeapMin` heap
   118         *
   119         *  This heap is a growth-only heap that is intended to be used by
   120         *  systems that never delete objects or free memory.  Objects can be
   121         *  created at runtime based on values determined at runtime, but
   122         *  objects can not be deleted.
   123         *
   124         *  @see HeapMin#Params
   125         */
   126        create();
   127        
   128        /*!
   129         *  ======== sectionName ========
   130         *  Section name of the heap
   131         *
   132         *  When creating heaps during configuration, this parameter specifies
   133         *  where the heap's buffer will be placed. This parameter is passed as
   134         *  the section name in the `{@link Memory#staticPlace}` function.
   135         *
   136         *  @see Memory#staticPlace
   137         */
   138        metaonly config String sectionName = null;
   139    
   140        /*!
   141         *  ======== buf ========
   142         *  Buffer that will be managed by the heap instance.
   143         *
   144         *  When creating a heap at runtime, the user must supply the memory
   145         *  that the heap will manage.  It is up to the caller to align
   146         *  the buffer as needed.
   147         *
   148         *  This parameter is ignored when creating heaps during configuration.
   149         */
   150        config Ptr buf = 0;
   151    
   152        /*!
   153         *  ======== size ========
   154         *  Size (in MADUs) of the heap.
   155         *
   156         *  This parameter specifies the size of the heap managed by a
   157         *  `HeapMin` instance.  In the static case, a buffer of length `size` 
   158         *  will be created.  In the dynamic case, `size` specifies the size of 
   159         *  the buffer (i.e. parameter `buf`) that the caller provides.
   160         *
   161         *  This is a required parameter. It must be set by the caller. Failure
   162         *  to do so, will result in a build error for the static create or an
   163         *  `{@link #A_zeroSize}` assert for the runtime create.
   164         */
   165        config Memory.Size size = 0;
   166        
   167        /*!
   168         *  ======== alloc ========
   169         *  Allocate a block of memory from the heap.
   170         *
   171         *  @a(Constraints)
   172         *  The alignment must be a power of 2.
   173         *
   174         *  @see IHeap#alloc
   175         */
   176        override Ptr alloc(SizeT size, SizeT align, Error.Block *eb);    
   177    
   178        /*!
   179         *  ======== free ========
   180         *  Free a block of memory back to the heap.
   181         *
   182         *  This is a growth only heap. Calling the `HeapMin_free` function
   183         *  will result in a `{@link #E_freeError}` error unless
   184         *  `{@link #freeError}` is set to `false`.
   185         *
   186         *  @see IHeap#free
   187         */
   188        override Void free(Ptr block, SizeT size);
   189        
   190        /*!
   191         *  ======== isBlocking ========
   192         *  Can this heap block the caller
   193         *
   194         *  @a(returns)
   195         *  `HeapMin` always returns `FALSE` since it never blocks on a
   196         *  resource.
   197         */
   198        override Bool isBlocking();    
   199    
   200    internal:
   201    
   202        struct Instance_State {
   203            Char        buf[];             /* Address of buffer being managed  */
   204            Memory.Size remainSize;        /* Size of remaining heap           */
   205            Memory.Size startSize;         /* Size of heap at the start        */
   206        };
   207    }
   208    /*
   209     *  @(#) xdc.runtime; 2, 1, 0,0; 7-26-2016 11:46:13; /db/ztree/library/trees/xdc/xdc-B21/src/packages/
   210     */
   211