dspbridge/inc/mem.h

/*
 *  Copyright 2001-2008 Texas Instruments - http://www.ti.com/
 * 
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

/*
 *  ======== mem.h ========
 *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
 *  Purpose:
 *      Memory management and address mapping services for the DSP/BIOS Bridge
 *      class driver and mini-driver.
 *
 *  Public Functions:
 *      MEM_Alloc
 *      MEM_AllocObject
 *      MEM_AllocPhysMem
 *      MEM_Calloc
 *      MEM_Exit
 *      MEM_FlushCache
 *      MEM_Free
 *      MEM_FreeObject
 *      MEM_FreePhysMem
 *      MEM_GetNumPages
 *      MEM_Init
 *      MEM_IsValidHandle
 *      MEM_LinearAddress
 *      MEM_PageLock
 *      MEM_PageUnlock
 *      MEM_UnMapLinearAddress
 *      MEM_VirtualToPhysical
 *
 *  Notes:
 *
 *! Revision History:
 *! ================
 *! 19-Apr-2004 sb: Added Alloc/Free PhysMem, FlushCache, VirtualToPhysical
 *! 01-Sep-2001 ag: Cleaned up notes for MEM_LinearAddress() does not
 *!                   require phys address to be page aligned!
 *! 02-Dec-1999 rr: stdwin.h included for retail build
 *! 12-Nov-1999 kc: Added warning about use of MEM_LinearAddress.
 *! 29-Oct-1999 kc: Cleaned up for code review.
 *! 10-Aug-1999 kc: Based on wsx-c18.
 *! 07-Jan-1998 gp: Added MEM_AllocUMB and MEM_UMBFree for User Mapped Buffers
 *!                 used by WMD_CHNL.
 *! 23-Dec-1997 cr: Code review cleanup, removed dead Ring 3 code.
 *! 04-Aug-1997 cr: Added explicit CDECL identifiers.
 *! 01-Nov-1996 gp: Updated based on code review.
 *! 04-Sep-1996 gp: Added MEM_PageLock() and MEM_PageUnlock() services.
 *! 14-Aug-1996 mg: Added MEM_GetPhysAddr() and MEM_GetNumPages()
 *! 25-Jul-1996 gp: Added MEM_IsValidHandle() macro.
 *! 10-May-1996 gp: Added MEM_Calloc().
 *! 25-Apr-1996 gp: Added MEM_PhysicalAddress()
 *! 17-Apr-1996 gp: Added MEM_Exit function; updated to latest naming standard.
 *! 08-Apr-1996 gp: Created.
 */

#ifndef MEM_
#define MEM_

