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

/*
 *  ======== memry.h ========
 *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
 *  Purpose:
 *      Functional interface for the memory manager, exported by the DSP
 *      system API DLL.  This interface is not publicly documented.
 *
 *  Public Functions:
 *      MEMRY_Alloc
 *      MEMRY_BindMem
 *      MEMRY_Calloc
 *      MEMRY_Free
 *      MEMRY_FreeVM
 *      MEMRY_LinearAddress
 *      MEMRY_ReserveVM
 *      MEMRY_PageLock
 *      MEMRY_PageUnlock
 *      MEMRY_UnMapLinearAddress
 *
 *! Revision History:
 *! ================
 *! 01-Sep-2001 ag: Added MEMRY_[UnMap]LinearAddress.
 *! 11-Oct-2000 ag: Added MEMRY_Reserve[Free]VM() & MEMRY_BindMem().
 *! 12-Nov-1999 kc: Updated for WinCE.
 *!
 */

#ifndef MEMRY_
#define MEMRY_

#ifdef __cplusplus
extern "C" {
#endif

#include <dspapi.h>

#include <memdefs.h>

/*
 *  MEMRY_[GET]SET]VIRTUALSEGID is used by Node & Strm to access virtual 
 *  address space in the correct client process context. The virtual to 
 *  physical mapping is done in the client process context.
 */
#define MEMRY_SETVIRTUALSEGID   MEM_SETVIRTUALSEGID
#define MEMRY_GETVIRTUALSEGID   MEM_GETVIRTUALSEGID
#define MEMRY_MASKVIRTUALSEGID  MEM_MASKVIRTUALSEGID

#ifndef LINUX

/*
 *  ======== MEMRY_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 the pageable memory.
 *                  - MEM_NONPAGED:Allocate from page locked memory.
 *  Returns:
 *      Pointer to a block of memory; or NULL if memory couldn't be
 *      allocated.
 *  Requires:
 *  Ensures:
 *      PVOID pointer returned is a valid memory location.
 */
	extern PVOID MEMRY_Alloc(ULONG cBytes, MEM_POOLATTRS type);

/*
 *  ======== MEMRY_BindBuf ========
 *  Purpose:
 *      Bind a Physical address to a Virtual Address.
 *      In WinCE performs a VirtualCopy().
 *  Parameters:
 *      pVA:        Ptr to reserved memory allocated by MEMRY_ReserveVM().
 *      pPA:        Ptr to a physical memory location.
 *      ulBytes:    Size of physical memory in bytes.
 *  Returns:
 *      TRUE if successful, else FALSE.
 *  Requires:
 *     pPA != NULL.
 *  Ensures:
 */
	extern bool MEMRY_BindMem(PVOID pVA, PVOID pPA, ULONG ulBytes);

/*
 *  ======== MEMRY_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 the pageable memory.
 *                  - MEM_NONPAGED:  Allocate from page locked memory.
 *  Returns:
 *      Pointer to a contiguous block of zeroed memory; or NULL if memory
 *      couldn't be allocated.
 *  Requires:
 *  Ensures:
 *      PVOID pointer returned is a valid memory location.
 */
	extern PVOID WINAPI MEMRY_Calloc(ULONG cBytes, MEM_POOLATTRS type);

/*
 *  ======== MEMRY_Free ========
 *  Purpose:
 *      Free the given block of system memory.
 *  Parameters:
 *      pMemBuf: Pointer to memory allocated by MEMRY_Alloc().
 *  Returns:
 *  Requires:
 *  Ensures:
 *      pMemBuf is no longer a valid pointer to memory.
 */
	extern VOID MEMRY_Free(IN PVOID pMemBuf);

/*
 *  ======== MEMRY_FreeVM ========
 *  Purpose:
 *      Free VM reserved by MEMRY_ReserveVM.
 *  Parameters:
 *      pVirtualAddr: Pointer to memory VM allocated by MEMRY_ReserveVM().
 *  Returns:
 *      TRUE on success, else FALSE.
 *  Requires:
 *     pVirtualAddr != 0
 *  Ensures:
 *
 */
	extern bool MEMRY_FreeVM(PVOID pVirtualAddr);

/*
 *  ======== MEMRY_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
 *      lpBuffer:       Pointer to a process-private data buffer.
 *      cSize:          Size in bytes of the data buffer.
 *  Returns:
 *      A pointer to linear page locked memory, or
 *      NULL if failure locking memory.
 *  Requires:
 *      The size (cSize) must accurately reflect the size of the buffer to
 *      be locked, since the page count is derived from this number.
 *  Ensures:
 *      Memory locked by this service can be accessed at interrupt time, or
 *      from other memory contexts.
 */
	extern DSPAPIDLL PVOID WINAPI MEMRY_PageLock(PVOID pBuffer,
						     ULONG cSize);

#endif				/* ifndef LINUX */

/*
 *  ======== MEMRY_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:
 *     PhysAddr != 0
 *  Ensures:
 *  Notes:
 *      If valid linear address is returned, be sure to call
 *      MEMRY_UnMapLinearAddress().
 */
	extern inline PVOID MEMRY_LinearAddress(PVOID pPhyAddr, ULONG cBytes) {
		return pPhyAddr;
	}
#ifndef LINUX
/*
 *  ======== MEMRY_PageUnlock ========
 *  Purpose:
 *      Unlocks a buffer previously locked using MEMRY_PageLock().
 *  Parameters:
 *      pBuffer:    Pointer to locked memory (as returned by MEMRY_PageLock()).
 *      cSize:      Size in bytes of the buffer.
 *  Returns:
 *      Returns DSP_SOK if unlock successful; else, returns DSP_EFAIL;
 *  Requires:
 *      pBuffer must be a pointer to a locked, shared data buffer previously
 *      locked with MEMRY_PageLock().
 *  Ensures:
 *      Will unlock the pages of memory when the lock count drops to zero.
 *      MEMRY_PageLock() increments the lock count, and MEMRY_PageUnlock
 *      decrements the count.
 */ extern DSPAPIDLL MEMRY_PageUnlock(PVOID pBuffer, ULONG cSize);

/*
 *  ======== MEMRY_ReserveVM ========
 *  Purpose:
 *    Reserve at least ulBytes (page size inc) virtual memory for this process.
 *  Parameters:
 *      ulBytes:   Size in bytes of the minimum space to reserve.
 *  Returns:
 *     Returns NULL on failure, else valid VA of at least ulBytes size.
 *  Requires:
 *  Ensures:
 */
	extern PVOID MEMRY_ReserveVM(ULONG cBytes);

#endif				/* ifndef LINUX */

/*
 *  ======== MEMRY_UnMapLinearAddress ========
 *  Purpose:
 *      Unmap the linear address mapped in MEMRY_LinearAddress.
 *  Parameters:
 *      pBaseAddr:  Ptr to mapped memory (as returned by MEMRY_LinearAddress()).
 *  Returns:
 *  Requires:
 *      - pBaseAddr is a valid linear address mapped in MEMRY_LinearAddress.
 *  Ensures:
 *      - pBaseAddr no longer points to a valid linear address.
 */
	extern inline VOID MEMRY_UnMapLinearAddress(PVOID pBaseAddr) {
	}

#ifdef __cplusplus
}
#endif

#endif				/* MEMRY_ */