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

   1 /*
   2  * mgr.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 MGR_
  20 #define MGR_
  21
  22 #include <dspbridge/mgrpriv.h>
  23
  24 #define MAX_EVENTS 32
  25
  26 /*
  27  *  ======== mgr_wait_for_bridge_events ========
  28  *  Purpose:
  29  *      Block on any Bridge event(s)
  30  *  Parameters:
  31  *      anotifications  : array of pointers to notification objects.
  32  *      count          : number of elements in above array
  33  *      pu_index         : index of signaled event object
  34  *      utimeout        : timeout interval in milliseocnds
  35  *  Returns:
  36  *      0         : Success.
  37  *      -ETIME    : Wait timed out. *pu_index is undetermined.
  38  *  Details:
  39  */
  40
  41 int mgr_wait_for_bridge_events(struct dsp_notification
  42                                       **anotifications,
  43                                       u32 count, u32 *pu_index,
  44                                       u32 utimeout);
  45
  46 /*
  47  *  ======== mgr_create ========
  48  *  Purpose:
  49  *      Creates the Manager Object. This is done during the driver loading.
  50  *      There is only one Manager Object in the DSP/BIOS Bridge.
  51  *  Parameters:
  52  *      mgr_obj:        Location to store created MGR Object handle.
  53  *      dev_node_obj:       Device object as known to the system.
  54  *  Returns:
  55  *      0:        Success
  56  *      -ENOMEM:    Failed to Create the Object
  57  *      -EPERM:      General Failure
  58  *  Requires:
  59  *      MGR Initialized (refs > 0 )
  60  *      mgr_obj != NULL.
  61  *  Ensures:
  62  *      0:        *mgr_obj is a valid MGR interface to the device.
  63  *                      MGR Object stores the DCD Manager Handle.
  64  *                      MGR Object stored in the Regsitry.
  65  *      !0:       MGR Object not created
  66  *  Details:
  67  *      DCD Dll is loaded and MGR Object stores the handle of the DLL.
  68  */
  69 extern int mgr_create(struct mgr_object **mgr_obj,
  70                              struct cfg_devnode *dev_node_obj);
  71
  72 /*
  73  *  ======== mgr_destroy ========
  74  *  Purpose:
  75  *      Destroys the MGR object. Called upon driver unloading.
  76  *  Parameters:
  77  *      hmgr_obj:     Handle to Manager object .
  78  *  Returns:
  79  *      0:        Success.
  80  *                      DCD Manager freed; MGR Object destroyed;
  81  *                      MGR Object deleted from the Registry.
  82  *      -EPERM:      Failed to destroy MGR Object
  83  *  Requires:
  84  *      MGR Initialized (refs > 0 )
  85  *      hmgr_obj is a valid MGR handle .
  86  *  Ensures:
  87  *      0:        MGR Object destroyed and hmgr_obj is Invalid MGR
  88  *                      Handle.
  89  */
  90 extern int mgr_destroy(struct mgr_object *hmgr_obj);
  91
  92 /*
  93  *  ======== mgr_enum_node_info ========
  94  *  Purpose:
  95  *      Enumerate and get configuration information about nodes configured
  96  *      in the node database.
  97  *  Parameters:
  98  *      node_id:              The node index (base 0).
  99  *      pndb_props:          Ptr to the dsp_ndbprops structure for output.
 100  *      undb_props_size:      Size of the dsp_ndbprops structure.
 101  *      pu_num_nodes:         Location where the number of nodes configured
 102  *                          in the database will be returned.
 103  *  Returns:
 104  *      0:            Success.
 105  *      -EINVAL:    Parameter node_id is > than the number of nodes.
 106  *                          configutred in the system
 107  *      -EIDRM:  During Enumeration there has been a change in
 108  *                              the number of nodes configured or in the
 109  *                              the properties of the enumerated nodes.
 110  *      -EPERM:          Failed to querry the Node Data Base
 111  *  Requires:
 112  *      pNDBPROPS is not null
 113  *      undb_props_size >= sizeof(dsp_ndbprops)
 114  *      pu_num_nodes is not null
 115  *      MGR Initialized (refs > 0 )
 116  *  Ensures:
 117  *      SUCCESS on successful retreival of data and *pu_num_nodes > 0 OR
 118  *      DSP_FAILED  && *pu_num_nodes == 0.
 119  *  Details:
 120  */
 121 extern int mgr_enum_node_info(u32 node_id,
 122                                      struct dsp_ndbprops *pndb_props,
 123                                      u32 undb_props_size,
 124                                      u32 *pu_num_nodes);
 125
 126 /*
 127  *  ======== mgr_enum_processor_info ========
 128  *  Purpose:
 129  *      Enumerate and get configuration information about available DSP
 130  *      processors
 131  *  Parameters:
 132  *      processor_id:         The processor index (zero-based).
 133  *      processor_info:     Ptr to the dsp_processorinfo structure .
 134  *      processor_info_size: Size of dsp_processorinfo structure.
 135  *      pu_num_procs:         Location where the number of DSPs configured
 136  *                          in the database will be returned
 137  *  Returns:
 138  *      0:            Success.
 139  *      -EINVAL:    Parameter processor_id is > than the number of
 140  *                          DSP Processors in the system.
 141  *      -EPERM:          Failed to querry the Node Data Base
 142  *  Requires:
 143  *      processor_info is not null
 144  *      pu_num_procs is not null
 145  *      processor_info_size >= sizeof(dsp_processorinfo)
 146  *      MGR Initialized (refs > 0 )
 147  *  Ensures:
 148  *      SUCCESS on successful retreival of data and *pu_num_procs > 0 OR
 149  *      DSP_FAILED && *pu_num_procs == 0.
 150  *  Details:
 151  */
 152 extern int mgr_enum_processor_info(u32 processor_id,
 153                                           struct dsp_processorinfo
 154                                           *processor_info,
 155                                           u32 processor_info_size,
 156                                           u8 *pu_num_procs);
 157 /*
 158  *  ======== mgr_exit ========
 159  *  Purpose:
 160  *      Decrement reference count, and free resources when reference count is
 161  *      0.
 162  *  Parameters:
 163  *  Returns:
 164  *  Requires:
 165  *      MGR is initialized.
 166  *  Ensures:
 167  *      When reference count == 0, MGR's private resources are freed.
 168  */
 169 extern void mgr_exit(void);
 170
 171 /*
 172  *  ======== mgr_get_dcd_handle ========
 173  *  Purpose:
 174  *      Retrieves the MGR handle. Accessor Function
 175  *  Parameters:
 176  *      mgr_handle:     Handle to the Manager Object
 177  *      dcd_handle:     Ptr to receive the DCD Handle.
 178  *  Returns:
 179  *      0:        Sucess
 180  *      -EPERM:      Failure to get the Handle
 181  *  Requires:
 182  *      MGR is initialized.
 183  *      dcd_handle != NULL
 184  *  Ensures:
 185  *      0 and *dcd_handle != NULL ||
 186  *      -EPERM and *dcd_handle == NULL
 187  */
 188 extern int mgr_get_dcd_handle(struct mgr_object
 189                                      *mgr_handle, u32 *dcd_handle);
 190
 191 /*
 192  *  ======== mgr_init ========
 193  *  Purpose:
 194  *      Initialize MGR's private state, keeping a reference count on each
 195  *      call. Initializes the DCD.
 196  *  Parameters:
 197  *  Returns:
 198  *      TRUE if initialized; FALSE if error occured.
 199  *  Requires:
 200  *  Ensures:
 201  *      TRUE: A requirement for the other public MGR functions.
 202  */
 203 extern bool mgr_init(void);
 204
 205 #endif /* MGR_ */