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 *  ======== cmm.h ========
19 *  DSP-BIOS Bridge driver support functions for TI OMAP processors.
20 *  Purpose:
21 *      The Communication Memory Management(CMM) module provides shared memory
22 *      management services for DSP/BIOS Bridge data streaming and messaging.
23 *      Multiple shared memory segments can be registered with CMM. Memory is
24 *      coelesced back to the appropriate pool when a buffer is freed.
25 *
26 *      The CMM_Xlator[xxx] functions are used for node messaging and data
27 *      streaming address translation to perform zero-copy inter-processor
28 *      data transfer(GPP<->DSP). A "translator" object is created for a node or
29 *      stream object that contains per thread virtual address information. This
30 *      translator info is used at runtime to perform SM address translation
31 *      to/from the DSP address space.
32 *
33 *
34 *  Public Functions:
35 *      CMM_CallocBuf
36 *      CMM_Create
37 *      CMM_Destroy
38 *      CMM_Exit
39 *      CMM_FreeBuf
40 *      CMM_GetHandle
41 *      CMM_GetInfo
42 *      CMM_Init
43 *      CMM_RegisterGPPSMSeg
44 *      CMM_UnRegisterGPPSMSeg
45 *      CMM_XlatorAllocBuf       (Note #1 below)
46 *      CMM_XlatorCreate           "
47 *      CMM_XlatorDelete           "
48 *      CMM_XlatorFreeBuf          "
49 *      CMM_XlatorTranslate        "
50 *
51 *
52 *  Notes:
53 *      #1: Used by Node and Stream modules for SM address translation.
54 *
55 *! Revision History:
56 *! ================
57 *! 30-Jan-2002 ag  Removed unused CMM_Alloc[Free]Desc & CMM_XlatorRegisterPa.
58 *!                 Renamed CMM_AllocBuf() to CMM_CallocBuf().
59 *! 29-Aug-2001 ag: Added dsp virt base and size to CMM_RegisterGPPSMSeg().
60 *! 12-Aug-2001 ag: Added CMM_UnRegisterGPP[DSP}SMSeg[s]().
61 *! 05-Dec-2000 ag: Added param to CMM_XlatorDelete() to force buf cleanup.
62 *! 30-Oct-2000 ag: Added conversion factor to CMM_RegisterDSP[GPP]SMSeg().
63 *! 12-Oct-2000 ag: Added CMM_Xlator[xxx] functions.
64 *! 10-Aug-2000 ag: Created.
65 *!
66 */
67
68#ifndef CMM_
69#define CMM_
70
71#ifdef __cplusplus
72extern "C" {
73#endif
74
75#include <devdefs.h>
76#include <dspapi.h>
77
78#include <cmmdefs.h>
79
80/*
81 *  ======== CMM_CallocBuf ========
82 *  Purpose:
83 *      Allocate memory buffers that can be used for data streaming or
84 *      messaging.
85 *  Parameters:
86 *      hCmmMgr:   Cmm Mgr handle.
87 *      uSize:     Number of bytes to allocate.
88 *      pAttr:     Attributes of memory to allocate.
89 *      ppBufVA:   Address of where to place VA.
90 *  Returns:
91 *      Pointer to a zero'd block of SM memory;
92 *      NULL if memory couldn't be allocated,
93 *      or if cBytes == 0,
94 *  Requires:
95 *      Valid hCmmMgr.
96 *      CMM initialized.
97 *  Ensures:
98 *      The returned pointer, if not NULL, points to a valid memory block of
99 *      the size requested.
100 *
101 */
102	extern PVOID CMM_CallocBuf(struct CMM_OBJECT* hCmmMgr,
103				   UINT uSize, struct CMM_ATTRS * pAttrs,
104				   OUT PVOID * ppBufVA);
105
106/*
107 *  ======== CMM_Create ========
108 *  Purpose:
109 *      Create a communication memory manager object.
110 *  Parameters:
111 *      phCmmMgr:   Location to store a communication manager handle on output.
112 *      hDevObject: Handle to a device object.
113 *      pMgrAttrs:  Comm mem manager attributes.
114 *  Returns:
115 *      DSP_SOK:        Success;
116 *      DSP_EMEMORY:    Insufficient memory for requested resources.
117 *      DSP_EFAIL:      Failed to initialize critical sect sync object.
118 *
119 *  Requires:
120 *      CMM_Init() called.
121 *      phCmmMgr != NULL.
122 *      pMgrAttrs->ulMinBlockSize >= 4 bytes.
123 *  Ensures:
124 *
125 */
126	extern DSP_STATUS CMM_Create(OUT struct CMM_OBJECT** phCmmMgr,
127				     struct DEV_OBJECT* hDevObject,
128				     IN CONST struct CMM_MGRATTRS *pMgrAttrs);
129
130/*
131 *  ======== CMM_Destroy ========
132 *  Purpose:
133 *      Destroy the communication memory manager object.
134 *  Parameters:
135 *      hCmmMgr:    Cmm Mgr handle.
136 *      bForce:     Force deallocation of all cmm memory immediately if set TRUE.
137 *                  If FALSE, and outstanding allocations will return DSP_EFAIL
138 *                  status.
139 *  Returns:
140 *      DSP_SOK:        CMM object & resources deleted.
141 *      DSP_EFAIL:      Unable to free CMM object due to outstanding allocation.
142 *      DSP_EHANDLE:    Unable to free CMM due to bad handle.
143 *  Requires:
144 *      CMM is initialized.
145 *      hCmmMgr != NULL.
146 *  Ensures:
147 *      Memory resources used by Cmm Mgr are freed.
148 */
149	extern DSP_STATUS CMM_Destroy(struct CMM_OBJECT* hCmmMgr, bool bForce);
150
151/*
152 *  ======== CMM_Exit ========
153 *  Purpose:
154 *      Discontinue usage of module. Cleanup CMM module if CMM cRef reaches zero.
155 *  Parameters:
156 *      n/a
157 *  Returns:
158 *      n/a
159 *  Requires:
160 *      CMM is initialized.
161 *  Ensures:
162 */
163	extern VOID CMM_Exit();
164
165/*
166 *  ======== CMM_FreeBuf ========
167 *  Purpose:
168 *      Free the given buffer.
169 *  Parameters:
170 *      hCmmMgr:    Cmm Mgr handle.
171 *      pBuf:       Pointer to memory allocated by CMM_CallocBuf().
172 *      ulSegId:    SM segment Id used in CMM_Calloc() attrs.
173 *                  Set to 0 to use default segment.
174 *  Returns:
175 *      DSP_SOK
176 *      DSP_EFAIL
177 *  Requires:
178 *      CMM initialized.
179 *      pBufPA != NULL
180 *  Ensures:
181 *
182 */
183	extern DSP_STATUS CMM_FreeBuf(struct CMM_OBJECT* hCmmMgr,
184				      PVOID pBufPA, ULONG ulSegId);
185
186/*
187 *  ======== CMM_GetHandle ========
188 *  Purpose:
189 *      Return the handle to the cmm mgr for the given device obj.
190 *  Parameters:
191 *      hProcessor:   Handle to a Processor.
192 *      phCmmMgr:     Location to store the shared memory mgr handle on output.
193 *
194 *  Returns:
195 *      DSP_SOK:        Cmm Mgr opaque handle returned.
196 *      DSP_EHANDLE:    Invalid handle.
197 *  Requires:
198 *      phCmmMgr != NULL
199 *      hDevObject != NULL
200 *  Ensures:
201 */
202	extern DSP_STATUS CMM_GetHandle(DSP_HPROCESSOR hProcessor,
203					OUT struct CMM_OBJECT** phCmmMgr);
204
205/*
206 *  ======== CMM_GetInfo ========
207 *  Purpose:
208 *      Return the current SM and VM utilization information.
209 *  Parameters:
210 *      hCmmMgr:     Handle to a Cmm Mgr.
211 *      pCmmInfo:    Location to store the Cmm information on output.
212 *
213 *  Returns:
214 *      DSP_SOK:        Success.
215 *      DSP_EHANDLE:    Invalid handle.
216 *      DSP_EINVALIDARG Invalid input argument.
217 *  Requires:
218 *  Ensures:
219 *
220 */
221	extern DSP_STATUS CMM_GetInfo(struct CMM_OBJECT* hCmmMgr,
222				      					OUT struct CMM_INFO * pCmmInfo);
223
224/*
225 *  ======== CMM_Init ========
226 *  Purpose:
227 *      Initializes private state of CMM module.
228 *  Parameters:
229 *  Returns:
230 *      TRUE if initialized; FALSE if error occured.
231 *  Requires:
232 *  Ensures:
233 *      CMM initialized.
234 */
235	extern bool CMM_Init();
236
237/*
238 *  ======== CMM_KernConvert ========
239 *  Purpose:
240 *      Convert between Kernel Va & DSP Address.
241 *      Used internally by Bridge.
242 *  Parameters:
243 *      hCmmMgr:    Handle to a Cmm Mgr.
244 *      pAddr       Kernel or DSP address to convert.
245 *      pAttrs      Attrs contains segment ID.Default if NULL.
246 *      xType       Conversion type. CMM_KERNVA2DSP or CMM_DSP2KERNVA.
247 *  Returns:
248 *      NULL on failure. non-null on success.
249 *  Requires:
250 *      pAddr != NULL,
251 *      ulSegId > 0,
252 *      xType CMM_KERNVA2DSP |  CMM_DSP2KERNVA.
253 *  Ensures:
254 *
255 */
256	extern PVOID CMM_KernConvert(struct CMM_OBJECT* hCmmMgr, PVOID pAddr,
257				     struct CMM_ATTRS * pAttrs, CMM_KERNMAPTYPE xType);
258
259/*
260 *  ======== CMM_RegisterGPPSMSeg ========
261 *  Purpose:
262 *      Register a block of SM with the CMM.
263 *  Parameters:
264 *      hCmmMgr:         Handle to a Cmm Mgr.
265 *      lpGPPBasePA:     GPP Base Physical address.
266 *      ulSize:          Size in GPP bytes.
267 *      dwDSPAddrOffset  GPP PA to DSP PA Offset.
268 *      cFactor:         Add offset if CMM_ADDTODSPPA, sub if CMM_SUBFROMDSPPA.
269 *      dwDSPBase:       DSP virtual base byte address.
270 *      ulDSPSize:       Size of DSP segment in bytes.
271 *      pulSegId:        Address to store segment Id.
272 *
273 *  Returns:
274 *      DSP_SOK:         Success.
275 *      DSP_EHANDLE:     Invalid hCmmMgr handle.
276 *      DSP_EINVALIDARG: Invalid input argument.
277 *      DSP_EFAIL:       Unable to register.
278 *      - On success *pulSegId is a valid SM segment ID.
279 *  Requires:
280 *      ulSize > 0
281 *      pulSegId != NULL
282 *      dwGPPBasePA != 0
283 *      cFactor = CMM_ADDTODSPPA || cFactor = CMM_SUBFROMDSPPA
284 *  Ensures:
285 *
286 */
287	extern DSP_STATUS CMM_RegisterGPPSMSeg(struct CMM_OBJECT* hCmmMgr,
288					       DWORD dwGPPBasePA,
289					       ULONG ulSize,
290					       DWORD dwDSPAddrOffset,
291					       CMM_CNVTTYPE cFactor,
292					       DWORD dwDSPBase,
293					       ULONG ulDSPSize,
294					       ULONG * pulSegId,
295					       DWORD dwGPPBaseBA);
296
297/*
298 *  ======== CMM_UnRegisterGPPSMSeg ========
299 *  Purpose:
300 *      Unregister the given memory segment that was previously registered
301 *      by CMM_RegisterGPPSMSeg.
302 *  Parameters:
303 *      hCmmMgr:    Handle to a Cmm Mgr.
304 *      ulSegId     Segment identifier returned by CMM_RegisterGPPSMSeg.
305 *  Returns:
306 *       DSP_SOK:         Success.
307 *       DSP_EHANDLE:     Invalid handle.
308 *       DSP_EINVALIDARG: Invalid ulSegId.
309 *       DSP_EFAIL:       Unable to unregister for unknown reason.
310 *  Requires:
311 *  Ensures:
312 *
313 */
314	extern DSP_STATUS CMM_UnRegisterGPPSMSeg(struct CMM_OBJECT* hCmmMgr,
315						 ULONG ulSegId);
316
317/*
318 *  ======== CMM_XlatorAllocBuf ========
319 *  Purpose:
320 *      Allocate the specified SM buffer and create a local memory descriptor.
321 *      Place on the descriptor on the translator's HaQ (Host Alloc'd Queue).
322 *  Parameters:
323 *      hXlator:    Handle to a Xlator object.
324 *      pVaBuf:     Virtual address ptr(client context)
325 *      uPaSize:    Size of SM memory to allocate.
326 *  Returns:
327 *      Ptr to valid physical address(Pa) of uPaSize bytes, NULL if failed.
328 *  Requires:
329 *      pVaBuf != 0.
330 *      uPaSize != 0.
331 *  Ensures:
332 *
333 */
334	extern PVOID CMM_XlatorAllocBuf(struct CMM_XLATOROBJECT* hXlator,
335					PVOID pVaBuf, UINT uPaSize);
336
337/*
338 *  ======== CMM_XlatorCreate ========
339 *  Purpose:
340 *      Create a translator(xlator) object used for process specific Va<->Pa
341 *      address translation. Node messaging and streams use this to perform
342 *      inter-processor(GPP<->DSP) zero-copy data transfer.
343 *  Parameters:
344 *      phXlator:       Address to place handle to a new Xlator handle.
345 *      hCmmMgr:        Handle to Cmm Mgr associated with this translator.
346 *      pXlatorAttrs:   Translator attributes used for the client NODE or STREAM.
347 *  Returns:
348 *      DSP_SOK:            Success.
349 *      DSP_EINVALIDARG:    Bad input Attrs.
350 *      DSP_EMEMORY:   Insufficient memory(local) for requested resources.
351 *  Requires:
352 *      phXlator != NULL
353 *      hCmmMgr != NULL
354 *      pXlatorAttrs != NULL
355 *  Ensures:
356 *
357 */
358	extern DSP_STATUS CMM_XlatorCreate(OUT struct CMM_XLATOROBJECT** phXlator,
359					   struct CMM_OBJECT* hCmmMgr,
360					   struct CMM_XLATORATTRS *pXlatorAttrs);
361
362/*
363 *  ======== CMM_XlatorDelete ========
364 *  Purpose:
365 *      Delete translator resources
366 *  Parameters:
367 *      hXlator:    handle to translator.
368 *      bForce:     bForce = TRUE will free XLators SM buffers/dscriptrs.
369 *  Returns:
370 *      DSP_SOK:        Success.
371 *      DSP_EHANDLE:    Bad translator handle.
372 *      DSP_EFAIL:      Unable to free translator resources.
373 *  Requires:
374 *      cRefs > 0
375 *  Ensures:
376 *
377 */
378	extern DSP_STATUS CMM_XlatorDelete(struct CMM_XLATOROBJECT* hXlator,
379																bool bForce);
380
381/*
382 *  ======== CMM_XlatorFreeBuf ========
383 *  Purpose:
384 *      Free SM buffer and descriptor.
385 *      Does not free client process VM.
386 *  Parameters:
387 *      hXlator:    handle to translator.
388 *      pBufVa      Virtual address of PA to free.
389 *  Returns:
390 *      DSP_SOK:        Success.
391 *      DSP_EHANDLE:    Bad translator handle.
392 *  Requires:
393 *  Ensures:
394 *
395 */
396	extern DSP_STATUS CMM_XlatorFreeBuf(struct CMM_XLATOROBJECT* hXlator,
397																PVOID pBufVa);
398
399/*
400 *  ======== CMM_XlatorInfo ========
401 *  Purpose:
402 *      Set/Get process specific "translator" address info.
403 *      This is used to perform fast virtaul address translation
404 *      for shared memory buffers between the GPP and DSP.
405 *  Parameters:
406 *     hXlator:     handle to translator.
407 *     pAddr:       Virtual base address of segment.
408 *     ulSize:      Size in bytes.
409 *     uSegId:      Segment identifier of SM segment(s)
410 *     bSetInfo     Set xlator fields if TRUE, else return base addr
411 *  Returns:
412 *      DSP_SOK:        Success.
413 *      DSP_EHANDLE:    Bad translator handle.
414 *  Requires:
415 *      (cRefs > 0)
416 *      (pAddr != NULL)
417 *      (ulSize > 0)
418 *  Ensures:
419 *
420 */
421	extern DSP_STATUS CMM_XlatorInfo(struct CMM_XLATOROBJECT* hXlator,
422					 IN OUT BYTE ** pAddr,
423					 ULONG ulSize, UINT uSegId,
424					 bool bSetInfo);
425
426/*
427 *  ======== CMM_XlatorTranslate ========
428 *  Purpose:
429 *      Perform address translation VA<->PA for the specified stream or
430 *      message shared memory buffer.
431 *  Parameters:
432 *     hXlator: handle to translator.
433 *     pAddr    address of buffer to translate.
434 *     xType    Type of address xlation. CMM_PA2VA or CMM_VA2PA.
435 *  Returns:
436 *     Valid address on success, else NULL.
437 *  Requires:
438 *      cRefs > 0
439 *      pAddr != NULL
440 *      xType >= CMM_VA2PA) && (xType <= CMM_DSPPA2PA)
441 *  Ensures:
442 *
443 */
444	extern PVOID CMM_XlatorTranslate(struct CMM_XLATOROBJECT* hXlator,
445					 PVOID pAddr, CMM_XLATETYPE xType);
446
447#ifdef __cplusplus
448}
449#endif
450#endif				/* CMM_ */
451