mem/src/mem_frameHeap.c

/*---------------------------------------------------------------------------*
  Project:     MEM library
  File:        mem_frameHeap.c
  Programmers: Makoto Takano

  Copyright 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.
 *---------------------------------------------------------------------------*/

#include <revolution/mem/frameHeap.h>
#include "heapCommoni.h"
#include <stdlib.h>


/* ========================================================================
    Macro constants
   ======================================================================== */

// Minimum alignment value
#define MIN_ALIGNMENT           4


/* ========================================================================
    static functions
   ======================================================================== */

/*---------------------------------------------------------------------------*
  Name:         IsValidFrmHeapHandle_

  Description:  Checks the signature to determine whether the frame heap is valid.

  Arguments:    handle:  The heap handle

  Returns:      TRUE		the heap handle is valid
                FALSE		the heap handle is not valid
 *---------------------------------------------------------------------------*/
static inline BOOL
IsValidFrmHeapHandle_( MEMHeapHandle handle )
{
    if ( handle == MEM_HEAP_INVALID_HANDLE )
    {
        return FALSE;
    }

    {
        MEMiHeapHead* pHeapHd = handle;
        return pHeapHd->signature == MEMi_FRMHEAP_SIGNATURE;
    }
}

/*---------------------------------------------------------------------------*
  Name:         GetFrmHeapHeadPtrFromHeapHead_

  Description:  Get pointer to frame heap header from pointer to heap header.

  Arguments:    pHHead:  Pointer to the heap header.

  Returns:      Returns the pointer to the frame heap header.
 *---------------------------------------------------------------------------*/
static inline MEMiFrmHeapHead*
GetFrmHeapHeadPtrFromHeapHead_( MEMiHeapHead* pHHead )
{
    return (MEMiFrmHeapHead*)AddU32ToPtr( pHHead, sizeof(MEMiHeapHead) );
}

/*---------------------------------------------------------------------------*
  Name:         GetHeapHeadPtrFromFrmHeapHead_

  Description:  Gets heap header pointer from frame heap header pointer.

  Arguments:    pFrmHeapHd:  frame heap header pointer.

  Returns:      Returns the pointer to the heap header.
 *---------------------------------------------------------------------------*/
static inline MEMiHeapHead*
GetHeapHeadPtrFromFrmHeapHead_( MEMiFrmHeapHead* pFrmHeapHd )
{
    return (MEMiHeapHead*)SubU32ToPtr(pFrmHeapHd, sizeof(MEMiHeapHead));
}

/*---------------------------------------------------------------------------*
  Name:         InitFrameHeap_

  Description:  Initializes the frame heap.

  Arguments:    startAddress:  Starting address of memory used as frame heap.
                endAddress:    Ending address +1 of the memory to be used as the frame heap.
                optFlag:       Option flag.

  Returns:      Returns the pointer to the heap header.
 *---------------------------------------------------------------------------*/
static MEMiHeapHead*
InitFrameHeap_(
    void*   startAddress,
    void*   endAddress,
    u16     optFlag
)
{
    MEMiHeapHead* pHeapHd = (MEMiHeapHead*)startAddress;
    MEMiFrmHeapHead* pFrmHeapHd = GetFrmHeapHeadPtrFromHeapHead_( pHeapHd );

    MEMiInitHeapHead(       // Heap common initialization
        pHeapHd,
        MEMi_FRMHEAP_SIGNATURE,
        AddU32ToPtr( pFrmHeapHd, sizeof(MEMiFrmHeapHead) ),    // heapStart
        endAddress,                                        // heapEnd
        optFlag );

    pFrmHeapHd->headAllocator = pHeapHd->heapStart;
    pFrmHeapHd->tailAllocator = pHeapHd->heapEnd;

    pFrmHeapHd->pState = NULL;   // State saving state location

    return pHeapHd;
}


