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