Jack2 1.9.6

driver.h

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__ */