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     *  ======== HeapStd.xdc ========
    15     *!  Open Issues: 
    16     *!  - Do not really know the largestFreeSize value in HeapStd_getStats() 
    17     */
    18    
    19    /*!
    20     *  ======== HeapStd ========
    21     *  Malloc/free based heap implementation.
    22     *
    23     *  This heap is based on the ANSI C Standard Library functions
    24     *  `malloc()` and `free()` and assumes that these functions are thread-safe.
    25     *  Please refer to the target specific documentation of the ANSI C Standard
    26     *  Library for details.
    27     *
    28     *  The largest free block that can be returned form `malloc()` cannot be
    29     *  determined. Therefore, the property `largestFreeSize` in
    30     *  `{@link Memory#Stats}` returned from `{@link #getStats()}` always returns
    31     *  0.
    32     * 
    33     *  @a(Constraints)
    34     *  The `{@link #alloc()}` function only supports alignment requests up to
    35     *  value returned from
    36     *  `{@link Memory#getMaxDefaultTypeAlign()}`.
    37     */
    38     
    39    @InstanceInitError  /* instance init can fail, call finalize if so */
    40    
    41    module HeapStd inherits xdc.runtime.IHeap {
    42        
    43        /*! @_nodoc */
    44        @XmlDtd
    45        metaonly struct Instance_View {
    46            Ptr             address;
    47            String          label;
    48            Memory.Size     remainSize;
    49            Memory.Size     startSize;
    50        }
    51        
    52        /*!
    53         *  ======== E_noRTSMemory ========
    54         *  Error raised if all the RTS heap is used up
    55         *
    56         *  The total size of all `HeapStd` instance allocations added together
    57         *  cannot exceed the `malloc`/`free` heap size determined by
    58         *  `{@link xdc.cfg.Program#heap}`. 
    59         */
    60        config Error.Id E_noRTSMemory = { 
    61            msg: "The RTS heap is used up. Examine Program.heap."
    62        }; 
    63            
    64        /*!
    65         *  ======== A_zeroSize ========
    66         *  Assert that the `{@link #size}` is non-zero on the create
    67         */     
    68        config Assert.Id A_zeroSize = {
    69            msg: "HeapStd_create cannot have a zero size value"
    70        };
    71            
    72        /*! 
    73         *  ======== A_invalidTotalFreeSize ========
    74         *  Assert that remaining size is less than or equal to starting size.
    75         *
    76         *  If this assertion is raised, it means that either incorrect sizes
    77         *  were passed to `{@link #free}` or multiple calls to `{@link #free}`
    78         *  were made with the same buffer.
    79         */     
    80        config Assert.Id A_invalidTotalFreeSize = {
    81            msg: "HeapStd instance totalFreeSize is greater than starting size"
    82        };
    83    
    84        /*!
    85         *  ======== A_invalidAlignment ========
    86         *  Assert that the alignment argument in alloc is valid
    87         *
    88         *  If this assertion is raised, it means that the requested alignment is
    89         *  greater than the maximum alignment allowed on the target.
    90         */     
    91        config Assert.Id A_invalidAlignment = {
    92            msg: "HeapStd_alloc - requested alignment is greater than allowed"
    93        };
    94    
    95    instance:
    96    
    97        /*!
    98         *  ======== create ========
    99         *  Create a `HeapStd` heap
   100         *
   101         *  This heap uses the ANSI C Standard Library functions
   102         *  `malloc()` and `free()` to manage memory and assumes that these
   103         *  functions are thread-safe.
   104         *
   105         *  @see HeapStd#Params
   106         */
   107        create();
   108        
   109        /*! 
   110         *  ======== size ========
   111         *  Size (in MAUs) of the heap.
   112         *
   113         *  This parameter specifies the size of the heap managed by a
   114         *  `HeapStd` instance. `HeapStd` is built upon the ANSI C Standard
   115         *  Library functions `malloc()` and `free()`.
   116         *
   117         *  The total size of all `HeapStd` instance allocations added together
   118         *  cannot exceed the `malloc`/`free` heap size determined by
   119         *  `{@link xdc.cfg.Program#heap Program.heap}`. 
   120         *
   121         *  This is a required parameter. It must be set by the caller. Failure
   122         *  to do so, will result in a build error for the static create or an
   123         *  assert for the runtime create.
   124         */    
   125        config Memory.Size size = 0;    
   126    
   127        /*!
   128         *  ======== alloc ========
   129         *  Allocates a block of memory from the heap.
   130         *
   131         *  @a(Constraints)
   132         *  The only alignment currently supported is the default
   133         *  alignment returned by the underlying `malloc()` implementation. 
   134         *  The align value must be less than or equal to the value returned from 
   135         *  `{@link Memory#getMaxDefaultTypeAlign()}`.
   136         *
   137         *  @see IHeap#alloc
   138         */
   139        override Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
   140        
   141        /*!
   142         *  ======== isBlocking ========
   143         *  Returns whether the heap may block during an `HeapStd_alloc()` or
   144         *  `HeapStd_free()`.
   145         *  
   146         *  @a(returns)      
   147         *  Since the implementation of the underlaying ANSI C Standard Library
   148         *  is not known, this function always returns the more restrictive case
   149         *  which is `TRUE`.
   150         */
   151        override Bool isBlocking();    
   152     
   153    internal:
   154    
   155        struct Module_State {
   156            Memory.Size remainRTSSize;      /* Remaining size of rts heap      */
   157        };
   158        
   159        struct Instance_State {
   160            Memory.Size remainSize;         /* Size of the remaining heap.      */
   161            Memory.Size startSize;          /* Starting size of the heap.       */
   162        };
   163    }
   164    /*
   165     *  @(#) xdc.runtime; 2, 1, 0,371; 2-10-2012 10:18:54; /db/ztree/library/trees/xdc/xdc-y21x/src/packages/
   166     */
   167