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