Home | History | Annotate | Download | only in inc
      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_ */
    244