hardware/ti/omap3/dspbridge/inc/memry.h

   1 /*
   2  *  Copyright 2001-2008 Texas Instruments - http://www.ti.com/
   3  *
   4  *  Licensed under the Apache License, Version 2.0 (the "License");
   5  *  you may not use this file except in compliance with the License.
   6  *  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *  Unless required by applicable law or agreed to in writing, software
  11  *  distributed under the License is distributed on an "AS IS" BASIS,
  12  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  *  See the License for the specific language governing permissions and
  14  *  limitations under the License.
  15  */
  16
  17 /*
  18  *  ======== memry.h ========
  19  *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
  20  *  Purpose:
  21  *      Functional interface for the memory manager, exported by the DSP
  22  *      system API DLL.  This interface is not publicly documented.
  23  *
  24  *  Public Functions:
  25  *      MEMRY_Alloc
  26  *      MEMRY_BindMem
  27  *      MEMRY_Calloc
  28  *      MEMRY_Free
  29  *      MEMRY_FreeVM
  30  *      MEMRY_LinearAddress
  31  *      MEMRY_ReserveVM
  32  *      MEMRY_PageLock
  33  *      MEMRY_PageUnlock
  34  *      MEMRY_UnMapLinearAddress
  35  *
  36  *! Revision History:
  37  *! ================
  38  *! 01-Sep-2001 ag: Added MEMRY_[UnMap]LinearAddress.
  39  *! 11-Oct-2000 ag: Added MEMRY_Reserve[Free]VM() & MEMRY_BindMem().
  40  *! 12-Nov-1999 kc: Updated for WinCE.
  41  *!
  42  */
  43
  44 #ifndef MEMRY_
  45 #define MEMRY_
  46
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51 #include <dspapi.h>
  52
  53 #include <memdefs.h>
  54
  55 /*
  56  *  MEMRY_[GET]SET]VIRTUALSEGID is used by Node & Strm to access virtual
  57  *  address space in the correct client process context. The virtual to
  58  *  physical mapping is done in the client process context.
  59  */
  60 #define MEMRY_SETVIRTUALSEGID   MEM_SETVIRTUALSEGID
  61 #define MEMRY_GETVIRTUALSEGID   MEM_GETVIRTUALSEGID
  62 #define MEMRY_MASKVIRTUALSEGID  MEM_MASKVIRTUALSEGID
  63
  64 #ifndef LINUX
  65
  66 /*
  67  *  ======== MEMRY_Alloc ========
  68  *  Purpose:
  69  *      Allocate memory from the paged or non-paged pools.
  70  *  Parameters:
  71  *      cBytes:     Number of bytes to allocate.
  72  *      type:       Type of memory to allocate; one of:
  73  *                  - MEM_PAGED:   Allocate from the pageable memory.
  74  *                  - MEM_NONPAGED:Allocate from page locked memory.
  75  *  Returns:
  76  *      Pointer to a block of memory; or NULL if memory couldn't be
  77  *      allocated.
  78  *  Requires:
  79  *  Ensures:
  80  *      PVOID pointer returned is a valid memory location.
  81  */
  82         extern PVOID MEMRY_Alloc(ULONG cBytes, MEM_POOLATTRS type);
  83
  84 /*
  85  *  ======== MEMRY_BindBuf ========
  86  *  Purpose:
  87  *      Bind a Physical address to a Virtual Address.
  88  *      In WinCE performs a VirtualCopy().
  89  *  Parameters:
  90  *      pVA:        Ptr to reserved memory allocated by MEMRY_ReserveVM().
  91  *      pPA:        Ptr to a physical memory location.
  92  *      ulBytes:    Size of physical memory in bytes.
  93  *  Returns:
  94  *      TRUE if successful, else FALSE.
  95  *  Requires:
  96  *     pPA != NULL.
  97  *  Ensures:
  98  */
  99         extern bool MEMRY_BindMem(PVOID pVA, PVOID pPA, ULONG ulBytes);
 100
 101 /*
 102  *  ======== MEMRY_Calloc ========
 103  *  Purpose:
 104  *      Allocate zero-initialized memory from the paged or non-paged pools.
 105  *  Parameters:
 106  *      cBytes:     Number of bytes to allocate.
 107  *      type:       Type of memory to allocate; one of:
 108  *                  - MEM_PAGED:     Allocate from the pageable memory.
 109  *                  - MEM_NONPAGED:  Allocate from page locked memory.
 110  *  Returns:
 111  *      Pointer to a contiguous block of zeroed memory; or NULL if memory
 112  *      couldn't be allocated.
 113  *  Requires:
 114  *  Ensures:
 115  *      PVOID pointer returned is a valid memory location.
 116  */
 117         extern PVOID WINAPI MEMRY_Calloc(ULONG cBytes, MEM_POOLATTRS type);
 118
 119 /*
 120  *  ======== MEMRY_Free ========
 121  *  Purpose:
 122  *      Free the given block of system memory.
 123  *  Parameters:
 124  *      pMemBuf: Pointer to memory allocated by MEMRY_Alloc().
 125  *  Returns:
 126  *  Requires:
 127  *  Ensures:
 128  *      pMemBuf is no longer a valid pointer to memory.
 129  */
 130         extern VOID MEMRY_Free(IN PVOID pMemBuf);
 131
 132 /*
 133  *  ======== MEMRY_FreeVM ========
 134  *  Purpose:
 135  *      Free VM reserved by MEMRY_ReserveVM.
 136  *  Parameters:
 137  *      pVirtualAddr: Pointer to memory VM allocated by MEMRY_ReserveVM().
 138  *  Returns:
 139  *      TRUE on success, else FALSE.
 140  *  Requires:
 141  *     pVirtualAddr != 0
 142  *  Ensures:
 143  *
 144  */
 145         extern bool MEMRY_FreeVM(PVOID pVirtualAddr);
 146
 147 /*
 148  *  ======== MEMRY_PageLock ========
 149  *  Purpose:
 150  *      Calls kernel services to map the set of pages identified by a private
 151  *      process pointer and a byte count into the calling process's globally
 152  *      shared address space.
 153  *  Parameters
 154  *      lpBuffer:       Pointer to a process-private data buffer.
 155  *      cSize:          Size in bytes of the data buffer.
 156  *  Returns:
 157  *      A pointer to linear page locked memory, or
 158  *      NULL if failure locking memory.
 159  *  Requires:
 160  *      The size (cSize) must accurately reflect the size of the buffer to
 161  *      be locked, since the page count is derived from this number.
 162  *  Ensures:
 163  *      Memory locked by this service can be accessed at interrupt time, or
 164  *      from other memory contexts.
 165  */
 166         extern DSPAPIDLL PVOID WINAPI MEMRY_PageLock(PVOID pBuffer,
 167                                                      ULONG cSize);
 168
 169 #endif                          /* ifndef LINUX */
 170
 171 /*
 172  *  ======== MEMRY_LinearAddress ========
 173  *  Purpose:
 174  *      Get the linear address corresponding to the given physical address.
 175  *  Parameters:
 176  *      pPhysAddr:      Physical address to be mapped.
 177  *      cBytes:         Number of bytes in physical range to map.
 178  *  Returns:
 179  *      The corresponding linear address, or NULL if unsuccessful.
 180  *  Requires:
 181  *     PhysAddr != 0
 182  *  Ensures:
 183  *  Notes:
 184  *      If valid linear address is returned, be sure to call
 185  *      MEMRY_UnMapLinearAddress().
 186  */
 187         extern inline PVOID MEMRY_LinearAddress(PVOID pPhyAddr, ULONG cBytes) {
 188                 return pPhyAddr;
 189         }
 190 #ifndef LINUX
 191 /*
 192  *  ======== MEMRY_PageUnlock ========
 193  *  Purpose:
 194  *      Unlocks a buffer previously locked using MEMRY_PageLock().
 195  *  Parameters:
 196  *      pBuffer:    Pointer to locked memory (as returned by MEMRY_PageLock()).
 197  *      cSize:      Size in bytes of the buffer.
 198  *  Returns:
 199  *      Returns DSP_SOK if unlock successful; else, returns DSP_EFAIL;
 200  *  Requires:
 201  *      pBuffer must be a pointer to a locked, shared data buffer previously
 202  *      locked with MEMRY_PageLock().
 203  *  Ensures:
 204  *      Will unlock the pages of memory when the lock count drops to zero.
 205  *      MEMRY_PageLock() increments the lock count, and MEMRY_PageUnlock
 206  *      decrements the count.
 207  */ extern DSPAPIDLL MEMRY_PageUnlock(PVOID pBuffer, ULONG cSize);
 208
 209 /*
 210  *  ======== MEMRY_ReserveVM ========
 211  *  Purpose:
 212  *    Reserve at least ulBytes (page size inc) virtual memory for this process.
 213  *  Parameters:
 214  *      ulBytes:   Size in bytes of the minimum space to reserve.
 215  *  Returns:
 216  *     Returns NULL on failure, else valid VA of at least ulBytes size.
 217  *  Requires:
 218  *  Ensures:
 219  */
 220         extern PVOID MEMRY_ReserveVM(ULONG cBytes);
 221
 222 #endif                          /* ifndef LINUX */
 223
 224 /*
 225  *  ======== MEMRY_UnMapLinearAddress ========
 226  *  Purpose:
 227  *      Unmap the linear address mapped in MEMRY_LinearAddress.
 228  *  Parameters:
 229  *      pBaseAddr:  Ptr to mapped memory (as returned by MEMRY_LinearAddress()).
 230  *  Returns:
 231  *  Requires:
 232  *      - pBaseAddr is a valid linear address mapped in MEMRY_LinearAddress.
 233  *  Ensures:
 234  *      - pBaseAddr no longer points to a valid linear address.
 235  */
 236         extern inline VOID MEMRY_UnMapLinearAddress(PVOID pBaseAddr) {
 237         }
 238
 239 #ifdef __cplusplus
 240 }
 241 #endif
 242
 243 #endif                          /* MEMRY_ */