| blob | d4cee9fba3e0884795abeaa8508b05d34ea276ff |
1 '\" te
2 .\" Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
5 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH DSP 7I "May 11, 2009"
7 .SH NAME
8 dsp \- generic audio device interface
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB#include\fR \fB<sys/soundcard.h>\fR
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 To record audio input, applications \fBopen()\fR the appropriate device and
19 read data from it using the \fBread()\fR system call. Similarly, sound data is
20 queued to the audio output port by using the \fBwrite\fR(2) system call. Device
21 configuration is performed using the \fBioctl\fR(2) interface.
22 .sp
23 .LP
24 Because some systems can contain more than one audio device, application
25 writers are encouraged to open the \fB/dev/mixer\fR device and determine the
26 physical devices present on the system using the \fBSNDCTL_SYSINFO\fR and
27 \fBSNDCTL_AUDIOINFO\fR ioctls. See \fBmixer\fR(7I). The user should be provided
28 a the ability to select a different audio device, or alternatively, an
29 environment variable such as \fBAUDIODSP\fR can be used. In the absence of any
30 specific configuration from the user, the generic device file, \fB/dev/dsp\fR,
31 can be used. This normally points to a reasonably appropriate default audio
32 device for the system.
33 .SS "Opening the Audio Device"
34 .sp
35 .LP
36 The audio device is not treated as an exclusive resource.
37 .sp
38 .LP
39 Each \fBopen()\fR completes as long as there are channels available to be
40 allocated. If no channels are available to be allocated, the call returns
41 \fB-1\fR with the \fBerrno\fR set to \fBEBUSY\fR.
42 .sp
43 .LP
44 Audio applications should explicitly set the encoding characteristics to match
45 the audio data requirements after opening the device, and not depend on any
46 default configuration.
47 .SS "Recording Audio Data"
48 .sp
49 .LP
50 The \fBread()\fR system call copies data from the system's buffers to the
51 application. Ordinarily, \fBread()\fR blocks until the user buffer is filled.
52 The \fBpoll\fR(2) system call can be used to determine the presence of data
53 that can be read without blocking. The device can alternatively be set to a
54 non-blocking mode, in which case \fBread()\fR completes immediately, but can
55 return fewer bytes than requested. Refer to the \fBread\fR(2) manual page for a
56 complete description of this behavior.
57 .sp
58 .LP
59 When the audio device is opened with read access, the device driver allocates
60 resources for recording. Since this consumes system resources, processes that
61 do not record audio data should open the device write-only (\fBO_WRONLY\fR).
62 .sp
63 .LP
64 The recording process can be stopped by using the \fBSNDCTL_DSP_HALT_INPUT\fR
65 ioctl, which also discards all pending record data in underlying device FIFOs.
66 .sp
67 .LP
68 Before changing record parameters, the input should be stopped using the
69 \fBSNDCTL_DSP_HALT_INPUT\fR ioctl, which also flushes the any underlying device
70 input FIFOs. (This is not necessary if the process never started recording by
71 calling \fBread\fR(2). Otherwise, subsequent reads can return samples in the
72 old format followed by samples in the new format. This is particularly
73 important when new parameters result in a changed sample size.
74 .sp
75 .LP
76 Input data can accumulate in device buffers very quickly. At a minimum, it
77 accumulates at 8000 bytes per second for 8-bit, 8 KHz, mono, \fBu-Law\fR data.
78 If the device is configured for more channels, higher sample resolution, or
79 higher sample rates, it accumulates even faster. If the application that
80 consumes the data cannot keep up with this data rate, the underlying FIFOs can
81 become full. When this occurs, any new incoming data is lost until the
82 application makes room available by consuming data. Additionally, a record
83 overrun is noted, which can be retrieved using the \fBSNDCTL_DSP_GETERROR\fR
84 ioctl.
85 .sp
86 .LP
87 Record volume for a stream can be adjusted by issuing the
88 \fBSNDCTL_DSP_SETRECVOL\fR ioctl. The volume can also be retrieved using the
89 \fBSNDCTL_DSP_GETRECVOL\fR.
90 .SS "Playing Audio Data"
91 .sp
92 .LP
93 The \fBwrite()\fR system call copies data from an application's buffer to the
94 device output FIFO. Ordinarily, \fBwrite()\fR blocks until the entire user
95 buffer is transferred. The device can alternatively be set to a non-blocking
96 mode, in which case \fBwrite()\fRcompletes immediately, but might have
97 transferred fewer bytes than requested. See \fBwrite\fR(2).
98 .sp
99 .LP
100 Although \fBwrite()\fR returns when the data is successfully queued, the actual
101 completion of audio output might take considerably longer. The
102 \fBSNDCTL_DSP_SYNC\fR ioctl can be issued to allow an application to block
103 until all of the queued output data has been played.
104 .sp
105 .LP
106 The final \fBclose\fR(2) of the file descriptor waits until all of the audio
107 output has drained. If a signal interrupts the \fBclose()\fR, or if the process
108 exits without closing the device, any remaining data queued for audio output is
109 flushed and the device is closed immediately.
110 .sp
111 .LP
112 The output of playback data can be halted entirely, by calling the
113 \fBSNDCTL_DSP_HALT_OUTPUT\fR ioctl. This also discards any data that is queued
114 for playback in device FIFOs.
115 .sp
116 .LP
117 Before changing playback parameters, the output should be drained using the
118 \fBSNDCTL_DSP_SYNC\fR ioctl, and then stopped using the
119 \fBSNDCTL_DSP_HALT_OUTPUT\fR ioctl, which also flushes the any underlying
120 device output FIFOs. This is not necessary if the process never started
121 playback, such as by calling \fBwrite\fR(2). This is particularly important
122 when new parameters result in a changed sample size.
123 .sp
124 .LP
125 Output data is played from the playback buffers at a default rate of at least
126 8000 bytes per second for u-Law, A-Law or 8-bit PCM data (faster for 16-bit
127 linear data or higher sampling rates). If the output FIFO becomes empty, the
128 framework plays silence, resulting in audible stall or click in the output,
129 until more data is supplied by the application. The condition is also noted as
130 a play underrun, which can be determined using the \fBSNDCTL_DSP_GETERROR\fR
131 ioctl.
132 .sp
133 .LP
134 Playback volume for a stream can be adjusted by issuing the
135 \fBSNDCTL_DSP_SETPLAYVOL\fR ioctl. The volume can also be retrieved using the
136 \fBSNDCTL_DSP_GETPLAYVOL\fR.
137 .SS "Asynchronous I/O"
138 .sp
139 .LP
140 The \fBO_NONBLOCK\fR flag can be set using the \fBF_SETFL\fR \fBfcntl\fR(2) to
141 enable non-blocking \fBread()\fR and \fBwrite()\fR requests. This is normally
142 sufficient for applications to maintain an audio stream in the background.
143 .sp
144 .LP
145 It is also possible to determine the amount of data that can be transferred for
146 playback or recording without blocking using the \fBSNDCTL_DSP_GETOSPACE\fR or
147 \fBSNDCTL_DSP_GETISPACE\fR ioctls, respectively.
148 .SS "Mixer Pseudo-Device"
149 .sp
150 .LP
151 The \fB/dev/mixer\fR provides access to global hardware settings such as master
152 volume settings, etc. It is also the interface used for determining the
153 hardware configuration on the system.
154 .sp
155 .LP
156 Applications should \fBopen\fR(2) \fB/dev/mixer\fR, and use the
157 \fBSNDCTL_SYSINFO\fR and \fBSNDCTL_AUDIOINFO\fR ioctls to determine the device
158 node names of audio devices on the system. See \fBmixer\fR(7I) for additional
159 details.
160 .SH IOCTLS
161 .SS "Information IOCTLs"
162 .sp
163 .LP
164 The following ioctls are supported on the audio device, as well as the mixer
165 device. See \fBmixer\fR(7I) for details.
166 .sp
167 .in +2
168 .nf
169 OSS_GETVERSION
170 SNDCTL_SYSINFO
171 SNDCTL_AUDIOINFO
172 SNDCTL_MIXERINFO
173 SNDCTL_CARDINFO
174 .fi
175 .in -2
177 .SS "Audio IOCTLs"
178 .sp
179 .LP
180 The \fBdsp\fR device supports the following ioctl commands:
181 .sp
182 .ne 2
183 .na
184 \fB\fBSNDCTL_DSP_SYNC\fR\fR
185 .ad
186 .RS 27n
187 The argument is ignored. This command suspends the calling process until the
188 output FIFOs are empty and all queued samples have been played, or until a
189 signal is delivered to the calling process. An implicit \fBSNDCTL_DSP_SYNC\fR
190 is performed on the final \fBclose()\fR of the \fBdsp\fR device.
191 .sp
192 This ioctl should not be used unnecessarily, as if it is used in the middle of
193 playback it causes a small click or pause, as the FIFOs are drained. The
194 correct use of this ioctl is just before changing sample formats.
195 .RE
197 .sp
198 .ne 2
199 .na
200 \fB\fBSNDCTL_DSP_HALT\fR\fR
201 .ad
202 .br
203 .na
204 \fB\fBSNDCTL_DSP_HALT_INPUT\fR\fR
205 .ad
206 .br
207 .na
208 \fB\fBSNDCTL_DSP_HALT_OUTPUT\fR\fR
209 .ad
210 .RS 27n
211 The argument is ignored. All input or output (or both) associated with the file
212 is halted, and any pending data is discarded.
213 .RE
215 .sp
216 .ne 2
217 .na
218 \fB\fBSNDCTL_DSP_SPEED\fR\fR
219 .ad
220 .RS 27n
221 The argument is a pointer to an integer, indicating the sample rate (in Hz) to
222 be used. The rate applies to both input and output for the file descriptor. On
223 return the actual rate, which can differ from that requested, is stored in the
224 integer pointed to by the argument. To query the configured speed without
225 changing it the value 0 can be used by the application
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fBSNDCTL_DSP_GETFMTS\fR\fR
232 .ad
233 .RS 27n
234 The argument is a pointer to an integer, which receives a bit mask of encodings
235 supported by the device. Possible values are
236 .sp
237 .in +2
238 .nf
239 AFMT_MU_LAW 8-bit unsigned u-Law
240 AFMT_A_LAW 8-bit unsigned a-Law
241 AFMT_U8 8-bit unsigned linear PCM
242 AFMT_S16_LE 16-bit signed
243 little-endian linear PCM
244 AFMT_S16_BE 16-bit signed
245 big-endian linear PCM
246 AFMT_S16_NE 16-bit signed native-endian
247 linear PCM
248 AFMT_U16_LE 16-bit unsigned
249 little-endian linear PCM
250 AFMT_U16_BE 16-bit unsigned big-endian
251 linear PCM
252 AFMT_U16_NE 16-bit unsigned big-endian
253 linear PCM
254 AFMT_S24_LE 24-bit signed little-endian
255 linear PCM, 32-bit aligned
256 AFMT_S24_BE 24-bit signed big-endian
257 linear PCM, 32-bit aligned
258 AFMT_S24_NE 24-bit signed native-endian
259 linear PCM, 32-bit aligned
260 AFMT_S32_LE 32-bit signed little-endian
261 linear PCM
262 AFMT_S32_BE 32-bit signed big-endian
263 linear PCM
264 AFMT_S32_NE 32-bit signed native-endian
265 linear PCM
266 AFMT_S24_PACKED 24-bit signed little-endian
267 packed linear PCM
268 .fi
269 .in -2
270 .sp
272 Not all devices support all of these encodings. This implementation uses
273 \fBAFMT_S24_LE\fR or \fBAFMT_S24_BE\fR, whichever is native, internally.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fBSNDCTL_DSP_SETFMT\fR\fR
280 .ad
281 .RS 27n
282 The argument is a pointer to an integer, which indicates the encoding to be
283 used. The same values as for \fBSNDCTL_DSP_GETFMT\fR can be used, but the
284 caller can only specify a single option. The encoding is used for both input
285 and output performed on the file descriptor.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fBSNDCTL_DSP_CHANNELS\fR\fR
292 .ad
293 .RS 27n
294 The argument is a pointer to an integer, indicating the number of channels to
295 be used (1 for mono, 2 for stereo, etc.) The value applies to both input and
296 output for the file descriptor. On return the actual channel configuration
297 (which can differ from that requested) is stored in the integer pointed to by
298 the argument. To query the configured channels without changing it the value 0
299 can be used by the application.
300 .RE
302 .sp
303 .ne 2
304 .na
305 \fB\fBSNDDCTL_DSP_GETCAPS\fR\fR
306 .ad
307 .RS 27n
308 The argument is a pointer to an integer bit mask, which indicates the
309 capabilities of the device. The bits returned can include
310 .sp
311 .in +2
312 .nf
313 PCM_CAP_OUTPUT Device supports playback
314 PCM_CAP_INPUT Device supports recording
315 PCM_CAP_DUPLEX Device supports simultaneous
316 playback and recording
317 .fi
318 .in -2
319 .sp
321 .RE
323 .sp
324 .ne 2
325 .na
326 \fB\fBSNDCTL_DSP_GETPLAYVOL\fR\fR
327 .ad
328 .br
329 .na
330 \fB\fBSNDCTL_DSP_GETRECVOL\fR\fR
331 .ad
332 .RS 27n
333 The argument is a pointer to an integer to receive the volume level for either
334 playback or record. The value is encoded as a stereo value with the values for
335 two channels in the least significant two bytes. The value for each channel
336 thus has a range of 0-100. In this implementation, only the low order byte is
337 used, as the value is treated as a monophonic value, but a stereo value (with
338 both channel levels being identical) is returned for compatibility.
339 .RE
341 .sp
342 .ne 2
343 .na
344 \fB\fBSNDCTL_DSP_SETPLAYVOL\fR\fR
345 .ad
346 .br
347 .na
348 \fB\fBSNDCTL_DSP_SETRECVOL\fR\fR
349 .ad
350 .RS 27n
351 The argument is a pointer to an integer indicating volume level for either
352 playback or record. The value is encoded as a stereo value with the values for
353 two channels in the least significant two bytes. The value for each channel has
354 a range of 0-100. Note that in this implementation, only the low order byte is
355 used, as the value is treated as a monophonic value. Portable applications
356 should assign the same value to both bytes
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fBSNDCTL_DSP_GETISPACE\fR\fR
363 .ad
364 .br
365 .na
366 \fB\fBSNDCTL_DSP_GETOSPACE\fR\fR
367 .ad
368 .RS 27n
369 The argument is a pointer to a \fBstruct audio_buf_info\fR, which has the
370 following structure:
371 .sp
372 .in +2
373 .nf
374 typedef struct audio_buf_info {
375 int fragments;* /# of available fragments */
376 int fragstotal;
377 /* Total # of fragments allocated */
378 int fragsize;
379 /* Size of a fragment in bytes */
380 int bytes;
381 /* Available space in bytes */
382 /* Note! 'bytes' could be more than
383 fragments*fragsize */
384 } audio_buf_info;
385 .fi
386 .in -2
387 .sp
389 The fields fragments, \fBfragstotal\fR, and \fBfragsize\fR are intended for use
390 with compatible applications (and in the future with \fBmmap\fR(2)) only, and
391 need not be used by typical applications. On successful return the bytes member
392 contains the number of bytes that can be transferred without blocking.
393 .RE
395 .sp
396 .ne 2
397 .na
398 \fB\fBSNDCTL_DSP_CURRENT_IPTR\fR\fR
399 .ad
400 .br
401 .na
402 \fB\fBSNDCTL_DSP_CURRENT_OPTR\fR\fR
403 .ad
404 .RS 27n
405 The argument is a pointer to an \fBoss_count_t\fR, which has the following
406 definition:
407 .sp
408 .in +2
409 .nf
410 typedef struct {
411 long long samples;
412 /* Total # of samples */
413 int fifo_samples;
414 /* Samples in device FIFO */
415 int filler[32];/* For future use */
416 } oss_count_t;
417 .fi
418 .in -2
419 .sp
421 The \fBsamples\fR field contains the total number of samples transferred by the
422 device so far. The \fBfifo_samples\fR is the depth of any hardware FIFO. This
423 structure can be useful for accurate stream positioning and latency
424 calculations.
425 .RE
427 .sp
428 .ne 2
429 .na
430 \fB\fBSNDCTL_DSP_GETIPTR\fR\fR
431 .ad
432 .br
433 .na
434 \fB\fBSNDCTL_DSP_GETOPTR\fR\fR
435 .ad
436 .RS 27n
437 The argument is a pointer to a \fBstruct count_info\fR, which has the following
438 definition:
439 .sp
440 .in +2
441 .nf
442 typedef struct count_info {
443 unsigned int bytes;
444 /* Total # of bytes processed */
445 int blocks;
446 /* # of fragment transitions since
447 last time */
448 int ptr;/* Current DMA pointer value */
449 } count_info;
450 .fi
451 .in -2
452 .sp
454 These ioctls are primarily supplied for compatibility, and should not be used
455 by most applications.
456 .RE
458 .sp
459 .ne 2
460 .na
461 \fB\fBSNDCTL_DSP_GETODELAY\fR\fR
462 .ad
463 .RS 27n
464 The argument is a pointer to an integer. On return, the integer contains the
465 number of bytes still to be played before the next byte written are played.
466 This can be used for accurate determination of device latency. The result can
467 differ from actual value by up the depth of the internal device FIFO, which is
468 typically 64 bytes.
469 .RE
471 .sp
472 .ne 2
473 .na
474 \fB\fBSNDCTL_DSP_GETERROR\fR\fR
475 .ad
476 .RS 27n
477 The argument is a pointer to a \fBstruct audio_errinfo\fR, defined as follows:
478 .sp
479 .in +2
480 .nf
481 typedef struct audio_errinfo {
482 int play_underruns;
483 int rec_overruns;
484 unsigned int play_ptradjust;
485 unsigned int rec_ptradjust;
486 int play_errorcount;
487 int rec_errorcount;
488 int play_lasterror;
489 int rec_lasterror;
490 int play_errorparm;
491 int rec_errorparm;
492 int filler[16];
493 } audio_errinfo;
494 .fi
495 .in -2
496 .sp
498 For this implementation, only the \fBplay_underruns\fR and \fBrec_overruns\fR
499 values are significant. No other fields are used in this implementation.
500 .sp
501 These fields are reset to zero each time their value is retrieved using this
502 ioctl.
503 .RE
505 .SS "Compatibility IOCTLS"
506 .sp
507 .LP
508 These ioctls are supplied exclusively for compatibility with existing
509 applications. Their use is not recommended, and they are not documented here.
510 Many of these are implemented as simple no-ops.
511 .sp
512 .in +2
513 .nf
514 SNDCTL_DSP_POST
515 SNDCTL_DSP_STEREO
516 SNDCTL_DSP_SETDUPLEX
517 SNDCTL_DSP_LOW_WATER
518 SNDCTL_DSP_PROFILE
519 SNDCTL_DSP_GETBLKSIZE
520 SNDCTL_DSP_SUBDIVIDE
521 SNDCTL_DSP_SETFRAGMENT
522 SNDCTL_DSP_COOKEDMODE
523 SNDCTL_DSP_READCTL
524 SNDCTL_DSP_WRITECTL
525 SNDCTL_DSP_SILENCE
526 SNDCTL_DSP_SKIP
527 SNDCTL_DSP_POST
528 SNDCTL_DSP_GET_RECSRC
529 SNDCTL_DSP_SET_RECSRC
530 SNDCTL_DSP_SET_RECSRC_NAMES
531 SNDCTL_DSP_GET_PLAYTGT
532 SNDCTL_DSP_SET_PLAYTGT
533 SNDCTL_DSP_SET_PLAYTGT_NAMES
534 SNDCTL_DSP_GETTRIGGER
535 SNDCTL_DSP_SETTRIGGER
536 SNDCTL_AUDIOINFO_EX
537 SNDCTL_ENGINEINFO
538 .fi
539 .in -2
540 .sp
542 .SH ERRORS
543 .sp
544 .LP
545 An \fBopen()\fR fails if:
546 .sp
547 .ne 2
548 .na
549 \fB\fBEBUSY\fR\fR
550 .ad
551 .RS 10n
552 The requested play or record access isbusy and either the \fBO_NDELAY\fR or
553 \fBO_NONBLOCK\fR flag was set in the \fBopen()\fR request.
554 .RE
556 .sp
557 .ne 2
558 .na
559 \fB\fBEINTR\fR\fR
560 .ad
561 .RS 10n
562 The requested play or record access is busy and a signal interrupted the
563 \fBopen()\fR request.
564 .RE
566 .sp
567 .ne 2
568 .na
569 \fB\fBEINVAL\fR\fR
570 .ad
571 .RS 10n
572 The device cannot support the requested play or record access.
573 .RE
575 .sp
576 .LP
577 An \fBioctl()\fR fails if:
578 .sp
579 .ne 2
580 .na
581 \fB\fBEINVAL\fR\fR
582 .ad
583 .RS 10n
584 The parameter changes requested in the ioctl are invalid or are not supported
585 by the device.
586 .RE
588 .SH FILES
589 .sp
590 .LP
591 The physical audio device names are system dependent and are rarely used by
592 programmers. Programmers should use the generic device names listed below.
593 .sp
594 .ne 2
595 .na
596 \fB\fB/dev/dsp\fR\fR
597 .ad
598 .RS 28n
599 Symbolic link to the system's primary audio device
600 .RE
602 .sp
603 .ne 2
604 .na
605 \fB\fB/dev/mixer\fR\fR
606 .ad
607 .RS 28n
608 Symbolic link to the pseudo mixer device for the system
609 .RE
611 .sp
612 .ne 2
613 .na
614 \fB\fB/dev/sndstat\fR\fR
615 .ad
616 .RS 28n
617 Symbolic link to the pseudo mixer device for the system
618 .RE
620 .sp
621 .ne 2
622 .na
623 \fB\fB/usr/share/audio/samples\fR\fR
624 .ad
625 .RS 28n
626 Audio files
627 .RE
629 .SH ATTRIBUTES
630 .sp
631 .LP
632 See \fBattributes\fR(5) for a description of the following attributes:
633 .sp
635 .sp
636 .TS
637 box;
638 c | c
639 l | l .
640 ATTRIBUTE TYPE ATTRIBUTE VALUE
641 _
642 Architecture SPARC, x86
643 _
644 Stability Level Uncommitted
645 .TE
647 .SH SEE ALSO
648 .sp
649 .LP
650 \fBclose\fR(2), \fBfcntl\fR(2), \fBioctl\fR(2), \fBmmap\fR(2), \fBopen\fR(2),
651 \fBpoll\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5),
652 \fBaudio\fR(7D), \fBmixer\fR(7I)