1 /* 2 * proc.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * This is the DSP API RM module interface. 7 * 8 * Copyright (C) 2005-2006 Texas Instruments, Inc. 9 * 10 * This package is free software; you can redistribute it and/or modify 11 * it under the terms of the GNU General Public License version 2 as 12 * published by the Free Software Foundation. 13 * 14 * THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR 15 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED 16 * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. 17 */ 18 19 #ifndef PROC_ 20 #define PROC_ 21 22 #include <dspbridge/cfgdefs.h> 23 #include <dspbridge/devdefs.h> 24 #include <dspbridge/drv.h> 25 26 extern char *iva_img; 27 28 /* 29 * ======== proc_attach ======== 30 * Purpose: 31 * Prepare for communication with a particular DSP processor, and return 32 * a handle to the processor object. The PROC Object gets created 33 * Parameters: 34 * processor_id : The processor index (zero-based). 35 * hmgr_obj : Handle to the Manager Object 36 * attr_in : Ptr to the dsp_processorattrin structure. 37 * A NULL value means use default values. 38 * ph_processor : Ptr to location to store processor handle. 39 * Returns: 40 * 0 : Success. 41 * -EPERM : General failure. 42 * -EFAULT : Invalid processor handle. 43 * 0: Success; Processor already attached. 44 * Requires: 45 * ph_processor != NULL. 46 * PROC Initialized. 47 * Ensures: 48 * -EPERM, and *ph_processor == NULL, OR 49 * Success and *ph_processor is a Valid Processor handle OR 50 * 0 and *ph_processor is a Valid Processor. 51 * Details: 52 * When attr_in is NULL, the default timeout value is 10 seconds. 53 */ 54 extern int proc_attach(u32 processor_id, 55 const struct dsp_processorattrin 56 *attr_in, void **ph_processor, 57 struct process_context *pr_ctxt); 58 59 /* 60 * ======== proc_auto_start ========= 61 * Purpose: 62 * A Particular device gets loaded with the default image 63 * if the AutoStart flag is set. 64 * Parameters: 65 * hdev_obj : Handle to the Device 66 * Returns: 67 * 0 : On Successful Loading 68 * -ENOENT : No DSP exec file found. 69 * -EPERM : General Failure 70 * Requires: 71 * hdev_obj != NULL. 72 * dev_node_obj != NULL. 73 * PROC Initialized. 74 * Ensures: 75 */ 76 extern int proc_auto_start(struct cfg_devnode *dev_node_obj, 77 struct dev_object *hdev_obj); 78 79 /* 80 * ======== proc_ctrl ======== 81 * Purpose: 82 * Pass control information to the GPP device driver managing the DSP 83 * processor. This will be an OEM-only function, and not part of the 84 * 'Bridge application developer's API. 85 * Parameters: 86 * hprocessor : The processor handle. 87 * dw_cmd : Private driver IOCTL cmd ID. 88 * pargs : Ptr to an driver defined argument structure. 89 * Returns: 90 * 0 : SUCCESS 91 * -EFAULT : Invalid processor handle. 92 * -ETIME: A Timeout Occurred before the Control information 93 * could be sent. 94 * -EPERM : General Failure. 95 * Requires: 96 * PROC Initialized. 97 * Ensures 98 * Details: 99 * This function Calls bridge_dev_ctrl. 100 */ 101 extern int proc_ctrl(void *hprocessor, 102 u32 dw_cmd, struct dsp_cbdata *arg); 103 104 /* 105 * ======== proc_detach ======== 106 * Purpose: 107 * Close a DSP processor and de-allocate all (GPP) resources reserved 108 * for it. The Processor Object is deleted. 109 * Parameters: 110 * pr_ctxt : The processor handle. 111 * Returns: 112 * 0 : Success. 113 * -EFAULT : InValid Handle. 114 * -EPERM : General failure. 115 * Requires: 116 * PROC Initialized. 117 * Ensures: 118 * PROC Object is destroyed. 119 */ 120 extern int proc_detach(struct process_context *pr_ctxt); 121 122 /* 123 * ======== proc_enum_nodes ======== 124 * Purpose: 125 * Enumerate the nodes currently allocated on a processor. 126 * Parameters: 127 * hprocessor : The processor handle. 128 * node_tab : The first Location of an array allocated for node 129 * handles. 130 * node_tab_size: The number of (DSP_HNODE) handles that can be held 131 * to the memory the client has allocated for node_tab 132 * pu_num_nodes : Location where DSPProcessor_EnumNodes will return 133 * the number of valid handles written to node_tab 134 * pu_allocated : Location where DSPProcessor_EnumNodes will return 135 * the number of nodes that are allocated on the DSP. 136 * Returns: 137 * 0 : Success. 138 * -EFAULT : Invalid processor handle. 139 * -EINVAL : The amount of memory allocated for node_tab is 140 * insufficent. That is the number of nodes actually 141 * allocated on the DSP is greater than the value 142 * specified for node_tab_size. 143 * -EPERM : Unable to get Resource Information. 144 * Details: 145 * Requires 146 * pu_num_nodes is not NULL. 147 * pu_allocated is not NULL. 148 * node_tab is not NULL. 149 * PROC Initialized. 150 * Ensures: 151 * Details: 152 */ 153 extern int proc_enum_nodes(void *hprocessor, 154 void **node_tab, 155 u32 node_tab_size, 156 u32 *pu_num_nodes, 157 u32 *pu_allocated); 158 159 /* 160 * ======== proc_get_resource_info ======== 161 * Purpose: 162 * Enumerate the resources currently available on a processor. 163 * Parameters: 164 * hprocessor : The processor handle. 165 * resource_type: Type of resource . 166 * resource_info: Ptr to the dsp_resourceinfo structure. 167 * resource_info_size: Size of the structure. 168 * Returns: 169 * 0 : Success. 170 * -EFAULT : Invalid processor handle. 171 * -EBADR: The processor is not in the PROC_RUNNING state. 172 * -ETIME: A timeout occurred before the DSP responded to the 173 * querry. 174 * -EPERM : Unable to get Resource Information 175 * Requires: 176 * resource_info is not NULL. 177 * Parameter resource_type is Valid.[TBD] 178 * resource_info_size is >= sizeof dsp_resourceinfo struct. 179 * PROC Initialized. 180 * Ensures: 181 * Details: 182 * This function currently returns 183 * -ENOSYS, and does not write any data to the resource_info struct. 184 */ 185 extern int proc_get_resource_info(void *hprocessor, 186 u32 resource_type, 187 struct dsp_resourceinfo 188 *resource_info, 189 u32 resource_info_size); 190 191 /* 192 * ======== proc_get_dev_object ========= 193 * Purpose: 194 * Returns the DEV Hanlde for a given Processor handle 195 * Parameters: 196 * hprocessor : Processor Handle 197 * device_obj : Location to store the DEV Handle. 198 * Returns: 199 * 0 : Success; *device_obj has Dev handle 200 * -EPERM : Failure; *device_obj is zero. 201 * Requires: 202 * device_obj is not NULL 203 * PROC Initialized. 204 * Ensures: 205 * 0 : *device_obj is not NULL 206 * -EPERM : *device_obj is NULL. 207 */ 208 extern int proc_get_dev_object(void *hprocessor, 209 struct dev_object **device_obj); 210 211 /* 212 * ======== proc_get_state ======== 213 * Purpose: 214 * Report the state of the specified DSP processor. 215 * Parameters: 216 * hprocessor : The processor handle. 217 * proc_state_obj : Ptr to location to store the dsp_processorstate 218 * structure. 219 * state_info_size: Size of dsp_processorstate. 220 * Returns: 221 * 0 : Success. 222 * -EFAULT : Invalid processor handle. 223 * -EPERM : General failure while querying processor state. 224 * Requires: 225 * proc_state_obj is not NULL 226 * state_info_size is >= than the size of dsp_processorstate structure. 227 * PROC Initialized. 228 * Ensures: 229 * Details: 230 */ 231 extern int proc_get_state(void *hprocessor, struct dsp_processorstate 232 *proc_state_obj, u32 state_info_size); 233 234 /* 235 * ======== PROC_GetProcessorID ======== 236 * Purpose: 237 * Report the state of the specified DSP processor. 238 * Parameters: 239 * hprocessor : The processor handle. 240 * proc_id : Processor ID 241 * 242 * Returns: 243 * 0 : Success. 244 * -EFAULT : Invalid processor handle. 245 * -EPERM : General failure while querying processor state. 246 * Requires: 247 * proc_state_obj is not NULL 248 * state_info_size is >= than the size of dsp_processorstate structure. 249 * PROC Initialized. 250 * Ensures: 251 * Details: 252 */ 253 extern int proc_get_processor_id(void *proc, u32 * proc_id); 254 255 /* 256 * ======== proc_get_trace ======== 257 * Purpose: 258 * Retrieve the trace buffer from the specified DSP processor. 259 * Parameters: 260 * hprocessor : The processor handle. 261 * pbuf : Ptr to buffer to hold trace output. 262 * max_size : Maximum size of the output buffer. 263 * Returns: 264 * 0 : Success. 265 * -EFAULT : Invalid processor handle. 266 * -EPERM : General failure while retireving processor trace 267 * Buffer. 268 * Requires: 269 * pbuf is not NULL 270 * max_size is > 0. 271 * PROC Initialized. 272 * Ensures: 273 * Details: 274 */ 275 extern int proc_get_trace(void *hprocessor, u8 * pbuf, u32 max_size); 276 277 /* 278 * ======== proc_load ======== 279 * Purpose: 280 * Reset a processor and load a new base program image. 281 * This will be an OEM-only function. 282 * Parameters: 283 * hprocessor: The processor handle. 284 * argc_index: The number of Arguments(strings)in the aArgV[] 285 * user_args: An Array of Arguments(Unicode Strings) 286 * user_envp: An Array of Environment settings(Unicode Strings) 287 * Returns: 288 * 0: Success. 289 * -ENOENT: The DSP Execuetable was not found. 290 * -EFAULT: Invalid processor handle. 291 * -EPERM : Unable to Load the Processor 292 * Requires: 293 * user_args is not NULL 294 * argc_index is > 0 295 * PROC Initialized. 296 * Ensures: 297 * Success and ProcState == PROC_LOADED 298 * or DSP_FAILED status. 299 * Details: 300 * Does not implement access rights to control which GPP application 301 * can load the processor. 302 */ 303 extern int proc_load(void *hprocessor, 304 const s32 argc_index, const char **user_args, 305 const char **user_envp); 306 307 /* 308 * ======== proc_register_notify ======== 309 * Purpose: 310 * Register to be notified of specific processor events 311 * Parameters: 312 * hprocessor : The processor handle. 313 * event_mask : Mask of types of events to be notified about. 314 * notify_type : Type of notification to be sent. 315 * hnotification: Handle to be used for notification. 316 * Returns: 317 * 0 : Success. 318 * -EFAULT : Invalid processor handle or hnotification. 319 * -EINVAL : Parameter event_mask is Invalid 320 * DSP_ENOTIMP : The notification type specified in uNotifyMask 321 * is not supported. 322 * -EPERM : Unable to register for notification. 323 * Requires: 324 * hnotification is not NULL 325 * PROC Initialized. 326 * Ensures: 327 * Details: 328 */ 329 extern int proc_register_notify(void *hprocessor, 330 u32 event_mask, u32 notify_type, 331 struct dsp_notification 332 *hnotification); 333 334 /* 335 * ======== proc_notify_clients ======== 336 * Purpose: 337 * Notify the Processor Clients 338 * Parameters: 339 * proc : The processor handle. 340 * events : Event to be notified about. 341 * Returns: 342 * 0 : Success. 343 * -EFAULT : Invalid processor handle. 344 * -EPERM : Failure to Set or Reset the Event 345 * Requires: 346 * events is Supported or Valid type of Event 347 * proc is a valid handle 348 * PROC Initialized. 349 * Ensures: 350 */ 351 extern int proc_notify_clients(void *proc, u32 events); 352 353 /* 354 * ======== proc_notify_all_clients ======== 355 * Purpose: 356 * Notify the Processor Clients 357 * Parameters: 358 * proc : The processor handle. 359 * events : Event to be notified about. 360 * Returns: 361 * 0 : Success. 362 * -EFAULT : Invalid processor handle. 363 * -EPERM : Failure to Set or Reset the Event 364 * Requires: 365 * events is Supported or Valid type of Event 366 * proc is a valid handle 367 * PROC Initialized. 368 * Ensures: 369 * Details: 370 * NODE And STRM would use this function to notify their clients 371 * about the state changes in NODE or STRM. 372 */ 373 extern int proc_notify_all_clients(void *proc, u32 events); 374 375 /* 376 * ======== proc_start ======== 377 * Purpose: 378 * Start a processor running. 379 * Processor must be in PROC_LOADED state. 380 * This will be an OEM-only function, and not part of the 'Bridge 381 * application developer's API. 382 * Parameters: 383 * hprocessor : The processor handle. 384 * Returns: 385 * 0 : Success. 386 * -EFAULT : Invalid processor handle. 387 * -EBADR: Processor is not in PROC_LOADED state. 388 * -EPERM : Unable to start the processor. 389 * Requires: 390 * PROC Initialized. 391 * Ensures: 392 * Success and ProcState == PROC_RUNNING or DSP_FAILED status. 393 * Details: 394 */ 395 extern int proc_start(void *hprocessor); 396 397 /* 398 * ======== proc_stop ======== 399 * Purpose: 400 * Start a processor running. 401 * Processor must be in PROC_LOADED state. 402 * This will be an OEM-only function, and not part of the 'Bridge 403 * application developer's API. 404 * Parameters: 405 * hprocessor : The processor handle. 406 * Returns: 407 * 0 : Success. 408 * -EFAULT : Invalid processor handle. 409 * -EBADR: Processor is not in PROC_LOADED state. 410 * -EPERM : Unable to start the processor. 411 * Requires: 412 * PROC Initialized. 413 * Ensures: 414 * Success and ProcState == PROC_RUNNING or DSP_FAILED status. 415 * Details: 416 */ 417 extern int proc_stop(void *hprocessor); 418 419 /* 420 * ======== proc_end_dma ======== 421 * Purpose: 422 * Begin a DMA transfer 423 * Parameters: 424 * hprocessor : The processor handle. 425 * pmpu_addr : Buffer start address 426 * ul_size : Buffer size 427 * dir : The direction of the transfer 428 * Requires: 429 * Memory was previously mapped. 430 */ 431 extern int proc_end_dma(void *hprocessor, void *pmpu_addr, u32 ul_size, 432 enum dma_data_direction dir); 433 /* 434 * ======== proc_begin_dma ======== 435 * Purpose: 436 * Begin a DMA transfer 437 * Parameters: 438 * hprocessor : The processor handle. 439 * pmpu_addr : Buffer start address 440 * ul_size : Buffer size 441 * dir : The direction of the transfer 442 * Requires: 443 * Memory was previously mapped. 444 */ 445 extern int proc_begin_dma(void *hprocessor, void *pmpu_addr, u32 ul_size, 446 enum dma_data_direction dir); 447 448 /* 449 * ======== proc_flush_memory ======== 450 * Purpose: 451 * Flushes a buffer from the MPU data cache. 452 * Parameters: 453 * hprocessor : The processor handle. 454 * pmpu_addr : Buffer start address 455 * ul_size : Buffer size 456 * ul_flags : Reserved. 457 * Returns: 458 * 0 : Success. 459 * -EFAULT : Invalid processor handle. 460 * -EPERM : General failure. 461 * Requires: 462 * PROC Initialized. 463 * Ensures: 464 * Details: 465 * All the arguments are currently ignored. 466 */ 467 extern int proc_flush_memory(void *hprocessor, 468 void *pmpu_addr, u32 ul_size, u32 ul_flags); 469 470 /* 471 * ======== proc_invalidate_memory ======== 472 * Purpose: 473 * Invalidates a buffer from the MPU data cache. 474 * Parameters: 475 * hprocessor : The processor handle. 476 * pmpu_addr : Buffer start address 477 * ul_size : Buffer size 478 * Returns: 479 * 0 : Success. 480 * -EFAULT : Invalid processor handle. 481 * -EPERM : General failure. 482 * Requires: 483 * PROC Initialized. 484 * Ensures: 485 * Details: 486 * All the arguments are currently ignored. 487 */ 488 extern int proc_invalidate_memory(void *hprocessor, 489 void *pmpu_addr, u32 ul_size); 490 491 /* 492 * ======== proc_map ======== 493 * Purpose: 494 * Maps a MPU buffer to DSP address space. 495 * Parameters: 496 * hprocessor : The processor handle. 497 * pmpu_addr : Starting address of the memory region to map. 498 * ul_size : Size of the memory region to map. 499 * req_addr : Requested DSP start address. Offset-adjusted actual 500 * mapped address is in the last argument. 501 * pp_map_addr : Ptr to DSP side mapped u8 address. 502 * ul_map_attr : Optional endianness attributes, virt to phys flag. 503 * Returns: 504 * 0 : Success. 505 * -EFAULT : Invalid processor handle. 506 * -EPERM : General failure. 507 * -ENOMEM : MPU side memory allocation error. 508 * -ENOENT : Cannot find a reserved region starting with this 509 * : address. 510 * Requires: 511 * pmpu_addr is not NULL 512 * ul_size is not zero 513 * pp_map_addr is not NULL 514 * PROC Initialized. 515 * Ensures: 516 * Details: 517 */ 518 extern int proc_map(void *hprocessor, 519 void *pmpu_addr, 520 u32 ul_size, 521 void *req_addr, 522 void **pp_map_addr, u32 ul_map_attr, 523 struct process_context *pr_ctxt); 524 525 /* 526 * ======== proc_reserve_memory ======== 527 * Purpose: 528 * Reserve a virtually contiguous region of DSP address space. 529 * Parameters: 530 * hprocessor : The processor handle. 531 * ul_size : Size of the address space to reserve. 532 * pp_rsv_addr : Ptr to DSP side reserved u8 address. 533 * Returns: 534 * 0 : Success. 535 * -EFAULT : Invalid processor handle. 536 * -EPERM : General failure. 537 * -ENOMEM : Cannot reserve chunk of this size. 538 * Requires: 539 * pp_rsv_addr is not NULL 540 * PROC Initialized. 541 * Ensures: 542 * Details: 543 */ 544 extern int proc_reserve_memory(void *hprocessor, 545 u32 ul_size, void **pp_rsv_addr, 546 struct process_context *pr_ctxt); 547 548 /* 549 * ======== proc_un_map ======== 550 * Purpose: 551 * Removes a MPU buffer mapping from the DSP address space. 552 * Parameters: 553 * hprocessor : The processor handle. 554 * map_addr : Starting address of the mapped memory region. 555 * Returns: 556 * 0 : Success. 557 * -EFAULT : Invalid processor handle. 558 * -EPERM : General failure. 559 * -ENOENT : Cannot find a mapped region starting with this 560 * : address. 561 * Requires: 562 * map_addr is not NULL 563 * PROC Initialized. 564 * Ensures: 565 * Details: 566 */ 567 extern int proc_un_map(void *hprocessor, void *map_addr, 568 struct process_context *pr_ctxt); 569 570 /* 571 * ======== proc_un_reserve_memory ======== 572 * Purpose: 573 * Frees a previously reserved region of DSP address space. 574 * Parameters: 575 * hprocessor : The processor handle. 576 * prsv_addr : Ptr to DSP side reservedBYTE address. 577 * Returns: 578 * 0 : Success. 579 * -EFAULT : Invalid processor handle. 580 * -EPERM : General failure. 581 * -ENOENT : Cannot find a reserved region starting with this 582 * : address. 583 * Requires: 584 * prsv_addr is not NULL 585 * PROC Initialized. 586 * Ensures: 587 * Details: 588 */ 589 extern int proc_un_reserve_memory(void *hprocessor, 590 void *prsv_addr, 591 struct process_context *pr_ctxt); 592 593 #endif /* PROC_ */ 594