/*---------------------------------------------------------------------------*
  Name:         AllocFromHead_

  Description:  Allocates the memory block from the top of the heap.
                There is an alignment specification.

  Arguments:    pHHead:  Pointer to the heap header.
                size   :    Size of the memory block to be allocated.
                alignment:  Alignment value.

  Returns:      Returns the pointer
                to the allocated memory block if the allocation is successful.
                If fails, NULL is returned.
 *---------------------------------------------------------------------------*/
static void*
AllocFromHead_(
    MEMiFrmHeapHead*    pFrmHeapHd,
    u32                 size,
    int                 alignment
)
{
    void* newBlock = RoundUpPtr(pFrmHeapHd->headAllocator, alignment);
    void* endAddress = AddU32ToPtr(newBlock, size);

    if ( GetUIntPtr(endAddress) > GetUIntPtr(pFrmHeapHd->tailAllocator) )
    {
        return NULL;
    }

    FillAllocMemory(  // Fill memory
        GetHeapHeadPtrFromFrmHeapHead_(pFrmHeapHd),
        pFrmHeapHd->headAllocator,
        GetOffsetFromPtr(pFrmHeapHd->headAllocator, endAddress));

    pFrmHeapHd->headAllocator = endAddress;

    return newBlock;
}

/*---------------------------------------------------------------------------*
  Name:         AllocFromTail_

  Description:  Allocates a memory block from the tail of the heap.
                There is an alignment specification.

  Arguments:    pHHead:     Pointer to the heap header.
                size   :       Size of the memory block to be allocated.
                alignment:  Alignment value.

  Returns:      Returns the pointer
                to the allocated memory block if the allocation is successful.
                If fails, NULL is returned.
 *---------------------------------------------------------------------------*/
static void*
AllocFromTail_(
    MEMiFrmHeapHead*    pFrmHeapHd,
    u32                 size,
    int                 alignment
)
{
    void* newBlock = RoundDownPtr(SubU32ToPtr(pFrmHeapHd->tailAllocator, size), alignment);

    if ( GetUIntPtr(newBlock) < GetUIntPtr(pFrmHeapHd->headAllocator) )
    {
        return NULL;
    }

    FillAllocMemory(  // Fill memory
        GetHeapHeadPtrFromFrmHeapHead_(pFrmHeapHd),
        newBlock,
        GetOffsetFromPtr(newBlock, pFrmHeapHd->tailAllocator) );

    pFrmHeapHd->tailAllocator = newBlock;

    return newBlock;
}

/*---------------------------------------------------------------------------*
  Name:         FreeHead_

  Description:  Free memory blocks allocated from the head of the heap area all at once.

  Arguments:    pHeapHd:  heap header pointer.

  Returns:      None.
 *---------------------------------------------------------------------------*/
static void
FreeHead_( MEMiHeapHead* pHeapHd )
{
    MEMiFrmHeapHead* pFrmHeapHd = GetFrmHeapHeadPtrFromHeapHead_(pHeapHd);

    FillFreeMemory(
        pHeapHd,
        pHeapHd->heapStart,
        GetOffsetFromPtr(pHeapHd->heapStart, pFrmHeapHd->headAllocator) );

    pFrmHeapHd->headAllocator = pHeapHd->heapStart;
    pFrmHeapHd->pState        = NULL;
}


/*---------------------------------------------------------------------------*
  Name:         FreeTail_

  Description:  Free the memory blocks allocated from the tail of the heap area all at once.

  Arguments:    pHeapHd:  heap header pointer.

  Returns:      None.
 *---------------------------------------------------------------------------*/
