1 /* 2 * dspbridge/mpu_api/inc/DSPNode.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 * ======== DSPNode.h ======== 20 * Description: 21 * This is the header for the DSP/BIOS Bridge node module. 22 * 23 * Public Functions: 24 * DSPNode_Allocate 25 * DSPNode_AllocMsgBuf 26 * DSPNode_ChangePriority 27 * DSPNode_Connect 28 * DSPNode_ConnectEx 29 * DSPNode_Create 30 * DSPNode_Delete 31 * DSPNode_FreeMsgBuf 32 * DSPNode_GetAttr 33 * DSPNode_GetMessage 34 * DSPNode_Pause 35 * DSPNode_PutMessage 36 * DSPNode_RegisterNotify 37 * DSPNode_Run 38 * DSPNode_Terminate 39 * 40 * Notes: 41 * 42 *! Revision History: 43 *! ================ 44 *! 23-Nov-2002 gp: Comment change: uEventMask now referred to as a "type". 45 *! Comment cleanup, correspondence to db_api.doc. 46 *! 12-Dec-2001 ag DSP_ENOTIMPL added to DSPNode_Connect(). 47 *! 11-Sep-2001 ag Added new error codes. 48 *! 23-Apr-2001 jeh Added pStatus parameter to DSPNode_Terminate. 49 *! 16-Feb-2001 jeh Added new error codes. 50 *! 13-Feb-2001 kc: DSP/BIOS Bridge name updates. 51 *! 27-Oct-2000 jeh Updated to version 0.9 API spec. 52 *! 07-Sep-2000 jeh Changed type HANDLE in DSPNode_RegisterNotify to 53 *! DSP_HNOTIFICATION. Added DSP_STRMATTR parameter to 54 *! DSPNode_Connect(). 55 *! 27-Jul-2000 rr: Updated to ver 0.8 of DSPAPI. 56 *! 27-Jun-2000 rr: Created from DBAPI.h 57 */ 58 59 #ifndef DSPNode_ 60 #define DSPNode_ 61 62 #ifdef __cplusplus 63 extern "C" { 64 #endif 65 66 /* 67 * ======== DSPNode_Allocate ======== 68 * Purpose: 69 * Allocate data structures for controlling and communicating with a node 70 * on a specific DSP processor. 71 * Parameters: 72 * hProcessor: The processor handle. 73 * pNodeID: Ptr to DSP_UUID for the node. 74 * pArgs: Ptr to optional node arguments. 75 * pAttrIn: Ptr to optional node attributes. 76 * phNode: Ptr to location to store node handle on return. 77 * Returns: 78 * DSP_SOK: Success. 79 * DSP_EPOINTER: One of the input parameters pointers is invalid. 80 * DSP_EHANDLE: Invalid processor handle. 81 * DSP_EMEMORY: Memory is not available to allocate a node 82 * DSP_EUUID: The node with the specified UUID is not registered. 83 * DSP_EWRONGSTATE: The specified processor is in the wrong state 84 * (not running) 85 * DSP_ERANGE: The iPriority field specified in pAttrIn is out 86 * of range. 87 * DSP_EFAIL: General failure. 88 */ 89 extern DBAPI 90 DSPNode_Allocate(DSP_HPROCESSOR hProcessor, 91 IN CONST struct DSP_UUID * pNodeID, 92 IN CONST OPTIONAL struct DSP_CBDATA * pArgs, 93 IN OPTIONAL struct DSP_NODEATTRIN * pAttrIn, 94 OUT DSP_HNODE * phNode); 95 96 /* 97 * ======== DSPNode_AllocMsgBuf ======== 98 * Purpose: 99 * Allocate and prepare a buffer whose descriptor will be passed to a DSP 100 * Node within a (DSP_MSG) message 101 * Parameters: 102 * hNode: The node handle. 103 * uSize: The size of the buffer (GPP bytes) to be allocated. 104 * pAttr: Pointer to a DSP_BUFFERATTR structure. 105 * pBuffer: Location to store the address of the allocated 106 * buffer on output. 107 * Returns: 108 * DSP_SOK: Success. 109 * DSP_EHANDLE: Invalid node handle. 110 * DSP_EMEMORY: Insufficent memory. 111 * DSP_EPOINTER: pBuffer is not a valid address. 112 * DSP_EFAIL: General Failure. 113 * DSP_EALIGNMENT: Alignment value not supported.(Must be 0, 1, 2, 4) 114 * DSP_EBADSEGID: Invalid Segment Id. 115 * DSP_ESIZE: Invalid Size. Must be greater than zero. 116 */ 117 extern DBAPI DSPNode_AllocMsgBuf(DSP_HNODE hNode, UINT uSize, 118 IN OPTIONAL struct DSP_BUFFERATTR * pAttr, 119 OUT BYTE ** pBuffer); 120 121 /* 122 * ======== DSPNode_ChangePriority ======== 123 * Purpose: 124 * Change a task node's runtime priority within the DSP RTOS. 125 * Parameters: 126 * hNode: The node handle. 127 * iPriority: New runtime priority level. 128 * Returns: 129 * DSP_SOK: Success. 130 * DSP_EHANDLE: Invalid node handle. 131 * DSP_ERANGE: iPriority is out of range. 132 * DSP_ENODETYPE: Operation is invalid for this node type. 133 * DSP_ETIMEOUT: A timeout occured before DSP responded. 134 * DSP_ERESTART: A critical error occurred and the DSP is being 135 * restarted. 136 * DSP_EWRONGSTATE: The node is not allocated, paused, or running. 137 * DSP_EFAIL: Unable to change the priority level. 138 */ 139 extern DBAPI DSPNode_ChangePriority(DSP_HNODE hNode, INT iPriority); 140 141 /* 142 * ======== DSPNode_Connect ======== 143 * Purpose: 144 * Make a stream connection, either between two nodes on a DSP, 145 * or between a node on a DSP and the GPP. 146 * Parameters: 147 * hNode: The first node handle. 148 * uStream: Output stream index on first node (0 based). 149 * hOtherNode: The second node handle. 150 * uOtherStream: Input stream index on second node (0 based). 151 * pAttrs: Stream attributes. If NULL, defaults used. 152 * Returns: 153 * DSP_SOK: Success. 154 * DSP_EHANDLE: Invalid node handle. 155 * DSP_EMEMORY: GPP memory allocation failure. 156 * DSP_EALREADYCONNCECTED: One of the specified connections has already 157 * been made. 158 * DSP_EWRONGSTATE: The node is not in the NODE_ALLOCATED state. 159 * DSP_EVALUE: A Stream index is not valid. 160 * DSP_ENOMORECONNECTIONS: No more connections are allowed 161 * DSP_EFAIL: Unable to make connection. 162 * DSP_ENOTIMPL: Stream mode valid but not supported. 163 * DSP_ESTRMMODE Illegal Stream mode specified. 164 * 165 */ 166 extern DBAPI DSPNode_Connect(DSP_HNODE hNode, UINT uStream, 167 DSP_HNODE hOtherNode, UINT uOtherStream, 168 IN OPTIONAL struct DSP_STRMATTR * pAttr); 169 170 /* 171 * ======== DSPNode_ConnectEx ======== 172 * Purpose: 173 * Make a stream connection, either between two nodes on a DSP, 174 * or between a node on a DSP and the GPP. 175 * Parameters: 176 * hNode: The first node handle. 177 * uStream: Output stream index on first node (0 based). 178 * hOtherNode: The second node handle. 179 * uOtherStream: Input stream index on second node (0 based). 180 * pAttrs: Stream attributes. If NULL, defaults used. 181 * pConnParam: A pointer to a DSP_CBDATA structure that defines 182 * connection parameter for device nodes to pass to DSP side. 183 * If the value of this parameter is NULL, then this API behaves 184 * like DSPNode_Connect. This parameter will have length of the 185 * string and the null terminated string in DSP_CBDATA struct. 186 * This can be extended in future to pass binary data. 187 * 188 * Returns: 189 * DSP_SOK: Success. 190 * DSP_EHANDLE: Invalid node handle. 191 * DSP_EMEMORY: GPP memory allocation failure. 192 * DSP_EALREADYCONNCECTED: One of the specified connections has already 193 * been made. 194 * DSP_EWRONGSTATE: The node is not in the NODE_ALLOCATED state. 195 * DSP_EVALUE: A Stream index is not valid. 196 * DSP_ENOMORECONNECTIONS: No more connections are allowed 197 * DSP_EFAIL: Unable to make connection. 198 * DSP_ENOTIMPL: Stream mode valid but not supported. 199 * DSP_ESTRMMODE Illegal Stream mode specified. 200 * 201 */ 202 extern DBAPI DSPNode_ConnectEx(DSP_HNODE hNode, UINT uStream, 203 DSP_HNODE hOtherNode, UINT uOtherStream, 204 IN OPTIONAL struct DSP_STRMATTR * pAttr, 205 IN OPTIONAL struct DSP_CBDATA * pConnParam); 206 207 /* 208 * ======== DSPNode_Create ======== 209 * Purpose: 210 * Create a node in a pre-run (i.e., inactive) state on its DSP processor. 211 * Parameters: 212 * hNode: The node handle. 213 * Returns: 214 * DSP_SOK: Success. 215 * DSP_EHANDLE: Invalid node handle. 216 * DSP_ESYMBOL: Create function, or iAlg, not found in the COFF file 217 * DSP_WRONGSTATE: Operation is invalid for the current node state. 218 * DSP_ETASK: Unable to create the task or process on the DSP. 219 * DSP_EMEMORY: Memory Allocation failure on the DSP. 220 * DSP_ERESOURCE: A requested resource is not available. 221 * DSP_EMULINST: Multiple instances are not allowed. 222 * DSP_ENOTFOUND: A specified entity was not found. 223 * DSP_EOUTOFIO: An I/O resource is not available. 224 * DSP_ESTREAM: Stream creation failure on the DSP. 225 * DSP_ETIMEOUT: A timeout occurred before the DSP responded. 226 * DSP_ERESTART: A critical error has occurred and the DSP is 227 * being restarted. 228 * DSP_EOVERLAYMEMORY: Overlay region for this phase in use by another node 229 * DSP_EUSER1-16: A node-specific failure occurred on the DSP. 230 * DSP_EFAIL: Unable to Create the node. 231 * Details: 232 */ 233 234 extern DBAPI DSPNode_Create(DSP_HNODE hNode); 235 236 /* 237 * ======== DSPNode_Delete ======== 238 * Purpose: 239 * Delete all DSP-side and GPP-side resources for the node. 240 * Parameters: 241 * hNode: The node handle. 242 * Returns: 243 * DSP_SOK: Success. 244 * DSP_EHANDLE: Invalid node handle. 245 * DSP_EDELETE: A Deletion failure occured. 246 * DSP_EFREE: A DSP memory free operation failed. 247 * DSP_EIOFREE: A DSP I/O free operation failed. 248 * DSP_ETIMEOUT: Timeout occured before the DSP responded. 249 * DSP_ERESTART: A critical error has occurred and the DSP is 250 * being restarted. 251 * DSP_EUSER1-16: A node-specific failure occurred on the DSP. 252 * DSP_EOVERLAYMEMORY: Overlay region for this phase in use by another node 253 * DSP_EFAIL: Unable to delete the node. 254 * DSP_ESYMBOL: Delete function not found in the COFF file. 255 */ 256 extern DBAPI DSPNode_Delete(DSP_HNODE hNode); 257 258 /* 259 * ======== DSPNode_FreeMsgBuf ======== 260 * Purpose: 261 * Free a message buffer previously allocated by DSPNode_AllocMsgBuf.. 262 * Parameters: 263 * hNode: The node handle. 264 * pBuffer: (Address) Buffer allocated by DSP_AllocMsgBuf. 265 * pAttr: Same buffer attributes passed to DSP_AllocMsgBuf. 266 * Returns: 267 * DSP_SOK: Success. 268 * DSP_EHANDLE: Invalid node handle. 269 * DSP_EPOINTER: pBuffer is not valid. 270 * DSP_EBADSEGID: Invalid Segment Id. 271 * DSP_EFAIL: Failure to free the buffer. 272 */ 273 extern DBAPI DSPNode_FreeMsgBuf(DSP_HNODE hNode, IN BYTE * pBuffer, 274 IN OPTIONAL struct DSP_BUFFERATTR * pAttr); 275 276 /* 277 * ======== DSPNode_GetAttr ======== 278 * Purpose: 279 * Copy the current attributes of the specified node. 280 * Parameters: 281 * hNode: The node handle. 282 * pAttr: Location to store the node attributes. 283 * uAttrSize: The size of structure. 284 * Returns: 285 * DSP_SOK: Success. 286 * DSP_EHANDLE: Invalid node handle. 287 * DSP_EPOINTER: Parameter pAttr is not valid. 288 * DSP_EFAIL: Unable to retrieve node attributes. 289 * DSP_ESIZE: The size of the specified DSP_NODEATTR structure 290 * is too small to hold all node information. 291 */ 292 extern DBAPI DSPNode_GetAttr(DSP_HNODE hNode, 293 OUT struct DSP_NODEATTR * pAttr, UINT uAttrSize); 294 295 /* 296 * ======== DSPNode_GetMessage ======== 297 * Purpose: 298 * Retrieve an event message from a task node. 299 * Parameters: 300 * hNode: The node handle. 301 * pMessage: The message structure. 302 * uTimeout: Timeout to wait for message. 303 * Returns: 304 * DSP_SOK: Success. 305 * DSP_EHANDLE: Invalid node handle. 306 * DSP_EPOINTER: Parameter pMessage is not valid. 307 * DSP_ENODETYPE: Messages cannot be retrieved from this type of 308 * node (eg a device node). 309 * DSP_ETIMEOUT: A timeout occurred and there is no message ready. 310 * DSP_ERESTART: A critical error has occurred and the DSP is 311 * being restarted. 312 * DSP_EFAIL: An error occurred trying to retrieve a message. 313 * DSP_ETRANSLATE Message contains a shared memory buffer and unable 314 * to map buffer to process. 315 */ 316 extern DBAPI DSPNode_GetMessage(DSP_HNODE hNode, OUT struct DSP_MSG * pMessage, 317 UINT uTimeout); 318 319 /* 320 * ======== DSPNode_Pause ======== 321 * Purpose: 322 * Temporarily suspend execution of a task node that is 323 * currently running on a DSP. 324 * Parameters: 325 * hNode: The node handle. 326 * Returns: 327 * DSP_SOK: Success. 328 * DSP_EHANDLE: Invalid node handle. 329 * DSP_ENODETYPE: Invalid operation for this node type. 330 * DSP_ETIMEOUT: A timeout occured before the DSP responded. 331 * DSP_EWRONGSTATE: Operation is invalid for the current node state. 332 * DSP_ERESTART: A critical error has occurred and the DSP is 333 * being restarted. 334 * DSP_EFAIL: General failure. 335 */ 336 extern DBAPI DSPNode_Pause(DSP_HNODE hNode); 337 338 /* 339 * ======== DSPNode_PutMessage ======== 340 * Purpose: 341 * Send an event message to a task node. 342 * Parameters: 343 * hNode: The node handle. 344 * pMessage: The message structure. 345 * uTimeout: Timeout (msecs) waiting for message to be queued. 346 * Returns: 347 * DSP_SOK: Success. 348 * DSP_EHANDLE: Invalid node handle. 349 * DSP_EPOINTER: Parameter pMessage is not valid. 350 * DSP_ENODETYPE: Invalid operation for this node type 351 * DSP_EWRONGSTATE: Node is in an invalid state to send a message. 352 * DSP_ETIMEOUT: Time out occured. 353 * DSP_ERESTART: A critical error has occurred and the DSP is 354 * being restarted. 355 * DSP_ETRANSLATE The shared memory buffer contained in the message 356 * could not be mapped into the clients address space. 357 * DSP_EFAIL: General failure. 358 */ 359 extern DBAPI DSPNode_PutMessage(DSP_HNODE hNode, 360 IN CONST struct DSP_MSG * pMessage, 361 UINT uTimeout); 362 363 /* 364 * ======== DSPNode_RegisterNotify ======== 365 * Purpose: 366 * Register to be notified of specific events for this node. 367 * Parameters: 368 * hNode: The node handle. 369 * uEventMask: Type of event about which to be notified. 370 * uNotifyType: Type of notification to be sent. 371 * hNotification: Handle of DSP_NOTIFICATION object. 372 * Returns: 373 * DSP_SOK: Success. 374 * DSP_EHANDLE: Invalid node handle or hNotification. 375 * DSP_EVALUE: Invalid uEventMask. 376 * DSP_ENOTIMP: The specifed uNotifyType is not supported. 377 * DSP_EFAIL: Unable to register for notification. 378 */ 379 extern DBAPI DSPNode_RegisterNotify(DSP_HNODE hNode, UINT uEventMask, 380 UINT uNotifyType, 381 struct DSP_NOTIFICATION* hNotification); 382 383 /* 384 * ======== DSPNode_Run ======== 385 * Purpose: 386 * Start a node running, or resume execution of a previously paused node. 387 * Parameters: 388 * hNode: The node handle. 389 * Returns: 390 * DSP_SOK: Success. 391 * DSP_EHANDLE: Invalid node handle. 392 * DSP_ENODETYPE: Invalid operation for this type of node. 393 * DSP_ESYMBOL: Execute function not found in the COFF file. 394 * DSP_EWRONGSTATE: The node is not in the Created or Paused state. 395 * DSP_ETIMEOUT: A timeout occured before the DSP responded. 396 * DSP_ERESTART: A critical error has occurred and the DSP is 397 * being restarted. 398 * DSP_EOVERLAYMEMORY: Overlay region for this phase in use by another node 399 * DSP_EFAIL: Unable to start or resume execution. 400 */ 401 extern DBAPI DSPNode_Run(DSP_HNODE hNode); 402 403 /* 404 * ======== DSPNode_Terminate ======== 405 * Purpose: 406 * Signal a task or xDAIS socket node running on a DSP processor that 407 * it should exit its execute-phase function. 408 * Parameters: 409 * hNode: Handle of node to terminate. 410 * pStatus: Location to execute-phase function return value. 411 * Possible values are between DSP_EUSER1-16. 412 * Returns: 413 * DSP_SOK: Success. 414 * DSP_EHANDLE: Invalid node handle. 415 * DSP_ENODETYPE: Invalid operation for this type of node. 416 * DSP_EWRONGSTATE: The node is not in the Created or Paused state. 417 * DSP_ETIMEOUT: A timeout occured before the DSP responded. 418 * DSP_ERESTART: A critical error has occurred and the DSP is 419 * being restarted. 420 * DSP_EFAIL: Unable to Terminate the node. 421 */ 422 extern DBAPI DSPNode_Terminate(DSP_HNODE hNode, DSP_STATUS * pStatus); 423 424 425 426 /* 427 * ======== DSPNode_GetUUIDProps ======== 428 * Purpose: 429 * Fetch the Node Properties from the DCD/DOF file, give the UUID 430 * Parameters: 431 * hProcessor: The processor handle. 432 * pNodeID: Ptr to DSP_UUID for the node. 433 * pNodeProps: Ptr to location to store node properties. 434 * Returns: 435 * DSP_SOK: Success. 436 * DSP_EPOINTER: One of the input parameters pointers is invalid. 437 * DSP_EHANDLE: Invalid processor handle. 438 * DSP_EMEMORY: Memory is not available to allocate a node 439 * DSP_EUUID: The node with the specified UUID is not registered. 440 * DSP_EWRONGSTATE: The specified processor is in the wrong state 441 * (not running) 442 * DSP_ERANGE: The iPriority field specified in pAttrIn is out 443 * of range. 444 * DSP_EFAIL: General failure. 445 */ 446 extern DBAPI DSPNode_GetUUIDProps(DSP_HPROCESSOR hProcessor, 447 IN CONST struct DSP_UUID * pNodeID, 448 OUT struct DSP_NDBPROPS * pNodeProps); 449 #ifdef __cplusplus 450 } 451 #endif 452 #endif /* DSPNode_ */ 453