** Warning: Cannot open xref database.
1 /*
2 Copyright (C) 2001 Paul Davis
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17
18 $Id: driver.h,v 1.20 2003/11/24 23:18:56 node Exp $
19 */
20
21 #ifndef __jack_driver_h__
22 #define __jack_driver_h__
23
24 #include <pthread.h>
25 #include <jack/types.h>
26 #include <jack/port.h>
27 #include <jack/driver_interface.h>
28
29 typedef float gain_t;
30 typedef long channel_t;
31
32 typedef enum {
33 Lock = 0x1,
34 NoLock = 0x2,
35 Sync = 0x4,
36 NoSync = 0x8
37 } ClockSyncStatus;
38
39 typedef void (*ClockSyncListenerFunction)(channel_t,ClockSyncStatus,void*);
40
41 typedef struct {
42 unsigned long id;
43 ClockSyncListenerFunction function;
44 void *arg;
45 } ClockSyncListener;
46
47 struct _jack_engine;
48 struct _jack_driver;
49
50 typedef int (*JackDriverAttachFunction)(struct _jack_driver *,
51 struct _jack_engine *);
52 typedef int (*JackDriverDetachFunction)(struct _jack_driver *,
53 struct _jack_engine *);
54 typedef int (*JackDriverReadFunction)(struct _jack_driver *,
55 jack_nframes_t nframes);
56 typedef int (*JackDriverWriteFunction)(struct _jack_driver *,
57 jack_nframes_t nframes);
58 typedef int (*JackDriverNullCycleFunction)(struct _jack_driver *,
59 jack_nframes_t nframes);
60 typedef int (*JackDriverStopFunction)(struct _jack_driver *);
61 typedef int (*JackDriverStartFunction)(struct _jack_driver *);
62 typedef int (*JackDriverBufSizeFunction)(struct _jack_driver *,
63 jack_nframes_t nframes);
64 /*
65 Call sequence summary:
66
67 1) engine loads driver via runtime dynamic linking
68 - calls jack_driver_load
69 - we call dlsym for "driver_initialize" and execute it
70 2) engine attaches to driver
71 3) engine starts driver
72 4) driver runs its own thread, calling
73 while () {
74 driver->wait ();
75 driver->engine->run_cycle ()
76 }
77 5) engine stops driver
78 6) engine detaches from driver
79 7) engine calls driver `finish' routine
80
81 Note that stop/start may be called multiple times in the event of an
82 error return from the `wait' function.
83 */
84
85 typedef struct _jack_driver {
86
87 /* The _jack_driver structure fields are included at the beginning of
88 each driver-specific structure using the JACK_DRIVER_DECL macro,
89 which is defined below. The comments that follow describe each
90 common field.
91
92 The driver should set this to be the interval it expects to elapse
93 between returning from the `wait' function. if set to zero, it
94 implies that the driver does not expect regular periodic wakeups.
95
96 jack_time_t period_usecs;
97
98
99 The driver should set this within its "wait" function to indicate
100 the UST of the most recent determination that the engine cycle
101 should run. it should not be set if the "extra_fd" argument of
102 the wait function is set to a non-zero value.
103
104 jack_time_t last_wait_ust;
105
106
107 These are not used by the driver. They should not be written to or
108 modified in any way
109
110 void *handle;
111 struct _jack_internal_client *internal_client;
112
113 This should perform any cleanup associated with the driver. it will
114 be called when jack server process decides to get rid of the
115 driver. in some systems, it may not be called at all, so the driver
116 should never rely on a call to this. it can set it to NULL if
117 it has nothing do do.
118
119 void (*finish)(struct _jack_driver *);
120
121
122 The JACK engine will call this when it wishes to attach itself to
123 the driver. the engine will pass a pointer to itself, which the driver
124 may use in anyway it wishes to. the driver may assume that this
125 is the same engine object that will make `wait' calls until a
126 `detach' call is made.
127
128 JackDriverAttachFunction attach;
129
130
131 The JACK engine will call this when it is finished using a driver.
132
133 JackDriverDetachFunction detach;
134
135
136 The JACK engine will call this when it wants to wait until the
137 driver decides that its time to process some data. the driver returns
138 a count of the number of audioframes that can be processed.
139
140 it should set the variable pointed to by `status' as follows:
141
142 zero: the wait completed normally, processing may begin
143 negative: the wait failed, and recovery is not possible
144 positive: the wait failed, and the driver stopped itself.
145 a call to `start' will return the driver to
146 a correct and known state.
147
148 the driver should also fill out the `delayed_usecs' variable to
149 indicate any delay in its expected periodic execution. for example,
150 if it discovers that its return from poll(2) is later than it
151 expects it to be, it would place an estimate of the delay
152 in this variable. the engine will use this to decide if it
153 plans to continue execution.
154
155 JackDriverWaitFunction wait;
156
157
158 The JACK engine will call this to ask the driver to move
159 data from its inputs to its output port buffers. it should
160 return 0 to indicate successful completion, negative otherwise.
161
162 This function will always be called after the wait function (above).
163
164 JackDriverReadFunction read;
165
166
167 The JACK engine will call this to ask the driver to move
168 data from its input port buffers to its outputs. it should
169 return 0 to indicate successful completion, negative otherwise.
170
171 this function will always be called after the read function (above).
172
173 JackDriverWriteFunction write;
174
175
176 The JACK engine will call this after the wait function (above) has
177 been called, but for some reason the engine is unable to execute
178 a full "cycle". the driver should do whatever is necessary to
179 keep itself running correctly, but cannot reference ports
180 or other JACK data structures in any way.
181
182 JackDriverNullCycleFunction null_cycle;
183
184
185 The engine will call this when it plans to stop calling the `wait'
186 function for some period of time. the driver should take
187 appropriate steps to handle this (possibly no steps at all).
188 NOTE: the driver must silence its capture buffers (if any)
189 from within this function or the function that actually
190 implements the change in state.
191
192 JackDriverStopFunction stop;
193
194
195 The engine will call this to let the driver know that it plans
196 to start calling the `wait' function on a regular basis. the driver
197 should take any appropriate steps to handle this (possibly no steps
198 at all). NOTE: The driver may wish to silence its playback buffers
199 (if any) from within this function or the function that actually
200 implements the change in state.
201
202 JackDriverStartFunction start;
203
204 The engine will call this to let the driver know that some client
205 has requested a new buffer size. The stop function will be called
206 prior to this, and the start function after this one has returned.
207
208 JackDriverBufSizeFunction bufsize;
209 */
210
211 /* define the fields here... */
212 #define JACK_DRIVER_DECL \
213 jack_time_t period_usecs; \
214 jack_time_t last_wait_ust; \
215 void *handle; \
216 struct _jack_client_internal * internal_client; \
217 void (*finish)(struct _jack_driver *);\
218 JackDriverAttachFunction attach; \
219 JackDriverDetachFunction detach; \
220 JackDriverReadFunction read; \
221 JackDriverWriteFunction write; \
222 JackDriverNullCycleFunction null_cycle; \
223 JackDriverStopFunction stop; \
224 JackDriverStartFunction start; \
225 JackDriverBufSizeFunction bufsize;
226
227 JACK_DRIVER_DECL /* expand the macro */
228
229 } jack_driver_t;
230
231
232 typedef jack_driver_desc_t * (*JackDriverDescFunction) ();
233
234 void jack_driver_init (jack_driver_t *);
235 void jack_driver_release (jack_driver_t *);
236
237 jack_driver_t *jack_driver_load (int argc, char **argv);
238 void jack_driver_unload (jack_driver_t *);
239
240
241 /****************************
242 *** Non-Threaded Drivers ***
243 ****************************/
244
245 /*
246 Call sequence summary:
247
248 1) engine loads driver via runtime dynamic linking
249 - calls jack_driver_load
250 - we call dlsym for "driver_initialize" and execute it
251 - driver_initialize calls jack_driver_nt_init
252 2) nt layer attaches to driver
253 3) nt layer starts driver
254 4) nt layer runs a thread, calling
255 while () {
256 driver->nt_run_ctcle();
257 }
258 5) nt layer stops driver
259 6) nt layer detaches driver
260 7) engine calls driver `finish' routine which calls jack_driver_nt_finish
261
262 Note that stop/start may be called multiple times in the event of an
263 error return from the `wait' function.
264
265
266 */
267
268 struct _jack_driver_nt;
269
270 typedef int (*JackDriverNTAttachFunction)(struct _jack_driver_nt *);
271 typedef int (*JackDriverNTDetachFunction)(struct _jack_driver_nt *);
272 typedef int (*JackDriverNTStopFunction)(struct _jack_driver_nt *);
273 typedef int (*JackDriverNTStartFunction)(struct _jack_driver_nt *);
274 typedef int (*JackDriverNTBufSizeFunction)(struct _jack_driver_nt *,
275 jack_nframes_t nframes);
276 typedef int (*JackDriverNTRunCycleFunction)(struct _jack_driver_nt *);
277
278 typedef struct _jack_driver_nt {
279
280 #define JACK_DRIVER_NT_DECL \
281 JACK_DRIVER_DECL \
282 struct _jack_engine * engine; \
283 volatile int nt_run; \
284 pthread_t nt_thread; \
285 pthread_mutex_t nt_run_lock; \
286 JackDriverNTAttachFunction nt_attach; \
287 JackDriverNTDetachFunction nt_detach; \
288 JackDriverNTStopFunction nt_stop; \
289 JackDriverNTStartFunction nt_start; \
290 JackDriverNTBufSizeFunction nt_bufsize; \
291 JackDriverNTRunCycleFunction nt_run_cycle;
292 #define nt_read read
293 #define nt_write write
294 #define nt_null_cycle null_cycle
295
296 JACK_DRIVER_NT_DECL
297
298
299 } jack_driver_nt_t;
300
301 void jack_driver_nt_init (jack_driver_nt_t * driver);
302 void jack_driver_nt_finish (jack_driver_nt_t * driver);
303
304
305 #endif /* __jack_driver_h__ */
306
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.