/*
 * Copyright 2010 Trident Microsystems (Far East) Ltd. All rights reserved.
 * All prior copyright rights in this work and the accompanying software
 * products transferred to Trident Microsystems (Far East) Ltd. by written
 * agreement.
 */
/*****************************************************************************/
/* Copyright (c) 2010 NXP B.V.  All rights are reserved.                     */
/*                                                                           */
/* Redistribution and use in source and binary forms, with or without        */
/* modification, are permitted provided that the following conditions        */
/* are met:                                                                  */
/*                                                                           */
/* Redistributions of source code must retain the above copyright            */
/* notice, this list of conditions and the following disclaimer.             */
/*                                                                           */
/* Redistributions in binary form must reproduce the above copyright         */
/* notice, this list of conditions and the following disclaimer in the       */
/* documentation and/or other materials provided with the distribution.      */
/*                                                                           */
/* Neither the name of NXP nor the names of its                              */
/* contributors may be used to endorse or promote products derived from      */
/* this software without specific prior written permission.                  */
/*                                                                           */
/* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS       */
/* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT         */
/* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR     */
/* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT      */
/* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,     */
/* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT          */
/* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,     */
/* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY     */
/* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT       */
/* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE         */
/* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH          */
/* DAMAGE.                                                                   */
/*                                                                           */
/*****************************************************************************/
//-----------------------------------------------------------------------------
// FILENAME:     tmml.h
//
// VERSION:      11
//
// DESCRIPTION:  Header file for the DVP Memory Management Library.
//
// DOCUMENT REF: DVP Memory Management Library Requirement Specification.
//
// NOTES:        none
//
//-----------------------------------------------------------------------------

#ifndef TMML_H
#define TMML_H

#undef TMFL_MML_DEBUG

#ifndef TMFL_MML_RETAIL
#define TMFL_MML_RETAIL
#endif
//-----------------------------------------------------------------------------
// Standard include files:
//-----------------------------------------------------------------------------
//
#include <tmNxTypes.h>                    // DVP standard data types/structures
#include <tmCompId.h>                   // DVP Component ID types/defines

//-----------------------------------------------------------------------------
// Project include files:
//-----------------------------------------------------------------------------
//

