usr/src/uts/common/sys/audiovar.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License, Version 1.0 only
   6  * (the "License").  You may not use this file except in compliance
   7  * with the License.
   8  *
   9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10  * or http://www.opensolaris.org/os/licensing.
  11  * See the License for the specific language governing permissions
  12  * and limitations under the License.
  13  *
  14  * When distributing Covered Code, include this CDDL HEADER in each
  15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16  * If applicable, add the following below this CDDL HEADER, with the
  17  * fields enclosed by brackets "[]" replaced with your own identifying
  18  * information: Portions Copyright [yyyy] [name of copyright owner]
  19  *
  20  * CDDL HEADER END
  21  */
  22 /*
  23  * Copyright (c) 1991-1992, 1997-2000 by Sun Microsystems, Inc.
  24  * All rights reserved.
  25  */
  26
  27 #ifndef _SYS_AUDIOVAR_H
  28 #define _SYS_AUDIOVAR_H
  29
  30 #pragma ident   "%Z%%M% %I%     %E% SMI"
  31
  32 /*
  33  * The audio driver is divided into generic (device-independent) and
  34  * device-specific modules.  The generic routines handle most STREAMS
  35  * protocol issues, communicating with the device-specific code via
  36  * function callouts and a chained control block structure.
  37  *
  38  * Separate control block lists are maintained for reading (record) and
  39  * writing (play).  These control blocks simulate a chained-DMA
  40  * structure, in that each block controls the transfer of data between
  41  * the device and a single contiguous memory segment.
  42  *
  43  * The command block contains buffer start and stop addresses, a link
  44  * address to the next block in the chain, a 'done' flag, a 'skip' flag
  45  * (indicating that this command block contains no data), and a pointer
  46  * to the STREAMS data block structure which is private to the generic
  47  * driver.
  48  *
  49  * The device-specific audio driver code is expected to honor the 'skip'
  50  * flag and set the 'done' flag when it has completed processing the
  51  * command block (i.e., the data transfer, if any, is complete).  For
  52  * record command blocks, it is also expected to add to the 'data'
  53  * pointer the number of bytes successfully read from the device.
  54  *
  55  * The device-specific driver module must initialize the static STREAMS
  56  * control structures and must provide an identify routine (sbus-only),
  57  * an attach routine, and an open routine.  The open routine verifies the
  58  * device unit number and calls the generic open routine with the address
  59  * of the audio_state structure for that unit.
  60  *
  61  * The generic audio driver makes calls to the device-specific code
  62  * through an ops-vector table.  The following routines must be provided:
  63  *
  64  * The 'close' routine is called after either the play or record stream
  65  * is closed.  It may perform device-specific cleanup and initialization.
  66  *
  67  * void dev_close(as)
  68  *      aud_stream_t            *as;    // Pointer to audio device state
  69  *
  70  *
  71  * The 'ioctl' routine is called from the STREAMS write put procedure
  72  * when a non-generic ioctl is encountered (AUDIO_SETINFO, AUDIO_GETINFO,
  73  * and AUDIO_DRAIN are the generic ioctls).  Any required data mblk_t is
  74  * allocated; its address is given by mp->b_cont (if this is a read/write
  75  * ioctl, the user-supplied buffer at mp->b_cont is reused).  If data is
  76  * successfully returned, the iocp->ioc_count field should be set with
  77  * the number of bytes returned.  If an error occurs, the 'ioctl' routine
  78  * should set iocp->ioc_error to the appropriate error code.  Otherwise,
  79  * the returned value should be AUDRETURN_CHANGE if a device state change
  80  * occurred (in which case a signal is sent to the control device, if
  81  * any) and AUDRETURN_NOCHANGE if no signal should be sent. If the ioctl
  82  * can not complete right away, it should return AUDRETURN_DELAYED
  83  * indicating that it will ack the ioctl at a later time.
  84  *
  85  * aud_return_t dev_ioctl(as, mp, iocp)
  86  *      aud_stream_t    *as;            // Pointer to audio device state
  87  *      mblk_t          *mp;            // ioctl STREAMS message block
  88  *      struct iocblk   *iocp;          // M_IOCTL message data
  89  *
  90  *
  91  * The 'start' routine is called to start i/o.  Ordinarily, it is called
  92  * from the device-specific 'queuecmd' routine, but it is also called
  93  * when paused output is resumed.
  94  *
  95  * void dev_start(as)
  96  *      aud_stream_t    *as;            // Pointer to audio device state
  97  *
  98  *
  99  * The 'stop' routine is called to stop i/o.  It is called when i/o is
 100  * paused, flushed, or the device is closed.  Note that currently queued
 101  * command blocks should not be flushed by this routine, since i/o may be
 102  * resumed from the current point.
 103  *
 104  * void dev_stop(as)
 105  *      aud_stream_t    *as;            // Pointer to audio device state
 106  *
 107  *
 108  * The 'setflag' routine is called to get a single device-specific flag.
 109  * The flag argument is either AUD_ACTIVE (return the active flag) or
 110  * AUD_ERRORRESET (zero the error flag, returning its previous value).
 111  * (The val argument is currently ignored.)
 112  *
 113  * void dev_setflag(as, flag, val)
 114  *      aud_stream_t    *as;            // Pointer to audio device state
 115  *      enum aud_opflag flag;           // AUD_ACTIVE || AUD_ERRORESET
 116  *
 117  *
 118  * The 'setinfo' routine is called to get or set device-specific fields
 119  * in the audio state structure.  If mp is NULL, the sample counters and
 120  * active flags should be set in v.  If mp is not NULL, then
 121  * mp->b_cont->data points to the audio_info_t structure supplied in an
 122  * AUDIO_SETINFO ioctl (ip).  All device-specific fields (gains, ports,
 123  * sample counts) in both v and the device itself should be updated, as
 124  * long as the corresponding field in ip is not set to AUD_INIT_VALUE.
 125  * When the sample counters are set, the value returned in v should be
 126  * the previous value. If the setinfo can not complete right away, it
 127  * should return AUDRETURN_DELAYED indicating that it will ack the ioctl
 128  * at a later time. If an error occurs on setinfo, the iocp->ioc_error
 129  * should be set as in dev_ioctl
 130  *
 131  * aud_return_t dev_setinfo(as, mp, iocp)
 132  *      aud_stream_t    *as;            // Pointer to audio device state
 133  *      mblk_t          *mp;            // user info structure or NULL
 134  *      struct iocblk   *iocp;          // M_IOCTL message data
 135  *
 136  *
 137  * The 'queuecmd' routine is called whenever a new command block is
 138  * linked into the chained command list.  The device-specific code must
 139  * ensure that the command is enqueued to the device and that i/o, if not
 140  * currently active, is started.
 141  *
 142  * void dev_queuecmd(as, cmdp)
 143  *      aud_stream_t    *as;            // Pointer to audio device state
 144  *      struct aud_cmd  *cmdp;          // new command block to queue
 145  *
 146  *
 147  * The 'flushcmd' routine is called whenever the chained command list is
 148  * flushed.  It is only called after i/o has been stopped (via the 'stop'
 149  * routine) and after the command list in the audio state structure has
 150  * been cleared.  The device-specific code should flush the device's
 151  * queued command list.
 152  *
 153  * void dev_flushcmd(as)
 154  *      aud_stream_t    *as;            // Pointer to audio device state
 155  */
 156
 157 #ifdef __cplusplus
 158 extern "C" {
 159 #endif
 160
 161
 162 /*
 163  * Various generic audio driver constants
 164  */
 165 #define AUD_INITVALUE   (~0)
 166 #define Modify(X)       ((uint_t)(X) != AUD_INITVALUE)
 167 #define Modifys(X)      ((X) != (ushort_t)AUD_INITVALUE)
 168 #define Modifyc(X)      ((X) != (uchar_t)AUD_INITVALUE)
 169
 170
 171 /*
 172  * Define the virtual chained-DMA control structure
 173  */
 174 typedef struct aud_cmd aud_cmd_t;
 175 struct aud_cmd {
 176         /*
 177          * Data pointers
 178          */
 179         uchar_t *data;          /* address of next transfer */
 180         uchar_t *enddata;       /* address+1 of last transfer */
 181
 182         /*
 183          * Linked list management
 184          */
 185         aud_cmd_t *next;        /* pointer to next or NULL */
 186         aud_cmd_t *lastfragment; /* last fragment in packet */
 187
 188         /*
 189          * Flags
 190          */
 191         uint_t :0;              /* Force word alignment */
 192         uchar_t skip;           /* TRUE => no xfers on buffer */
 193         uchar_t done;           /* TRUE => buffer processed */
 194
 195         uchar_t iotype;         /* copy of mblk's db_type */
 196         boolean_t processed;    /* TRUE if processed cmd at head of list */
 197
 198         audtrace_hdr_t tracehdr; /* trace info */
 199
 200         /*
 201          * Device-independent private, opaque storage
 202          */
 203         void *dihandle;
 204 };
 205
 206
 207 /*
 208  * Define the list-head for queued control structures
 209  */
 210 typedef struct aud_cmdlist aud_cmdlist_t;
 211 struct aud_cmdlist {
 212         aud_cmd_t *head;        /* First queued command block */
 213         aud_cmd_t *tail;        /* Last queued command block */
 214         aud_cmd_t *free;        /* Head of free list */
 215 };
 216
 217
 218 /*
 219  * Define possible return values from the setinfo and ioctl calls
 220  */
 221 typedef enum {
 222         AUDRETURN_CHANGE,
 223         AUDRETURN_NOCHANGE,
 224         AUDRETURN_DELAYED
 225 } aud_return_t;
 226
 227
 228 /*
 229  * Define legal values for the 'flag' argument to the 'setflag' callout
 230  */
 231 enum aud_opflag {
 232         AUD_ACTIVE,             /* active flag */
 233         AUD_ERRORRESET          /* error flag (reset after read) */
 234 };
 235
 236
 237 /*
 238  * The audio stream type determines the legal operations for a stream in the
 239  * generic portion of an audio driver.
 240  */
 241 typedef enum {
 242         AUDTYPE_NONE = 00,      /* Not a legal device */
 243         AUDTYPE_DATA = 01,      /* Data, IOCTL, etc., but not signals */
 244         AUDTYPE_CONTROL = 02,   /* IOCTL, etc., but not M_DATA */
 245         AUDTYPE_BOTH = 03       /* Anything is ok, signals delivered */
 246 } aud_streamtype_t;
 247
 248 #define ISPLAYSTREAM(as)        (ISDATASTREAM(as) && (as->openflag & FWRITE))
 249 #define ISRECORDSTREAM(as)      (ISDATASTREAM(as) && (as->openflag & FREAD))
 250 #define ISDATASTREAM(as)        (((as->type) & (AUDTYPE_DATA)) != 0)
 251 #define ISCONTROLSTREAM(as)     (((as->type) & (AUDTYPE_CONTROL)) != 0)
 252
 253
 254 typedef enum {
 255         AUDMODE_NONE = 00,      /* Not a legal mode */
 256         AUDMODE_AUDIO = 01,     /* Transparent audio mode */
 257         AUDMODE_HDLC = 02       /* HDLC datacomm mode */
 258 } aud_modetype_t;
 259
 260
 261 /*
 262  * This structure describes the state of the audio device and queues
 263  */
 264 typedef struct aud_state aud_state_t;
 265 struct aud_state {
 266         /*
 267          * Back-pointer to the device-dependent audio state
 268          */
 269         void *ddstate;
 270
 271         /*
 272          * Device-independent audio state
 273          */
 274         uint_t monitor_gain;    /* input to output mix: 0 - 255 */
 275         boolean_t output_muted; /* true if output is muted */
 276         uint_t hw_features;     /* hardware features this driver supports */
 277         uint_t sw_features;     /* software features this driver supports */
 278         uint_t sw_features_enabled;     /* supported SW features enabled */
 279
 280         /*
 281          * Audio ops vector
 282          */
 283         struct aud_ops *ops;
 284 };
 285
 286 /*
 287  * STREAMS routines pass the address of a 'struct audstream' when calling
 288  * put and service procedures.  This structure points to the STREAMS
 289  * queues and back to the containing 'struct aud_state'.
 290  */
 291 typedef struct aud_stream aud_stream_t;
 292 struct aud_stream {
 293         aud_state_t *distate;   /* pointer to driver data */
 294         aud_streamtype_t type;  /* defines legal operations */
 295         aud_modetype_t mode;    /* Audio or HDLC data */
 296         boolean_t signals_okay; /* Can send sigs up this aud_stream */
 297
 298         /*
 299          * Sideways pointers to related aud_stream_t structures
 300          */
 301         aud_stream_t *control_as; /* control stream */
 302         aud_stream_t *output_as; /* play stream */
 303         aud_stream_t *input_as; /* record stream */
 304
 305         /*
 306          * Software state
 307          */
 308         aud_cmdlist_t cmdlist;  /* command chains */
 309         audio_prinfo_t info;    /* info for this stream side */
 310         int openflag;           /* open flag & (FREAD|FWRITE) */
 311         boolean_t draining;     /* TRUE if output draining */
 312         int maxfrag_size;       /* max aud_cmd_t fragment size */
 313         struct {
 314                 int action;             /* IOCTL action */
 315                 mblk_t *mp;             /* Pending ioctl */
 316                 ulong_t priv;           /* private state */
 317                 uint_t ioctl_id;        /* from ioc_id */
 318                 cred_t *credp;          /* from ioc_cr */
 319                 int reason;             /* HW implementation dep. reason */
 320                 boolean_t (*handler)(aud_stream_t *, mblk_t *, int,
 321                     boolean_t);
 322         } dioctl;               /* Delayed ioctls */
 323         uint_t sequence;        /* packet sequence number */
 324
 325         /*
 326          * STREAMS information
 327          */
 328         queue_t *readq;         /* STREAMS read queue */
 329         queue_t *writeq;        /* STREAMS write queue */
 330         queue_t *traceq;        /* STREAMS trace queue */
 331
 332         /*
 333          * OS-Dependent information
 334          *
 335          * NB - For now we lock on a per-unit basis, so this points to
 336          * the mutex of the unit it belongs to.  Other arrangements can
 337          * be made later
 338          *
 339          * The condition variable in a output stream is used to wait for
 340          * output to drain.
 341          *
 342          * The condition variable in a control stream is used to wait on
 343          * open if the device is in use.
 344          */
 345         kmutex_t *lock;         /* low-level lock */
 346         kcondvar_t cv;          /* generic condition variable */
 347 };
 348
 349 #define LOCK_AS(as)     mutex_enter((as)->lock)
 350 #define UNLOCK_AS(as)   mutex_exit((as)->lock)
 351 #define ASSERT_ASLOCKED(as) ASSERT(MUTEX_HELD((as)->lock))
 352
 353 #define AUDIOCACTION_INIT       (0) /* no ioctl in progress */
 354 #define AUDIOCACTION_WAIT       (1) /* copyout response not received */
 355 #define AUDIOCACTION_WAITING    (2) /* read to ack/nak */
 356
 357
 358 /*
 359  * Argument for audio_sensig
 360  */
 361 typedef enum {
 362         AUDIO_SENDSIG_NONE = 0, /* Default */
 363         AUDIO_SENDSIG_EXPLICIT, /* Send signal up this aud_stream only */
 364         AUDIO_SENDSIG_ALL       /* Send signal up all related aud_streams */
 365 } audio_sendsig_t;
 366
 367
 368 /*
 369  * Define the ops-vector table for device-specific callouts
 370  *
 371  * close        close routine
 372  * ioctl        ioctl routine
 373  * start        routine to start I/O on a stream
 374  * stop         routine to stop I/O on a stream
 375  * setflag      routine to get or set a flag value
 376  * setinfo      routine to get or set the audio state structure
 377  * queuecmd     routine to queue a command on the HW command list
 378  * flushcmd     routine to flush the HW's command list
 379  */
 380 typedef struct aud_ops  aud_ops_t;
 381 struct aud_ops {
 382 #ifdef __STDC__
 383         void (*close)(aud_stream_t *);
 384         aud_return_t (*ioctl)(aud_stream_t *, queue_t *, mblk_t *);
 385         aud_return_t (*mproto)(aud_stream_t *, mblk_t *);
 386         void (*start)(aud_stream_t *);
 387         void (*stop)(aud_stream_t *);
 388         uint_t (*setflag)(aud_stream_t *, enum aud_opflag, uint_t);
 389         aud_return_t (*setinfo)(aud_stream_t *, mblk_t *, int *);
 390         void (*queuecmd)(aud_stream_t *, aud_cmd_t *);
 391         void (*flushcmd)(aud_stream_t *);
 392 #else /* __STDC__ */
 393         void (*close)();
 394         aud_return_t (*ioctl)();
 395         aud_return_t (*mproto)();
 396         void (*start)();
 397         void (*stop)();
 398         uint_t (*setflag)();
 399         aud_return_t (*setinfo)();
 400         void (*queuecmd)();
 401         void (*flushcmd)();
 402 #endif /* __STDC__ */
 403 };
 404
 405
 406 /*
 407  * Define pseudo-routine names for the device-specific callouts
 408  */
 409 #define AUD_CLOSE(A)            (*(A)->distate->ops->close)(A)
 410 #define AUD_IOCTL(A, Q, M)      (*(A)->distate->ops->ioctl)(A, Q, M)
 411 #define AUD_MPROTO(A, M)        (*(A)->distate->ops->mproto)(A, M)
 412 #define AUD_START(A)            (*(A)->distate->ops->start)(A)
 413 #define AUD_STOP(A)             (*(A)->distate->ops->stop)(A)
 414 #define AUD_SETFLAG(A, F, X)    (*(A)->distate->ops->setflag)(A, F, X)
 415 #define AUD_GETFLAG(A, F)       (*(A)->distate->ops->setflag)(A, F, \
 416     AUD_INITVALUE)
 417 #define AUD_SETINFO(A, M, E)    (*(A)->distate->ops->setinfo)(A, M, E)
 418 #define AUD_GETINFO(A)          (*(A)->distate->ops->setinfo)(A, NULL, NULL)
 419 #define AUD_QUEUECMD(A, C)      (*(A)->distate->ops->queuecmd)(A, C)
 420 #define AUD_FLUSHCMD(A)         (*(A)->distate->ops->flushcmd)(A)
 421
 422
 423 /*
 424  * Device Independent Audio driver function prototypes
 425  */
 426 #ifdef __STDC__
 427 extern int      audio_open(aud_stream_t *, queue_t *, dev_t *, int, int);
 428 extern int      audio_close(queue_t *, int, cred_t *);
 429 extern int      audio_wput(queue_t *, mblk_t *);
 430 extern int      audio_wsrv(queue_t *);
 431 extern int      audio_rput(queue_t *, mblk_t *);
 432 extern int      audio_rsrv(queue_t *);
 433 extern void     audio_gc_output(aud_stream_t *);
 434 extern void     audio_process_output(aud_stream_t *);
 435 extern void     audio_process_input(aud_stream_t *);
 436 extern void     audio_sendsig(aud_stream_t *, audio_sendsig_t);
 437 extern void     audio_flush_cmdlist(aud_stream_t *);
 438 extern void     audio_ack(queue_t *, mblk_t *, int);
 439 extern void     audio_copyout(queue_t *, mblk_t *, caddr_t, uint_t);
 440 extern void     audio_pause_play(aud_stream_t *);
 441 extern void     audio_pause_record(aud_stream_t *);
 442 extern void     audio_resume_play(aud_stream_t *);
 443 extern void     audio_resume_record(aud_stream_t *);
 444 extern void     audio_trace(aud_stream_t *, aud_cmd_t *);
 445 extern void     audio_trace_hdr(aud_stream_t *, audtrace_hdr_t *);
 446 #else /* __STDC__ */
 447 extern int      audio_open();
 448 extern int      audio_close();
 449 extern int      audio_wput();
 450 extern int      audio_wsrv();
 451 extern int      audio_rput();
 452 extern int      audio_rsrv();
 453 extern void     audio_gc_output();
 454 extern void     audio_process_output();
 455 extern void     audio_process_input();
 456 extern void     audio_sendsig();
 457 extern void     audio_flush_cmdlist();
 458 extern void     audio_ack();
 459 extern void     audio_copyout();
 460 extern void     audio_pause_play();
 461 extern void     audio_pause_record();
 462 extern void     audio_resume_play();
 463 extern void     audio_resume_record();
 464 extern void     audio_trace()
 465 extern void     audio_trace_hdr();
 466 #endif /* __STDC__ */
 467
 468 #ifdef __cplusplus
 469 }
 470 #endif
 471
 472 #endif /* _SYS_AUDIOVAR_H */