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

   1 /*
   2  * disp.h
   3  *
   4  * DSP-BIOS Bridge driver support functions for TI OMAP processors.
   5  *
   6  * DSP/BIOS Bridge Node Dispatcher.
   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 DISP_
  20 #define DISP_
  21
  22 #include <dspbridge/dbdefs.h>
  23 #include <dspbridge/nodedefs.h>
  24 #include <dspbridge/nodepriv.h>
  25 #include <dspbridge/dispdefs.h>
  26
  27 /*
  28  *  ======== disp_create ========
  29  *  Create a NODE Dispatcher object. This object handles the creation,
  30  *  deletion, and execution of nodes on the DSP target, through communication
  31  *  with the Resource Manager Server running on the target. Each NODE
  32  *  Manager object should have exactly one NODE Dispatcher.
  33  *
  34  *  Parameters:
  35  *      dispatch_obj:   Location to store node dispatcher object on output.
  36  *      hdev_obj:     Device for this processor.
  37  *      disp_attrs:     Node dispatcher attributes.
  38  *  Returns:
  39  *      0:                Success;
  40  *      -ENOMEM:            Insufficient memory for requested resources.
  41  *      -EPERM:              Unable to create dispatcher.
  42  *  Requires:
  43  *      disp_init(void) called.
  44  *      disp_attrs != NULL.
  45  *      hdev_obj != NULL.
  46  *      dispatch_obj != NULL.
  47  *  Ensures:
  48  *      0:        IS_VALID(*dispatch_obj).
  49  *      error:          *dispatch_obj == NULL.
  50  */
  51 extern int disp_create(struct disp_object **dispatch_obj,
  52                               struct dev_object *hdev_obj,
  53                               const struct disp_attr *disp_attrs);
  54
  55 /*
  56  *  ======== disp_delete ========
  57  *  Delete the NODE Dispatcher.
  58  *
  59  *  Parameters:
  60  *      disp_obj:  Node Dispatcher object.
  61  *  Returns:
  62  *  Requires:
  63  *      disp_init(void) called.
  64  *      Valid disp_obj.
  65  *  Ensures:
  66  *      disp_obj is invalid.
  67  */
  68 extern void disp_delete(struct disp_object *disp_obj);
  69
  70 /*
  71  *  ======== disp_exit ========
  72  *  Discontinue usage of DISP module.
  73  *
  74  *  Parameters:
  75  *  Returns:
  76  *  Requires:
  77  *      disp_init(void) previously called.
  78  *  Ensures:
  79  *      Any resources acquired in disp_init(void) will be freed when last DISP
  80  *      client calls disp_exit(void).
  81  */
  82 extern void disp_exit(void);
  83
  84 /*
  85  *  ======== disp_init ========
  86  *  Initialize the DISP module.
  87  *
  88  *  Parameters:
  89  *  Returns:
  90  *      TRUE if initialization succeeded, FALSE otherwise.
  91  *  Ensures:
  92  */
  93 extern bool disp_init(void);
  94
  95 /*
  96  *  ======== disp_node_change_priority ========
  97  *  Change the priority of a node currently running on the target.
  98  *
  99  *  Parameters:
 100  *      disp_obj:            Node Dispatcher object.
 101  *      hnode:                  Node object representing a node currently
 102  *                              allocated or running on the DSP.
 103  *      ulFxnAddress:           Address of RMS function for changing priority.
 104  *      node_env:                Address of node's environment structure.
 105  *      prio:              New priority level to set node's priority to.
 106  *  Returns:
 107  *      0:                Success.
 108  *      -ETIME:           A timeout occurred before the DSP responded.
 109  *  Requires:
 110  *      disp_init(void) called.
 111  *      Valid disp_obj.
 112  *      hnode != NULL.
 113  *  Ensures:
 114  */
 115 extern int disp_node_change_priority(struct disp_object
 116                                             *disp_obj,
 117                                             struct node_object *hnode,
 118                                             u32 rms_fxn,
 119                                             nodeenv node_env, s32 prio);
 120
 121 /*
 122  *  ======== disp_node_create ========
 123  *  Create a node on the DSP by remotely calling the node's create function.
 124  *
 125  *  Parameters:
 126  *      disp_obj:    Node Dispatcher object.
 127  *      hnode:          Node handle obtained from node_allocate().
 128  *      ul_fxn_addr:      Address or RMS create node function.
 129  *      ul_create_fxn:    Address of node's create function.
 130  *      pargs:          Arguments to pass to RMS node create function.
 131  *      node_env:       Location to store node environment pointer on
 132  *                      output.
 133  *  Returns:
 134  *      0:        Success.
 135  *      -ETIME:   A timeout occurred before the DSP responded.
 136  *      -EPERM:      A failure occurred, unable to create node.
 137  *  Requires:
 138  *      disp_init(void) called.
 139  *      Valid disp_obj.
 140  *      pargs != NULL.
 141  *      hnode != NULL.
 142  *      node_env != NULL.
 143  *      node_get_type(hnode) != NODE_DEVICE.
 144  *  Ensures:
 145  */
 146 extern int disp_node_create(struct disp_object *disp_obj,
 147                                    struct node_object *hnode,
 148                                    u32 rms_fxn,
 149                                    u32 ul_create_fxn,
 150                                    const struct node_createargs
 151                                    *pargs, nodeenv *node_env);
 152
 153 /*
 154  *  ======== disp_node_delete ========
 155  *  Delete a node on the DSP by remotely calling the node's delete function.
 156  *
 157  *  Parameters:
 158  *      disp_obj:    Node Dispatcher object.
 159  *      hnode:          Node object representing a node currently
 160  *                      loaded on the DSP.
 161  *      ul_fxn_addr:      Address or RMS delete node function.
 162  *      ul_delete_fxn:    Address of node's delete function.
 163  *      node_env:        Address of node's environment structure.
 164  *  Returns:
 165  *      0:        Success.
 166  *      -ETIME:   A timeout occurred before the DSP responded.
 167  *  Requires:
 168  *      disp_init(void) called.
 169  *      Valid disp_obj.
 170  *      hnode != NULL.
 171  *  Ensures:
 172  */
 173 extern int disp_node_delete(struct disp_object *disp_obj,
 174                                    struct node_object *hnode,
 175                                    u32 rms_fxn,
 176                                    u32 ul_delete_fxn, nodeenv node_env);
 177
 178 /*
 179  *  ======== disp_node_run ========
 180  *  Start execution of a node's execute phase, or resume execution of a node
 181  *  that has been suspended (via DISP_NodePause()) on the DSP.
 182  *
 183  *  Parameters:
 184  *      disp_obj:    Node Dispatcher object.
 185  *      hnode:          Node object representing a node to be executed
 186  *                      on the DSP.
 187  *      ul_fxn_addr:      Address or RMS node execute function.
 188  *      ul_execute_fxn:   Address of node's execute function.
 189  *      node_env:        Address of node's environment structure.
 190  *  Returns:
 191  *      0:        Success.
 192  *      -ETIME:   A timeout occurred before the DSP responded.
 193  *  Requires:
 194  *      disp_init(void) called.
 195  *      Valid disp_obj.
 196  *      hnode != NULL.
 197  *  Ensures:
 198  */
 199 extern int disp_node_run(struct disp_object *disp_obj,
 200                                 struct node_object *hnode,
 201                                 u32 rms_fxn,
 202                                 u32 ul_execute_fxn, nodeenv node_env);
 203
 204 #endif /* DISP_ */