Jack2 1.9.6
|
00001 /* 00002 Copyright (C) 2001 Paul Davis 00003 00004 This program is free software; you can redistribute it and/or modify 00005 it under the terms of the GNU General Public License as published by 00006 the Free Software Foundation; either version 2 of the License, or 00007 (at your option) any later version. 00008 00009 This program is distributed in the hope that it will be useful, 00010 but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 GNU General Public License for more details. 00013 00014 You should have received a copy of the GNU General Public License 00015 along with this program; if not, write to the Free Software 00016 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00017 00018 $Id: driver.h,v 1.2 2005/11/23 11:24:29 letz Exp $ 00019 */ 00020 00021 #ifndef __jack_driver_h__ 00022 #define __jack_driver_h__ 00023 00024 #include <pthread.h> 00025 #include "types.h" 00026 #include "jslist.h" 00027 #include "driver_interface.h" 00028 00029 typedef float gain_t; 00030 typedef long channel_t; 00031 00032 typedef enum { 00033 Lock = 0x1, 00034 NoLock = 0x2, 00035 Sync = 0x4, 00036 NoSync = 0x8 00037 } ClockSyncStatus; 00038 00039 typedef void (*ClockSyncListenerFunction)(channel_t, ClockSyncStatus, void*); 00040 00041 typedef struct 00042 { 00043 unsigned long id; 00044 ClockSyncListenerFunction function; 00045 void *arg; 00046 } 00047 ClockSyncListener; 00048 00049 struct _jack_engine; 00050 struct _jack_driver; 00051 00052 typedef int (*JackDriverAttachFunction)(struct _jack_driver *, 00053 struct _jack_engine *); 00054 typedef int (*JackDriverDetachFunction)(struct _jack_driver *, 00055 struct _jack_engine *); 00056 typedef int (*JackDriverReadFunction)(struct _jack_driver *, 00057 jack_nframes_t nframes); 00058 typedef int (*JackDriverWriteFunction)(struct _jack_driver *, 00059 jack_nframes_t nframes); 00060 typedef int (*JackDriverNullCycleFunction)(struct _jack_driver *, 00061 jack_nframes_t nframes); 00062 typedef int (*JackDriverStopFunction)(struct _jack_driver *); 00063 typedef int (*JackDriverStartFunction)(struct _jack_driver *); 00064 typedef int (*JackDriverBufSizeFunction)(struct _jack_driver *, 00065 jack_nframes_t nframes); 00066 /* 00067 Call sequence summary: 00068 00069 1) engine loads driver via runtime dynamic linking 00070 - calls jack_driver_load 00071 - we call dlsym for "driver_initialize" and execute it 00072 2) engine attaches to driver 00073 3) engine starts driver 00074 4) driver runs its own thread, calling 00075 while () { 00076 driver->wait (); 00077 driver->engine->run_cycle () 00078 } 00079 5) engine stops driver 00080 6) engine detaches from driver 00081 7) engine calls driver `finish' routine 00082 00083 Note that stop/start may be called multiple times in the event of an 00084 error return from the `wait' function. 00085 */ 00086 00087 typedef struct _jack_driver 00088 { 00089 00090 /* The _jack_driver structure fields are included at the beginning of 00091 each driver-specific structure using the JACK_DRIVER_DECL macro, 00092 which is defined below. The comments that follow describe each 00093 common field. 00094 00095 The driver should set this to be the interval it expects to elapse 00096 between returning from the `wait' function. if set to zero, it 00097 implies that the driver does not expect regular periodic wakeups. 00098 00099 jack_time_t period_usecs; 00100 00101 00102 The driver should set this within its "wait" function to indicate 00103 the UST of the most recent determination that the engine cycle 00104 should run. it should not be set if the "extra_fd" argument of 00105 the wait function is set to a non-zero value. 00106 00107 jack_time_t last_wait_ust; 00108 00109 00110 These are not used by the driver. They should not be written to or 00111 modified in any way 00112 00113 void *handle; 00114 struct _jack_internal_client *internal_client; 00115 00116 This should perform any cleanup associated with the driver. it will 00117 be called when jack server process decides to get rid of the 00118 driver. in some systems, it may not be called at all, so the driver 00119 should never rely on a call to this. it can set it to NULL if 00120 it has nothing do do. 00121 00122 void (*finish)(struct _jack_driver *); 00123 00124 00125 The JACK engine will call this when it wishes to attach itself to 00126 the driver. the engine will pass a pointer to itself, which the driver 00127 may use in anyway it wishes to. the driver may assume that this 00128 is the same engine object that will make `wait' calls until a 00129 `detach' call is made. 00130 00131 JackDriverAttachFunction attach; 00132 00133 00134 The JACK engine will call this when it is finished using a driver. 00135 00136 JackDriverDetachFunction detach; 00137 00138 00139 The JACK engine will call this when it wants to wait until the 00140 driver decides that its time to process some data. the driver returns 00141 a count of the number of audioframes that can be processed. 00142 00143 it should set the variable pointed to by `status' as follows: 00144 00145 zero: the wait completed normally, processing may begin 00146 negative: the wait failed, and recovery is not possible 00147 positive: the wait failed, and the driver stopped itself. 00148 a call to `start' will return the driver to 00149 a correct and known state. 00150 00151 the driver should also fill out the `delayed_usecs' variable to 00152 indicate any delay in its expected periodic execution. for example, 00153 if it discovers that its return from poll(2) is later than it 00154 expects it to be, it would place an estimate of the delay 00155 in this variable. the engine will use this to decide if it 00156 plans to continue execution. 00157 00158 JackDriverWaitFunction wait; 00159 00160 00161 The JACK engine will call this to ask the driver to move 00162 data from its inputs to its output port buffers. it should 00163 return 0 to indicate successful completion, negative otherwise. 00164 00165 This function will always be called after the wait function (above). 00166 00167 JackDriverReadFunction read; 00168 00169 00170 The JACK engine will call this to ask the driver to move 00171 data from its input port buffers to its outputs. it should 00172 return 0 to indicate successful completion, negative otherwise. 00173 00174 this function will always be called after the read function (above). 00175 00176 JackDriverWriteFunction write; 00177 00178 00179 The JACK engine will call this after the wait function (above) has 00180 been called, but for some reason the engine is unable to execute 00181 a full "cycle". the driver should do whatever is necessary to 00182 keep itself running correctly, but cannot reference ports 00183 or other JACK data structures in any way. 00184 00185 JackDriverNullCycleFunction null_cycle; 00186 00187 00188 The engine will call this when it plans to stop calling the `wait' 00189 function for some period of time. the driver should take 00190 appropriate steps to handle this (possibly no steps at all). 00191 NOTE: the driver must silence its capture buffers (if any) 00192 from within this function or the function that actually 00193 implements the change in state. 00194 00195 JackDriverStopFunction stop; 00196 00197 00198 The engine will call this to let the driver know that it plans 00199 to start calling the `wait' function on a regular basis. the driver 00200 should take any appropriate steps to handle this (possibly no steps 00201 at all). NOTE: The driver may wish to silence its playback buffers 00202 (if any) from within this function or the function that actually 00203 implements the change in state. 00204 00205 JackDriverStartFunction start; 00206 00207 The engine will call this to let the driver know that some client 00208 has requested a new buffer size. The stop function will be called 00209 prior to this, and the start function after this one has returned. 00210 00211 JackDriverBufSizeFunction bufsize; 00212 */ 00213 00214 /* define the fields here... */ 00215 #define JACK_DRIVER_DECL \ 00216 jack_time_t period_usecs; \ 00217 jack_time_t last_wait_ust; \ 00218 void *handle; \ 00219 struct _jack_client_internal * internal_client; \ 00220 void (*finish)(struct _jack_driver *);\ 00221 JackDriverAttachFunction attach; \ 00222 JackDriverDetachFunction detach; \ 00223 JackDriverReadFunction read; \ 00224 JackDriverWriteFunction write; \ 00225 JackDriverNullCycleFunction null_cycle; \ 00226 JackDriverStopFunction stop; \ 00227 JackDriverStartFunction start; \ 00228 JackDriverBufSizeFunction bufsize; 00229 00230 JACK_DRIVER_DECL /* expand the macro */ 00231 } 00232 jack_driver_t; 00233 00234 typedef jack_driver_desc_t * (*JackDriverDescFunction) (); 00235 00236 void jack_driver_init (jack_driver_t *); 00237 void jack_driver_release (jack_driver_t *); 00238 00239 jack_driver_t *jack_driver_load (int argc, char **argv); 00240 void jack_driver_unload (jack_driver_t *); 00241 00242 /**************************** 00243 *** Non-Threaded Drivers *** 00244 ****************************/ 00245 00246 /* 00247 Call sequence summary: 00248 00249 1) engine loads driver via runtime dynamic linking 00250 - calls jack_driver_load 00251 - we call dlsym for "driver_initialize" and execute it 00252 - driver_initialize calls jack_driver_nt_init 00253 2) nt layer attaches to driver 00254 3) nt layer starts driver 00255 4) nt layer runs a thread, calling 00256 while () { 00257 driver->nt_run_ctcle(); 00258 } 00259 5) nt layer stops driver 00260 6) nt layer detaches driver 00261 7) engine calls driver `finish' routine which calls jack_driver_nt_finish 00262 00263 Note that stop/start may be called multiple times in the event of an 00264 error return from the `wait' function. 00265 */ 00266 00267 struct _jack_driver_nt; 00268 00269 typedef int (*JackDriverNTAttachFunction)(struct _jack_driver_nt *); 00270 typedef int (*JackDriverNTDetachFunction)(struct _jack_driver_nt *); 00271 typedef int (*JackDriverNTStopFunction)(struct _jack_driver_nt *); 00272 typedef int (*JackDriverNTStartFunction)(struct _jack_driver_nt *); 00273 typedef int (*JackDriverNTBufSizeFunction)(struct _jack_driver_nt *, 00274 jack_nframes_t nframes); 00275 typedef int (*JackDriverNTRunCycleFunction)(struct _jack_driver_nt *); 00276 00277 typedef struct _jack_driver_nt 00278 { 00279 #define JACK_DRIVER_NT_DECL \ 00280 JACK_DRIVER_DECL \ 00281 struct _jack_engine * engine; \ 00282 volatile int nt_run; \ 00283 pthread_t nt_thread; \ 00284 pthread_mutex_t nt_run_lock; \ 00285 JackDriverNTAttachFunction nt_attach; \ 00286 JackDriverNTDetachFunction nt_detach; \ 00287 JackDriverNTStopFunction nt_stop; \ 00288 JackDriverNTStartFunction nt_start; \ 00289 JackDriverNTBufSizeFunction nt_bufsize; \ 00290 JackDriverNTRunCycleFunction nt_run_cycle; 00291 #define nt_read read 00292 #define nt_write write 00293 #define nt_null_cycle null_cycle 00294 00295 JACK_DRIVER_NT_DECL 00296 } 00297 jack_driver_nt_t; 00298 00299 void jack_driver_nt_init (jack_driver_nt_t * driver); 00300 void jack_driver_nt_finish (jack_driver_nt_t * driver); 00301 00302 #endif /* __jack_driver_h__ */