1    /* 
     2     * Copyright (c) 2010, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * 
    32     */
    33    
    34    import xdc.runtime.Memory;
    35    import xdc.runtime.Error;
    36    
    37    /*
    38     *  ======== HeapStdAlign.xdc ========
    39     *
    40     */
    41    
    42    /*!
    43     *  ======== HeapStdAlign ========
    44     *  Malloc/free based heap implementation.
    45     *
    46     *  This heap is based on the ANSI C Standard Library functions
    47     *  `malloc()` and `free()` and assumes that these functions are thread-safe.
    48     *  Please refer to the target specific documentation of the ANSI C Standard
    49     *  Library for details.
    50     *
    51     *  The largest free block that can be returned form `malloc()` cannot be
    52     *  determined. Therefore, the property `largestFreeSize` in
    53     *  `{@link Memory#Stats}` returned from `{@link #getStats()}` always returns
    54     *  0.
    55     *
    56     *  @a(Constraints)
    57     *  The `{@link #alloc()}` function only supports alignment requests up to
    58     *  value returned from
    59     *  `{@link Memory#getMaxDefaultTypeAlign()}`.
    60     */
    61    
    62    @InstanceInitError  /* instance init can fail, call finalize if so */
    63    
    64    module HeapStdAlign inherits xdc.runtime.IHeap {
    65    
    66        /*! @_nodoc */
    67        @XmlDtd
    68        metaonly struct Instance_View {
    69            Ptr             address;
    70            String          label;
    71            Memory.Size     remainSize;
    72            Memory.Size     startSize;
    73        }
    74    
    75        /*!
    76         *  ======== E_noRTSMemory ========
    77         *  Error raised if all the RTS heap is used up
    78         *
    79         *  The total size of all `HeapStdAlign` instance allocations added
    80         *  together cannot exceed the `malloc`/`free` heap size determined by
    81         *  `{@link xdc.cfg.Program#heap}`.
    82         */
    83        config xdc.runtime.Error.Id E_noRTSMemory  =
    84            {msg: "The RTS heap is used up. Examine Program.heap."};
    85    
    86        /*!
    87         *  ======== A_zeroSize ========
    88         *  Assert that the `{@link #size}` is non-zero on the create
    89         */
    90        config xdc.runtime.Assert.Id A_zeroSize  =
    91                {msg: "HeapStdAlign_create cannot have a zero size value"};
    92    
    93        /*!
    94         *  Assert raised when the requested alignment is not a power of 2.
    95         */
    96        config xdc.runtime.Assert.Id A_align =
    97            {msg: "A_align: Requested align is not a power of 2"};
    98    
    99        /*!
   100         *  ======== A_invalidTotalFreeSize ========
   101         *  Assert that remaining size is less than or equal to starting size.
   102         *
   103         *  If this assertion is raised, it means that either incorrect sizes
   104         *  were passed to `{@link #free}` or multiple calls to `{@link #free}`
   105         *  were made with the same buffer.
   106         */
   107        config xdc.runtime.Assert.Id A_invalidTotalFreeSize = {
   108            msg: "HeapStdAlign instance totalFreeSize > than starting size"
   109        };
   110    
   111    instance:
   112    
   113        /*!
   114         *  ======== create ========
   115         *  Create a `HeapStdAlign` heap
   116         *
   117         *  This heap uses the ANSI C Standard Library functions
   118         *  `malloc()` and `free()` to manage memory and assumes that these
   119         *  functions are thread-safe.
   120         *
   121         *  @see HeapStdAlign#Params
   122         */
   123        create();
   124    
   125        /*!
   126         *  ======== size ========
   127         *  Size (in MAUs) of the heap.
   128         *
   129         *  This parameter specifies the size of the heap managed by a
   130         *  `HeapStdAlign` instance. `HeapStdAlign` is built upon the ANSI C
   131         *  Standard Library functions `malloc()` and `free()`.
   132         *
   133         *  The total size of all `HeapStdAlign` instance allocations added
   134         *  together cannot exceed the `malloc`/`free` heap size determined by
   135         *  `{@link xdc.cfg.Program#heap Program.heap}`.
   136         *
   137         *  This is a required parameter. It must be set by the caller. Failure
   138         *  to do so, will result in a build error for the static create or an
   139         *  assert for the runtime create.
   140         */
   141        config Memory.Size size = 0;
   142    
   143        /*!
   144         *  ======== alloc ========
   145         *  Allocates a block of memory from the heap.
   146         *
   147         *  @a(Constraints)
   148         *  The only alignment currently supported is the default
   149         *  alignment returned by the underlying `malloc()` implementation.
   150         *  The align value must be less than or equal to the value returned from
   151         *  `{@link Memory#getMaxDefaultTypeAlign()}`.
   152         *
   153         *  @see IHeap#alloc
   154         */
   155        override Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
   156    
   157        /*!
   158         *  ======== isBlocking ========
   159         *  Returns whether the heap may block during an `HeapStdAlign_alloc()` or
   160         *  `HeapStdAlign_free()`.
   161         *
   162         *  @a(returns)
   163         *  Since the implementation of the underlaying ANSI C Standard Library
   164         *  is not known, this function always returns the more restrictive case
   165         *  which is `TRUE`.
   166         */
   167        override Bool isBlocking();
   168    
   169    internal:
   170    
   171        struct Module_State {
   172            Memory.Size remainRTSSize;      /* Remaining size of rts heap      */
   173        };
   174    
   175        struct Instance_State {
   176            Memory.Size remainSize;         /* Size of the remaining heap.      */
   177            Memory.Size startSize;          /* Starting size of the heap.       */
   178        };
   179    }
   180    
   181    /*
   182     *  @(#) xdcruntime.heaps; 1, 0, 0,36; 10-29-2010 17:24:38; /db/atree/library/trees/osal/osal-c12x/src/ xlibrary
   183    
   184     */
   185