drivers/staging/tidspbridge/include/dspbridge/dev.h

   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  */
  57 extern 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  */
  92 extern 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  */
 127 extern 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  */
 152 extern 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  */
 170 extern 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  */
 188 extern 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  */
 210 extern 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  */
 233 extern 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  */
 256 extern 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  */
 277 extern 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  */
 297 extern 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  */
 318 extern 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  */
 339 extern 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  */
 360 extern 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  */
 382 extern 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  */
 403 extern 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  */
 428 extern 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  */
 445 extern 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  */
 467 extern 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  */
 492 extern 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  */
 513 extern 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  */
 529 extern 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  */
 542 extern 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  */
 560 extern 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  */
 585 extern 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  */
 613 extern 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  */
 636 extern 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  */
 650 extern 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  */
 667 extern 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  */
 682 extern 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  */
 700 extern int dev_start_device(struct cfg_devnode *dev_node_obj);
 701
 702 #endif /* DEV_ */