static void
FreeTail_( MEMiHeapHead* pHeapHd )
{
    MEMiFrmHeapHead* pFrmHeapHd = GetFrmHeapHeadPtrFromHeapHead_(pHeapHd);

    FillFreeMemory(
        pHeapHd,
        pFrmHeapHd->tailAllocator,
        GetOffsetFromPtr(pFrmHeapHd->tailAllocator, pHeapHd->heapEnd) );

    /*
        In order not to accidentally restore released memory blocks due to recovery of the heap allocation state,
        reset the tail allocation pointer of the save information.
     */
    {
        MEMiFrmHeapState* pState;
        for ( pState = pFrmHeapHd->pState; pState; pState = pState->pPrevState )
        {
            pState->tailAllocator = pHeapHd->heapEnd;
        }
    }

    pFrmHeapHd->tailAllocator = pHeapHd->heapEnd;
}


/*---------------------------------------------------------------------------*
  Name:         PrintSize_

  Description:  Output size and percentage.

  Arguments:    size   :       Target size.
                wholeSize:  Whole size.

  Returns:      None.
 *---------------------------------------------------------------------------*/
#if defined(_DEBUG)

static void
PrintSize_(
    u32     size,
    u32     wholeSize
)
{
    OSReport("%9d (%6.2f%%)", size, 100.0 * size / wholeSize);
}

// #if defined(_DEBUG)
#endif


/* ========================================================================
    External Functions (Non-Public)
   ======================================================================== */

/*---------------------------------------------------------------------------*
  Name:         MEMiGetFreeStartForFrmHeap

  Description:  Gets the head address of the free area of the frame heap.

  Arguments:    heap : Handle for frame heap

  Returns:      Returns the head address of the free area of the frame heap.
 *---------------------------------------------------------------------------*/
void*
MEMiGetFreeStartForFrmHeap( MEMHeapHandle heap )
{
    ASSERT(IsValidFrmHeapHandle_(heap));

    return GetFrmHeapHeadPtrFromHeapHead_(heap)->headAllocator;
}

/*---------------------------------------------------------------------------*
  Name:         MEMiGetFreeEndForFrmHeap

  Description:  Gets the end address of the free area of the frame heap.

  Arguments:    heap : Handle for frame heap

  Returns:      Returns the end address +1 of the free area of the frame heap.
 *---------------------------------------------------------------------------*/
void*
MEMiGetFreeEndForFrmHeap( MEMHeapHandle heap )
{
    ASSERT(IsValidFrmHeapHandle_(heap));

    return GetFrmHeapHeadPtrFromHeapHead_(heap)->tailAllocator;
}


/*---------------------------------------------------------------------------*
  Name:         MEMiDumpFrmHeap

  Description:  Displays the data inside the frame heap.
                This function is for debugging.

  Arguments:    heap :    Handle for frame heap

  Returns:      None.
 *---------------------------------------------------------------------------*/
#if defined(_DEBUG)

void
MEMiDumpFrmHeap( MEMHeapHandle heap )
{
    ASSERT(IsValidFrmHeapHandle_(heap));

    {
        MEMiHeapHead *const    pHeapHd    = heap;
        MEMiFrmHeapHead *const pFrmHeapHd = GetFrmHeapHeadPtrFromHeapHead_( pHeapHd );
        const u32              heapSize   = GetOffsetFromPtr( pHeapHd->heapStart, pHeapHd->heapEnd );

        MEMiDumpHeapHead(pHeapHd);

        OSReport(  "     head [%p - %p) ", pHeapHd->heapStart, pFrmHeapHd->headAllocator);
        PrintSize_(GetOffsetFromPtr(pHeapHd->heapStart, pFrmHeapHd->headAllocator), heapSize);
        OSReport("\n     free                           ");
        PrintSize_(GetOffsetFromPtr(pFrmHeapHd->headAllocator, pFrmHeapHd->tailAllocator), heapSize);
        OSReport("\n     tail [%p - %p) ", pFrmHeapHd->tailAllocator, pHeapHd->heapEnd);
        PrintSize_(GetOffsetFromPtr(pFrmHeapHd->tailAllocator, pHeapHd->heapEnd), heapSize);
        OSReport("\n");

        if ( pFrmHeapHd->pState )
        {
            MEMiFrmHeapState* pState;

            OSReport("    state : [tag]   [head]      [tail]\n");

            for ( pState = pFrmHeapHd->pState; pState; pState = pState->pPrevState )
            {
                OSReport("            '%c%c%c%c' : %p %p\n", pState->tagName >>24, (pState->tagName >>16) & 0xFF, (pState->tagName >>8) & 0xFF, pState->tagName & 0xFF,
                                        pState->headAllocator, pState->tailAllocator);
            }
        }

        OSReport("\n");
    }
}