#ifdef __cplusplus
extern "C" {
#endif

#include <dspapi.h>

#include <memdefs.h>

/*
 *  ======== MEM_Alloc ========
 *  Purpose:
 *      Allocate memory from the paged or non-paged pools.
 *  Parameters:
 *      cBytes: Number of bytes to allocate.
 *      type:   Type of memory to allocate; one of:
 *              MEM_PAGED: Allocate from pageable memory.
 *              MEM_NONPAGED: Allocate from page locked memory.
 *  Returns:
 *      Pointer to a block of memory;
 *      NULL if memory couldn't be allocated, if cBytes == 0, or if type is
 *      not one of MEM_PAGED or MEM_NONPAGED.
 *  Requires:
 *      MEM initialized.
 *  Ensures:
 *      The returned pointer, if not NULL, points to a valid memory block of
 *      the size requested.
 */
#ifdef __KERNEL__
	extern PVOID MEM_Alloc(IN ULONG cBytes, IN MEM_POOLATTRS type);
#else
#define MEM_Alloc(size, type) malloc (size)
#endif

/*
 *  ======== MEM_AllocObject ========
 *  Purpose:
 *      Allocate an object, and set it's signature.
 *  Parameters:
 *      pObj:       Pointer to the new object.
 *      Obj:        Type of the object to allocate.
 *      Signature:  Magic field value.  Must be non-zero.
 *  Returns:
 *  Requires:
 *      Same requirements as MEM_Calloc(); and
 *      The object structure has a dwSignature field.  The compiler ensures
 *      this requirement.
 *  Ensures:
 *      A subsequent call to MEM_IsValidHandle() will succeed for this object.
 */
#define MEM_AllocObject(pObj, Obj, Signature)           \
{                                                       \
    pObj = MEM_Calloc(sizeof(Obj), MEM_NONPAGED);       \
    if (pObj) {                                         \
        pObj->dwSignature = Signature;                  \
    }                                                   \
}

/*  ======== MEM_AllocPhysMem ========
 *  Purpose:
 *      Allocate physically contiguous, uncached memory
 *  Parameters:
 *      cBytes:     Number of bytes to allocate.
 *      ulAlign:    Alignment Mask.
 *      pPhysicalAddress: Physical address of allocated memory.
 *  Returns:
 *      Pointer to a block of memory;
 *      NULL if memory couldn't be allocated, or if cBytes == 0.
 *  Requires:
 *      MEM initialized.
 *  Ensures:
 *      The returned pointer, if not NULL, points to a valid memory block of
 *      the size requested.  Returned physical address refers to physical
 *      location of memory.
 */
	extern PVOID MEM_AllocPhysMem(IN ULONG cBytes,
				      IN ULONG ulAlign,
				      OUT ULONG * pPhysicalAddress);

/*
 *  ======== MEM_Calloc ========
 *  Purpose:
 *      Allocate zero-initialized memory from the paged or non-paged pools.
 *  Parameters:
 *      cBytes: Number of bytes to allocate.
 *      type:   Type of memory to allocate; one of:
 *              MEM_PAGED:   Allocate from pageable memory.
 *              MEM_NONPAGED: Allocate from page locked memory.
 *  Returns:
 *      Pointer to a block of zeroed memory;
 *      NULL if memory couldn't be allocated, if cBytes == 0, or if type is
 *      not one of MEM_PAGED or MEM_NONPAGED.
 *  Requires:
 *      MEM initialized.
 *  Ensures:
 *      The returned pointer, if not NULL, points to a valid memory block
 *      of the size requested.
 */
	extern PVOID MEM_Calloc(IN ULONG cBytes, IN MEM_POOLATTRS type);

/*
 *  ======== MEM_Exit ========
 *  Purpose:
 *      Discontinue usage of module; free resources when reference count
 *      reaches 0.
 *  Parameters:
 *  Returns:
 *  Requires:
 *      MEM is initialized.
 *  Ensures:
 *      Resources used by module are freed when cRef reaches zero.
 */
	extern VOID MEM_Exit();

/*
 *  ======== MEM_FlushCache ========
 *  Purpose:
 *      Performs system cache sync with discard
 *  Parameters:
 *      pMemBuf:    Pointer to memory region to be flushed.
 *      pMemBuf:    Size of the memory region to be flushed.
 *  Returns:
 *  Requires:
 *      MEM is initialized.
 *  Ensures:
 *      Cache is synchronized
 */
	extern VOID MEM_FlushCache(PVOID pMemBuf, ULONG cBytes,INT FlushType);

/*
 *  ======== MEM_Free ========
 *  Purpose:
 *      Free the given block of system memory.
 *  Parameters:
 *      pMemBuf:    Pointer to memory allocated by MEM_Calloc/Alloc().
 *  Returns:
 *  Requires:
 *      MEM initialized.
 *      pMemBuf is a valid memory address returned by MEM_Calloc/Alloc().
 *  Ensures:
 *      pMemBuf is no longer a valid pointer to memory.
 */
#ifdef __KERNEL__
	extern VOID MEM_Free(IN PVOID pMemBuf);
#else
#define MEM_Free(ptr) free (ptr)
#endif

/*
 *  ======== MEM_VFree ========
 *  Purpose:
 *      Free the given block of system memory.
 *  Parameters:
 *      pMemBuf:    Pointer to memory allocated by MEM_Calloc/Alloc().
 *  Returns:
 *  Requires:
 *      MEM initialized.
 *      pMemBuf is a valid memory address returned by MEM_Calloc/Alloc().
 *  Ensures:
 *      pMemBuf is no longer a valid pointer to memory.
 */
#ifdef __KERNEL__
	extern VOID MEM_VFree(IN PVOID pMemBuf);
#endif

/*
 *  ======== MEM_FreePhysMem ========
 *  Purpose:
 *      Free the given block of physically contiguous memory.
 *  Parameters:
 *      pVirtualAddress:  Pointer to virtual memory region allocated by MEM_AllocPhysMem().
 *      pPhysicalAddress:  Pointer to physical memory region  allocated by MEM_AllocPhysMem().
 *      cBytes:  Size of the memory region allocated by MEM_AllocPhysMem().
 *  Returns:
 *  Requires:
 *      MEM initialized.
 *      pVirtualAddress is a valid memory address returned by
 *          MEM_AllocPhysMem()
 *  Ensures:
 *      pVirtualAddress is no longer a valid pointer to memory.
 */
	extern VOID MEM_FreePhysMem(PVOID pVirtualAddress,
				    DWORD pPhysicalAddress, ULONG cBytes);

/*
 *  ======== MEM_FreeObject ========
 *  Purpose:
 *      Utility macro to invalidate an object's signature, and deallocate it.
 *  Parameters:
 *      pObj:   Pointer to the object to free.
 *  Returns:
 *  Requires:
 *      Same requirements as MEM_Free().
 *  Ensures:
 *      A subsequent call to MEM_IsValidHandle() will fail for this object.
 */
#define MEM_FreeObject(pObj)    \
{                               \
    pObj->dwSignature = 0x00;   \
    MEM_Free(pObj);             \
}

/*
 *  ======== MEM_GetNumPages ========
 *  Purpose:
 *      Calculate the number of pages corresponding to the supplied buffer.
 *  Parameters:
 *      pAddr:  Linear (virtual) address of the buffer.
 *      cBytes: Number of bytes in the buffer.
 *  Returns:
 *      Number of pages.
 *  Requires:
 *      MEM initialized.
 *  Ensures:
 *      If cBytes > 0, number of pages returned > 0.
 */
	extern INT MEM_GetNumPages(IN PVOID pAddr, IN ULONG cBytes);

/*
 *  ======== MEM_Init ========
 *  Purpose:
 *      Initializes private state of MEM module.
 *  Parameters:
 *  Returns:
 *      TRUE if initialized; FALSE if error occured.
 *  Requires:
 *  Ensures:
 *      MEM initialized.
 */
	extern bool MEM_Init();

/*
 *  ======== MEM_IsValidHandle ========
 *  Purpose:
 *      Validate the object handle.
 *  Parameters:
 *      hObj:   Handle to object created with MEM_AllocObject().
 *      Sig:    Expected signature DWORD.
 *  Returns:
 *      TRUE if handle is valid; FALSE otherwise.
 *  Requires:
 *      The object structure has a dwSignature field. Ensured by compiler.
 *  Ensures:
 */
#define MEM_IsValidHandle(hObj, Sig)                \
     ((hObj != NULL) && (hObj->dwSignature == Sig))

/* Structure reflecting a physical address and size of memory referenced. */
	struct MEM_PHYSICAL {
		DWORD dwPhysAddr;
		DWORD nBytes;
	} ;

/*
 *  ======== MEM_LinearAddress ========
 *  Purpose:
 *      Get the linear address corresponding to the given physical address.
 *  Parameters:
 *      pPhysAddr:  Physical address to be mapped.
 *      cBytes:     Number of bytes in physical range to map.
 *  Returns:
 *      The corresponding linear address, or NULL if unsuccessful.
 *  Requires:
 *      MEM initialized.
 *  Ensures:
 *  Notes:
 *      If valid linear address is returned, be sure to call
 *      MEM_UnmapLinearAddress().
 */
#ifndef LINUX
	extern PVOID MEM_LinearAddress(IN PVOID pPhyAddr, IN ULONG cBytes);
#else
#define MEM_LinearAddress(pPhyAddr, cBytes) pPhyAddr
#endif

#ifndef LINUX
/*
 *  ======== MEM_PageLock ========
 *  Purpose:
 *      Calls kernel services to map the set of pages identified by a private
 *      process pointer and a byte count into the calling process's globally
 *      shared address space.
 *  Parameters
 *      pBuffer:    Pointer to a process-private data buffer.
 *      cSize:      Size in bytes of the data buffer.
 *  Returns:
 *      A pointer to linear page locked memory;
 *      NULL if a failure occured locking memory.
 *  Requires:
 *      - MEM initialized.
 *      - The size (cSize) must accurately reflect the size of the buffer to
 *        be locked, since the page count is derived from this number.
 *      - Valid pBuffer.
 *  Ensures:
 *      Memory locked by this service can be accessed at interrupt time, or
 *      from other memory contexts.
 */
	extern PVOID MEM_PageLock(IN PVOID pBuffer, IN ULONG cSize);

/*
 *  ======== MEM_PageUnlock ========
 *  Purpose:
 *      Unlocks a buffer previously locked using MEM_PageLock().
 *  Parameters:
 *      pBuffer:    Pointer to locked memory (as returned by MEM_PageLock()).
 *      cSize:      Size in bytes of the buffer.
 *  Returns:
 *      Returns DSP_SOK if unlock successful; else, returns DSP_EFAIL;
 *  Requires:
 *      - MEM initialized.
 *      - Valid pBuffer.
 *  Ensures:
 *      Will unlock the pages of memory when the lock count drops to zero.
 *      (MEM_PageLock() increments the lock count, and MEM_PageUnlock
 *      decrements the count).
 */
	extern DSP_STATUS MEM_PageUnlock(IN PVOID pBuffer, IN ULONG cSize);
#endif

/*
 *  ======== MEM_UnmapLinearAddress ========
 *  Purpose:
 *      Unmap the linear address mapped in MEM_LinearAddress.
 *  Parameters:
 *      pBaseAddr: Ptr to mapped memory (as returned by MEM_LinearAddress()).
 *  Returns:
 *  Requires:
 *      - MEM initialized.
 *      - pBaseAddr is a valid linear address mapped in MEM_LinearAddress.
 *  Ensures:
 *      - pBaseAddr no longer points to a valid linear address.
 */
#ifndef LINUX
	extern VOID MEM_UnmapLinearAddress(IN PVOID pBaseAddr);
#else
#define MEM_UnmapLinearAddress(pBaseAddr)
#endif

/*
 *  ======== MEM_VirtualToPhysical ========
 *  Purpose:
 *      Given a user allocated virtual address, return the corresponding
 *      physical address based on the page frame address.
 *  Parameters:
 *      dwVirtAddr: Linear address of user allocated (and mapped) buffer.
 *  Returns:
 *      Returns corresponding physical address or NULL if unsuccessful
 *  Requires:
 *      - MEM initialized.
 *      - dwVirtAddr is a valid linear address.
 */
	extern DWORD MEM_VirtualToPhysical(IN DWORD dwVirtAddr);

/*
 *  ======== MEM_ExtPhysPoolInit ========
 *  Purpose:
 *      Uses the physical memory chunk passed for internal consitent memory allocations.
 *      physical address based on the page frame address.
 *  Parameters:
 *      poolPhysBase  starting address of the physical memory pool.
 *      poolSize      size of the physical memory pool.
 *  Returns:
 *      none.
 *  Requires:
 *      - MEM initialized.
 *      - valid physical address for the base and size > 0
 */
	extern VOID MEM_ExtPhysPoolInit(IN DWORD poolPhysBase,
					IN DWORD poolSize);

#ifdef __cplusplus
}
#endif
#endif				/* MEM_ */