Jack2  1.9.9
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 }
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 }
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 }
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__ */