// #if defined(_DEBUG)
#endif


/* ========================================================================
    External functions (public)
   ======================================================================== */

/*---------------------------------------------------------------------------*
  Name:         MEMCreateFrmHeapEx

  Description:  Creates a frame heap.

  Arguments:    startAddress: Start address of heap area
                size   :         Size of heap area
                optFlag:      Option flag.
                              MEM_HEAP_OPT_0_CLEAR    -- 0 clear flag at memory allocation
                              MEM_HEAP_OPT_DEBUG_FILL -- the debug fill flag

  Returns:      Returns the handle for the created frame heap if the function succeeds.
                If the function fails, MEM_INVALID_HEAP_HANDLE is returned.

  Memo:         Base is not thread save.
                When you thread save, please try to add the argument specifying the heap attribute,
                or please suppress the function that sets the attribute.
 *---------------------------------------------------------------------------*/
MEMHeapHandle
MEMCreateFrmHeapEx(
    void*   startAddress,
    u32     size,
    u16     optFlag
)
{
    void* endAddress;

    ASSERT(startAddress != NULL);

    endAddress   = RoundDownPtr(AddU32ToPtr(startAddress, size), MIN_ALIGNMENT);
    startAddress = RoundUpPtr(startAddress, MIN_ALIGNMENT);

    if ( GetUIntPtr(startAddress) > GetUIntPtr(endAddress)
         ||  GetOffsetFromPtr(startAddress, endAddress) < sizeof(MEMiHeapHead) + sizeof(MEMiFrmHeapHead)
    )
    {
        return MEM_HEAP_INVALID_HANDLE;
    }

    {   // Initialize frame heap
        MEMiHeapHead* pHHead = InitFrameHeap_( startAddress, endAddress, optFlag );
        return pHHead;  // The pointer to the heap header is used as-is as the handle value.
    }
}


/*---------------------------------------------------------------------------*
  Name:         MEMDestroyFrmHeap

  Description:  Destroys the frame heap.

  Arguments:    heap : Handle for frame heap

  Returns:      Returns a pointer to the region occupied by the destroyed heap.
 *---------------------------------------------------------------------------*/
void*
MEMDestroyFrmHeap( MEMHeapHandle heap )
{
    ASSERT(IsValidFrmHeapHandle_(heap));

    MEMiFinalizeHeap(heap);
    return (void*)heap;
}

/*---------------------------------------------------------------------------*
  Name:         MEMAllocFromFrmHeapEx

  Description:  Allocates a memory block from the frame heap
                The memory block alignment can be specified.
                If a negative alignment value is specified, an empty region is searched for from the back of the heap.

  Arguments:    heap :      Handle for frame heap
                size   :      Size of the memory block to be allocated (in bytes)
                alignment: Alignment of the memory block to be allocated.
                           The following values can be specified: �}4, �}8, �}16, �}32, �}64, �}128, ...

  Returns:      Returns the pointer
                to the allocated memory block if the allocation is successful.
                If fails, NULL is returned.
 *---------------------------------------------------------------------------*/
