1 /* 2 * dspbridge/mpu_api/inc/DSPProcessor.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 /* 20 * ======== DSPProcessor.h ======== 21 * Description: 22 * This is the header for the DSP/BIOS Bridge processor module. 23 * 24 * Public Functions: 25 * DSPProcessor_Attach 26 * DSPProcessor_Detach 27 * DSPProcessor_EnumNodes 28 * DSPProcessor_FlushMemory 29 * DSPProcessor_GetResourceInfo 30 * DSPProcessor_GetState 31 * DSPProcessor_Map 32 * DSPProcessor_RegisterNotify 33 * DSPProcessor_ReserveMemory 34 * DSPProcessor_UnMap 35 * DSPProcessor_UnReserveMemory 36 * DSPProcessor_InvalidateMemory 37 38 * Notes: 39 * 40 *! Revision History: 41 *! ================ 42 *! 04-04-2007 sh Added DSPProcessor_InvalidateMemory 43 *! 19-Apr-2004 sb Aligned DMM definitions with Symbian 44 *! 08-Mar-2004 sb Added the Dynamic Memory Mapping APIs 45 *! 23-Nov-2002 gp: Comment cleanup. 46 *! 13-Feb-2001 kc: DSP/BIOS Bridge name updates. 47 *! 29-Nov-2000 rr: OEM Fxns moved to DSPProcessor_OEM.h 48 *! Incorporated code review changes. 49 *! 27-Oct-2000 jeh Changed uNotifyMask to uNotifyType. 50 *! 28-Sep-2000 rr: Updated to Version 0.9. 51 *! 07-Sep-2000 jeh Changed type HANDLE in DSPProcessor_RegisterNotify to 52 *! DSP_HNOTIFICATION. 53 *! 14-Aug-2000 rr: Cleaned up. 54 *! 20-Jul-2000 rr: Updated to Version 0.8 55 *! 27-Jun-2000 rr: Created from DBAPI.h 56 */ 57 58 #ifndef DSPPROCESSOR_ 59 #define DSPPROCESSOR_ 60 61 #ifdef __cplusplus 62 extern "C" { 63 #endif 64 65 /* 66 * ======== DSPProcessor_Attach ======== 67 * Purpose: 68 * Prepare for communication with a particular DSP processor, and return 69 * a processor handle for subsequent operations. 70 * Parameters: 71 * uProcessor: The processor index. 72 * pAttrIn: Ptr to the DSP_PROCESSORATTRIN structure. 73 * A NULL value means use default values. 74 * phProcessor: Ptr to location to store processor handle. 75 * Returns: 76 * DSP_SOK: Success. 77 * DSP_EPOINTER: Parameter phProcessor is not valid. 78 * DSP_EINVALIDARG: Parameter uProcessor is invalid 79 * DSP_EFAIL: Unable to attach the processor 80 * DSP_SALREADYATTACHED: Success; Processor already attached. 81 * Details: 82 * Returns DSP_EINVALIDARG if uProcessor index >= number of processors. 83 * When pAttrIn is NULL, the default timeout value is 10 seconds. 84 * This call does not affect the actual execution state of the DSP. 85 */ 86 extern DBAPI DSPProcessor_Attach(UINT uProcessor, 87 OPTIONAL CONST struct DSP_PROCESSORATTRIN * 88 pAttrIn, 89 OUT DSP_HPROCESSOR * phProcessor); 90 91 /* 92 * ======== DSPProcessor_Detach ======== 93 * Purpose: 94 * Detach from a DSP processor and de-allocate all (GPP) resources reserved 95 * for it. 96 * Parameters: 97 * hProcessor: The processor handle. 98 * Returns: 99 * DSP_SOK: Success. 100 * DSP_EHANDLE: Invalid processor handle. 101 * DSP_EFAIL: Unable to detach from the processor. 102 * Details: 103 * This call does not affect the actual execution state of the DSP. 104 */ 105 extern DBAPI DSPProcessor_Detach(DSP_HPROCESSOR hProcessor); 106 107 /* 108 * ======== DSPProcessor_EnumNodes ======== 109 * Purpose: 110 * Enumerate the nodes currently allocated on a processor. 111 * Parameters: 112 * hProcessor: The processor handle. 113 * aNodeTab: An array allocated to receive the node handles. 114 * uNodeTabSize: The number of (DSP_HNODE) handles that can be held 115 * in aNodeTab. 116 * puNumNodes: Location where DSPProcessor_EnumNodes will return 117 * the number of valid handles written to aNodeTab 118 * puAllocated: Location where DSPProcessor_EnumNodes will return 119 * the number of nodes that are allocated on the DSP. 120 * Returns: 121 * DSP_SOK: Success. 122 * DSP_EHANDLE: Invalid processor handle. 123 * DSP_EPOINTER: Parameters puNumNodes or puAllocated is not valid 124 * DSP_ESIZE: The amount of memory allocated for aNodeTab is 125 * insufficent. The number of nodes actually 126 * allocated on the DSP is greater than the value 127 * specified for uNodeTabSize. 128 * DSP_EFAIL: A failure occurred during enumeration. 129 * Details: 130 */ 131 extern DBAPI DSPProcessor_EnumNodes(DSP_HPROCESSOR hProcessor, 132 IN DSP_HNODE * aNodeTab, 133 IN UINT uNodeTabSize, 134 OUT UINT * puNumNodes, 135 OUT UINT * puAllocated); 136 137 /* 138 * ======== DSPProcessor_FlushMemory ======== 139 * Purpose: 140 * Flushes a buffer from the MPU data cache. 141 * Parameters: 142 * hProcessor : The processor handle. 143 * pMpuAddr : Buffer start address 144 * ulSize : Buffer size 145 * ulFlags : Reserved. 146 * Returns: 147 * DSP_SOK : Success. 148 * DSP_EHANDLE : Invalid processor handle. 149 * DSP_EFAIL : General failure. 150 * Requires: 151 * PROC Initialized. 152 * Ensures: 153 * Details: 154 * All the arguments are currently ignored. 155 */ 156 extern DBAPI DSPProcessor_FlushMemory(DSP_HPROCESSOR hProcessor, 157 PVOID pMpuAddr, 158 ULONG ulSize, ULONG ulFlags); 159 160 /* 161 * ======== DSPProcessor_InvalidateMemory ======== 162 * Purpose: 163 * Invalidates a buffer from the MPU data cache. 164 * Parameters: 165 * hProcessor : The processor handle. 166 * pMpuAddr : Buffer start address 167 * ulSize : Buffer size 168 * Returns: 169 * DSP_SOK : Success. 170 * DSP_EHANDLE : Invalid processor handle. 171 * DSP_EFAIL : General failure. 172 * Requires: 173 * PROC Initialized. 174 * Ensures: 175 * Details: 176 */ 177 extern DBAPI DSPProcessor_InvalidateMemory(DSP_HPROCESSOR hProcessor, 178 PVOID pMpuAddr, 179 ULONG ulSize); 180 181 /* 182 * ======== DSPProcessor_GetResourceInfo ======== 183 * Purpose: 184 * Get information about a DSP Resources. 185 * Parameters: 186 * hProcessor: The processor handle. 187 * uResourceType: Type of resource to be reported. 188 * pResourceInfo: Ptr to the DSP_RESOURCEINFO structure in which 189 * the processor resource information will be returned. 190 * uResourceInfoSize: Size of the DSP_RESOURCEINFO structure. 191 * Returns: 192 * DSP_SOK: Success. 193 * DSP_EHANDLE: Invalid processor handle. 194 * DSP_EPOINTER: Parameter pResourceInfo is not valid 195 * DSP_EVALUE: Parameter uResourceType is invalid. 196 * DSP_EWRONGSTATE: The processor is not in the PROC_RUNNING state. 197 * DSP_ETIMEOUT: A timeout occured before the DSP responded to the 198 * querry. 199 * DSP_ERESTART: A Critical error has occured and the DSP is being 200 * restarted. 201 * DSP_ESIZE: The size of the specified DSP_RESOURCEINFO struct 202 * is too small to hold all the information. 203 * DSP_EFAIL: Unable to get Resource Information 204 * Details: 205 */ 206 extern DBAPI DSPProcessor_GetResourceInfo(DSP_HPROCESSOR hProcessor, 207 UINT uResourceType, 208 OUT struct DSP_RESOURCEINFO * 209 pResourceInfo, 210 UINT uResourceInfoSize); 211 212 /* 213 * ======== DSPProcessor_GetState ======== 214 * Purpose: 215 * Report the state of the specified DSP processor. 216 * Parameters: 217 * hProcessor: The processor handle. 218 * pProcStatus: Ptr to location to store the DSP_PROCESSORSTATE 219 * structure. 220 * uStateInfoSize: Size of DSP_PROCESSORSTATE. 221 * Returns: 222 * DSP_SOK: Success. 223 * DSP_EHANDLE: Invalid processor handle. 224 * DSP_EPOINTER: Parameter pProcStatus is not valid. 225 * DSP_EFAIL: General failure while querying processor state. 226 * DSP_ESIZE: uStateInfoSize is smaller than sizeof 227 * DSP_PROCESSORSTATE. 228 * Details: 229 */ 230 extern DBAPI DSPProcessor_GetState(DSP_HPROCESSOR hProcessor, 231 OUT struct DSP_PROCESSORSTATE * pProcStatus, 232 UINT uStateInfoSize); 233 234 /* 235 * ======== DSPProcessor_Map ======== 236 * Purpose: 237 * Maps a MPU buffer to DSP address space. 238 * Parameters: 239 * hProcessor : The processor handle. 240 * pMpuAddr : Starting address of the memory region to map. 241 * ulSize : Size of the memory region to map. 242 * pReqAddr : Requested DSP start address. Offset-adjusted actual 243 * mapped address is in the last argument. 244 * ppMapAddr : Ptr to DSP side mapped BYTE address. 245 * ulMapAttr : Optional endianness attributes, virt to phys flag. 246 * Returns: 247 * DSP_SOK : Success. 248 * DSP_EHANDLE : Invalid processor handle. 249 * DSP_EFAIL : General failure. 250 * DSP_EMEMORY : MPU side memory allocation error. 251 * DSP_ENOTFOUND : Cannot find a reserved region starting with this 252 * : address. 253 * Requires: 254 * pMpuAddr is not NULL 255 * ulSize is not zero 256 * ppMapAddr is not NULL 257 * PROC Initialized. 258 * Ensures: 259 * Details: 260 */ 261 extern DBAPI DSPProcessor_Map(DSP_HPROCESSOR hProcessor, 262 PVOID pMpuAddr, 263 ULONG ulSize, 264 PVOID pReqAddr, 265 PVOID * ppMapAddr, ULONG ulMapAttr); 266 267 /* 268 * ======== DSPProcessor_RegisterNotify ======== 269 * Purpose: 270 * Register to be notified of specific processor events 271 * Parameters: 272 * hProcessor: The processor handle. 273 * uEventMask: Type of event to be notified about. 274 * uNotifyType: Type of notification to be sent. 275 * hNotification: Handle or event name to be used for notification. 276 * about, or to de-register this notification. 277 * Returns: 278 * DSP_SOK: Success. 279 * DSP_EHANDLE: Invalid processor handle or hNotification. 280 * DSP_EVALUE: Parameter uEventMask is Invalid 281 * DSP_ENOTIMP: The notification type specified in uNotifyType 282 * is not supported. 283 * DSP_EFAIL: Unable to register for notification. 284 * Details: 285 */ 286 extern DBAPI DSPProcessor_RegisterNotify(DSP_HPROCESSOR hProcessor, 287 UINT uEventMask, 288 UINT uNotifyType, 289 struct DSP_NOTIFICATION* 290 hNotification); 291 292 /* 293 * ======== DSPProcessor_ReserveMemory ======== 294 * Purpose: 295 * Reserve a virtually contiguous region of DSP address space. 296 * Parameters: 297 * hProcessor : The processor handle. 298 * ulSize : Size of the address space to reserve. 299 * ppRsvAddr : Ptr to DSP side reserved BYTE address. 300 * Returns: 301 * DSP_SOK : Success. 302 * DSP_EHANDLE : Invalid processor handle. 303 * DSP_EFAIL : General failure. 304 * DSP_EMEMORY : Cannot reserve chunk of this size. 305 * Requires: 306 * ppRsvAddr is not NULL 307 * PROC Initialized. 308 * Ensures: 309 * Details: 310 */ 311 extern DBAPI DSPProcessor_ReserveMemory(DSP_HPROCESSOR hProcessor, 312 ULONG ulSize, 313 PVOID * ppRsvAddr); 314 315 /* 316 * ======== DSPProcessor_UnMap ======== 317 * Purpose: 318 * Removes a MPU buffer mapping from the DSP address space. 319 * Parameters: 320 * hProcessor : The processor handle. 321 * pMapAddr : Starting address of the mapped memory region. 322 * Returns: 323 * DSP_SOK : Success. 324 * DSP_EHANDLE : Invalid processor handle. 325 * DSP_EFAIL : General failure. 326 * DSP_ENOTFOUND : Cannot find a mapped region starting with this 327 * : address. 328 * Requires: 329 * pMapAddr is not NULL 330 * PROC Initialized. 331 * Ensures: 332 * Details: 333 */ 334 extern DBAPI DSPProcessor_UnMap(DSP_HPROCESSOR hProcessor, 335 PVOID pMapAddr); 336 337 /* 338 * ======== DSPProcessor_UnReserveMemory ======== 339 * Purpose: 340 * Frees a previously reserved region of DSP address space. 341 * Parameters: 342 * hProcessor : The processor handle. 343 * pRsvAddr : Ptr to DSP side reservedBYTE address. 344 * Returns: 345 * DSP_SOK : Success. 346 * DSP_EHANDLE : Invalid processor handle. 347 * DSP_EFAIL : General failure. 348 * DSP_ENOTFOUND : Cannot find a reserved region starting with this 349 * : address. 350 * Requires: 351 * pRsvAddr is not NULL 352 * PROC Initialized. 353 * Ensures: 354 * Details: 355 */ 356 extern DBAPI DSPProcessor_UnReserveMemory(DSP_HPROCESSOR hProcessor, 357 PVOID pRsvAddr); 358 359 #ifdef __cplusplus 360 } 361 #endif 362 #endif /* DSPPROCESSOR_ */ 363