1/*
2 * dspbridge/mpu_api/inc/memry.h
3 *
4 * DSP-BIOS Bridge driver support functions for TI OMAP processors.
5 *
6 * Copyright (C) 2007 Texas Instruments, Inc.
7 *
8 * This program is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as published
10 * by the Free Software Foundation version 2.1 of the License.
11 *
12 * This program is distributed .as is. WITHOUT ANY WARRANTY of any kind,
13 * whether express or implied; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15 * Lesser General Public License for more details.
16 */
17
18/*
19 *  ======== memry.h ========
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
48extern "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