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    @RomConsts
    41    
    42    module HeapStd inherits xdc.runtime.IHeap {
    43    
    44        /*! @_nodoc */
    45        @XmlDtd
    46        metaonly struct Instance_View {
    47            Ptr             address;
    48            String          label;
    49            Memory.Size     remainSize;
    50            Memory.Size     startSize;
    51        }
    52    
    53        /*!
    54         *  ======== HEAP_MAX ========
    55         *  Maximum heap size of HeapStd
    56         *
    57         *  This parameter defines maximum heap size that can be allocated to a
    58         *  `HeapStd` instance. Using this parameter to create `HeapStd` instances
    59         *  will disable the internal size checks in `HeapStd` module.
    60         */
    61        const SizeT HEAP_MAX = ~0U;
    62    
    63        /*!
    64         *  ======== E_noRTSMemory ========
    65         *  Error raised if all the RTS heap is used up
    66         *
    67         *  The total size of all `HeapStd` instance allocations added together
    68         *  cannot exceed the `malloc`/`free` heap size determined by
    69         *  `{@link xdc.cfg.Program#heap}`.
    70         */
    71        config Error.Id E_noRTSMemory = {
    72            msg: "The RTS heap is used up. Examine Program.heap."
    73        };
    74    
    75        /*!
    76         *  ======== A_zeroSize ========
    77         *  Assert that the `{@link #size}` is non-zero on the create
    78         */
    79        config Assert.Id A_zeroSize = {
    80            msg: "HeapStd_create cannot have a zero size value"
    81        };
    82    
    83        /*!
    84         *  ======== A_align ========
    85         *  Assert that the `{@link #size}` is a power of 2
    86         */
    87        config Assert.Id A_align = {
    88            msg: "HeapStd_alloc alignment must be a power of 2"
    89        };
    90    
    91        /*!
    92         *  ======== A_invalidTotalFreeSize ========
    93         *  Assert that remaining size is less than or equal to starting size.
    94         *
    95         *  If this assertion is raised, it means that either incorrect sizes
    96         *  were passed to `{@link #free}` or multiple calls to `{@link #free}`
    97         *  were made with the same buffer.
    98         */
    99        config Assert.Id A_invalidTotalFreeSize = {
   100            msg: "HeapStd instance totalFreeSize is greater than starting size"
   101        };
   102    
   103        /*!
   104         *  ======== A_invalidAlignment ========
   105         *  Assert that the alignment argument in alloc is valid
   106         *  @_nodoc
   107         *
   108         *  If this assertion is raised, it means that the requested alignment is
   109         *  greater than the maximum alignment allowed on the target.
   110         */
   111        config Assert.Id A_invalidAlignment = {
   112            msg: "HeapStd_alloc - requested alignment is greater than allowed"
   113        };
   114    
   115    instance:
   116    
   117        /*!
   118         *  ======== create ========
   119         *  Create a `HeapStd` heap
   120         *
   121         *  This heap uses the ANSI C Standard Library functions
   122         *  `malloc()` and `free()` to manage memory and assumes that these
   123         *  functions are thread-safe.
   124         *
   125         *  @see HeapStd#Params
   126         */
   127        create();
   128    
   129        /*!
   130         *  ======== size ========
   131         *  Size (in MAUs) of the heap.
   132         *
   133         *  This parameter specifies the size of the heap managed by a
   134         *  `HeapStd` instance. `HeapStd` is built upon the ANSI C Standard
   135         *  Library functions `malloc()` and `free()`.
   136         *
   137         *  The total size of all `HeapStd` instance allocations added together
   138         *  cannot exceed the `malloc`/`free` heap size determined by
   139         *  `{@link xdc.cfg.Program#heap Program.heap}`.
   140         *
   141         *  This is a required parameter. It must be set by the caller. Failure
   142         *  to do so, will result in a build error for the static create or an
   143         *  assert for the runtime create.
   144         */
   145        config Memory.Size size = 0;
   146    
   147        /*!
   148         *  ======== alloc ========
   149         *  Allocates a block of memory from the heap.
   150         *
   151         *  @a(Constraints)
   152         *  The only alignment currently supported is the default
   153         *  alignment returned by the underlying `malloc()` implementation.
   154         *  The align value must be less than or equal to the value returned from
   155         *  `{@link Memory#getMaxDefaultTypeAlign()}`.
   156         *
   157         *  @see IHeap#alloc
   158         */
   159        override Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
   160    
   161        /*!
   162         *  ======== isBlocking ========
   163         *  Returns whether the heap may block during an `HeapStd_alloc()` or
   164         *  `HeapStd_free()`.
   165         *
   166         *  @a(returns)
   167         *  Since the implementation of the underlaying ANSI C Standard Library
   168         *  is not known, this function always returns the more restrictive case
   169         *  which is `TRUE`.
   170         */
   171        override Bool isBlocking();
   172    
   173    internal:
   174    
   175        struct Module_State {
   176            Memory.Size remainRTSSize;      /* Remaining size of rts heap      */
   177        };
   178    
   179        struct Instance_State {
   180            Memory.Size remainSize;         /* Size of the remaining heap.      */
   181            Memory.Size startSize;          /* Starting size of the heap.       */
   182        };
   183    }
   184    /*
   185     *  @(#) xdc.runtime; 2, 1, 0,0; 7-26-2016 11:46:13; /db/ztree/library/trees/xdc/xdc-B21/src/packages/
   186     */
   187