1 MIXER(7I) Ioctl Requests MIXER(7I)
2
3 NAME
4 mixer - generic mixer device interface
5
6 SYNOPSIS
7 #include <sys/soundcard.h>
8
9 DESCRIPTION
10 Mixer Pseudo-Device
11 The /dev/mixer pseudo-device is provided for two purposes:
12
13 o The first purpose is for applications that wish to learn about
14 the list of audio devices on the system, so that they can
15 select (or provide for users to select) an appropriate audio
16 device. The /dev/mixer pseudo-device provides interfaces to
17 enumerate all of the audio devices on the system.
18
19 o The second purpose is for mixer panel type applications which
20 need to control master settings for the audio hardware in the
21 system, such as gain levels, balance, port functionality, and
22 other device features.
23
24 Ordinary audio applications should not attempt to adjust their playback
25 or record volumes or other device settings using this device. Instead,
26 they should use the SNDCTL_DSP_SETPLAYVOL and SNDCTL_DSP_SETRECVOL ioctls
27 that are documented in dsp(7I).
28
29 Sndstat Device
30 The /dev/sndstat device supports read(2), and can be read to retrieve
31 human-readable information about the audio devices on the system.
32 Software should not attempt to interpret the contents of this device.
33
34 IOCTLS
35 Information IOCTLs
36 The following ioctls are intended to aid applications in identifying the
37 audio devices available on the system. These ioctls can be issued
38 against either the pseudo-device /dev/mixer, or a against a file
39 descriptor open to any other audio device in the system.
40
41 Applications should issue SNDCTL_SYSINFO first to learn what audio
42 devices and mixers are available on the system, and then use
43 SNDCTL_AUDIOINFO or SNDCTL_MIXERINFO to obtain more information about the
44 audio devices or mixers, respectively.
45
46 OSS_GETVERSION The argument is a pointer to an integer, which
47 retrieves the version of the OSS API used. The value
48 is encoded with the major version (currently 4) encoded
49 in the most significant 16 bits, and a minor version
50 encoded in the lower 16 bits.
51
52 SNDCTL_SYSINFO The argument is a pointer to an oss_sysinfo structure,
53 which has the following definition:
54
55 typedef struct oss_sysinfo {
56 char product[32]; /* E.g. SunOS Audio */
57 char version[32]; /* E.g. 4.0a */
58 int versionnum; /* See OSS_GETVERSION */
59 char options[128]; /* NOT SUPPORTED */
60
61 int numaudios; /* # of audio/dsp devices */
62 int openedaudio[8]; /* Reserved, always 0 */
63
64 int numsynths; /* NOT SUPPORTED, always 0 */
65 int nummidis; /* NOT SUPPORTED, always 0 */
66 int numtimers; /* NOT SUPPORTED, always 0 */
67 int nummixers; /* # of mixer devices */
68
69 /* Mask of midi devices are busy */
70 int openedmidi[8];
71
72 /* Number of sound cards in the system */
73 int numcards;
74
75 /* Number of audio engines in the system */
76 int numaudioengines;
77 char license[16]; /* E.g. "GPL" or "CDDL" */
78 char revision_info[256]; /* Reserved */
79 int filler[172]; /* Reserved */
80 } oss_sysinfo;
81
82 The important fields here are numaudios, which is used
83 to determine the number of audio devices that can be
84 queried with SNDCTL_AUDIOINFO, nummixers which provides
85 a count of mixers on the system, and numcards which
86 counts to total number of aggregate devices. A card
87 can consist of one or more audio devices and one or
88 more mixers, although more typically there is exactly
89 one audio device and one mixer for each card.
90
91 SNDCTL_AUDIOINFO The argument is a pointer to an oss_audioinfo
92 structure, which has the following structure:
93
94 typedef struct oss_audioinfo {
95 int dev; /* Device to query */
96 char name[64]; /* Human readable name */
97 int busy; /* reserved */
98 int pid; /* reserved */
99
100 /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */
101 int caps;
102 int iformats; /* Supported input formats */
103 int oformats; /* Supported output formats */
104 int magic; /* reserved */
105 char cmd[64]; /* reserved */
106 int card_number;
107 int port_number; /* reserved */
108 int mixer_dev;
109
110 /* Obsolete field. Replaced by devnode */
111 int legacy_device;
112 int enabled; /* reserved */
113 int flags; /* reserved */
114 int min_rate; /* Minimum sample rate */
115 int max_rate; /* Maximum sample rate */
116 int min_channels; /* Minimum number of channels */
117 int max_channels; /* Maximum number of channels */
118 int binding; /* reserved */
119 int rate_source; /* reserved */
120 char handle[32]; /* reserved */
121 unsigned int nrates; /* reserved */
122 unsigned int rates[20]; /* reserved */
123 char song_name[64]; /* reserved */
124 char label[16]; /* reserved */
125 int latency; /* reserved */
126
127 /* Device special file name (absolute path) */
128 char devnode[32];
129 int next_play_engine; /* reserved */
130 int next_rec_engine; /* reserved */
131 int filler[184]; /* reserved */
132 } oss_audioinfo;
133
134 In the above structure, all of the fields are reserved
135 except the following: dev, name, card_number,
136 mixer_dev, caps, min_rate, max_rate, min_channels,
137 max_channels, and devnode. The reserved fields are
138 provided for compatibility with other OSS
139 implementations, and available for legacy applications.
140 New applications should not attempt to use these
141 fields.
142
143 The dev field should be initialized by the application
144 to the number of the device to query. This is a number
145 between zero (inclusive) and value of numaudios
146 (exclusive) returned by SNDCTL_SYSINFO. Alternatively,
147 when issuing the ioctl against a real mixer or dsp
148 device, the special value -1 can be used to indicate
149 that the query is being made against the device opened.
150 If -1 is used, the field is overwritten with the device
151 number for the current device on successful return.
152
153 No other fields are significant upon entry, but a
154 successful return contains details of the device.
155
156 The name field is a human readable name representing
157 the device. Applications should not try to interpret
158 it.
159
160 The card_number field indicates the number assigned to
161 the aggregate device. This can be used with the
162 SNDCTL_CARDINFO ioctl.
163
164 The mixer_dev is the mixer device number for the mixing
165 device associated with the audio device. This can be
166 used with the SNDCTL_MIXERINFO ioctl.
167
168 The caps field contains any of the bits PCM_CAP_INPUT,
169 PCM_CAP_OUTPUT, and PCM_CAP_DUPLEX. Indicating whether
170 the device support input, output, and whether input and
171 output can be used simultaneously. All other bits are
172 reserved.
173
174 The min_rate and max_rate fields indicate the minimum
175 and maximum sample rates supported by the device. Most
176 applications should try to use the maximum supported
177 rate for the best audio quality and lowest system
178 resource consumption.
179
180 The min_channels and max_channels provide an indication
181 of the number of channels (1 for mono, 2 for stereo, 6
182 for 5.1, etc.) supported by the device.
183
184 The devnode field contains the actual full path to the
185 device node for this device, such as
186 /dev/sound/audio810:0dsp. Applications should open
187 this file to access the device.
188
189 SNDCTL_CARDINFO The argument is a pointer to a struct oss_card_info,
190 which has the following definition:
191
192 typedef struct oss_card_info {
193 int card;
194 char shortname[16];
195 char longname[128];
196 int flags; /* reserved */
197 char hw_info[400];
198 int intr_count; /* reserved */
199 int ack_count; /* reserved */
200 int filler[154];
201 } oss_card_info;
202
203 This ioctl is used to query for information about the
204 aggregate audio device.
205
206 The card field should be initialized by the application
207 to the number of the card to query. This is a number
208 between zero (inclusive) and value of numcards
209 (exclusive) returned by SNDCTL_SYSINFO. Alternatively,
210 when issuing the ioctl against a real mixer or dsp
211 device, the special value -1 can be used to indicate
212 that the query is being made against the device opened.
213 If -1 is used, the field is overwritten with the number
214 for the current hardware device on successful return.
215
216 The shortname, longname, and hw_info contain ASCIIZ
217 strings describing the device in more detail. The
218 hw_info member can contain multiple lines of detail,
219 each line ending in a NEWLINE.
220
221 The flag, intr_count, and ack_count fields are not used
222 by this implementation.
223
224 SNDCTL_MIXERINFO The argument is a pointer to a struct oss_mixer_info,
225 which has the following definition:
226
227 typedef struct oss_mixerinfo {
228 int dev;
229 char id[16]; /* Reserved */
230 char name[32];
231 int modify_counter;
232 int card_number;
233 int port_number; /* Reserved */
234 char handle[32]; /* Reserved */
235 int magic; /* Reserved */
236 int enabled; /* Reserved */
237 int caps; /* Reserved */
238 int flags; /* Reserved */
239 int nrext;
240 int priority;
241
242 /* Deice special file name (absolute path) */
243 char devnode[32];
244 int legacy_device; /* Reserved */
245 int filler[245]; /* Reserved */
246 } oss_mixerinfo;
247
248 In the above structure, all of the fields are reserved
249 except the following: dev, name, modify_counter,
250 card_number, nrext, priority, and devnode. The
251 reserved fields are provided for compatibility with
252 other OSS implementations, and available for legacy
253 applications. New applications should not attempt to
254 use these fields.
255
256 The dev field should be initialized by the application
257 to the number of the device to query. This is a number
258 between zero inclusive and value of nummixers
259 (exclusive) returned by SNDCTL_SYSINFO, or by
260 SNDCTL_MIX_NRMIX. Alternatively, when issuing the
261 ioctl against a real mixer or dsp device, the special
262 value -1 can be used to indicate that the query is
263 being made against the device opened. If -1 is used,
264 the field is overwritten with the mixer number for the
265 current open file on successful return.
266
267 No other fields are significant upon entry, but on
268 successful return contains details of the device.
269
270 The name field is a human readable name representing
271 the device. Applications should not try to interpret
272 it.
273
274 The modify_counter is changed by the mixer framework
275 each time the settings for the various controls or
276 extensions of the device are changed. Applications can
277 poll this value to learn if any other changes need to
278 be searched for.
279
280 The card_number field is the number of the aggregate
281 audio device this mixer is located on. It can be used
282 with the SNDCTL_CARDINFO ioctl.
283
284 The nrext field is the number of mixer extensions
285 available on this mixer. See the SNDCTL_MIX_NREXT
286 description.
287
288 The priority is used by the framework to assign a
289 preference that applications can use in choosing a
290 device. Higher values are preferable. Mixers with
291 priorities less than -1 should never be selected by
292 default.
293
294 The devnode field contains the actual full path to the
295 device node for the physical mixer, such as
296 /dev/sound/audio810:0mixer. Applications should open
297 this file to access the mixer settings.
298
299 Mixer Extension IOCTLs
300 The pseudo /dev/mixer device supports ioctls that can change the various
301 settings for the audio hardware in the system.
302
303 Those ioctls should only be used by dedicated mixer applications or
304 desktop volume controls, and not by typical ordinary audio applications
305 such as media players. Ordinary applications that wish to adjust their
306 own volume settings should use the SNDCTL_DSP_SETPLAYVOL or
307 SNDCTL_DSP_SETRECVOL ioctls for that purpose. See dsp(7I) for more
308 information. Ordinary applications should never attempt to change master
309 port selection or hardware settings such as monitor gain settings.
310
311 The ioctls in this section can only be used to access the mixer device
312 that is associated with the current file descriptor.
313
314 Applications should not assume that a single /dev/mixer node is able to
315 access any physical settings. Instead, they should use the ioctl
316 SNDCTL_MIXERINFO to determine the device path for the real mixer device,
317 and issue ioctls on a file descriptor opened against the corresponding
318 devnode field.
319
320 When a dev member is specified in each of the following ioctls, the
321 application should specify -1, although for compatibility the mixer
322 allows the application to specify the mixer device number.
323
324 SNDCTL_MIX_NRMIX The argument is a pointer to an integer, which
325 receives the number of mixer devices in the system.
326 Each can be queried by using its number with the
327 SNDCTL_MIXERINFO ioctl. The same information is
328 available using the SNDCTL_SYSINFO ioctl.
329
330 SNDCTL_MIX_NREXT The argument is a pointer to an integer. On entry,
331 the integer should contain the special value -1. On
332 return the argument receives the number of mixer
333 extensions (or mixer controls) supported by the
334 mixer device. More details about each extension can
335 be obtained by SNDCTL_MIX_EXTINFO ioctl.
336
337 SNDCTL_MIX_EXTINFO The argument is a pointer to an oss_mixext structure
338 which is defined as follows:
339
340 typedef struct oss_mixext {
341 int dev; /* Mixer device number */
342 int ctrl; /* Extension number */
343 int type; /* Entry type */
344 int maxvalue;
345 int minvalue;
346 int flags;
347 char id[16]; /* Mnemonic ID (internal use) */
348 int parent; /* Entry# of parent (-1 if root) */
349 int dummy; /* NOT SUPPORTED */
350 int timestamp;
351 char data[64]; /* Reserved */
352
353 /* Mask of allowed enum values */
354 unsigned char enum_present[32];
355 int control_no; /* Reserved */
356 unsigned int desc; /* NOT SUPPORTED */
357 char extname[32];
358 int update_counter;
359 int filler[7]; /* Reserved */
360 } oss_mixext;
361
362 On entry, the dev field should be initialized to the
363 value -1, and the ctrl field should be initialized
364 with the number of the extension being accessed.
365 Between 0, inclusive, and the value returned by
366 SNDCTL_MIX_NREXT, exclusive.
367
368 Mixer extensions are organized as a logical tree,
369 starting with a root node. The root node always has
370 a ctrl value of zero. The structure of the tree can
371 be determined by looking at the parent field, which
372 contains the extension number of the parent
373 extension, or -1 if the extension is the root
374 extension.
375
376 The type indicates the type of extension used. This
377 implementation supports the following values:
378
379 MIXT_DEVROOT Root node for extension tree
380 MIXT_GROUP Logical grouping of controls
381 MXIT_ONOFF Boolean value, 0 = off, 1 = on.
382 MIXT_ENUM Enumerated value, 0 to maxvalue.
383 MIXT_MONOSLIDER Monophonic slider, 0 to 255.
384 MIXT_STEREOSLIDER Stereophonic slider, 0 to 255
385 (encoded as lower two bytes in
386 value.)
387 MIXT_MARKER Place holder, can ignore.
388
389 The flags field is a bit array. This implementation
390 makes use of the following possible bits:
391
392 MIXF_READABLE Extension's value is readable.
393 MIXF_WRITEABLE Extension's value is modifiable.
394 MIXF_POLL Extension can self-update.
395 MIXF_PCMVOL Extension is for master PCM
396 playback volume.
397 MIXF_MAINVOL Extension is for a typical analog
398 volume
399 MIXF_RECVOL Extension is for master record
400 gain.
401 MIXF_MONVOL Extension is for a monitor
402 source's gain.
403
404 The id field contains an ASCIIZ identifier for the
405 extension.
406
407 The timestamp field is set when the extension tree
408 is first initialized. Applications must use the
409 same timestamp value when attempting to change the
410 values. A change in the timestamp indicates a
411 change a in the structure of the extension tree.
412
413 The enum_present field is a bit mask of possible
414 enumeration values. If a bit is present in the
415 enum_present mask, then the corresponding
416 enumeration value is legal. The mask is in little
417 endian order.
418
419 The desc field provides information about scoping,
420 which can be useful as layout hints to applications.
421 The following hints are available:
422
423 MIXEXT_SCOPE_MASK Mask of possible scope
424 values.
425 MIXEXT_SCOPE_INPUT Extension is an input
426 control.
427 MIXEXT_SCOPE_OUTPUT Extension is an output
428 control.
429 MIXEXT_SCOPE_MONITOR Extension relates to input
430 monitoring.
431 MIXEXT_SCOPE_OTHER scoping hint provided.
432
433 The extname is the full name of the extension.
434
435 The update_counter is incremented each time the
436 control's value is changed.
437
438 SNDCTL_MIX_ENUMINFO The argument is a pointer to an oss_mixer_enuminfo
439 structure, which is defined as follows:
440
441 typedef struct oss_mixer_enuminfo {
442 int dev;
443 int ctrl;
444 int nvalues;
445 int version;
446 short strindex[255];
447 char strings[3000];
448 } oss_mixer_enuminfo;
449
450 On entry, the dev field should be initialized to the
451 value -1, and the ctrl field should be initialized
452 with the number of the extension being accessed.
453 Between 0, inclusive, and the value returned by
454 SNDCTL_MIX_NREXT, exclusive.
455
456 On return the nvalues field contains the number of
457 values, and strindex contains an array of indices
458 into the strings member, each index pointing to an
459 ASCIIZ describing the enumeration value.
460
461 SNDCTL_MIX_READ
462 SNDCTL_MIX_WRITE The argument is a pointer to an oss_mixer_value
463 structure, defined as follows:
464
465 typedef struct oss_mixer_value {
466 int dev;
467 int ctrl;
468 int value;
469
470 /* Reserved for future use. Initialize to 0 */
471 int flags;
472
473 /* Must be set to oss_mixext.timestamp */
474 int timestamp;
475
476 /* Reserved for future use. Initialize to 0 */
477 int filler[8];
478 } oss_mixer_value;
479
480 On entry, the dev field should be initialized to the
481 value -1, and the ctrl field should be initialized
482 with the number of the extension being accessed.
483 Between 0, inclusive, and the value returned by
484 SNDCTL_MIX_NREXT, exclusive. Additionally, the
485 timestamp member must be initialized to the same
486 value as was supplied in the oss_mixext structure
487 used with SNDCTL_MIX_EXTINFO.
488
489 For SNDCTL_MIX_WRITE, the application should supply
490 the new value for the extension. For
491 SNDCTL_MIX_READ, the mixer returns the extensions
492 current value in value.
493
494 Compatibility IOCTLs
495 The following ioctls are for compatibility use only:
496
497 SOUND_MIXER_READ_VOLUME
498 SOUND_MIXER_READ_PCM
499 SOUND_MIXER_READ_OGAIN
500 SOUND_MIXER_READ_RECGAIN
501 SOUND_MIXER_READ_RECLEV
502 SOUND_MIXER_READ_IGAIN
503 SOUND_MIXER_READ_RECSRC
504 SOUND_MIXER_READ_RECMASK
505 SOUND_MIXER_READ_DEVMASK
506 SOUND_MIXER_READ_STEREODEVS
507 SOUND_MIXER_WRITE_VOLUME
508 SOUND_MIXER_WRITE_PCM
509 SOUND_MIXER_WRITE_OGAIN
510 SOUND_MIXER_WRITE_RECGAIN
511 SOUND_MIXER_WRITE_RECLEV
512 SOUND_MIXER_WRITE_IGAIN
513 SOUND_MIXER_WRITE_RECSRC
514 SOUND_MIXER_WRITE_RECMASK
515 SOUND_MIXER_INFO
516 SNDCTL_AUDIOINFO_EX
517 SNDCTL_ENGINEINFO
518
519 These ioctls can affect the software volume levels associated with the
520 calling process. They have no effect on the physical hardware levels or
521 settings. They should not be used in new applications.
522
523 FILES
524 /dev/mixer Symbolic link to the pseudo mixer device for the system
525
526 /dev/sndstat Sound status device
527
528 ERRORS
529 An ioctl(2) fails if:
530
531 EINVAL The parameter changes requested in the ioctl are invalid or are
532 not supported by the device.
533
534 ENXIO The device or extension referenced does not exist.
535
536 ARCHITECTURE
537 SPARC x86
538
539 INTERFACE STABILITY
540 The information and mixer extension IOCTLs are Uncommitted. The
541 Compatibility IOCTLs are Obsolete Uncommitted. The extension names are
542 Uncommitted.
543
544 SEE ALSO
545 close(2), ioctl(2), open(2), read(2), attributes(5), dsp(7I)
546
547 BUGS
548 The names of mixer extensions are not guaranteed to be predictable.
549
550 illumos February 17, 2020 illumos