#ifdef __cplusplus
extern "C"
{
#endif

//-----------------------------------------------------------------------------
// Types and defines:
//-----------------------------------------------------------------------------
//


//-----------------------------------------------------------------------------
// TMML Physical Address Type Definition
//
typedef UInt32 tmmlPhysAddr_t, *ptmmlPhysAddr_t;


//-----------------------------------------------------------------------------
// TMML Memspace Handle Definition
//
typedef UInt32 tmmlMmspHandle_t, *ptmmlMmspHandle_t;


//-----------------------------------------------------------------------------
// TMML Bufferpool Handle Definition
//
typedef UInt32 tmmlBufPoolHandle_t, *ptmmlBufPoolHandle_t;


//-----------------------------------------------------------------------------
// TMML Memory Handle Definition
//
typedef UInt32 tmmlMemoryHandle_t, *ptmmlMemoryHandle_t;


//-----------------------------------------------------------------------------
// TMML Memspace Information Structure
//
#define tmmlFastSizeBound 60

typedef struct tmmlMmspInfo_Label
{
    tmmlMmspHandle_t handle;

    Int       totalSize;        // total size malloc'd for this space
    Int       segmentSize;      // size of small block segments
    Int       incrementSize;    // memory space extension chunk size

    struct
    {
        Int   totalFreeSpace;   // total free space in var block heap
        Int   maxFreeBlocksize; // largest free block in var block heap
        Int   nrOfFreeBlocks;   // nr of free blocks in var block heap
    } variableBlockInfo;

    struct
    {
        Int   amountSegments;   // nr of small block segments alloc'd for this
                                // size
        Int   nrOfFreeBlocks;   // nr of small blocks available in this size
    } smallBlockInfo[tmmlFastSizeBound];

} tmmlMmspInfo_t, *ptmmlMmspInfo_t;


//-----------------------------------------------------------------------------
// TMML Standard Function Definitions
//

// Memory Allocation Function Type Definition
// params: data  [I] user defined input params
//                   (pData param of tmmlCustomCreate()
//         size  [I] size of memoryblock to allocate
// return: pointer to allocated memory
//
typedef Pointer (*tmmlMallocFunc_t)(Pointer data, Int size);


// Memory Deallocation Function Type Definition
// params: data  [I] user defined input params
//                   (pData param of tmmlCustomCreate())
//         block [I] block to free
//
typedef void (*tmmlFreeFunc_t)(Pointer data, Pointer block);

// Memspace Traversal Function Type Definition
// params: handle  [I] handle of memspace this function is called for
//         pParms  [I] user defined input parameters
typedef void (*tmmlMmspFunc_t)(tmmlMmspHandle_t handle, Pointer pParms);


//-----------------------------------------------------------------------------
// TMML Memspace Property Types
//
typedef enum tmmlMmspProperty_Label
{
    tmmlNormal     = 0x00, // system memory space
    tmmlContiguous = 0x01, // contiguous memory space
    tmmlSpShared   = 0x02, // memory space shared between processes
    tmmlMpShared   = 0x03, // memory space shared between processors
    tmmlMpCached   = 0x04  // memory space shared between processors and cached
} tmmlMmspProperty_t, *ptmmlMmspProperty_t;

//-----------------------------------------------------------------------------
// TMML Memspace Creation Flags
//
// Note: The flag tmmlMmspNormal is only provided for backward compatibility.
//       For the creation of a non-extendible system memory space, use the flag
//       tmmlMmspNone instead.
//
typedef UInt32  tmmlMmspCreateFlags_t;
typedef UInt32* ptmmlMmspCreateFlags_t;
#define tmmlMmspNone        0x00 // non-extendible system memory space
#define tmmlMmspNormal      0x01 // non-extendible system memory space
#define tmmlMmspContiguous  0x02 // non-extendible contiguous memory space
#define tmmlMmspSpShared    0x04 // non-ext. mem. space shared between processes
#define tmmlMmspMpShared    0x08 // non-ext. mem. space shared between processors
#define tmmlMmspMpCached    0x10 // non-ext. mem. space shared between processors
                                 // and cached
#define tmmlMmspExtendible  0x20 // extendible memory space


//-----------------------------------------------------------------------------
// TMML Buffer Pool Creation Flags
//
typedef UInt32 tmmlBufPoolCreateFlags_t;
typedef UInt32* ptmmlBufPoolCreateFlags_t;
#define tmmlBufPoolNone          0x00 // the buffers are not cache aligned nor
                                      // is their contents cleared to 0
#define tmmlBufPoolCacheAligned  0x01 // the buffers are cache aligned
#define tmmlBufPoolCleared       0x02  // the buffers' contents are cleared to 0


//-----------------------------------------------------------------------------
// TMML Memory Allocation Flags
//
typedef UInt32 tmmlMallocFlags_t;
typedef UInt32* ptmmlMallocFlags_t;
#define tmmlMallocNone          0x00 // the memory block is not cache aligned nor
                                     // is its contents cleared to 0
#define tmmlMallocCacheAligned  0x01 // the memory block is cache aligned
#define tmmlMallocCleared       0x02 // the memory block contents is cleared to 0
#define tmmlMallocCacheSet      0x80 // the memory is aligned to a specific cache set
                                     // (only used in tmmlMallocAlign for TM)

//-----------------------------------------------------------------------------
// TMML Memory Reallocation Flags
//
typedef UInt32 tmmlReallocFlags_t;
typedef UInt32* ptmmlReallocFlags_t;
#define tmmlReallocNone  0x00 // default flag


//-----------------------------------------------------------------------------
// TMML Software Version Number
//

// NOTE: The TMML compatibility number, major version number, and minor version
//       number must be kept current with any TMML interface changes. Changes
//       to the TMML interface that are not backwards compatible result in a
//       compatibility number incremental change. If interfaces are changed but
//       remain backwards compatible, the compatibility number remains the same
//       but the major version number is incremented. Software that will use
//       the TMML can check these version numbers both at build time (using the
//       C preprocessor) and at runtime by calling the tmmlGetSWVersion func-
//       tion. Refer to the DVP Software Versioning Specification for more
//       details.
//
#define TMML_COMPATIBILITY_NR     1 // TMML Compatibility number
#define TMML_MAJOR_VERSION_NR     8 // TMML Major Version number
#define TMML_MINOR_VERSION_NR     1 // TMML Minor Version number


//-----------------------------------------------------------------------------
// TMML Status/Error Codes
//
#define TMML_ERR_BASE             (CID_COMP_MML)
#define TMML_ERR_COMP             (CID_COMP_MML | TM_ERR_COMP_UNIQUE_START)


//-----------------------------------------------------------------------------
// TMML Standard/Required Status Codes
//
#define TMML_ERR_COMPATIBILITY    (TMML_ERR_BASE + TM_ERR_COMPATIBILITY)
#define TMML_ERR_MAJOR_VERSION    (TMML_ERR_BASE + TM_ERR_MAJOR_VERSION)
#define TMML_ERR_COMP_VERSION     (TMML_ERR_BASE + TM_ERR_COMP_VERSION)
#define TMML_ERR_BAD_UNIT_NUMBER  (TMML_ERR_BASE + TM_ERR_BAD_UNIT_NUMBER)
#define TMML_ERR_INVALID_HANDLE   (TMML_ERR_BASE + TM_ERR_BAD_HANDLE)
#define TMML_ERR_BAD_PARAMETER    (TMML_ERR_BASE + TM_ERR_BAD_PARAMETER)
#define TMML_ERR_INVALID_FLAGS    (TMML_ERR_BASE + TM_ERR_INCONSISTENT_PARAMS)
#define TMML_ERR_NOT_SUPPORTED    (TMML_ERR_BASE + TM_ERR_NOT_SUPPORTED)
#define TMML_ERR_INIT_FAILED      (TMML_ERR_BASE + TM_ERR_INIT_FAILED)
#define TMML_ERR_LOCK             (TMML_ERR_BASE + TM_ERR_LOCK)
#define TMML_ERR_UNLOCK           (TMML_ERR_BASE + TM_ERR_UNLOCK)
#define TMML_ERR_OUT_OF_MEMORY    (TMML_ERR_BASE + TM_ERR_OUT_OF_MEMORY)
#define TMML_ERR_VIRT_ADDR        (TMML_ERR_BASE + TM_ERR_BAD_VIRT_ADDRESS)
#define TMML_ERR_PHYS_ADDR        (TMML_ERR_BASE + TM_ERR_BAD_PHYS_ADDRESS)


//-----------------------------------------------------------------------------
// TMML Specific Status Codes
//
#define TMML_ERR_UNKNOWN          (TMML_ERR_COMP + 0x0001)
#define TMML_ERR_BUFFERS_FULL     (TMML_ERR_COMP + 0x0002)
#define TMML_ERR_BUFFER_POOL_FULL (TMML_ERR_COMP + 0x0003)


//-----------------------------------------------------------------------------
// Exported functions:
//-----------------------------------------------------------------------------
//

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlInit:
//
// DESCRIPTION: This function performs the initialization of the DVP MML. It
//              first retrieves the configuration parameters from the configu-
//              ration file and overwrites the default values. Subsequently,
//              the appropriate internal (cache) alignment is set. Then the
//              memory layout is retrieved and the address translation offsets
//              as well as the critical regions are initialised. Finally, the
//              master control structures and the bufferpool and the memspace
//              control blocks are initialised.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_INIT_FAILED      initialization failed
//              TMML_ERR_OUT_OF_MEMORY    could not allocate control data
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlInit (
    void
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlExit:
//
// DESCRIPTION: This function performs the de-initialization of the DVP MML.
//              The memspace and bufferpool control blocks, as well as the
//              master control structures are de-initialised. Then the critical
//              regions and the address translation offsets are de-initialised.
//              Finally the memory layout is de-initialised.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlExit (
    void
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlGetSWVersion:
//
// DESCRIPTION: Returns the TMML interface compatibility number, major version,
//              and minor version. It is called to validate the TMML interface
//              compatibility and version information before the interface is
//              used. If the caller of this function detects a mismatch with
//              it's expected interface compatibility number or major version
//              number, it should not use the interface as functions and/or
//              parameters are likely to have changed (the reason for the ver-
//              sion number changes).
//
// RETURN:      TM_OK                         success
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlGetSWVersion (
    ptmSWVersion_t pTmmlVersionInfo // O: TMML software version info pointer
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlCreate:
//
// DESCRIPTION: The function creates a heap with the specified size and returns
//              a memspace handle for the heap created. The handle is Null when
//              no memory could be allocated for it. The heap's properties can
//              be set through the creation flags. Set the tmmlMmspNormal flag
//              to create a heap in system memory. Set the tmmlMmspContiguous
//              flag to create a heap in contiguous memory. Set the
//              tmmlMmspSpShared flag to create a heap that is shared between
//              processes. Set the tmmlMmspMpShared flag to create a heap that
//              is shared between processors. Set the tmmlMmspMpCached flag to
//              create a heap that is cached and shared between processors.
//              The tmmlMmspExtendible flag may be OR-ed together with one of
//              the others to create an extendible memory heap. If the
//              tmmlMmspExtendible flag isn't set the automatic extension will
//              be disabled. If the flag is set to tmmlMmspNone a non
//              extentible tmmlMmspNormal heap is created.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_FLAGS        invalid flag combination
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       This function results in calling the system memory allocation
//              function (eg: malloc()). If your system is configured that the
//              system memory allocation function blocks on OOM conditions this
//              function is unable to return TMML_ERR_OUT_OF_MEMORY.
//              (eg: for pSOS check LC_WAITOPT in sys_conf.h)
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlCreate (
    ptmmlMmspHandle_t     pHandle,   // O: pointer to memspace handle returned
                                     //    upon success
    UInt32                nrOfBytes, // I: size of the memspace
    tmmlMmspCreateFlags_t flags      // I: memspace creation flags
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlCustomCreate:
//
// DESCRIPTION: Creates a memspace with specified size using the specified
//              malloc function, and returns a handle, or Null when no memory
//              could be allocated for it. A call to tmmDelete with a handle
//              previously returned by tmmlCreate or tmmlCustomCreate, will use
//              the free function provided as input parameter.
//              For use of the flags parameter see tmmlCreate() description..
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_FLAGS        invalid flag combination
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlCustomCreate (
    ptmmlMmspHandle_t     pHandle,   // O: pointer to memspace handle returned
                                     //    upon success
    UInt32                nrOfBytes, // I: size of the memspace
    tmmlMallocFunc_t      malloc,    // I: function to be used for allocating the
                                     //    memspace
    tmmlFreeFunc_t        free,      // I: function to be used for freeing the
                                     //    memspace
    pVoid                 pData,     // I: argument for malloc and free functions
    tmmlMmspCreateFlags_t flags      // I: memspace creation flags
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlCreateBufferPool:
//
// DESCRIPTION: Creates a bufferpool of a specified number of buffers with a
//              specified size. The bufferpool will be created in the memspace
//              passed in. If Null is passed in as the memspace to allocate the
//              bufferpool in, a memspace will internally be created to accomo-
//              date the requested bufferpool. This internally created memspace
//              well be a non-extendible system memspace, and is not returned
//              to the user (as it is non-extendible, the possible usage would
//              be limited anyhow). The bufferpool properties can be set by the
//              bufferpool creation flags. The flags may be OR-ed together. Set
//              the flag tmmlBufPoolNone for buffers that aren't cache aligned
//              and whose contents isn't cleared to zero. Set the flag tmmlBuf-
//              PoolCacheAligned for buffers that are cache aligned. Set the
//              flag tmmlBufPoolCleared for buffers whose contents is to be
//              cleared to zero. The flags may also be OR-ed together.
//              NOTE: The maximum number of buffer pools per memory region
//                    that can be created is configurable by the user.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_FLAGS        invalid flag combination
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_BUFFER_POOL_FULL     no more buffer pools available
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlCreateBufferPool (
    tmmlMmspHandle_t         handle,         // I: handle to memspace to create
                                             //    bufferpool in, or Null
    ptmmlBufPoolHandle_t     pBufPoolHandle, // O: handle to bufferpool return-
                                             //    ed upon success
    UInt32                   nrOfBuffers,    // I: nr of buffers requested
    UInt32                   sizeOfBuffers,  // I: size of each buffer
    tmmlBufPoolCreateFlags_t flags           // I: bufferpool creation flags
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlDeleteBufferPool:
//
// DESCRIPTION: Deletes the bufferpool specified by the bufferpool handle that
//              is passed in. If the bufferpool handle passed in is invalid, an
//              error is returned. If the tmmlCreateBufferPool() function used
//              to create the bufferpool that is to be deleted, was called with
//              a Null memspace handle, the internally created memspace will be
//              deleted as well.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_HANDLE       invalid bufferpool handle
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlDeleteBufferPool (
    tmmlBufPoolHandle_t bufPoolHandle // I: handle to bufferpool to delete
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlGetBuffer:
//
// DESCRIPTION: Gets a buffer from the specified bufferpool. If no more buffers
//              are available within the bufferpool or if the bufferpool handle
//              passed in is invalid, an error is returned.
//              A buffer retrieved with tmmlGetBuffer can be freed using
//              tmmlFreeBuffer.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_BUFFERS_FULL         no more buffers available
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlGetBuffer (
    tmmlBufPoolHandle_t bufPoolHandle, // I: bufpool handle to get buffer from
    pVoid               *ppAddress     // O: buffer returned upon success
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlFreeBuffer:
//
// DESCRIPTION: This function frees a single buffer from the specified
//              bufferpool. To free all allocated buffers at once
//              tmmlDeleteBufferPool can be used.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlFreeBuffer (
    tmmlBufPoolHandle_t bufPoolHandle, // I: bufpool handle to free buffer from
    pVoid               pAddress       // I: buffer to be freed
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlDelete:
//
// DESCRIPTION: Deletes a previously allocated memory space, and returns all
//              its extension chunks back to the underlying memory manager.
//              If the heap was created with the tmmlCustomCreate. The heap
//              will be freed with the free function given to tmmlCustomCreate.
//              tmmlDelete also frees al allocated memory blocks and
//              bufferpools in the specified heap.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlDelete (
    tmmlMmspHandle_t    handle     // I: handle to memspace to delete
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlMalloc:
//
// DESCRIPTION: Attempts the allocation of a block of memory of the specified
//              size within the specified memory space
//              If the flag TMFL_MML_DEBUG_MALLOC is set this macro gets resol-
//              ved to a tmmlDebugMalloc() call. If the flag is not set this
//              macro gets resolved to a tmmlRetailMalloc() call. If the flag
//              is set the sizes of the guarded areas before and after the user
//              part of the memory block are given by the macro definitions
//              TMML_BSIZE, and TMML_ASIZE respectively, which are defined to
//              be zero by default.
//
//              The same story holds for tmmlMallocAlign.
//
//              If a Null handle is used the memory will be allocated in the
//              system memspace.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_FLAGS        invalid flag combination
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
#ifdef    TMFL_MML_DEBUG_MALLOC

    #ifndef    TMML_BSIZE
        #define TMML_BSIZE        37 // size of the guarded area before the user
                                    // part of the memory block
    #endif //  TMML_BSIZE

    #ifndef    TMML_ASIZE
        #define TMML_ASIZE        37 // size of the guarded area after the user
                                    // part of the memory block
    #endif //  TMML_ASIZE

    #define tmmlMalloc(handle,nrOfBytes,ppAddress,flags)                                                 \
                tmmlDebugMalloc(handle,nrOfBytes,ppAddress,TMML_BSIZE,TMML_ASIZE,__FILE__,__LINE__,flags)

    #define tmmlMallocAlign(handle,nrOfBytes,ppAddress,flags,alignment)                                                 \
                tmmlDebugMallocAlign(handle,nrOfBytes,ppAddress,TMML_BSIZE,TMML_ASIZE,__FILE__,__LINE__,flags,(UInt32)alignment)

#else

    #define tmmlMalloc(handle,nrOfBytes,ppAddress,flags)                      \
                tmmlRetailMalloc(handle,nrOfBytes,ppAddress,flags)

    #define tmmlMallocAlign(handle,nrOfBytes,ppAddress,flags,alignment)                      \
                tmmlRetailMallocAlign(handle,nrOfBytes,ppAddress,flags,alignment)

#endif // TMFL_MML_DEBUG_MALLOC

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlRetailMalloc:
//
// DESCRIPTION: Attemps the allocation of a block of memory of the specified
//              size within the specified memspace. The allocation properties
//              can be set by the memory allocation flags. The flags may be
//              OR-ed together. Set the flag tmmlMallocNone for a memory block
//              that is not cache aligned and whose contents is not cleared to
//              zero. Set the flag tmmlMallocCacheAligned for a memory block
//              that is cache aligned. Set the flag tmmlMallocCleared for a
//              memory block whose contents is cleared to zero.
//
//              This is the optimized version of tmmlDebugMalloc, does not add
//              guarded areas or other debug features.
//              An application should typically use tmmlMalloc(). tmmlMalloc
//              resolves to tmmlRetailMalloc if TMFL_MML_DEBUG_MALLOC is
//              not defined.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_FLAGS        invalid flag combination
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlRetailMalloc (
    tmmlMmspHandle_t  handle,     // I: handle to memspace to allocate from
    UInt32            nrOfBytes,  // I: number of bytes to allocate
    pVoid             *ppAddress, // O: address returned upon success
    tmmlMallocFlags_t flags       // I: memory allocation flags
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlDebugMalloc:
//
// DESCRIPTION: As tmmlMalloc, adds guarded areas for debugging purposes.
//              Attemps the allocation of guarded memory if the debug version of
//              the tmml library is used. Otherwise this function is
//              the same as tmmlRetailMalloc. Guarded memory blocks
//              have guarded regions immediately before and after their user
//              space. Guard regions are filled with a magic pattern that can
//              be checked for corruption at critical moments. Guarded memory
//              blocks also have file position and line info attached, by which
//              their creators can be located. The allocation properties can be
//              set by the memory allocation flags. The flags may be OR-ed to-
//              gether. Set the flag tmmlMallocNone for a memory block that is
//              not cache aligned and whose contents is not cleared to zero.
//              Set the flag tmmlMallocCacheAligned for a memory block that is
//              cache aligned. Set the flag tmmlMallocCleared for a memory
//              block whose contents is cleared to zero.
//
//              An application should typically use tmmlMalloc(). To enable
//              debugging for memory errors, the application or the library to
//              be debugged, should be recompiled with TMFL_MML_DEBUG_MALLOC,
//              TMML_ASIZE and TMML_BSIZE defined and the debug tmml library
//              should be linked in.
//
//              An application can use tmmlCheck() to check if the guard areas are
//              not overwritten.
//              An application can use tmmlPrintGuarded() to list all the
//              currently allocated memory blocks. This is usefull for tracing memory leaks.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_FLAGS        invalid flag combination
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       In the non-debugging form of this library, bSize, aSize, file
//              and line are ignored.
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlDebugMalloc (
    tmmlMmspHandle_t  handle,     // I: handle to memspace to allocate from
    UInt32            nrOfBytes,  // I: number of bytes to allocate
    pVoid             *ppAddress, // O: address returned upon success
    UInt16            bSize,      // I: size of guarded area before the user
                                  //    part of the memory block
    UInt16            aSize,      // I: size of guarded area after the user
                                  //    part of the memory block
    String            file,       // I: for passing file information
    Int               line,       // I: for passing line information
    tmmlMallocFlags_t flags       // I: memory allocation flags
    );
//-----------------------------------------------------------------------------
// FUNCTION:    tmmlRetailMallocAlign:
//
// DESCRIPTION: This function has the same functionality as tmmlRetailMalloc
//              the only difference with tmmlRetailMalloc is that the memory
//              will be aligned to the PHYSICAL memory boundary given by the
//              parameter alignment.
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_FLAGS        invalid flag combination
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlRetailMallocAlign (
    tmmlMmspHandle_t  handle,     // I: handle to memspace to allocate from
    UInt32            nrOfBytes,  // I: number of bytes to allocate
    pVoid             *ppAddress, // O: address returned upon success
    tmmlMallocFlags_t flags,      // I: memory allocation flags
    UInt32            alignment   // I: physical boundary for allocation
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlDebugMalloc:
//
// DESCRIPTION: This function has the same functionality as tmmlDebugMalloc
//              the only difference with tmmlDebugMalloc is that the memory
//              will be aligned to the PHYSICAL memory boundary given by the
//              parameter alignment.
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_FLAGS        invalid flag combination
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       In the non-debugging form of this library, bSize, aSize, file
//              and line are ignored.
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlDebugMallocAlign (
    tmmlMmspHandle_t  handle,     // I: handle to memspace to allocate from
    UInt32            nrOfBytes,  // I: number of bytes to allocate
    pVoid             *ppAddress, // O: address returned upon success
    UInt16            bSize,      // I: size of guarded area before the user
                                  //    part of the memory block
    UInt16            aSize,      // I: size of guarded area after the user
                                  //    part of the memory block
    String            file,       // I: for passing file information
    Int               line,       // I: for passing line information
    tmmlMallocFlags_t flags,      // I: memory allocation flags
    UInt32            alignment   // I: physical boundary for allocation
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlFree:
//
// DESCRIPTION: Frees previously allocated memory.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlFree (
    pVoid    pAddress    // I: block to be freed
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlRealloc:
//
// DESCRIPTION: Changes the size of a memory block and returns a pointer to the
//              new, possibly resized block. If successful, this function
//              correctly handles guarded, cache aligned and normal memory
//              blocks. If a guarded block is passed in, the result will also
//              be guarded with the same guard parameters (i.e. bSize, aSize,
//              line and file). The same is true for cache aligned input
//              blocks. The data contents of the original memory block are
//              copied into the reallocated block. The memory reallocation
//              flags parameter is reserved for future use. Set this flag to
//              tmmlReallocNone.
//
//              If a Null handle is used the system memspace will be used.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_FLAGS        invalid flag combination
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlRealloc (
    tmmlMmspHandle_t   handle,        // I: handle to memspace to allocate from
    UInt32             nrOfBytes,     // I: number of bytes to allocate
    pVoid              pAddressIn,    // I: address of memory block
    pVoid              *ppAddressOut, // O: address returned upon success
    tmmlReallocFlags_t flags          // I: memory reallocation flags
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlGetInfo:
//
// DESCRIPTION: Gets the current information of the specified memory space.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlGetInfo (
    tmmlMmspHandle_t handle, // I: handle to memspace to get info from
    ptmmlMmspInfo_t  pInfo   // O: information block to fill
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlPrintGuarded:
//
// DESCRIPTION: Prints a list to the DP buffer of all guarded blocks in the
//              specified memory space and checks the guards for each of the
//              blocks and prints diagnostics in the DP buffer.
//              If a Null handle is used the guarded blocks of the system
//              memspace are printed.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_INVALID_HANDLE       invalid memspace handle
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlPrintGuarded (
    tmmlMmspHandle_t handle // I: handle to memspace to get info from
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlCheck:
//
// DESCRIPTION: Performs a consistency check on the internal state of the
//              memory manager, and print diagnostic on stderr.
//              It also checks all guards for all blocks in all memspaces and
//              reports guard errors in the DP buffer.
//
// RETURN:      none
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
void
tmmlCheck(
    void
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlTraverseSpaces:
//
// DESCRIPTION: Applies the specified function to all memory spaces.
//              (including system memspace)
//
// RETURN:      none
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
void
tmmlTraverseSpaces (
    tmmlMmspFunc_t function, // I: function to apply to all spaces
    pVoid          pData     // I: input parameters to the function
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlLockPages:
//
// DESCRIPTION: Both locks the corresponding pages into memory and returns an
//              array of the physical start addresses of those pages. For OS's
//              that support paging, in the case of paged memory (tmmlMmsp-
//              Normal or tmmlMmspSpShared), all underlying pages are locked
//              and an array of physical addresses is returned. The first
//              address of this array is the physical address corresponding
//              with the virtual address passed in as the start of the virtual
//              memory block that needed to be page-locked. The subsequent
//              addresses of this array are the physical start addresses of the
//              other pages that make up the virtual memory block. It is the
//              user's responsibility to provide enough memory to store all the
//              physical page addresses. In order to calculate this required
//              memory size, the page size is needed, which can be obtained by
//              calling tmmlGetPageSize(). Typically, the size of the virtual
//              memory block will be integer divided by the page size and in-
//              cremented with 1. In the case of non-paged memory (tmmlMmsp-
//              Contiguous, tmmlMmspMpShared or tmmlMmspMpCached), the underly-
//              ing memory can't be swapped out anyway and therefore no action
//              is required as far as locking the memory is concerned. Further,
//              also an array of physical addresses is returned in this case.
//              Again, the first address of this array is the physical address
//              corresponding with the virtual address passed in, and the sub-
//              sequent addresses of this array are the physical start address-
//              es of the other pages. Note that pages in this case only have a
//              conceptual meaning as we are dealing with non-paged memory. It
//              is again the user's responsibility to provide enough memory to
//              store all the physical page addresses. Again, for OS's that do
//              not support paging, the underlying memory can't be swapped out
//              anyway and therefore no action is required as far as locking
//              the memory is concerned. And an array of physical addresses is
//              also returned in this case. However, now the array will only
//              consist of one physical address, namely the physical address
//              corresponding with the virtual address passed in, as the entire
//              memory space is seen as one page when no paging is supported.
//              Indeed, when the required memory size to store the physical
//              addresses in is calculated, the memory block size is divided by
//              the page size (which is the maximum memory size, so the divi-
//              sion results in zero) and incremented with 1, ending up with an
//              array of only one address. Finally note that the virtual
//              address that is passed in doesn't have to be page-aligned.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_LOCK             lock error
//              TMML_ERR_VIRT_ADDR        invalid virtual address
//              TMML_ERR_NOT_SUPPORTED    function not supported
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlLockPages (
    pVoid           pVirtualAddress, // I: virtual address
    UInt32          memoryBlockSize, // I: memory block size (in bytes)
    ptmmlPhysAddr_t pPhysicalAddress // O: array of physical addresses
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlUnLockPages:
//
// DESCRIPTION: Unlocks the corresponding pages so that they can be swapped out
//              of memory again. For OS's that support paging, in the case of
//              paged memory (tmmlMmspNormal or tmmlMmspSpShared), all under-
//              lying pages are unlocked. In the case of non-paged memory
//              (tmmlMmspContiguous, tmmlMmspMpShared or tmmlMmspMpCached), the
//              underlying memory can't be swapped out anyway and therefore no
//              action is required as far as unlocking the memory is concerned.
//              For OS's that don't support paging, again, the underlying memo-
//              ry can't be swapped out and therefore again no action is re-
//              quired as far as unlocking the memory is concerned. Note that
//              the virtual address that is passed in doesn't have to be page-
//              aligned.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_UNLOCK           unlock error
//              TMML_ERR_VIRT_ADDR        invalid virtual address
//              TMML_ERR_NOT_SUPPORTED    function not supported
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlUnLockPages (
    pVoid  pVirtualAddress, // I: virtual address
    UInt32 memoryBlockSize  // I: memory block size (in bytes)
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlMapPhysToVirt:
//
// DESCRIPTION: Maps the specified physical address range to the virtual memory
//              space of the calling process. Note that the resulting virtual
//              memory is not managed by the DVP MML. An error is returned if
//              insufficient space is available in order to map the physical
//              address range.
//
// RETURN:      TM_OK                         success
//              TMML_ERR_OUT_OF_MEMORY        out of memory
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlMapPhysToVirt (
    pVoid          *ppVirtualAddress, // O: base virtual address that maps the
                                      //    base physical address
    tmmlPhysAddr_t physicalAddress,   // I: starting physical address of the
                                      //    range to be mapped
    UInt32         nrOfBytes          // I: number of bytes to be mapped
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlUnMapPhysToVirt:
//
// DESCRIPTION: Unmaps a specified physical address range previously mapped by
//              tmmlMapPhysToVirt().
//
// RETURN:      TM_OK                         success
//              TMML_ERR_UNKNOWN              un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlUnMapPhysToVirt (
    pVoid  pVirtualAddress, // I: base virtual address to which the physical
                            //    pages were mapped
    UInt32 nrOfBytes        // I: number of bytes that were mapped
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlGetPageSize:
//
// DESCRIPTION: Returns the actual page size (in bytes) when running on OS's
//              that use paging (WinNT, WinCE), and returns the maximum possi-
//              ble memory size (in bytes) when running on OS's that don't use
//              paging (pSOS). So when no paging is supported the entire memory
//              space is seen as one page. In the case of pSOS-TM the page size
//              returned is 2^32 bytes. In the case of pSOS-MIPS the page size
//              returned is 2^29 bytes (because in this case only addresses re-
//              siding in the virtual memory segments kseg0 or kseg1 can be
//              used, which are both 512 Mb in size).
//
// RETURN:      TM_OK                 success
//              TMML_ERR_UNKNOWN      un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlGetPageSize (
    pUInt32 pPageSize // O: ptr to page size (in bytes) returned upon success
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlGetOffsetPhysToVirt:
//
// DESCRIPTION: When the flags tmmlContiguous, tmmlMpShared or tmmlMpCached are
//              set, the offset returned is the offset between the process-
//              dependent mapped virtual start address of the memory space, and
//              its process-independent physical start address. In these cases
//              the offset is a signed integer returning the mapped virtual
//              address subtracted by the corresponding physical address. When
//              tmmlSpShared is set, the returned offset is the process-depen-
//              dent mapped virtual start address of the sp shared space. These
//              offsets are typically used in virtual-to-physical and physical-
//              to-virtual translations, when addresses need to be communicated
//              between different processes or processors. In one process the
//              (process-specific) offset for a particular memory space will be
//              subtracted from the virtual address, resulting in a physical
//              address (when the flags tmmlContiguous, tmmlMpShared or tmmlMp-
//              Cached are set) or resulting in the offset of that virtual
//              address from the start of the memory space (when the flag tmml-
//              SpShared is set). In another process the (process-specific)
//              offset for the same memory space will be added again, resulting
//              in a virtual address that can be used in this process. When the
//              flag tmmlNormal is set, the error code TMML_ERR_INVALID_FLAGS
//              will be returned as in this case the underlying memory is (pos-
//              sibly) non-contiguous system memory, and thus returning one
//              single offset would not make sense. When the flag tmmlSpShared
//              is set and no dedicated sp shared memory space is defined, the
//              error code TMML_ERR_INVALID_FLAGS is returned. When the flag is
//              tmmlMpShared and there is no dedicated mp shared memory space
//              defined, the error code TMML_ERR_INVALID_FLAGS is returned.
//              When the flag is tmmlMpCached and there is no dedicated mp
//              cached memory space defined, the error TMML_ERR_INVALID_FLAGS
//              is returned. When the flag is tmmlContiguous and there is no
//              dedicated contiguous memory space defined, the error code
//              TMML_ERR_INVALID_FLAGS is returned.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_INVALID_FLAGS    invalid flag combination
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlGetOffsetPhysToVirt (
    tmmlMmspProperty_t mmspFlag, // I: memspace type
    pInt32             pOffset   // O: ptr to offset (in bytes) returned
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlCacheFlush:
//
// DESCRIPTION: Writes back the contents of the cache for the delimited block
//              of data. The delimitation of the contents is provided by an
//              address and a length in bytes. If the address passed in is Null
//              the entire data cache will be written back.
//              All data cache lines that have been written back are
//              still valid.
//
//              Only valid system memory virtual addresses should be passed to
//              this function.  If the start or end address is not on a cache
//              line boundary, the start address will be rounded down to the
//              nearest cache line start and the end address will be rounded
//              up to the nearest cache line end.
//
// RETURN:      TM_OK                 success
//
// NOTES:       This function may cause the system to crash if used improperly.
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlCacheFlush (
    pVoid  pAddress, // I: base address for the write back operation
    UInt32 nrOfBytes // I: size of the block
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlCacheInvalidate:
//
// DESCRIPTION: Invalidates the contents of the cache for the delimited block
//              of data. Cache line contents are invalidated without
//              writing them back to system memory.
//              This forces any access to the delimited data to be
//              performed directly from SDRAM. The delimitation of the contents
//              is provided by an address and a length in bytes. If the address
//              passed in is Null, the entire data cache will be invalidated.
//
//              Only valid system memory virtual addresses should be passed to
//              this function.  If the start or end address is not on a cache
//              line boundary, the start address will be rounded down to the
//              nearest cache line start and the end address will be rounded
//              up to the nearest cache line end.
//
// RETURN:      TM_OK                 success
//
// NOTES:       This function may cause the system to crash if used improperly.
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlCacheInvalidate (
    pVoid  pAddress, // I: base address for the invalidate operation
    UInt32 nrOfBytes // I: size of the block
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlGetMemHandle:
//
// DESCRIPTION: Retrieves the memory handle associated with the virtual address
//              passed in, based on the memspace type.
//
//              Typically, virtual-to-physical and physical-to-virtual transla-
//              tions are done by adding/subtracting the physical-to-virtual
//              offset, which can be retrieved by calling tmmlGetOffsetPhysTo-
//              Virt(). However, as the offset can be different for every mem-
//              space type, a prerequisite for this call is that the user knows
//              the memspace type in which the address was allocated. In order
//              to abstract the user from this knowledge, and to facilitate
//              address translations, the concept of a memory handle was intro-
//              duced. The advantage of using a memory handle is that the user
//              doesn't have to store the memspace type the memory was alloca-
//              ted in. In order to pass addresses across processes/processors,
//              the virtual address in one process is translated into a memory
//              handle which can be translated in any process and on any
//              processor into a virtual address that can be used in this
//              process' context. The memory handle can also be translated into
//              a process/processor-independent physical address.
//
//              When the flag tmmlNormal is passed in as the memspace type, the
//              error code TMML_ERR_INVALID_FLAGS is returned, because memory
//              allocated from a tmmlNormal memspace cannot be shared across
//              processes or processors.
//
//              NOTE: a memory handle is _not_ the same as a memspace handle
//
// RETURN:      TM_OK                     success
//              TMML_ERR_INVALID_FLAGS    invalid flag combination
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlGetMemHandle (
    pVoid               pVirtualAddress, // I: virtual address
    tmmlMmspProperty_t  mmspFlag,        // I: memspace type
    ptmmlMemoryHandle_t pMemoryHandle    // O: ptr to memory handle
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlMemHandleToVirt:
//
// DESCRIPTION: Translates a memory handle into the corresponding virtual
//              address. When the memory handle passed in originated from a
//              memspace of type tmmlSpShared, tmmlContiguous, tmmlMpShared
//              or tmmlMpCached the memory handle is translated into the
//              corresponding virtual address. A memory handle is obtained by
//              calling the function tmmlGetMemHandle().
//
//              When the memory handle originated from a memspace of type
//              tmmlNormal, the error code TMML_ERR_INVALID_FLAGS is returned.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_INVALID_FLAGS    invalid flag combination
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlMemHandleToVirt (
    tmmlMemoryHandle_t memoryHandle,     // I: memory handle
    pVoid              *ppVirtualAddress // O: ptr to virtual address
    );

//-----------------------------------------------------------------------------
// FUNCTION:    tmmlMemHandleToPhys:
//
// DESCRIPTION: Translates a memory handle into the corresponding physical
//              address.
//              When the memory handle passed in originated from a memspace of
//              type tmmlContiguous, tmmlMpShared or tmmlMpCached, the memory
//              handle is translated into the corresponding physical address.
//              A memory handle is obtained by calling the function tmmlGetMem-
//              Handle(). The memory that the memory handle corresponds to
//              needs to be page-locked and contiguous.
//
//              When the memory handle originated from a memspace of type
//              tmmlNormal or type tmmlSpShared, the error code TMML_ERR_-
//              INVALID_FLAGS is returned.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_INVALID_FLAGS    invalid flag combination
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//-----------------------------------------------------------------------------
//
tmErrorCode_t
tmmlMemHandleToPhys (
    tmmlMemoryHandle_t memoryHandle,    // I: memory handle
    ptmmlPhysAddr_t    pPhysicalAddress // O: ptr to physical address
    );

//---------------------------------------------------------------------------
// FUNCTION:    tmmlVirtToMmspProperty:
//
// DESCRIPTION: Retrieve the memspace property from the virtual address
//              This can be used if you want to obtain a memory handle with
//              tmmlGetMemHandle without knowing what memspace type the address is in.
//
// RETURN:      TM_OK                     success
//
// NOTES:       none
//---------------------------------------------------------------------------
//
tmErrorCode_t
tmmlVirtToMmspProperty (
     pVoid               pVirtualAddress, // I: Virtual address
     ptmmlMmspProperty_t mmspFlag         // O: ptr to mmsp property
     );


//---------------------------------------------------------------------------
// FUNCTION:    tmmlMemHandleToMmspProperty:
//
// DESCRIPTION: Retrieve the memspace property from the memspace from which
//              the memory handle originated.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_INVALID_HANDLE   invalid memory handle
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//---------------------------------------------------------------------------
//
tmErrorCode_t
tmmlMemHandleToMmspProperty (
    tmmlMemoryHandle_t  memoryHandle, // I: memory handle
    ptmmlMmspProperty_t pMmspProperty // O: ptr to mmsp property
    );

//---------------------------------------------------------------------------
// FUNCTION:    tmmlMmspHandleToMmspProperty:
//
// DESCRIPTION: Retrieve the memspace property from the memspace from which
//              the memspace handle originated.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_INVALID_HANDLE   invalid memspace handle
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//---------------------------------------------------------------------------
//
tmErrorCode_t
tmmlMmspHandleToMmspProperty (
    tmmlMmspHandle_t    mmspHandle,   // I: mmsp handle
    ptmmlMmspProperty_t pMmspProperty // O: ptr to mmsp property
    );

//---------------------------------------------------------------------------
// FUNCTION:    tmmlBufPoolHandleToMmspProperty:
//
// DESCRIPTION: Retrieve the memspace property from the memspace in which the
//              bufferpool was created.
//
// RETURN:      TM_OK                     success
//              TMML_ERR_INVALID_HANDLE   invalid bufpool handle
//              TMML_ERR_UNKNOWN          un-identified error
//
// NOTES:       none
//---------------------------------------------------------------------------
//
tmErrorCode_t
tmmlBufPoolHandleToMmspProperty (
    tmmlBufPoolHandle_t bufPoolHandle, // I: bufpool handle
    ptmmlMmspProperty_t pMmspProperty  // O: ptr to mmsp property
    );


#ifdef __cplusplus
}
#endif

#endif // TMML_H