void*
MEMAllocFromFrmHeapEx(
    MEMHeapHandle     heap,
    u32               size,
    int               alignment
)
{
    void* memory = NULL;
    MEMiFrmHeapHead* pFrmHeapHd;

    ASSERT(IsValidFrmHeapHandle_(heap));

    // alignment check
    ASSERT(alignment % MIN_ALIGNMENT == 0);
    ASSERT((abs(alignment) & (abs(alignment) - 1)) == 0);
    ASSERT(MIN_ALIGNMENT <= abs(alignment));

    pFrmHeapHd = GetFrmHeapHeadPtrFromHeapHead_(heap);

    if ( size == 0 )
    {
        size = 1;
    }

    size = RoundUp(size, MIN_ALIGNMENT);

    LockHeap( heap );

    if ( alignment >= 0 )   // Allocate from the front of the heap
    {
        memory = AllocFromHead_(pFrmHeapHd, size, alignment);
    }
    else                    // Allocate from the end of the heap
    {
        memory = AllocFromTail_(pFrmHeapHd, size, -alignment);
    }

    UnlockHeap( heap );

    return memory;
}

/*---------------------------------------------------------------------------*
  Name:         MEMFreeToFrmHeap

  Description:  This function returns the memory block to the frame heap.

  Arguments:    heap : Handle for frame heap
                mode: Method of returning memory block

  Returns:      None.
 *---------------------------------------------------------------------------*/
void
MEMFreeToFrmHeap(
    MEMHeapHandle    heap,
    int              mode
)
{
    ASSERT(IsValidFrmHeapHandle_(heap));

    LockHeap( heap );

    if (mode & MEM_FRMHEAP_FREE_HEAD)
    {
        FreeHead_(heap);
    }

    if (mode & MEM_FRMHEAP_FREE_TAIL)
    {
        FreeTail_(heap);
    }

    UnlockHeap( heap );
}

/*---------------------------------------------------------------------------*
  Name:         MEMGetAllocatableSizeForFrmHeapEx

  Description:  Get the maximum allocatable size in the frame heap.
                The memory block alignment can be specified.

  Arguments:    heap :      Handle for frame heap
                alignment: Alignment of the memory block to be allocated.
                           The following values can be specified: �}4, �}8, �}16, �}32, �}64, �}128, ...

  Returns:      Returns the maximum allocatable size in the frame heap (in bytes)
 *---------------------------------------------------------------------------*/
u32
MEMGetAllocatableSizeForFrmHeapEx(
    MEMHeapHandle    heap,
    int              alignment
)
{
    ASSERT(IsValidFrmHeapHandle_(heap));

    // alignment check
    ASSERT(alignment % MIN_ALIGNMENT == 0);
    ASSERT((abs(alignment) & (abs(alignment) - 1)) == 0);
    ASSERT(MIN_ALIGNMENT <= abs(alignment));

    alignment = abs(alignment); // Convert to a positive value just to be sure

    {
        u32 retVal;
        const MEMiFrmHeapHead* pFrmHeapHd = GetFrmHeapHeadPtrFromHeapHead_(heap);
        BOOL                   enabled    = OSDisableInterrupts();
        const void*            block      = RoundUpPtr(pFrmHeapHd->headAllocator, alignment);

        if ( GetUIntPtr(block) > GetUIntPtr(pFrmHeapHd->tailAllocator) )
        {
            retVal = 0;
        }
        else
        {
            retVal = GetOffsetFromPtr( block, pFrmHeapHd->tailAllocator );
        }
        (void)OSRestoreInterrupts( enabled );
        return retVal;
    }
}


/*---------------------------------------------------------------------------*
  Name:         MEMRecordStateForFrmHeap

  Description:  This function records the current use status of the frame heap.
                You can return to the recorded memory usage status later.
                20 bytes are used to record the status.

  Arguments:    heap :     Handle for frame heap
                tagName:  Tag name given to the status record.

  Returns:      Returns TRUE if successful.
                Returns FALSE if unsuccessful.
 *---------------------------------------------------------------------------*/
