include/sys/audioio.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 (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21 /*
  22  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
  23  * Use is subject to license terms.
  24  */
  25
  26 #ifndef _SYS_AUDIOIO_H
  27 #define _SYS_AUDIOIO_H
  28
  29 #include <sys/types.h>
  30 #include <sys/types32.h>
  31 #include <sys/time.h>
  32 #include <sys/ioccom.h>
  33
  34 /*
  35  * These are the ioctl calls for all Solaris audio devices, including
  36  * the x86 and SPARCstation audio devices.
  37  *
  38  * You are encouraged to design your code in a modular fashion so that
  39  * future changes to the interface can be incorporated with little
  40  * trouble.
  41  */
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 /*
  48  * This structure contains state information for audio device IO streams.
  49  */
  50 struct audio_prinfo {
  51         /*
  52          * The following values describe the audio data encoding.
  53          */
  54         uint_t sample_rate;     /* samples per second */
  55         uint_t channels;        /* number of interleaved channels */
  56         uint_t precision;       /* bit-width of each sample */
  57         uint_t encoding;        /* data encoding method */
  58
  59         /*
  60          * The following values control audio device configuration
  61          */
  62         uint_t gain;            /* gain level: 0 - 255 */
  63         uint_t port;            /* selected I/O port (see below) */
  64         uint_t avail_ports;     /* available I/O ports (see below) */
  65         uint_t mod_ports;       /* I/O ports that are modifiable (see below) */
  66         uint_t _xxx;            /* Reserved for future use */
  67
  68         uint_t buffer_size;     /* I/O buffer size */
  69
  70         /*
  71          * The following values describe driver state
  72          */
  73         uint_t samples;         /* number of samples converted */
  74         uint_t eof;             /* End Of File counter (play only) */
  75
  76         uchar_t pause;          /* non-zero for pause, zero to resume */
  77         uchar_t error;          /* non-zero if overflow/underflow */
  78         uchar_t waiting;        /* non-zero if a process wants access */
  79         uchar_t balance;        /* stereo channel balance */
  80
  81         ushort_t minordev;
  82
  83         /*
  84          * The following values are read-only state flags
  85          */
  86         uchar_t open;           /* non-zero if open access permitted */
  87         uchar_t active;         /* non-zero if I/O is active */
  88 };
  89 typedef struct audio_prinfo audio_prinfo_t;
  90
  91
  92 /*
  93  * This structure describes the current state of the audio device.
  94  */
  95 struct audio_info {
  96         /*
  97          * Per-stream information
  98          */
  99         audio_prinfo_t play;    /* output status information */
 100         audio_prinfo_t record;  /* input status information */
 101
 102         /*
 103          * Per-unit/channel information
 104          */
 105         uint_t monitor_gain;    /* input to output mix: 0 - 255 */
 106         uchar_t output_muted;   /* non-zero if output is muted */
 107         uchar_t ref_cnt;        /* driver reference count, read only */
 108         uchar_t _xxx[2];        /* Reserved for future use */
 109         uint_t hw_features;     /* hardware features this driver supports */
 110         uint_t sw_features;     /* supported SW features */
 111         uint_t sw_features_enabled;     /* supported SW feat. enabled */
 112 };
 113 typedef struct audio_info audio_info_t;
 114
 115
 116 /*
 117  * Audio encoding types
 118  */
 119 #define AUDIO_ENCODING_NONE     (0)     /* no encoding assigned */
 120 #define AUDIO_ENCODING_ULAW     (1)     /* u-law encoding       */
 121 #define AUDIO_ENCODING_ALAW     (2)     /* A-law encoding       */
 122 #define AUDIO_ENCODING_LINEAR   (3)     /* Signed Linear PCM encoding   */
 123 #define AUDIO_ENCODING_DVI      (104)   /* DVI ADPCM            */
 124 #define AUDIO_ENCODING_LINEAR8  (105)   /* 8 bit UNSIGNED       */
 125
 126 /*
 127  * These ranges apply to record, play, and monitor gain values
 128  */
 129 #define AUDIO_MIN_GAIN  (0)     /* minimum gain value */
 130 #define AUDIO_MAX_GAIN  (255)   /* maximum gain value */
 131 #define AUDIO_MID_GAIN  (AUDIO_MAX_GAIN / 2)
 132
 133 /*
 134  * These values apply to the balance field to adjust channel gain values
 135  */
 136 #define AUDIO_LEFT_BALANCE      (0)     /* left channel only    */
 137 #define AUDIO_MID_BALANCE       (32)    /* equal left/right channel */
 138 #define AUDIO_RIGHT_BALANCE     (64)    /* right channel only   */
 139 #define AUDIO_BALANCE_SHIFT     (3)
 140
 141 /*
 142  * Generic minimum/maximum limits for number of channels, both modes
 143  */
 144 #define AUDIO_CHANNELS_MONO     (1)
 145 #define AUDIO_CHANNELS_STEREO   (2)
 146 #define AUDIO_MIN_PLAY_CHANNELS (AUDIO_CHANNELS_MONO)
 147 #define AUDIO_MAX_PLAY_CHANNELS (AUDIO_CHANNELS_STEREO)
 148 #define AUDIO_MIN_REC_CHANNELS  (AUDIO_CHANNELS_MONO)
 149 #define AUDIO_MAX_REC_CHANNELS  (AUDIO_CHANNELS_STEREO)
 150
 151 /*
 152  * Generic minimum/maximum limits for sample precision
 153  */
 154 #define AUDIO_PRECISION_8               (8)
 155 #define AUDIO_PRECISION_16              (16)
 156
 157 #define AUDIO_MIN_PLAY_PRECISION        (8)
 158 #define AUDIO_MAX_PLAY_PRECISION        (32)
 159 #define AUDIO_MIN_REC_PRECISION         (8)
 160 #define AUDIO_MAX_REC_PRECISION         (32)
 161
 162 /*
 163  * Define some convenient names for typical audio ports
 164  */
 165 #define AUDIO_NONE              0x00    /* all ports off */
 166 /*
 167  * output ports (several may be enabled simultaneously)
 168  */
 169 #define AUDIO_SPEAKER           0x01    /* output to built-in speaker */
 170 #define AUDIO_HEADPHONE         0x02    /* output to headphone jack */
 171 #define AUDIO_LINE_OUT          0x04    /* output to line out   */
 172 #define AUDIO_SPDIF_OUT         0x08    /* output to SPDIF port */
 173 #define AUDIO_AUX1_OUT          0x10    /* output to aux1 out   */
 174 #define AUDIO_AUX2_OUT          0x20    /* output to aux2 out   */
 175
 176 /*
 177  * input ports (usually only one at a time)
 178  */
 179 #define AUDIO_MICROPHONE        0x01    /* input from microphone */
 180 #define AUDIO_LINE_IN           0x02    /* input from line in   */
 181 #define AUDIO_CD                0x04    /* input from on-board CD inputs */
 182 #define AUDIO_INTERNAL_CD_IN    AUDIO_CD        /* input from internal CDROM */
 183 #define AUDIO_SPDIF_IN          0x08    /* input from SPDIF port */
 184 #define AUDIO_AUX1_IN           0x10    /* input from aux1 in   */
 185 #define AUDIO_AUX2_IN           0x20    /* input from aux2 in   */
 186 #define AUDIO_CODEC_LOOPB_IN    0x40    /* input from Codec internal loopback */
 187 #define AUDIO_SUNVTS            0x80    /* SunVTS input setting-internal LB */
 188
 189 /*
 190  * Define the hw_features
 191  */
 192 #define AUDIO_HWFEATURE_DUPLEX  0x00000001u     /* simult. play & rec support */
 193 #define AUDIO_HWFEATURE_MSCODEC 0x00000002u     /* multi-stream Codec */
 194 #define AUDIO_HWFEATURE_IN2OUT  0x00000004u     /* input to output loopback */
 195 #define AUDIO_HWFEATURE_PLAY    0x00000008u     /* device supports play */
 196 #define AUDIO_HWFEATURE_RECORD  0x00000010u     /* device supports record */
 197
 198 /*
 199  * Define the sw_features
 200  */
 201 #define AUDIO_SWFEATURE_MIXER   0x00000001u     /* audio mixer audio pers mod */
 202
 203 /*
 204  * This macro initializes an audio_info structure to 'harmless' values.
 205  * Note that (~0) might not be a harmless value for a flag that was
 206  * a signed int.
 207  */
 208 #define AUDIO_INITINFO(i)       {                                       \
 209         uint_t  *__x__;                                                 \
 210         for (__x__ = (uint_t *)(i);                                     \
 211             (char *)__x__ < (((char *)(i)) + sizeof (audio_info_t));    \
 212             *__x__++ = (uint_t)~0);                                     \
 213 }
 214
 215
 216 /*
 217  * Parameter for the AUDIO_GETDEV ioctl to determine current
 218  * audio devices.
 219  */
 220 #define MAX_AUDIO_DEV_LEN       (16)
 221 struct audio_device {
 222         char name[MAX_AUDIO_DEV_LEN];
 223         char version[MAX_AUDIO_DEV_LEN];
 224         char config[MAX_AUDIO_DEV_LEN];
 225 };
 226 typedef struct audio_device audio_device_t;
 227
 228
 229 /*
 230  * Ioctl calls for the audio device.
 231  */
 232
 233 /*
 234  * AUDIO_GETINFO retrieves the current state of the audio device.
 235  *
 236  * AUDIO_SETINFO copies all fields of the audio_info structure whose
 237  * values are not set to the initialized value (-1) to the device state.
 238  * It performs an implicit AUDIO_GETINFO to return the new state of the
 239  * device.  Note that the record.samples and play.samples fields are set
 240  * to the last value before the AUDIO_SETINFO took effect.  This allows
 241  * an application to reset the counters while atomically retrieving the
 242  * last value.
 243  *
 244  * AUDIO_DRAIN suspends the calling process until the write buffers are
 245  * empty.
 246  *
 247  * AUDIO_GETDEV returns a structure of type audio_device_t which contains
 248  * three strings.  The string "name" is a short identifying string (for
 249  * example, the SBus Fcode name string), the string "version" identifies
 250  * the current version of the device, and the "config" string identifies
 251  * the specific configuration of the audio stream.  All fields are
 252  * device-dependent -- see the device specific manual pages for details.
 253  */
 254 #define AUDIO_GETINFO   _IOR('A', 1, audio_info_t)
 255 #define AUDIO_SETINFO   _IOWR('A', 2, audio_info_t)
 256 #define AUDIO_DRAIN     _IO('A', 3)
 257 #define AUDIO_GETDEV    _IOR('A', 4, audio_device_t)
 258
 259 /*
 260  * The following ioctl sets the audio device into an internal loopback mode,
 261  * if the hardware supports this.  The argument is TRUE to set loopback,
 262  * FALSE to reset to normal operation.  If the hardware does not support
 263  * internal loopback, the ioctl should fail with EINVAL.
 264  */
 265 #define AUDIO_DIAG_LOOPBACK     _IOW('A', 101, int)
 266
 267 #ifdef __cplusplus
 268 }
 269 #endif
 270
 271 #endif /* _SYS_AUDIOIO_H */