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