BOOL
MEMRecordStateForFrmHeap(
    MEMHeapHandle    heap,
    u32              tagName
)
{
    BOOL retVal;
    ASSERT(IsValidFrmHeapHandle_(heap));

    LockHeap( heap );
    {
        MEMiFrmHeapHead* pFrmHeapHd  = GetFrmHeapHeadPtrFromHeapHead_(heap);
        void* oldHeadAllocator       = pFrmHeapHd->headAllocator;

        // Allocate memory for saving information.
        MEMiFrmHeapState* pState = (MEMiFrmHeapState*)AllocFromHead_(pFrmHeapHd, sizeof(MEMiFrmHeapState), MIN_ALIGNMENT);

        if ( ! pState )
        {
            retVal = FALSE;
            goto ret_;
        }

        // Store the current status
        pState->tagName       = tagName;
        pState->headAllocator = oldHeadAllocator;
        pState->tailAllocator = pFrmHeapHd->tailAllocator;
        pState->pPrevState    = pFrmHeapHd->pState;

        pFrmHeapHd->pState = pState;
        retVal = TRUE;
    }
ret_:
    UnlockHeap( heap );

    return retVal;
}

/*---------------------------------------------------------------------------*
  Name:         MEMFreeByStateToFrmHeap

  Description:  This function returns the frame heap memory block based on the recorded status.
                This function uses the specified tag name to restore the memory usage status in effect immediately prior to
                calling RecordStateForFrmHeap().
                If 0 is specified for the tag name the status is returned to that in effect
                right before the last call of RecordStateForFrmHeap().

                When a memory block is returned by specifying a tag name,
                the recorded information will disappear if RecordStateForFrmHeap()
                is called later.

  Arguments:    heap :     Handle for frame heap
                tagName:  Tag name given to the status record.

  Returns:      Returns TRUE if successful.
                Returns FALSE if unsuccessful.
 *---------------------------------------------------------------------------*/
BOOL
MEMFreeByStateToFrmHeap(
    MEMHeapHandle    heap,
    u32              tagName
)
{
    BOOL retVal;
    ASSERT(IsValidFrmHeapHandle_(heap));

    LockHeap( heap );
    {
        MEMiFrmHeapHead*  pFrmHeapHd = GetFrmHeapHeadPtrFromHeapHead_(heap);
        MEMiFrmHeapState* pState = pFrmHeapHd->pState;

        if ( tagName != 0 )   // The tag name specification exists
        {
            for ( ; pState; pState = pState->pPrevState )
            {
                if ( pState->tagName == tagName )
                {
                    break;
                }
            }
        }

        if ( ! pState )
        {
            retVal = FALSE;
            goto ret_;
        }

        {
            void* oldHeadAllocator = pFrmHeapHd->headAllocator;
            void* oldTailAllocator = pFrmHeapHd->tailAllocator;

            pFrmHeapHd->headAllocator = pState->headAllocator;
            pFrmHeapHd->tailAllocator = pState->tailAllocator;
            pFrmHeapHd->pState = pState->pPrevState;

            FillFreeMemory( heap,
                            pFrmHeapHd->headAllocator,
                            GetOffsetFromPtr(pFrmHeapHd->headAllocator, oldHeadAllocator) );
            FillFreeMemory( heap,
                            oldTailAllocator,
                            GetOffsetFromPtr(oldTailAllocator, pFrmHeapHd->tailAllocator) );
        }

        retVal = TRUE;
    }
ret_:
    UnlockHeap( heap );
    return retVal;
}

/*---------------------------------------------------------------------------*
  Name:         MEMAdjustFrmHeap

  Description:  This function frees the open region of the frame heap from the
                heap region and reduces the heap region by that amount.
                There must not be memory blocks allocated from the back of heap memory.

  Arguments:    heap :     Handle for frame heap

  Returns:      Returns the frame heap size in bytes after reduction if successful.
                (in bytes).
                Returns 0 if unsuccessful.
 *---------------------------------------------------------------------------*/
