Jack2: driver.h Source File

Jack2 1.9.12

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