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