u32
MEMAdjustFrmHeap( MEMHeapHandle heap )
{
    ASSERT(IsValidFrmHeapHandle_(heap));

    {
        MEMiHeapHead*    pHeapHd    = heap;
        MEMiFrmHeapHead* pFrmHeapHd = GetFrmHeapHeadPtrFromHeapHead_( pHeapHd );
        u32              retVal;

        LockHeap( heap );

        // The function fails if there are any memory blocks allocated from end.
        if ( 0 < GetOffsetFromPtr( pFrmHeapHd->tailAllocator, pHeapHd->heapEnd ) )
        {
            retVal = 0;
            goto ret_;
        }

        pFrmHeapHd->tailAllocator = pHeapHd->heapEnd = pFrmHeapHd->headAllocator;

        retVal = GetOffsetFromPtr( heap, pHeapHd->heapEnd );
ret_:
        UnlockHeap( heap );
        return retVal;
    }
}

/*---------------------------------------------------------------------------*
  Name:         MEMResizeForMBlockFrmHeap

  Description:  This function changes the size of the memory block allocated from the frame heap.

                The memory block to be resized must be the end
                memory block allocated in the forward direction from the available region of the heap.

  Arguments:    heap :      Handle for frame heap
                memBlock:  Pointer to the memory block to be resized.
                newSize:   The new size to be allocated (in bytes).
                           If a value less than 4 is specified processing is performed as if 4 was specified.

  Returns:      Returns the size of the resized memory block (in bytes) if the function is successful.
                Returns 0 if the function fails.
 *---------------------------------------------------------------------------*/
u32
MEMResizeForMBlockFrmHeap(
    MEMHeapHandle    heap,
    void*            memBlock,
    u32              newSize
)
{
    MEMiHeapHead*    pHeapHd    = NULL;
    MEMiFrmHeapHead* pFrmHeapHd = NULL;

    ASSERT(IsValidFrmHeapHandle_(heap));
    ASSERT(memBlock == RoundDownPtr(memBlock, MIN_ALIGNMENT));  // Check if at the minimum alignment boundary.

    pHeapHd    = heap;
    pFrmHeapHd = GetFrmHeapHeadPtrFromHeapHead_( pHeapHd );

    ASSERT( ComparePtr(pHeapHd->heapStart, memBlock) <= 0
               &&  ComparePtr(pFrmHeapHd->headAllocator, memBlock) > 0 );   // Be sure that memory blocks exist in the forward direction
    ASSERT( pFrmHeapHd->pState == NULL
               ||  ComparePtr(pFrmHeapHd->pState, memBlock) < 0 );          // Be sure that there is no status saved after the memory block

    /*
        Set up so newSize cannot be 0.
        If it is somehow 0, it's because the memory block specified by memBlock has ceased to exist.
    */
    if ( newSize == 0 )
    {
        newSize = 1;
    }
    newSize = RoundUp( newSize, MIN_ALIGNMENT );

    LockHeap( heap );
    {
        const u32 oldSize = GetOffsetFromPtr( memBlock, pFrmHeapHd->headAllocator );
        void* endAddress  = AddU32ToPtr( memBlock, newSize );

        if ( newSize == oldSize )  // If the block size is not changed
        {
            goto ret_;
        }

        if ( newSize > oldSize )  // During magnification
        {
            if ( ComparePtr( endAddress, pFrmHeapHd->tailAllocator ) > 0 )  // If the size is insufficient
            {
                newSize = 0;
                goto ret_;
            }

            FillAllocMemory( heap, pFrmHeapHd->headAllocator, newSize - oldSize );
        }
        else                      // During reduction
        {
            FillFreeMemory( heap, endAddress, oldSize - newSize );
        }

        pFrmHeapHd->headAllocator = endAddress;
    }
ret_:
    UnlockHeap( heap );
    return newSize;
}