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     *  ======== IHeap.xdc ========
    15     *! - if we ever change the name of this interface, we should change it to
    16     *!   IMemoryProvider
    17     */
    18    
    19    /*!
    20     *  ======== IHeap ========
    21     *  Interface to heap functions.
    22     *
    23     *  All heap implementations inherit from this interface.
    24     *  The implementations can have additional configuration
    25     *  parmeters and functions.
    26     *
    27     */
    28    interface IHeap {
    29    
    30    instance:
    31    
    32        /*!
    33         *  ======== alloc ========
    34         *  Allocates a block of memory from the heap.
    35         *
    36         *  This method returns a block of memory from the heap.
    37         *  It is called by the `{@link xdc.runtime.Memory#alloc()}` function.
    38         *
    39         *  @param(size)     size (in MADUs) of the block
    40         *  @param(align)    alignment (in MADUs)  of the block
    41         *  @param(eb)       pointer to error block
    42         *
    43         *  @a(returns)      Returns the address of the allocated memory.
    44         */
    45        Ptr alloc(SizeT size, SizeT align, Error.Block *eb);
    46    
    47        /*!
    48         *  ======== create ========
    49         *  Create a heap.
    50         *
    51         *  See specific `IHeap` implementation for parameters used.
    52         */
    53        create();
    54    
    55        /*!
    56         *  ======== free ========
    57         *  Free a block of memory back to the heap.
    58         *
    59         *  This method gives back a block of memory to a heap.
    60         *  It is called by the `{@link xdc.runtime.Memory#free()}` function.
    61         *
    62         *  @param(block)    non-`NULL` address of allocated block to free
    63         *  @param(size)     size (in MADUs) of the block of memory to free
    64         */
    65        Void free(Ptr block, SizeT size);
    66    
    67        /*!
    68         *  ======== isBlocking ========
    69         *  Returns whether the heap may block during an `{@link #alloc()}` or
    70         *  `{@link #free()}`.
    71         *
    72         *  @a(returns)      If the heap might block, `TRUE` is returned.
    73         *                   If the heap does not block, `FALSE` is returned.
    74         */
    75        Bool isBlocking();
    76    
    77        /*!
    78         *  ======== getStats ========
    79         *  Retrieve the statistics from the heap.
    80         *
    81         *  The caller passes in a pointer to a `{@link xdc.runtime.Memory#Stats}`
    82         *  structure and `getStats` fills in this structure.
    83         *
    84         *  This function is called by the `{@link xdc.runtime.Memory#getStats()}`
    85         *  function.
    86         *
    87         *  @param(stats)    non-`NULL` pointer to an output buffer
    88         */
    89        Void getStats(Memory.Stats *stats);
    90    }
    91    /*
    92     *  @(#) xdc.runtime; 2, 1, 0,298; 1-12-2011 10:12:28; /db/ztree/library/trees/xdc/xdc-v55x/src/packages/
    93     */
    94