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
