1/* 2 * dev.h 3 * 4 * DSP-BIOS Bridge driver support functions for TI OMAP processors. 5 * 6 * Bridge Bridge driver device operations. 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 DEV_ 20#define DEV_ 21 22/* ----------------------------------- Module Dependent Headers */ 23#include <dspbridge/chnldefs.h> 24#include <dspbridge/cmm.h> 25#include <dspbridge/cod.h> 26#include <dspbridge/dehdefs.h> 27#include <dspbridge/nodedefs.h> 28#include <dspbridge/dispdefs.h> 29#include <dspbridge/dspdefs.h> 30#include <dspbridge/dmm.h> 31#include <dspbridge/host_os.h> 32 33/* ----------------------------------- This */ 34#include <dspbridge/devdefs.h> 35 36/* 37 * ======== dev_brd_write_fxn ======== 38 * Purpose: 39 * Exported function to be used as the COD write function. This function 40 * is passed a handle to a DEV_hObject by ZL in arb, then calls the 41 * device's bridge_brd_write() function. 42 * Parameters: 43 * arb: Handle to a Device Object. 44 * dev_ctxt: Handle to Bridge driver defined device info. 45 * dsp_addr: Address on DSP board (Destination). 46 * host_buf: Pointer to host buffer (Source). 47 * ul_num_bytes: Number of bytes to transfer. 48 * mem_type: Memory space on DSP to which to transfer. 49 * Returns: 50 * Number of bytes written. Returns 0 if the DEV_hObject passed in via 51 * arb is invalid. 52 * Requires: 53 * DEV Initialized. 54 * host_buf != NULL 55 * Ensures: 56 */ 57extern u32 dev_brd_write_fxn(void *arb, 58 u32 dsp_add, 59 void *host_buf, u32 ul_num_bytes, u32 mem_space); 60 61/* 62 * ======== dev_create_device ======== 63 * Purpose: 64 * Called by the operating system to load the Bridge Driver for a 65 * 'Bridge device. 66 * Parameters: 67 * device_obj: Ptr to location to receive the device object handle. 68 * driver_file_name: Name of Bridge driver PE DLL file to load. If the 69 * absolute path is not provided, the file is loaded 70 * through 'Bridge's module search path. 71 * host_config: Host configuration information, to be passed down 72 * to the Bridge driver when bridge_dev_create() is called. 73 * pDspConfig: DSP resources, to be passed down to the Bridge driver 74 * when bridge_dev_create() is called. 75 * dev_node_obj: Platform specific device node. 76 * Returns: 77 * 0: Module is loaded, device object has been created 78 * -ENOMEM: Insufficient memory to create needed resources. 79 * -EPERM: Unable to find Bridge driver entry point function. 80 * -ESPIPE: Unable to load ZL DLL. 81 * Requires: 82 * DEV Initialized. 83 * device_obj != NULL. 84 * driver_file_name != NULL. 85 * host_config != NULL. 86 * pDspConfig != NULL. 87 * Ensures: 88 * 0: *device_obj will contain handle to the new device object. 89 * Otherwise, does not create the device object, ensures the Bridge driver 90 * module is unloaded, and sets *device_obj to NULL. 91 */ 92extern int dev_create_device(struct dev_object 93 **device_obj, 94 const char *driver_file_name, 95 struct cfg_devnode *dev_node_obj); 96 97/* 98 * ======== dev_create_iva_device ======== 99 * Purpose: 100 * Called by the operating system to load the Bridge Driver for IVA. 101 * Parameters: 102 * device_obj: Ptr to location to receive the device object handle. 103 * driver_file_name: Name of Bridge driver PE DLL file to load. If the 104 * absolute path is not provided, the file is loaded 105 * through 'Bridge's module search path. 106 * host_config: Host configuration information, to be passed down 107 * to the Bridge driver when bridge_dev_create() is called. 108 * pDspConfig: DSP resources, to be passed down to the Bridge driver 109 * when bridge_dev_create() is called. 110 * dev_node_obj: Platform specific device node. 111 * Returns: 112 * 0: Module is loaded, device object has been created 113 * -ENOMEM: Insufficient memory to create needed resources. 114 * -EPERM: Unable to find Bridge driver entry point function. 115 * -ESPIPE: Unable to load ZL DLL. 116 * Requires: 117 * DEV Initialized. 118 * device_obj != NULL. 119 * driver_file_name != NULL. 120 * host_config != NULL. 121 * pDspConfig != NULL. 122 * Ensures: 123 * 0: *device_obj will contain handle to the new device object. 124 * Otherwise, does not create the device object, ensures the Bridge driver 125 * module is unloaded, and sets *device_obj to NULL. 126 */ 127extern int dev_create_iva_device(struct dev_object 128 **device_obj, 129 const char *driver_file_name, 130 const struct cfg_hostres 131 *host_config, 132 struct cfg_devnode *dev_node_obj); 133 134/* 135 * ======== dev_create2 ======== 136 * Purpose: 137 * After successful loading of the image from api_init_complete2 138 * (PROC Auto_Start) or proc_load this fxn is called. This creates 139 * the Node Manager and updates the DEV Object. 140 * Parameters: 141 * hdev_obj: Handle to device object created with dev_create_device(). 142 * Returns: 143 * 0: Successful Creation of Node Manager 144 * -EPERM: Some Error Occurred. 145 * Requires: 146 * DEV Initialized 147 * Valid hdev_obj 148 * Ensures: 149 * 0 and hdev_obj->hnode_mgr != NULL 150 * else hdev_obj->hnode_mgr == NULL 151 */ 152extern int dev_create2(struct dev_object *hdev_obj); 153 154/* 155 * ======== dev_destroy2 ======== 156 * Purpose: 157 * Destroys the Node manager for this device. 158 * Parameters: 159 * hdev_obj: Handle to device object created with dev_create_device(). 160 * Returns: 161 * 0: Successful Creation of Node Manager 162 * -EPERM: Some Error Occurred. 163 * Requires: 164 * DEV Initialized 165 * Valid hdev_obj 166 * Ensures: 167 * 0 and hdev_obj->hnode_mgr == NULL 168 * else -EPERM. 169 */ 170extern int dev_destroy2(struct dev_object *hdev_obj); 171 172/* 173 * ======== dev_destroy_device ======== 174 * Purpose: 175 * Destroys the channel manager for this device, if any, calls 176 * bridge_dev_destroy(), and then attempts to unload the Bridge module. 177 * Parameters: 178 * hdev_obj: Handle to device object created with 179 * dev_create_device(). 180 * Returns: 181 * 0: Success. 182 * -EFAULT: Invalid hdev_obj. 183 * -EPERM: The Bridge driver failed it's bridge_dev_destroy() function. 184 * Requires: 185 * DEV Initialized. 186 * Ensures: 187 */ 188extern int dev_destroy_device(struct dev_object 189 *hdev_obj); 190 191/* 192 * ======== dev_get_chnl_mgr ======== 193 * Purpose: 194 * Retrieve the handle to the channel manager created for this device. 195 * Parameters: 196 * hdev_obj: Handle to device object created with 197 * dev_create_device(). 198 * *mgr: Ptr to location to store handle. 199 * Returns: 200 * 0: Success. 201 * -EFAULT: Invalid hdev_obj. 202 * Requires: 203 * mgr != NULL. 204 * DEV Initialized. 205 * Ensures: 206 * 0: *mgr contains a handle to a channel manager object, 207 * or NULL. 208 * else: *mgr is NULL. 209 */ 210extern int dev_get_chnl_mgr(struct dev_object *hdev_obj, 211 struct chnl_mgr **mgr); 212 213/* 214 * ======== dev_get_cmm_mgr ======== 215 * Purpose: 216 * Retrieve the handle to the shared memory manager created for this 217 * device. 218 * Parameters: 219 * hdev_obj: Handle to device object created with 220 * dev_create_device(). 221 * *mgr: Ptr to location to store handle. 222 * Returns: 223 * 0: Success. 224 * -EFAULT: Invalid hdev_obj. 225 * Requires: 226 * mgr != NULL. 227 * DEV Initialized. 228 * Ensures: 229 * 0: *mgr contains a handle to a channel manager object, 230 * or NULL. 231 * else: *mgr is NULL. 232 */ 233extern int dev_get_cmm_mgr(struct dev_object *hdev_obj, 234 struct cmm_object **mgr); 235 236/* 237 * ======== dev_get_dmm_mgr ======== 238 * Purpose: 239 * Retrieve the handle to the dynamic memory manager created for this 240 * device. 241 * Parameters: 242 * hdev_obj: Handle to device object created with 243 * dev_create_device(). 244 * *mgr: Ptr to location to store handle. 245 * Returns: 246 * 0: Success. 247 * -EFAULT: Invalid hdev_obj. 248 * Requires: 249 * mgr != NULL. 250 * DEV Initialized. 251 * Ensures: 252 * 0: *mgr contains a handle to a channel manager object, 253 * or NULL. 254 * else: *mgr is NULL. 255 */ 256extern int dev_get_dmm_mgr(struct dev_object *hdev_obj, 257 struct dmm_object **mgr); 258 259/* 260 * ======== dev_get_cod_mgr ======== 261 * Purpose: 262 * Retrieve the COD manager create for this device. 263 * Parameters: 264 * hdev_obj: Handle to device object created with 265 * dev_create_device(). 266 * *cod_mgr: Ptr to location to store handle. 267 * Returns: 268 * 0: Success. 269 * -EFAULT: Invalid hdev_obj. 270 * Requires: 271 * cod_mgr != NULL. 272 * DEV Initialized. 273 * Ensures: 274 * 0: *cod_mgr contains a handle to a COD manager object. 275 * else: *cod_mgr is NULL. 276 */ 277extern int dev_get_cod_mgr(struct dev_object *hdev_obj, 278 struct cod_manager **cod_mgr); 279 280/* 281 * ======== dev_get_deh_mgr ======== 282 * Purpose: 283 * Retrieve the DEH manager created for this device. 284 * Parameters: 285 * hdev_obj: Handle to device object created with dev_create_device(). 286 * *deh_manager: Ptr to location to store handle. 287 * Returns: 288 * 0: Success. 289 * -EFAULT: Invalid hdev_obj. 290 * Requires: 291 * deh_manager != NULL. 292 * DEH Initialized. 293 * Ensures: 294 * 0: *deh_manager contains a handle to a DEH manager object. 295 * else: *deh_manager is NULL. 296 */ 297extern int dev_get_deh_mgr(struct dev_object *hdev_obj, 298 struct deh_mgr **deh_manager); 299 300/* 301 * ======== dev_get_dev_node ======== 302 * Purpose: 303 * Retrieve the platform specific device ID for this device. 304 * Parameters: 305 * hdev_obj: Handle to device object created with 306 * dev_create_device(). 307 * dev_nde: Ptr to location to get the device node handle. 308 * Returns: 309 * 0: Returns a DEVNODE in *dev_node_obj. 310 * -EFAULT: Invalid hdev_obj. 311 * Requires: 312 * dev_nde != NULL. 313 * DEV Initialized. 314 * Ensures: 315 * 0: *dev_nde contains a platform specific device ID; 316 * else: *dev_nde is NULL. 317 */ 318extern int dev_get_dev_node(struct dev_object *hdev_obj, 319 struct cfg_devnode **dev_nde); 320 321/* 322 * ======== dev_get_dev_type ======== 323 * Purpose: 324 * Retrieve the platform specific device ID for this device. 325 * Parameters: 326 * hdev_obj: Handle to device object created with 327 * dev_create_device(). 328 * dev_nde: Ptr to location to get the device node handle. 329 * Returns: 330 * 0: Success 331 * -EFAULT: Invalid hdev_obj. 332 * Requires: 333 * dev_nde != NULL. 334 * DEV Initialized. 335 * Ensures: 336 * 0: *dev_nde contains a platform specific device ID; 337 * else: *dev_nde is NULL. 338 */ 339extern int dev_get_dev_type(struct dev_object *device_obj, 340 u8 *dev_type); 341 342/* 343 * ======== dev_get_first ======== 344 * Purpose: 345 * Retrieve the first Device Object handle from an internal linked list of 346 * of DEV_OBJECTs maintained by DEV. 347 * Parameters: 348 * Returns: 349 * NULL if there are no device objects stored; else 350 * a valid DEV_HOBJECT. 351 * Requires: 352 * No calls to dev_create_device or dev_destroy_device (which my modify the 353 * internal device object list) may occur between calls to dev_get_first 354 * and dev_get_next. 355 * Ensures: 356 * The DEV_HOBJECT returned is valid. 357 * A subsequent call to dev_get_next will return the next device object in 358 * the list. 359 */ 360extern struct dev_object *dev_get_first(void); 361 362/* 363 * ======== dev_get_intf_fxns ======== 364 * Purpose: 365 * Retrieve the Bridge driver interface function structure for the 366 * loaded Bridge driver. 367 * Parameters: 368 * hdev_obj: Handle to device object created with 369 * dev_create_device(). 370 * *if_fxns: Ptr to location to store fxn interface. 371 * Returns: 372 * 0: Success. 373 * -EFAULT: Invalid hdev_obj. 374 * Requires: 375 * if_fxns != NULL. 376 * DEV Initialized. 377 * Ensures: 378 * 0: *if_fxns contains a pointer to the Bridge 379 * driver interface; 380 * else: *if_fxns is NULL. 381 */ 382extern int dev_get_intf_fxns(struct dev_object *hdev_obj, 383 struct bridge_drv_interface **if_fxns); 384 385/* 386 * ======== dev_get_io_mgr ======== 387 * Purpose: 388 * Retrieve the handle to the IO manager created for this device. 389 * Parameters: 390 * hdev_obj: Handle to device object created with 391 * dev_create_device(). 392 * *mgr: Ptr to location to store handle. 393 * Returns: 394 * 0: Success. 395 * -EFAULT: Invalid hdev_obj. 396 * Requires: 397 * mgr != NULL. 398 * DEV Initialized. 399 * Ensures: 400 * 0: *mgr contains a handle to an IO manager object. 401 * else: *mgr is NULL. 402 */ 403extern int dev_get_io_mgr(struct dev_object *hdev_obj, 404 struct io_mgr **mgr); 405 406/* 407 * ======== dev_get_next ======== 408 * Purpose: 409 * Retrieve the next Device Object handle from an internal linked list of 410 * of DEV_OBJECTs maintained by DEV, after having previously called 411 * dev_get_first() and zero or more dev_get_next 412 * Parameters: 413 * hdev_obj: Handle to the device object returned from a previous 414 * call to dev_get_first() or dev_get_next(). 415 * Returns: 416 * NULL if there are no further device objects on the list or hdev_obj 417 * was invalid; 418 * else the next valid DEV_HOBJECT in the list. 419 * Requires: 420 * No calls to dev_create_device or dev_destroy_device (which my modify the 421 * internal device object list) may occur between calls to dev_get_first 422 * and dev_get_next. 423 * Ensures: 424 * The DEV_HOBJECT returned is valid. 425 * A subsequent call to dev_get_next will return the next device object in 426 * the list. 427 */ 428extern struct dev_object *dev_get_next(struct dev_object 429 *hdev_obj); 430 431/* 432 * ========= dev_get_msg_mgr ======== 433 * Purpose: 434 * Retrieve the msg_ctrl Manager Handle from the DevObject. 435 * Parameters: 436 * hdev_obj: Handle to the Dev Object 437 * msg_man: Location where msg_ctrl Manager handle will be returned. 438 * Returns: 439 * Requires: 440 * DEV Initialized. 441 * Valid hdev_obj. 442 * node_man != NULL. 443 * Ensures: 444 */ 445extern void dev_get_msg_mgr(struct dev_object *hdev_obj, 446 struct msg_mgr **msg_man); 447 448/* 449 * ========= dev_get_node_manager ======== 450 * Purpose: 451 * Retrieve the Node Manager Handle from the DevObject. It is an 452 * accessor function 453 * Parameters: 454 * hdev_obj: Handle to the Dev Object 455 * node_man: Location where Handle to the Node Manager will be 456 * returned.. 457 * Returns: 458 * 0: Success 459 * -EFAULT: Invalid Dev Object handle. 460 * Requires: 461 * DEV Initialized. 462 * node_man is not null 463 * Ensures: 464 * 0: *node_man contains a handle to a Node manager object. 465 * else: *node_man is NULL. 466 */ 467extern int dev_get_node_manager(struct dev_object 468 *hdev_obj, 469 struct node_mgr **node_man); 470 471/* 472 * ======== dev_get_symbol ======== 473 * Purpose: 474 * Get the value of a symbol in the currently loaded program. 475 * Parameters: 476 * hdev_obj: Handle to device object created with 477 * dev_create_device(). 478 * str_sym: Name of symbol to look up. 479 * pul_value: Ptr to symbol value. 480 * Returns: 481 * 0: Success. 482 * -EFAULT: Invalid hdev_obj. 483 * -ESPIPE: Symbols couldn not be found or have not been loaded onto 484 * the board. 485 * Requires: 486 * str_sym != NULL. 487 * pul_value != NULL. 488 * DEV Initialized. 489 * Ensures: 490 * 0: *pul_value contains the symbol value; 491 */ 492extern int dev_get_symbol(struct dev_object *hdev_obj, 493 const char *str_sym, u32 * pul_value); 494 495/* 496 * ======== dev_get_bridge_context ======== 497 * Purpose: 498 * Retrieve the Bridge Context handle, as returned by the 499 * bridge_dev_create fxn. 500 * Parameters: 501 * hdev_obj: Handle to device object created with dev_create_device() 502 * *phbridge_context: Ptr to location to store context handle. 503 * Returns: 504 * 0: Success. 505 * -EFAULT: Invalid hdev_obj. 506 * Requires: 507 * phbridge_context != NULL. 508 * DEV Initialized. 509 * Ensures: 510 * 0: *phbridge_context contains context handle; 511 * else: *phbridge_context is NULL; 512 */ 513extern int dev_get_bridge_context(struct dev_object *hdev_obj, 514 struct bridge_dev_context 515 **phbridge_context); 516 517/* 518 * ======== dev_exit ======== 519 * Purpose: 520 * Decrement reference count, and free resources when reference count is 521 * 0. 522 * Parameters: 523 * Returns: 524 * Requires: 525 * DEV is initialized. 526 * Ensures: 527 * When reference count == 0, DEV's private resources are freed. 528 */ 529extern void dev_exit(void); 530 531/* 532 * ======== dev_init ======== 533 * Purpose: 534 * Initialize DEV's private state, keeping a reference count on each call. 535 * Parameters: 536 * Returns: 537 * TRUE if initialized; FALSE if error occured. 538 * Requires: 539 * Ensures: 540 * TRUE: A requirement for the other public DEV functions. 541 */ 542extern bool dev_init(void); 543 544/* 545 * ======== dev_is_locked ======== 546 * Purpose: 547 * Predicate function to determine if the device has been 548 * locked by a client for exclusive access. 549 * Parameters: 550 * hdev_obj: Handle to device object created with 551 * dev_create_device(). 552 * Returns: 553 * 0: TRUE: device has been locked. 554 * 0: FALSE: device not locked. 555 * -EFAULT: hdev_obj was invalid. 556 * Requires: 557 * DEV Initialized. 558 * Ensures: 559 */ 560extern int dev_is_locked(struct dev_object *hdev_obj); 561 562/* 563 * ======== dev_insert_proc_object ======== 564 * Purpose: 565 * Inserts the Processor Object into the List of PROC Objects 566 * kept in the DEV Object 567 * Parameters: 568 * proc_obj: Handle to the Proc Object 569 * hdev_obj Handle to the Dev Object 570 * bAttachedNew Specifies if there are already processors attached 571 * Returns: 572 * 0: Successfully inserted into the list 573 * Requires: 574 * proc_obj is not NULL 575 * hdev_obj is a valid handle to the DEV. 576 * DEV Initialized. 577 * List(of Proc object in Dev) Exists. 578 * Ensures: 579 * 0 & the PROC Object is inserted and the list is not empty 580 * Details: 581 * If the List of Proc Object is empty bAttachedNew is TRUE, it indicated 582 * this is the first Processor attaching. 583 * If it is False, there are already processors attached. 584 */ 585extern int dev_insert_proc_object(struct dev_object 586 *hdev_obj, 587 u32 proc_obj, 588 bool *already_attached); 589 590/* 591 * ======== dev_remove_proc_object ======== 592 * Purpose: 593 * Search for and remove a Proc object from the given list maintained 594 * by the DEV 595 * Parameters: 596 * p_proc_object: Ptr to ProcObject to insert. 597 * dev_obj: Ptr to Dev Object where the list is. 598 * already_attached: Ptr to return the bool 599 * Returns: 600 * 0: If successful. 601 * -EPERM Failure to Remove the PROC Object from the list 602 * Requires: 603 * DevObject is Valid 604 * proc_obj != 0 605 * dev_obj->proc_list != NULL 606 * !LST_IS_EMPTY(dev_obj->proc_list) 607 * already_attached !=NULL 608 * Ensures: 609 * Details: 610 * List will be deleted when the DEV is destroyed. 611 * 612 */ 613extern int dev_remove_proc_object(struct dev_object 614 *hdev_obj, u32 proc_obj); 615 616/* 617 * ======== dev_notify_clients ======== 618 * Purpose: 619 * Notify all clients of this device of a change in device status. 620 * Clients may include multiple users of BRD, as well as CHNL. 621 * This function is asychronous, and may be called by a timer event 622 * set up by a watchdog timer. 623 * Parameters: 624 * hdev_obj: Handle to device object created with dev_create_device(). 625 * ret: A status word, most likely a BRD_STATUS. 626 * Returns: 627 * 0: All registered clients were asynchronously notified. 628 * -EINVAL: Invalid hdev_obj. 629 * Requires: 630 * DEV Initialized. 631 * Ensures: 632 * 0: Notifications are queued by the operating system to be 633 * delivered to clients. This function does not ensure that 634 * the notifications will ever be delivered. 635 */ 636extern int dev_notify_clients(struct dev_object *hdev_obj, u32 ret); 637 638/* 639 * ======== dev_remove_device ======== 640 * Purpose: 641 * Destroys the Device Object created by dev_start_device. 642 * Parameters: 643 * dev_node_obj: Device node as it is know to OS. 644 * Returns: 645 * 0: If success; 646 * <error code> Otherwise. 647 * Requires: 648 * Ensures: 649 */ 650extern int dev_remove_device(struct cfg_devnode *dev_node_obj); 651 652/* 653 * ======== dev_set_chnl_mgr ======== 654 * Purpose: 655 * Set the channel manager for this device. 656 * Parameters: 657 * hdev_obj: Handle to device object created with 658 * dev_create_device(). 659 * hmgr: Handle to a channel manager, or NULL. 660 * Returns: 661 * 0: Success. 662 * -EFAULT: Invalid hdev_obj. 663 * Requires: 664 * DEV Initialized. 665 * Ensures: 666 */ 667extern int dev_set_chnl_mgr(struct dev_object *hdev_obj, 668 struct chnl_mgr *hmgr); 669 670/* 671 * ======== dev_set_msg_mgr ======== 672 * Purpose: 673 * Set the Message manager for this device. 674 * Parameters: 675 * hdev_obj: Handle to device object created with dev_create_device(). 676 * hmgr: Handle to a message manager, or NULL. 677 * Returns: 678 * Requires: 679 * DEV Initialized. 680 * Ensures: 681 */ 682extern void dev_set_msg_mgr(struct dev_object *hdev_obj, struct msg_mgr *hmgr); 683 684/* 685 * ======== dev_start_device ======== 686 * Purpose: 687 * Initializes the new device with bridge environment. This involves 688 * querying CM for allocated resources, querying the registry for 689 * necessary dsp resources (requested in the INF file), and using this 690 * information to create a bridge device object. 691 * Parameters: 692 * dev_node_obj: Device node as it is know to OS. 693 * Returns: 694 * 0: If success; 695 * <error code> Otherwise. 696 * Requires: 697 * DEV initialized. 698 * Ensures: 699 */ 700extern int dev_start_device(struct cfg_devnode *dev_node_obj); 701 702#endif /* DEV_ */ 703