/*---------------------------------------------------------------------------*

  Copyright (C) 2010-2011 Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

 *---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*
  Project:     MEM library
  File:        frameHeap.h
  Programmers: Takano Makoto

  Copyright (C) 2005 Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.
 *---------------------------------------------------------------------------*/

#ifndef MEM_FRAMEHEAP_H__
#define MEM_FRAMEHEAP_H__

#ifdef __cplusplus
extern "C" {
#endif


#include <types.h>
#include <cafe/mem/heapCommon.h>

/* =======================================================================
    Constant Definitions
   ======================================================================== */

#define MEM_FRMHEAP_FREE_HEAD (1 <<0)
#define MEM_FRMHEAP_FREE_TAIL (1 <<1)
#define MEM_FRMHEAP_FREE_ALL  (MEM_FRMHEAP_FREE_HEAD | MEM_FRMHEAP_FREE_TAIL)


/* =======================================================================
    Type Definitions
   ======================================================================== */

typedef struct MEMiFrmHeapState MEMiFrmHeapState;

// Structure for state storage.
struct MEMiFrmHeapState
{
    u32                 tagName;        // Tag name.
    void*               headAllocator;  // Head location of the frame heap.
    void*               tailAllocator;  // Tail location of the frame heap.
    MEMiFrmHeapState*   pPrevState;     // Pointer to the last state storage.
};

typedef struct MEMiFrmHeapHead MEMiFrmHeapHead;

// Header information for the frame heap.
struct MEMiFrmHeapHead
{
    void*               headAllocator;  // Pointer to head memory allocation.
    void*               tailAllocator;  // Pointer to tail memory allocation.

    MEMiFrmHeapState*   pState;         // State storage parameter.
};


/* =======================================================================
    Macro Functions
   ======================================================================== */


/* =======================================================================
    Function Prototypes
   ======================================================================== */

void*       MEMiGetFreeStartForFrmHeap( MEMHeapHandle heap );

void*       MEMiGetFreeEndForFrmHeap  ( MEMHeapHandle heap );

void        MEMiDumpFrmHeap( MEMHeapHandle heap );

MEMHeapHandle  MEMCreateFrmHeapEx(
                                void*   startAddress,
                                u32     size,
                                u16     optFlag );

void*            MEMDestroyFrmHeap( MEMHeapHandle heap );

void*            MEMAllocFromFrmHeapEx(
                                MEMHeapHandle   heap,
                                u32             size,
                                int             alignment );

void             MEMFreeToFrmHeap( MEMHeapHandle heap, int mode );

u32              MEMGetAllocatableSizeForFrmHeapEx( MEMHeapHandle heap, int alignment );

BOOL             MEMRecordStateForFrmHeap( MEMHeapHandle heap, u32 tagName );

BOOL             MEMFreeByStateToFrmHeap( MEMHeapHandle heap, u32 tagName );

u32              MEMAdjustFrmHeap( MEMHeapHandle heap );

u32              MEMResizeForMBlockFrmHeap(
                                MEMHeapHandle    heap,
                                void*            memBlock,
                                u32              newSize );


/* =======================================================================
    Inline Functions
   ======================================================================== */

/*---------------------------------------------------------------------------*
  Name:         MEMCreateFrmHeap

  Description:  Creates a frame heap.

  Arguments:    startAddress: Start address of the heap area.
                size:         Size of the heap area.

  Returns:      Returns the handle for the created frame heap if the function succeeds.
                MEM_INVALID_HEAP_HANDLE is returned if the function fails.
 *---------------------------------------------------------------------------*/
static inline MEMHeapHandle
MEMCreateFrmHeap(
    void*   startAddress,
    u32     size
)
{
    return MEMCreateFrmHeapEx( startAddress, size, 0 );
}


/*---------------------------------------------------------------------------*
  Name:         MEMAllocFromFrmHeap

  Description:  Allocates a memory block from the frame heap.
                The alignment of the memory block is 4-byte fixed.

  Arguments:    heap:   Handle for the frame heap.
                size:   Size of the memory block to allocate (in bytes).

  Returns:      Returns a pointer to the allocated memory block if the allocation was successful.
                 
                If the operation fails, NULL is returned.
 *---------------------------------------------------------------------------*/
static inline void*
MEMAllocFromFrmHeap(
    MEMHeapHandle   heap,
    u32             size
)
{
    return MEMAllocFromFrmHeapEx( heap, size, MEM_HEAP_DEFAULT_ALIGNMENT );
}


/*---------------------------------------------------------------------------*
  Name:         MEMGetAllocatableSizeForFrmHeap

  Description:  Gets the maximum allocatable size in the frame heap.
                The alignment of the memory block is 4-byte fixed.

  Arguments:    heap:      Handle for the frame heap.

  Returns:      Returns the maximum allocatable size in the frame heap (in bytes).
 *---------------------------------------------------------------------------*/
static inline u32
MEMGetAllocatableSizeForFrmHeap( MEMHeapHandle heap )
{
    return MEMGetAllocatableSizeForFrmHeapEx( heap, MEM_HEAP_DEFAULT_ALIGNMENT );
}


#ifdef __cplusplus
} /* extern "C" */
#endif

/* MEM_FRAMEHEAP_H__ */
#endif