| /* |
| * Copyright 2001-2008 Texas Instruments - http://www.ti.com/ |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| /* |
| * ======== cmm.h ======== |
| * DSP-BIOS Bridge driver support functions for TI OMAP processors. |
| * Purpose: |
| * The Communication Memory Management(CMM) module provides shared memory |
| * management services for DSP/BIOS Bridge data streaming and messaging. |
| * Multiple shared memory segments can be registered with CMM. Memory is |
| * coelesced back to the appropriate pool when a buffer is freed. |
| * |
| * The CMM_Xlator[xxx] functions are used for node messaging and data |
| * streaming address translation to perform zero-copy inter-processor |
| * data transfer(GPP<->DSP). A "translator" object is created for a node or |
| * stream object that contains per thread virtual address information. This |
| * translator info is used at runtime to perform SM address translation |
| * to/from the DSP address space. |
| * |
| * |
| * Public Functions: |
| * CMM_CallocBuf |
| * CMM_Create |
| * CMM_Destroy |
| * CMM_Exit |
| * CMM_FreeBuf |
| * CMM_GetHandle |
| * CMM_GetInfo |
| * CMM_Init |
| * CMM_RegisterGPPSMSeg |
| * CMM_UnRegisterGPPSMSeg |
| * CMM_XlatorAllocBuf (Note #1 below) |
| * CMM_XlatorCreate " |
| * CMM_XlatorDelete " |
| * CMM_XlatorFreeBuf " |
| * CMM_XlatorTranslate " |
| * |
| * |
| * Notes: |
| * #1: Used by Node and Stream modules for SM address translation. |
| * |
| *! Revision History: |
| *! ================ |
| *! 30-Jan-2002 ag Removed unused CMM_Alloc[Free]Desc & CMM_XlatorRegisterPa. |
| *! Renamed CMM_AllocBuf() to CMM_CallocBuf(). |
| *! 29-Aug-2001 ag: Added dsp virt base and size to CMM_RegisterGPPSMSeg(). |
| *! 12-Aug-2001 ag: Added CMM_UnRegisterGPP[DSP}SMSeg[s](). |
| *! 05-Dec-2000 ag: Added param to CMM_XlatorDelete() to force buf cleanup. |
| *! 30-Oct-2000 ag: Added conversion factor to CMM_RegisterDSP[GPP]SMSeg(). |
| *! 12-Oct-2000 ag: Added CMM_Xlator[xxx] functions. |
| *! 10-Aug-2000 ag: Created. |
| *! |
| */ |
| |
| #ifndef CMM_ |
| #define CMM_ |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| #include <devdefs.h> |
| #include <dspapi.h> |
| |
| #include <cmmdefs.h> |
| |
| /* |
| * ======== CMM_CallocBuf ======== |
| * Purpose: |
| * Allocate memory buffers that can be used for data streaming or |
| * messaging. |
| * Parameters: |
| * hCmmMgr: Cmm Mgr handle. |
| * uSize: Number of bytes to allocate. |
| * pAttr: Attributes of memory to allocate. |
| * ppBufVA: Address of where to place VA. |
| * Returns: |
| * Pointer to a zero'd block of SM memory; |
| * NULL if memory couldn't be allocated, |
| * or if cBytes == 0, |
| * Requires: |
| * Valid hCmmMgr. |
| * CMM initialized. |
| * Ensures: |
| * The returned pointer, if not NULL, points to a valid memory block of |
| * the size requested. |
| * |
| */ |
| extern PVOID CMM_CallocBuf(struct CMM_OBJECT* hCmmMgr, |
| UINT uSize, struct CMM_ATTRS * pAttrs, |
| OUT PVOID * ppBufVA); |
| |
| /* |
| * ======== CMM_Create ======== |
| * Purpose: |
| * Create a communication memory manager object. |
| * Parameters: |
| * phCmmMgr: Location to store a communication manager handle on output. |
| * hDevObject: Handle to a device object. |
| * pMgrAttrs: Comm mem manager attributes. |
| * Returns: |
| * DSP_SOK: Success; |
| * DSP_EMEMORY: Insufficient memory for requested resources. |
| * DSP_EFAIL: Failed to initialize critical sect sync object. |
| * |
| * Requires: |
| * CMM_Init() called. |
| * phCmmMgr != NULL. |
| * pMgrAttrs->ulMinBlockSize >= 4 bytes. |
| * Ensures: |
| * |
| */ |
| extern DSP_STATUS CMM_Create(OUT struct CMM_OBJECT** phCmmMgr, |
| struct DEV_OBJECT* hDevObject, |
| IN CONST struct CMM_MGRATTRS *pMgrAttrs); |
| |
| /* |
| * ======== CMM_Destroy ======== |
| * Purpose: |
| * Destroy the communication memory manager object. |
| * Parameters: |
| * hCmmMgr: Cmm Mgr handle. |
| * bForce: Force deallocation of all cmm memory immediately if set TRUE. |
| * If FALSE, and outstanding allocations will return DSP_EFAIL |
| * status. |
| * Returns: |
| * DSP_SOK: CMM object & resources deleted. |
| * DSP_EFAIL: Unable to free CMM object due to outstanding allocation. |
| * DSP_EHANDLE: Unable to free CMM due to bad handle. |
| * Requires: |
| * CMM is initialized. |
| * hCmmMgr != NULL. |
| * Ensures: |
| * Memory resources used by Cmm Mgr are freed. |
| */ |
| extern DSP_STATUS CMM_Destroy(struct CMM_OBJECT* hCmmMgr, bool bForce); |
| |
| /* |
| * ======== CMM_Exit ======== |
| * Purpose: |
| * Discontinue usage of module. Cleanup CMM module if CMM cRef reaches zero. |
| * Parameters: |
| * n/a |
| * Returns: |
| * n/a |
| * Requires: |
| * CMM is initialized. |
| * Ensures: |
| */ |
| extern VOID CMM_Exit(); |
| |
| /* |
| * ======== CMM_FreeBuf ======== |
| * Purpose: |
| * Free the given buffer. |
| * Parameters: |
| * hCmmMgr: Cmm Mgr handle. |
| * pBuf: Pointer to memory allocated by CMM_CallocBuf(). |
| * ulSegId: SM segment Id used in CMM_Calloc() attrs. |
| * Set to 0 to use default segment. |
| * Returns: |
| * DSP_SOK |
| * DSP_EFAIL |
| * Requires: |
| * CMM initialized. |
| * pBufPA != NULL |
| * Ensures: |
| * |
| */ |
| extern DSP_STATUS CMM_FreeBuf(struct CMM_OBJECT* hCmmMgr, |
| PVOID pBufPA, ULONG ulSegId); |
| |
| /* |
| * ======== CMM_GetHandle ======== |
| * Purpose: |
| * Return the handle to the cmm mgr for the given device obj. |
| * Parameters: |
| * hProcessor: Handle to a Processor. |
| * phCmmMgr: Location to store the shared memory mgr handle on output. |
| * |
| * Returns: |
| * DSP_SOK: Cmm Mgr opaque handle returned. |
| * DSP_EHANDLE: Invalid handle. |
| * Requires: |
| * phCmmMgr != NULL |
| * hDevObject != NULL |
| * Ensures: |
| */ |
| extern DSP_STATUS CMM_GetHandle(DSP_HPROCESSOR hProcessor, |
| OUT struct CMM_OBJECT** phCmmMgr); |
| |
| /* |
| * ======== CMM_GetInfo ======== |
| * Purpose: |
| * Return the current SM and VM utilization information. |
| * Parameters: |
| * hCmmMgr: Handle to a Cmm Mgr. |
| * pCmmInfo: Location to store the Cmm information on output. |
| * |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Invalid handle. |
| * DSP_EINVALIDARG Invalid input argument. |
| * Requires: |
| * Ensures: |
| * |
| */ |
| extern DSP_STATUS CMM_GetInfo(struct CMM_OBJECT* hCmmMgr, |
| OUT struct CMM_INFO * pCmmInfo); |
| |
| /* |
| * ======== CMM_Init ======== |
| * Purpose: |
| * Initializes private state of CMM module. |
| * Parameters: |
| * Returns: |
| * TRUE if initialized; FALSE if error occured. |
| * Requires: |
| * Ensures: |
| * CMM initialized. |
| */ |
| extern bool CMM_Init(); |
| |
| /* |
| * ======== CMM_KernConvert ======== |
| * Purpose: |
| * Convert between Kernel Va & DSP Address. |
| * Used internally by Bridge. |
| * Parameters: |
| * hCmmMgr: Handle to a Cmm Mgr. |
| * pAddr Kernel or DSP address to convert. |
| * pAttrs Attrs contains segment ID.Default if NULL. |
| * xType Conversion type. CMM_KERNVA2DSP or CMM_DSP2KERNVA. |
| * Returns: |
| * NULL on failure. non-null on success. |
| * Requires: |
| * pAddr != NULL, |
| * ulSegId > 0, |
| * xType CMM_KERNVA2DSP | CMM_DSP2KERNVA. |
| * Ensures: |
| * |
| */ |
| extern PVOID CMM_KernConvert(struct CMM_OBJECT* hCmmMgr, PVOID pAddr, |
| struct CMM_ATTRS * pAttrs, CMM_KERNMAPTYPE xType); |
| |
| /* |
| * ======== CMM_RegisterGPPSMSeg ======== |
| * Purpose: |
| * Register a block of SM with the CMM. |
| * Parameters: |
| * hCmmMgr: Handle to a Cmm Mgr. |
| * lpGPPBasePA: GPP Base Physical address. |
| * ulSize: Size in GPP bytes. |
| * dwDSPAddrOffset GPP PA to DSP PA Offset. |
| * cFactor: Add offset if CMM_ADDTODSPPA, sub if CMM_SUBFROMDSPPA. |
| * dwDSPBase: DSP virtual base byte address. |
| * ulDSPSize: Size of DSP segment in bytes. |
| * pulSegId: Address to store segment Id. |
| * |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Invalid hCmmMgr handle. |
| * DSP_EINVALIDARG: Invalid input argument. |
| * DSP_EFAIL: Unable to register. |
| * - On success *pulSegId is a valid SM segment ID. |
| * Requires: |
| * ulSize > 0 |
| * pulSegId != NULL |
| * dwGPPBasePA != 0 |
| * cFactor = CMM_ADDTODSPPA || cFactor = CMM_SUBFROMDSPPA |
| * Ensures: |
| * |
| */ |
| extern DSP_STATUS CMM_RegisterGPPSMSeg(struct CMM_OBJECT* hCmmMgr, |
| DWORD dwGPPBasePA, |
| ULONG ulSize, |
| DWORD dwDSPAddrOffset, |
| CMM_CNVTTYPE cFactor, |
| DWORD dwDSPBase, |
| ULONG ulDSPSize, |
| ULONG * pulSegId, |
| DWORD dwGPPBaseBA); |
| |
| /* |
| * ======== CMM_UnRegisterGPPSMSeg ======== |
| * Purpose: |
| * Unregister the given memory segment that was previously registered |
| * by CMM_RegisterGPPSMSeg. |
| * Parameters: |
| * hCmmMgr: Handle to a Cmm Mgr. |
| * ulSegId Segment identifier returned by CMM_RegisterGPPSMSeg. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Invalid handle. |
| * DSP_EINVALIDARG: Invalid ulSegId. |
| * DSP_EFAIL: Unable to unregister for unknown reason. |
| * Requires: |
| * Ensures: |
| * |
| */ |
| extern DSP_STATUS CMM_UnRegisterGPPSMSeg(struct CMM_OBJECT* hCmmMgr, |
| ULONG ulSegId); |
| |
| /* |
| * ======== CMM_XlatorAllocBuf ======== |
| * Purpose: |
| * Allocate the specified SM buffer and create a local memory descriptor. |
| * Place on the descriptor on the translator's HaQ (Host Alloc'd Queue). |
| * Parameters: |
| * hXlator: Handle to a Xlator object. |
| * pVaBuf: Virtual address ptr(client context) |
| * uPaSize: Size of SM memory to allocate. |
| * Returns: |
| * Ptr to valid physical address(Pa) of uPaSize bytes, NULL if failed. |
| * Requires: |
| * pVaBuf != 0. |
| * uPaSize != 0. |
| * Ensures: |
| * |
| */ |
| extern PVOID CMM_XlatorAllocBuf(struct CMM_XLATOROBJECT* hXlator, |
| PVOID pVaBuf, UINT uPaSize); |
| |
| /* |
| * ======== CMM_XlatorCreate ======== |
| * Purpose: |
| * Create a translator(xlator) object used for process specific Va<->Pa |
| * address translation. Node messaging and streams use this to perform |
| * inter-processor(GPP<->DSP) zero-copy data transfer. |
| * Parameters: |
| * phXlator: Address to place handle to a new Xlator handle. |
| * hCmmMgr: Handle to Cmm Mgr associated with this translator. |
| * pXlatorAttrs: Translator attributes used for the client NODE or STREAM. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EINVALIDARG: Bad input Attrs. |
| * DSP_EMEMORY: Insufficient memory(local) for requested resources. |
| * Requires: |
| * phXlator != NULL |
| * hCmmMgr != NULL |
| * pXlatorAttrs != NULL |
| * Ensures: |
| * |
| */ |
| extern DSP_STATUS CMM_XlatorCreate(OUT struct CMM_XLATOROBJECT** phXlator, |
| struct CMM_OBJECT* hCmmMgr, |
| struct CMM_XLATORATTRS *pXlatorAttrs); |
| |
| /* |
| * ======== CMM_XlatorDelete ======== |
| * Purpose: |
| * Delete translator resources |
| * Parameters: |
| * hXlator: handle to translator. |
| * bForce: bForce = TRUE will free XLators SM buffers/dscriptrs. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Bad translator handle. |
| * DSP_EFAIL: Unable to free translator resources. |
| * Requires: |
| * cRefs > 0 |
| * Ensures: |
| * |
| */ |
| extern DSP_STATUS CMM_XlatorDelete(struct CMM_XLATOROBJECT* hXlator, |
| bool bForce); |
| |
| /* |
| * ======== CMM_XlatorFreeBuf ======== |
| * Purpose: |
| * Free SM buffer and descriptor. |
| * Does not free client process VM. |
| * Parameters: |
| * hXlator: handle to translator. |
| * pBufVa Virtual address of PA to free. |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Bad translator handle. |
| * Requires: |
| * Ensures: |
| * |
| */ |
| extern DSP_STATUS CMM_XlatorFreeBuf(struct CMM_XLATOROBJECT* hXlator, |
| PVOID pBufVa); |
| |
| /* |
| * ======== CMM_XlatorInfo ======== |
| * Purpose: |
| * Set/Get process specific "translator" address info. |
| * This is used to perform fast virtaul address translation |
| * for shared memory buffers between the GPP and DSP. |
| * Parameters: |
| * hXlator: handle to translator. |
| * pAddr: Virtual base address of segment. |
| * ulSize: Size in bytes. |
| * uSegId: Segment identifier of SM segment(s) |
| * bSetInfo Set xlator fields if TRUE, else return base addr |
| * Returns: |
| * DSP_SOK: Success. |
| * DSP_EHANDLE: Bad translator handle. |
| * Requires: |
| * (cRefs > 0) |
| * (pAddr != NULL) |
| * (ulSize > 0) |
| * Ensures: |
| * |
| */ |
| extern DSP_STATUS CMM_XlatorInfo(struct CMM_XLATOROBJECT* hXlator, |
| IN OUT BYTE ** pAddr, |
| ULONG ulSize, UINT uSegId, |
| bool bSetInfo); |
| |
| /* |
| * ======== CMM_XlatorTranslate ======== |
| * Purpose: |
| * Perform address translation VA<->PA for the specified stream or |
| * message shared memory buffer. |
| * Parameters: |
| * hXlator: handle to translator. |
| * pAddr address of buffer to translate. |
| * xType Type of address xlation. CMM_PA2VA or CMM_VA2PA. |
| * Returns: |
| * Valid address on success, else NULL. |
| * Requires: |
| * cRefs > 0 |
| * pAddr != NULL |
| * xType >= CMM_VA2PA) && (xType <= CMM_DSPPA2PA) |
| * Ensures: |
| * |
| */ |
| extern PVOID CMM_XlatorTranslate(struct CMM_XLATOROBJECT* hXlator, |
| PVOID pAddr, CMM_XLATETYPE xType); |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| #endif /* CMM_ */ |
