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