Compiles on Windows again.
[jack2.git] / linux / driver.h
blob4e353b4b7596108902b24f74fdb0c6af99f35dc3
1 /*
2 Copyright (C) 2001 Paul Davis
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.
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.
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.
18 $Id: driver.h,v 1.2 2005/11/23 11:24:29 letz Exp $
21 #ifndef __jack_driver_h__
22 #define __jack_driver_h__
24 #include <pthread.h>
25 #include "types.h"
26 #include "jslist.h"
27 #include "driver_interface.h"
29 typedef float gain_t;
30 typedef long channel_t;
32 typedef enum {
33 Lock = 0x1,
34 NoLock = 0x2,
35 Sync = 0x4,
36 NoSync = 0x8
37 } ClockSyncStatus;
39 typedef void (*ClockSyncListenerFunction)(channel_t, ClockSyncStatus, void*);
41 typedef struct
43 unsigned long id;
44 ClockSyncListenerFunction function;
45 void *arg;
47 ClockSyncListener;
49 struct _jack_engine;
50 struct _jack_driver;
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);
67 Call sequence summary:
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 ()
79 5) engine stops driver
80 6) engine detaches from driver
81 7) engine calls driver `finish' routine
83 Note that stop/start may be called multiple times in the event of an
84 error return from the `wait' function.
87 typedef struct _jack_driver
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.
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.
99 jack_time_t period_usecs;
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.
107 jack_time_t last_wait_ust;
110 These are not used by the driver. They should not be written to or
111 modified in any way
113 void *handle;
114 struct _jack_internal_client *internal_client;
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.
122 void (*finish)(struct _jack_driver *);
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.
131 JackDriverAttachFunction attach;
134 The JACK engine will call this when it is finished using a driver.
136 JackDriverDetachFunction detach;
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.
143 it should set the variable pointed to by `status' as follows:
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.
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.
158 JackDriverWaitFunction wait;
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.
165 This function will always be called after the wait function (above).
167 JackDriverReadFunction read;
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.
174 this function will always be called after the read function (above).
176 JackDriverWriteFunction write;
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.
185 JackDriverNullCycleFunction null_cycle;
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.
195 JackDriverStopFunction stop;
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.
205 JackDriverStartFunction start;
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.
211 JackDriverBufSizeFunction bufsize;
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;
230 JACK_DRIVER_DECL /* expand the macro */
232 jack_driver_t;
234 typedef jack_driver_desc_t * (*JackDriverDescFunction) ();
236 void jack_driver_init (jack_driver_t *);
237 void jack_driver_release (jack_driver_t *);
239 jack_driver_t *jack_driver_load (int argc, char **argv);
240 void jack_driver_unload (jack_driver_t *);
242 /****************************
243 *** Non-Threaded Drivers ***
244 ****************************/
247 Call sequence summary:
249 1) engine loads driver via runtime dynamic linking
250 - calls jack_driver_load
251 - we call dlsym for "driver_initialize" and execute it
252 - driver_initialize calls jack_driver_nt_init
253 2) nt layer attaches to driver
254 3) nt layer starts driver
255 4) nt layer runs a thread, calling
256 while () {
257 driver->nt_run_ctcle();
259 5) nt layer stops driver
260 6) nt layer detaches driver
261 7) engine calls driver `finish' routine which calls jack_driver_nt_finish
263 Note that stop/start may be called multiple times in the event of an
264 error return from the `wait' function.
267 struct _jack_driver_nt;
269 typedef int (*JackDriverNTAttachFunction)(struct _jack_driver_nt *);
270 typedef int (*JackDriverNTDetachFunction)(struct _jack_driver_nt *);
271 typedef int (*JackDriverNTStopFunction)(struct _jack_driver_nt *);
272 typedef int (*JackDriverNTStartFunction)(struct _jack_driver_nt *);
273 typedef int (*JackDriverNTBufSizeFunction)(struct _jack_driver_nt *,
274 jack_nframes_t nframes);
275 typedef int (*JackDriverNTRunCycleFunction)(struct _jack_driver_nt *);
277 typedef struct _jack_driver_nt
279 #define JACK_DRIVER_NT_DECL \
280 JACK_DRIVER_DECL \
281 struct _jack_engine * engine; \
282 volatile int nt_run; \
283 pthread_t nt_thread; \
284 pthread_mutex_t nt_run_lock; \
285 JackDriverNTAttachFunction nt_attach; \
286 JackDriverNTDetachFunction nt_detach; \
287 JackDriverNTStopFunction nt_stop; \
288 JackDriverNTStartFunction nt_start; \
289 JackDriverNTBufSizeFunction nt_bufsize; \
290 JackDriverNTRunCycleFunction nt_run_cycle;
291 #define nt_read read
292 #define nt_write write
293 #define nt_null_cycle null_cycle
295 JACK_DRIVER_NT_DECL
297 jack_driver_nt_t;
299 void jack_driver_nt_init (jack_driver_nt_t * driver);
300 void jack_driver_nt_finish (jack_driver_nt_t * driver);
302 #endif /* __jack_driver_h__ */