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 26extern 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 */ 54extern 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 */ 76extern 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 Occured 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 */ 101extern 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 */ 120extern 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 */ 153extern 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 occured 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 */ 185extern 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_exit ======== 193 * Purpose: 194 * Decrement reference count, and free resources when reference count is 195 * 0. 196 * Parameters: 197 * Returns: 198 * Requires: 199 * PROC is initialized. 200 * Ensures: 201 * When reference count == 0, PROC's private resources are freed. 202 */ 203extern void proc_exit(void); 204 205/* 206 * ======== proc_get_dev_object ========= 207 * Purpose: 208 * Returns the DEV Hanlde for a given Processor handle 209 * Parameters: 210 * hprocessor : Processor Handle 211 * device_obj : Location to store the DEV Handle. 212 * Returns: 213 * 0 : Success; *device_obj has Dev handle 214 * -EPERM : Failure; *device_obj is zero. 215 * Requires: 216 * device_obj is not NULL 217 * PROC Initialized. 218 * Ensures: 219 * 0 : *device_obj is not NULL 220 * -EPERM : *device_obj is NULL. 221 */ 222extern int proc_get_dev_object(void *hprocessor, 223 struct dev_object **device_obj); 224 225/* 226 * ======== proc_init ======== 227 * Purpose: 228 * Initialize PROC's private state, keeping a reference count on each 229 * call. 230 * Parameters: 231 * Returns: 232 * TRUE if initialized; FALSE if error occured. 233 * Requires: 234 * Ensures: 235 * TRUE: A requirement for the other public PROC functions. 236 */ 237extern bool proc_init(void); 238 239/* 240 * ======== proc_get_state ======== 241 * Purpose: 242 * Report the state of the specified DSP processor. 243 * Parameters: 244 * hprocessor : The processor handle. 245 * proc_state_obj : Ptr to location to store the dsp_processorstate 246 * structure. 247 * state_info_size: Size of dsp_processorstate. 248 * Returns: 249 * 0 : Success. 250 * -EFAULT : Invalid processor handle. 251 * -EPERM : General failure while querying processor state. 252 * Requires: 253 * proc_state_obj is not NULL 254 * state_info_size is >= than the size of dsp_processorstate structure. 255 * PROC Initialized. 256 * Ensures: 257 * Details: 258 */ 259extern int proc_get_state(void *hprocessor, struct dsp_processorstate 260 *proc_state_obj, u32 state_info_size); 261 262/* 263 * ======== PROC_GetProcessorID ======== 264 * Purpose: 265 * Report the state of the specified DSP processor. 266 * Parameters: 267 * hprocessor : The processor handle. 268 * proc_id : Processor ID 269 * 270 * Returns: 271 * 0 : Success. 272 * -EFAULT : Invalid processor handle. 273 * -EPERM : General failure while querying processor state. 274 * Requires: 275 * proc_state_obj is not NULL 276 * state_info_size is >= than the size of dsp_processorstate structure. 277 * PROC Initialized. 278 * Ensures: 279 * Details: 280 */ 281extern int proc_get_processor_id(void *proc, u32 * proc_id); 282 283/* 284 * ======== proc_get_trace ======== 285 * Purpose: 286 * Retrieve the trace buffer from the specified DSP processor. 287 * Parameters: 288 * hprocessor : The processor handle. 289 * pbuf : Ptr to buffer to hold trace output. 290 * max_size : Maximum size of the output buffer. 291 * Returns: 292 * 0 : Success. 293 * -EFAULT : Invalid processor handle. 294 * -EPERM : General failure while retireving processor trace 295 * Buffer. 296 * Requires: 297 * pbuf is not NULL 298 * max_size is > 0. 299 * PROC Initialized. 300 * Ensures: 301 * Details: 302 */ 303extern int proc_get_trace(void *hprocessor, u8 * pbuf, u32 max_size); 304 305/* 306 * ======== proc_load ======== 307 * Purpose: 308 * Reset a processor and load a new base program image. 309 * This will be an OEM-only function. 310 * Parameters: 311 * hprocessor: The processor handle. 312 * argc_index: The number of Arguments(strings)in the aArgV[] 313 * user_args: An Array of Arguments(Unicode Strings) 314 * user_envp: An Array of Environment settings(Unicode Strings) 315 * Returns: 316 * 0: Success. 317 * -ENOENT: The DSP Execuetable was not found. 318 * -EFAULT: Invalid processor handle. 319 * -EPERM : Unable to Load the Processor 320 * Requires: 321 * user_args is not NULL 322 * argc_index is > 0 323 * PROC Initialized. 324 * Ensures: 325 * Success and ProcState == PROC_LOADED 326 * or DSP_FAILED status. 327 * Details: 328 * Does not implement access rights to control which GPP application 329 * can load the processor. 330 */ 331extern int proc_load(void *hprocessor, 332 const s32 argc_index, const char **user_args, 333 const char **user_envp); 334 335/* 336 * ======== proc_register_notify ======== 337 * Purpose: 338 * Register to be notified of specific processor events 339 * Parameters: 340 * hprocessor : The processor handle. 341 * event_mask : Mask of types of events to be notified about. 342 * notify_type : Type of notification to be sent. 343 * hnotification: Handle to be used for notification. 344 * Returns: 345 * 0 : Success. 346 * -EFAULT : Invalid processor handle or hnotification. 347 * -EINVAL : Parameter event_mask is Invalid 348 * DSP_ENOTIMP : The notification type specified in uNotifyMask 349 * is not supported. 350 * -EPERM : Unable to register for notification. 351 * Requires: 352 * hnotification is not NULL 353 * PROC Initialized. 354 * Ensures: 355 * Details: 356 */ 357extern int proc_register_notify(void *hprocessor, 358 u32 event_mask, u32 notify_type, 359 struct dsp_notification 360 *hnotification); 361 362/* 363 * ======== proc_notify_clients ======== 364 * Purpose: 365 * Notify the Processor Clients 366 * Parameters: 367 * proc : The processor handle. 368 * events : Event to be notified about. 369 * Returns: 370 * 0 : Success. 371 * -EFAULT : Invalid processor handle. 372 * -EPERM : Failure to Set or Reset the Event 373 * Requires: 374 * events is Supported or Valid type of Event 375 * proc is a valid handle 376 * PROC Initialized. 377 * Ensures: 378 */ 379extern int proc_notify_clients(void *proc, u32 events); 380 381/* 382 * ======== proc_notify_all_clients ======== 383 * Purpose: 384 * Notify the Processor Clients 385 * Parameters: 386 * proc : The processor handle. 387 * events : Event to be notified about. 388 * Returns: 389 * 0 : Success. 390 * -EFAULT : Invalid processor handle. 391 * -EPERM : Failure to Set or Reset the Event 392 * Requires: 393 * events is Supported or Valid type of Event 394 * proc is a valid handle 395 * PROC Initialized. 396 * Ensures: 397 * Details: 398 * NODE And STRM would use this function to notify their clients 399 * about the state changes in NODE or STRM. 400 */ 401extern int proc_notify_all_clients(void *proc, u32 events); 402 403/* 404 * ======== proc_start ======== 405 * Purpose: 406 * Start a processor running. 407 * Processor must be in PROC_LOADED state. 408 * This will be an OEM-only function, and not part of the 'Bridge 409 * application developer's API. 410 * Parameters: 411 * hprocessor : The processor handle. 412 * Returns: 413 * 0 : Success. 414 * -EFAULT : Invalid processor handle. 415 * -EBADR: Processor is not in PROC_LOADED state. 416 * -EPERM : Unable to start the processor. 417 * Requires: 418 * PROC Initialized. 419 * Ensures: 420 * Success and ProcState == PROC_RUNNING or DSP_FAILED status. 421 * Details: 422 */ 423extern int proc_start(void *hprocessor); 424 425/* 426 * ======== proc_stop ======== 427 * Purpose: 428 * Start a processor running. 429 * Processor must be in PROC_LOADED state. 430 * This will be an OEM-only function, and not part of the 'Bridge 431 * application developer's API. 432 * Parameters: 433 * hprocessor : The processor handle. 434 * Returns: 435 * 0 : Success. 436 * -EFAULT : Invalid processor handle. 437 * -EBADR: Processor is not in PROC_LOADED state. 438 * -EPERM : Unable to start the processor. 439 * Requires: 440 * PROC Initialized. 441 * Ensures: 442 * Success and ProcState == PROC_RUNNING or DSP_FAILED status. 443 * Details: 444 */ 445extern int proc_stop(void *hprocessor); 446 447/* 448 * ======== proc_end_dma ======== 449 * Purpose: 450 * Begin a DMA transfer 451 * Parameters: 452 * hprocessor : The processor handle. 453 * pmpu_addr : Buffer start address 454 * ul_size : Buffer size 455 * dir : The direction of the transfer 456 * Requires: 457 * Memory was previously mapped. 458 */ 459extern int proc_end_dma(void *hprocessor, void *pmpu_addr, u32 ul_size, 460 enum dma_data_direction dir); 461/* 462 * ======== proc_begin_dma ======== 463 * Purpose: 464 * Begin a DMA transfer 465 * Parameters: 466 * hprocessor : The processor handle. 467 * pmpu_addr : Buffer start address 468 * ul_size : Buffer size 469 * dir : The direction of the transfer 470 * Requires: 471 * Memory was previously mapped. 472 */ 473extern int proc_begin_dma(void *hprocessor, void *pmpu_addr, u32 ul_size, 474 enum dma_data_direction dir); 475 476/* 477 * ======== proc_flush_memory ======== 478 * Purpose: 479 * Flushes a buffer from the MPU data cache. 480 * Parameters: 481 * hprocessor : The processor handle. 482 * pmpu_addr : Buffer start address 483 * ul_size : Buffer size 484 * ul_flags : Reserved. 485 * Returns: 486 * 0 : Success. 487 * -EFAULT : Invalid processor handle. 488 * -EPERM : General failure. 489 * Requires: 490 * PROC Initialized. 491 * Ensures: 492 * Details: 493 * All the arguments are currently ignored. 494 */ 495extern int proc_flush_memory(void *hprocessor, 496 void *pmpu_addr, u32 ul_size, u32 ul_flags); 497 498/* 499 * ======== proc_invalidate_memory ======== 500 * Purpose: 501 * Invalidates a buffer from the MPU data cache. 502 * Parameters: 503 * hprocessor : The processor handle. 504 * pmpu_addr : Buffer start address 505 * ul_size : Buffer size 506 * Returns: 507 * 0 : Success. 508 * -EFAULT : Invalid processor handle. 509 * -EPERM : General failure. 510 * Requires: 511 * PROC Initialized. 512 * Ensures: 513 * Details: 514 * All the arguments are currently ignored. 515 */ 516extern int proc_invalidate_memory(void *hprocessor, 517 void *pmpu_addr, u32 ul_size); 518 519/* 520 * ======== proc_map ======== 521 * Purpose: 522 * Maps a MPU buffer to DSP address space. 523 * Parameters: 524 * hprocessor : The processor handle. 525 * pmpu_addr : Starting address of the memory region to map. 526 * ul_size : Size of the memory region to map. 527 * req_addr : Requested DSP start address. Offset-adjusted actual 528 * mapped address is in the last argument. 529 * pp_map_addr : Ptr to DSP side mapped u8 address. 530 * ul_map_attr : Optional endianness attributes, virt to phys flag. 531 * Returns: 532 * 0 : Success. 533 * -EFAULT : Invalid processor handle. 534 * -EPERM : General failure. 535 * -ENOMEM : MPU side memory allocation error. 536 * -ENOENT : Cannot find a reserved region starting with this 537 * : address. 538 * Requires: 539 * pmpu_addr is not NULL 540 * ul_size is not zero 541 * pp_map_addr is not NULL 542 * PROC Initialized. 543 * Ensures: 544 * Details: 545 */ 546extern int proc_map(void *hprocessor, 547 void *pmpu_addr, 548 u32 ul_size, 549 void *req_addr, 550 void **pp_map_addr, u32 ul_map_attr, 551 struct process_context *pr_ctxt); 552 553/* 554 * ======== proc_reserve_memory ======== 555 * Purpose: 556 * Reserve a virtually contiguous region of DSP address space. 557 * Parameters: 558 * hprocessor : The processor handle. 559 * ul_size : Size of the address space to reserve. 560 * pp_rsv_addr : Ptr to DSP side reserved u8 address. 561 * Returns: 562 * 0 : Success. 563 * -EFAULT : Invalid processor handle. 564 * -EPERM : General failure. 565 * -ENOMEM : Cannot reserve chunk of this size. 566 * Requires: 567 * pp_rsv_addr is not NULL 568 * PROC Initialized. 569 * Ensures: 570 * Details: 571 */ 572extern int proc_reserve_memory(void *hprocessor, 573 u32 ul_size, void **pp_rsv_addr, 574 struct process_context *pr_ctxt); 575 576/* 577 * ======== proc_un_map ======== 578 * Purpose: 579 * Removes a MPU buffer mapping from the DSP address space. 580 * Parameters: 581 * hprocessor : The processor handle. 582 * map_addr : Starting address of the mapped memory region. 583 * Returns: 584 * 0 : Success. 585 * -EFAULT : Invalid processor handle. 586 * -EPERM : General failure. 587 * -ENOENT : Cannot find a mapped region starting with this 588 * : address. 589 * Requires: 590 * map_addr is not NULL 591 * PROC Initialized. 592 * Ensures: 593 * Details: 594 */ 595extern int proc_un_map(void *hprocessor, void *map_addr, 596 struct process_context *pr_ctxt); 597 598/* 599 * ======== proc_un_reserve_memory ======== 600 * Purpose: 601 * Frees a previously reserved region of DSP address space. 602 * Parameters: 603 * hprocessor : The processor handle. 604 * prsv_addr : Ptr to DSP side reservedBYTE address. 605 * Returns: 606 * 0 : Success. 607 * -EFAULT : Invalid processor handle. 608 * -EPERM : General failure. 609 * -ENOENT : Cannot find a reserved region starting with this 610 * : address. 611 * Requires: 612 * prsv_addr is not NULL 613 * PROC Initialized. 614 * Ensures: 615 * Details: 616 */ 617extern int proc_un_reserve_memory(void *hprocessor, 618 void *prsv_addr, 619 struct process_context *pr_ctxt); 620 621#endif /* PROC_ */ 622