xref: /illumos-gate/usr/src/uts/common/sys/audioio.h (revision 88447a05)
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 */
272