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
72 extern "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