diff options
Diffstat (limited to 'usr/src/man/man7i/dsp.7i')
| -rw-r--r-- | usr/src/man/man7i/dsp.7i | 602 |
1 files changed, 0 insertions, 602 deletions
diff --git a/usr/src/man/man7i/dsp.7i b/usr/src/man/man7i/dsp.7i deleted file mode 100644 index 1c0fa9fc07..0000000000 --- a/usr/src/man/man7i/dsp.7i +++ /dev/null @@ -1,602 +0,0 @@ -.\" Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved. -.\" Copyright 2018, Joyent, Inc. -.\" 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. -.\" 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 -.\" fields enclosed by brackets "[]" replaced with your own identifying -.\" information: Portions Copyright [yyyy] [name of copyright owner] -.Dd July 9, 2018 -.Dt DSP 7I -.Os -.Sh NAME -.Nm dsp -.Nd generic audio device interface -.Sh SYNOPSIS -.In sys/soundcard.h -.Sh DESCRIPTION -To record audio input, applications -.Xr open 2 -the appropriate device and -read data from it using the -.Xr read 2 -system call. -Similarly, sound data is queued to the audio output port by using the -.Xr write 2 -system call. -Device configuration is performed using the -.Xr ioctl 2 -interface. -.Pp -Because some systems can contain more than one audio device, application -writers are encouraged to open the -.Pa /dev/mixer -device and determine the -physical devices present on the system using the -.Dv SNDCTL_SYSINFO -and -.Dv SNDCTL_AUDIOINFO -ioctls. -See -.Xr mixer 7I . -The user should be provided -wth the ability to select a different audio device, or alternatively, an -environment variable such as -.Ev AUDIODSP -can be used. -In the absence of any -specific configuration from the user, the generic device file, -.Pa /dev/dsp , -can be used. -This normally points to a reasonably appropriate default audio -device for the system. -.Ss "Opening the Audio Device" -The audio device is not treated as an exclusive resource. -.Pp -Each -.Xr open 2 -completes as long as there are channels available to be allocated. -If no channels are available to be allocated, the call returns -.Sy -1 -with the -.Va errno -set to -.Er EBUSY . -.Pp -Audio applications should explicitly set the encoding characteristics to match -the audio data requirements after opening the device, and not depend on any -default configuration. -.Ss "Recording Audio Data" -The -.Xr read 2 -system call copies data from the system's buffers to the application. -Ordinarily, -.Xr read 2 -blocks until the user buffer is filled. -The -.Xr poll 2 -system call can be used to determine the presence of data -that can be read without blocking. -The device can alternatively be set to a -non-blocking mode, in which case -.Xr read 2 -completes immediately, but can return fewer bytes than requested. -Refer to the -.Xr read 2 -manual page for a complete description of this behavior. -.Pp -When the audio device is opened with read access, the device driver allocates -resources for recording. -Since this consumes system resources, processes that -do not record audio data should open the device write-only -.Pq Dv O_WRONLY . -.Pp -The recording process can be stopped by using the -.Dv SNDCTL_DSP_HALT_INPUT -ioctl, which also discards all pending record data in underlying device FIFOs. -.Pp -Before changing record parameters, the input should be stopped using the -.Dv SNDCTL_DSP_HALT_INPUT -ioctl, which also flushes the any underlying device input FIFOs. -(This is not necessary if the process never started recording by calling -.Xr read 2 . -Otherwise, subsequent reads can return samples in the -old format followed by samples in the new format. -This is particularly -important when new parameters result in a changed sample size. -.Pp -Input data can accumulate in device buffers very quickly. -At a minimum, it accumulates at 8000 bytes per second for 8-bit, 8 KHz, mono, -.Sy \(*m-Law -data. -If the device is configured for more channels, higher sample resolution, or -higher sample rates, it accumulates even faster. -If the application that consumes the data cannot keep up with this data rate, -the underlying FIFOs can become full. -When this occurs, any new incoming data is lost until the -application makes room available by consuming data. -Additionally, a record overrun is noted, which can be retrieved using the -.Dv SNDCTL_DSP_GETERROR -ioctl. -.Pp -Record volume for a stream can be adjusted by issuing the -.Dv SNDCTL_DSP_SETRECVOL -ioctl. -The volume can also be retrieved using the -.Dv SNDCTL_DSP_GETRECVOL . -.Ss "Playing Audio Data" -The -.Xr write 1 -system call copies data from an application's buffer to the device output FIFO. -Ordinarily, -.Xr write 2 -blocks until the entire user -buffer is transferred. -The device can alternatively be set to a non-blocking -mode, in which case -.Xr write 2 -completes immediately, but might have -transferred fewer bytes than requested. -See -.Xr write 2 . -.Pp -Although -.Xr write 2 -returns when the data is successfully queued, the actual -completion of audio output might take considerably longer. -The -.Dv SNDCTL_DSP_SYNC -ioctl can be issued to allow an application to block -until all of the queued output data has been played. -.Pp -The final -.Xr close 2 -of the file descriptor waits until all of the audio output has drained. -If a signal interrupts the -.Xr close 2 , -or if the process -exits without closing the device, any remaining data queued for audio output is -flushed and the device is closed immediately. -.Pp -The output of playback data can be halted entirely, by calling the -.Dv SNDCTL_DSP_HALT_OUTPUT -ioctl. -This also discards any data that is queued for playback in device FIFOs. -.Pp -Before changing playback parameters, the output should be drained using the -.Dv SNDCTL_DSP_SYNC -ioctl, and then stopped using the -.Dv SNDCTL_DSP_HALT_OUTPUT -ioctl, which also flushes the any underlying device output FIFOs. -This is not necessary if the process never started playback, such as by calling -.Xr write 2 . -This is particularly important -when new parameters result in a changed sample size. -.Pp -Output data is played from the playback buffers at a default rate of at least -8000 bytes per second for \(*m-Law, A-Law or 8-bit PCM data (faster for 16-bit -linear data or higher sampling rates). -If the output FIFO becomes empty, the -framework plays silence, resulting in audible stall or click in the output, -until more data is supplied by the application. -The condition is also noted as -a play underrun, which can be determined using the -.Dv SNDCTL_DSP_GETERROR -ioctl. -.Pp -Playback volume for a stream can be adjusted by issuing the -.Dv SNDCTL_DSP_SETPLAYVOL -ioctl. -The volume can also be retrieved using the -.Dv SNDCTL_DSP_GETPLAYVOL . -.Ss "Asynchronous I/O" -The -.Dv O_NONBLOCK -flag can be set using the -.Dv F_SETFL -.Xr fcntl 2 -to enable non-blocking -.Xr read 2 -and -.Xr write 2 -requests. -This is normally -sufficient for applications to maintain an audio stream in the background. -.Pp -It is also possible to determine the amount of data that can be transferred for -playback or recording without blocking using the -.Dv SNDCTL_DSP_GETOSPACE -or -.Dv SNDCTL_DSP_GETISPACE -ioctls, respectively. -.Ss "Mixer Pseudo-Device" -The -.Pa /dev/mixer -provides access to global hardware settings such as master volume settings, etc. -It is also the interface used for determining the -hardware configuration on the system. -.Pp -Applications should -.Xr open 2 -.Pa /dev/mixer , -and use the -.Dv SNDCTL_SYSINFO -and -.Dv SNDCTL_AUDIOINFO -ioctls to determine the device node names of audio devices on the system. -See -.Xr mixer 7I -for additional details. -.Sh IOCTLS -.Ss "Information IOCTLs" -The following ioctls are supported on the audio device, as well as the mixer -device. -See -.Xr mixer 7I -for details. -.Bd -literal -offset 2n -.Dv OSS_GETVERSION -.Dv SNDCTL_SYSINFO -.Dv SNDCTL_AUDIOINFO -.Dv SNDCTL_MIXERINFO -.Dv SNDCTL_CARDINFO -.Ed -.Ss "Audio IOCTLs" -The -.Nm -device supports the following ioctl commands: -.Pp -.\" A compact list is used so that items with multiple tags don't have -.\" vertical whitespace. However that means explicit .Pp statements must -.\" be added. -.Bl -tag -width "SNDCTL_DSP_CURRENT_IPTR" -compact -.It Dv SNDCTL_DSP_SYNC -The argument is ignored. -This command suspends the calling process until the -output FIFOs are empty and all queued samples have been played, or until a -signal is delivered to the calling process. -An implicit -.Dv SNDCTL_DSP_SYNC -is performed on the final -.Xr close 2 -of the -.Nm -device. -.Pp -This ioctl should not be used unnecessarily, as if it is used in the middle of -playback it causes a small click or pause, as the FIFOs are drained. -The correct use of this ioctl is just before changing sample formats. -.Pp -.It Dv SNDCTL_DSP_HALT -.It Dv SNDCTL_DSP_HALT_INPUT -.It Dv SNDCTL_DSP_HALT_OUTPUT -The argument is ignored. -All input or output (or both) associated with the file -is halted, and any pending data is discarded. -.Pp -.It Dv SNDCTL_DSP_SPEED -The argument is a pointer to an integer, indicating the sample rate (in Hz) to -be used. -The rate applies to both input and output for the file descriptor. -On return the actual rate, which can differ from that requested, is stored in -the integer pointed to by the argument. -To query the configured speed without -changing it the value 0 can be used by the application. -.Pp -.It Dv SNDCTL_DSP_GETFMTS -The argument is a pointer to an integer, which receives a bit mask of encodings -supported by the device. -Possible values are: -.Pp -.Bl -tag -width "AFMT_S24_PACKED" -compact -offset 2n -.It Dv AFMT_MU_LAW -8-bit unsigned \(*m-Law -.It Dv AFMT_A_LAW -8-bit unsigned a-Law -.It Dv AFMT_U8 -8-bit unsigned linear PCM -.It Dv AFMT_S16_LE -16-bit signed little-endian linear PCM -.It Dv AFMT_S16_BE -16-bit signed big-endian linear PCM -.It Dv AFMT_S16_NE -16-bit signed native-endian linear PCM -.It Dv AFMT_U16_LE -16-bit unsigned little-endian linear PCM -.It Dv AFMT_U16_BE -16-bit unsigned big-endian linear PCM -.It Dv AFMT_U16_NE -16-bit unsigned native-endian linear PCM -.It Dv AFMT_S24_LE -24-bit signed little-endian linear PCM, 32-bit aligned -.It Dv AFMT_S24_BE -24-bit signed big-endian linear PCM, 32-bit aligned -.It Dv AFMT_S24_NE -24-bit signed native-endian linear PCM, 32-bit aligned -.It Dv AFMT_S32_LE -32-bit signed little-endian linear PCM -.It Dv AFMT_S32_BE -32-bit signed big-endian linear PCM -.It Dv AFMT_S32_NE -32-bit signed native-endian linear PCM -.It Dv AFMT_S24_PACKED -24-bit signed little-endian packed linear PCM -.El -.Pp -Not all devices support all of these encodings. -This implementation uses -.Dv AFMT_S24_LE -or -.Dv AFMT_S24_BE , -whichever is native, internally. -.Pp -.It Dv SNDCTL_DSP_SETFMT -The argument is a pointer to an integer, which indicates the encoding to be -used. -The same values as for -.Dv SNDCTL_DSP_GETFMT -can be used, but the caller can only specify a single option. -The encoding is used for both input -and output performed on the file descriptor. -.Pp -.It Dv SNDCTL_DSP_CHANNELS -The argument is a pointer to an integer, indicating the number of channels to -be used (1 for mono, 2 for stereo, etc.) -The value applies to both input and output for the file descriptor. -On return the actual channel configuration (which can differ from that -requested) is stored in the integer pointed to by the argument. -To query the configured channels without changing it the value 0 -can be used by the application. -.Pp -.It Dv SNDDCTL_DSP_GETCAPS -The argument is a pointer to an integer bit mask, which indicates the -capabilities of the device. -The bits returned can include: -.Pp -.Bl -tag -width "PCM_CAP_DUPLEX" -compact -offset 2n -.It Dv PCM_CAP_OUTPUT -Device supports playback -.It Dv PCM_CAP_INPUT -Device supports recording -.It Dv PCM_CAP_DUPLEX -Device supports simultaneous playback and recording -.El -.Pp -.It Dv SNDCTL_DSP_GETPLAYVOL -.It Dv SNDCTL_DSP_GETRECVOL -The argument is a pointer to an integer to receive the volume level for either -playback or record. -The value is encoded as a stereo value with the values for -two channels in the least significant two bytes. -The value for each channel thus has a range of 0-100. -In this implementation, only the low order byte is -used, as the value is treated as a monophonic value, but a stereo value (with -both channel levels being identical) is returned for compatibility. -.Pp -.It Dv SNDCTL_DSP_SETPLAYVOL -.It Dv SNDCTL_DSP_SETRECVOL -The argument is a pointer to an integer indicating volume level for either -playback or record. -The value is encoded as a stereo value with the values for -two channels in the least significant two bytes. -The value for each channel has a range of 0-100. -Note that in this implementation, only the low order byte is -used, as the value is treated as a monophonic value. -Portable applications should assign the same value to both bytes. -.Pp -.It Dv SNDCTL_DSP_GETISPACE -.It Dv SNDCTL_DSP_GETOSPACE -The argument is a pointer to a -.Vt struct audio_buf_info , -which has the following structure: -.Bd -literal -offset 2n -typedef struct audio_buf_info { - int fragments; /* # of available fragments */ - int fragstotal; - /* Total # of fragments allocated */ - int fragsize; - /* Size of a fragment in bytes */ - int bytes; - /* Available space in bytes */ - /* - * Note! 'bytes' could be more than - * fragments*fragsize - */ -} audio_buf_info; -.Ed -.Pp -The fields -.Fa fragments , -.Fa fragstotal , -and -.Fa fragsize -are intended for use with compatible applications (and in the future with -.Xr mmap 2 ) -only, and need not be used by typical applications. -On successful return the bytes member -contains the number of bytes that can be transferred without blocking. -.Pp -.It Dv SNDCTL_DSP_CURRENT_IPTR -.It Dv SNDCTL_DSP_CURRENT_OPTR -The argument is a pointer to an -.Vt oss_count_t , -which has the following definition: -.Bd -literal -offset 2n -typedef struct { - long long samples; - /* Total # of samples */ - int fifo_samples; - /* Samples in device FIFO */ - int filler[32]; /* For future use */ -} oss_count_t; -.Ed -.Pp -The -.Fa samples -field contains the total number of samples transferred by the -device so far. -The -.Fa fifo_samples -is the depth of any hardware FIFO. -This structure can be useful for accurate stream positioning and latency -calculations. -.Pp -.It Dv SNDCTL_DSP_GETIPTR -.It Dv SNDCTL_DSP_GETOPTR -The argument is a pointer to a -.Vt struct count_info , -which has the following definition: -.Bd -literal -offset 2n -typedef struct count_info { - unsigned int bytes; - /* Total # of bytes processed */ - int blocks; - /* - * # of fragment transitions since - * last time - */ - int ptr; /* Current DMA pointer value */ -} count_info; -.Ed -.Pp -These ioctls are primarily supplied for compatibility, and should not be used -by most applications. -.Pp -.It Dv SNDCTL_DSP_GETODELAY -The argument is a pointer to an integer. -On return, the integer contains the -number of bytes still to be played before the next byte written are played. -This can be used for accurate determination of device latency. -The result can differ from actual value by up the depth of the internal device -FIFO, which is typically 64 bytes. -.Pp -.It Dv SNDCTL_DSP_GETERROR -The argument is a pointer to a -.Vt struct audio_errinfo , -defined as follows: -.Bd -literal -offset 2n -typedef struct audio_errinfo { - int play_underruns; - int rec_overruns; - unsigned int play_ptradjust; - unsigned int rec_ptradjust; - int play_errorcount; - int rec_errorcount; - int play_lasterror; - int rec_lasterror; - int play_errorparm; - int rec_errorparm; - int filler[16]; -} audio_errinfo; -.Ed -.Pp -For this implementation, only the -.Fa play_underruns -and -.Fa rec_overruns -values are significant. -No other fields are used in this implementation. -.Pp -These fields are reset to zero each time their value is retrieved using this -ioctl. -.El -.Ss "Compatibility IOCTLS" -These ioctls are supplied exclusively for compatibility with existing -applications. -Their use is not recommended, and they are not documented here. -Many of these are implemented as simple no-ops. -.Pp -.Bl -tag -width "Dv" -offset 2n -compact -.It Dv SNDCTL_DSP_POST -.It Dv SNDCTL_DSP_STEREO -.It Dv SNDCTL_DSP_SETDUPLEX -.It Dv SNDCTL_DSP_LOW_WATER -.It Dv SNDCTL_DSP_PROFILE -.It Dv SNDCTL_DSP_GETBLKSIZE -.It Dv SNDCTL_DSP_SUBDIVIDE -.It Dv SNDCTL_DSP_SETFRAGMENT -.It Dv SNDCTL_DSP_COOKEDMODE -.It Dv SNDCTL_DSP_READCTL -.It Dv SNDCTL_DSP_WRITECTL -.It Dv SNDCTL_DSP_SILENCE -.It Dv SNDCTL_DSP_SKIP -.It Dv SNDCTL_DSP_POST -.It Dv SNDCTL_DSP_GET_RECSRC -.It Dv SNDCTL_DSP_SET_RECSRC -.It Dv SNDCTL_DSP_SET_RECSRC_NAMES -.It Dv SNDCTL_DSP_GET_PLAYTGT -.It Dv SNDCTL_DSP_SET_PLAYTGT -.It Dv SNDCTL_DSP_SET_PLAYTGT_NAMES -.It Dv SNDCTL_DSP_GETTRIGGER -.It Dv SNDCTL_DSP_SETTRIGGER -.It Dv SNDCTL_AUDIOINFO_EX -.It Dv SNDCTL_ENGINEINFO -.El -.Sh FILES -The physical audio device names are system dependent and are rarely used by -programmers. -Programmers should use the generic device names listed below. -.Bl -tag -width "/usr/share/audio/samples" -.It Pa /dev/dsp -Symbolic link to the system's primary audio device -.It Pa /dev/mixer -Symbolic link to the pseudo mixer device for the system -.It Pa /dev/sndstat -Symbolic link to the pseudo mixer device for the system -.It Pa /usr/share/audio/samples -Audio files -.El -.Sh ERRORS -An -.Xr open 2 -call fails if: -.Bl -tag -width "EINVAL" -.It Er EBUSY -The requested play or record access is busy and either the -.Dv O_NDELAY -or -.Dv O_NONBLOCK -flag was set in the -.Xr open 2 -request. -.It Er EINTR -The requested play or record access is busy and a signal interrupted the -.Xr open 2 -request. -.It Er EINVAL -The device cannot support the requested play or record access. -.El -.Pp -An -.Xr ioctl 2 -call fails if: -.Bl -tag -width "EINVAL" -.It Er EINVAL -The parameter changes requested in the ioctl are invalid or are not supported -by the device. -.El -.Sh ARCHITECTURE -SPARC -X86 -.Sh INTERFACE STABILITY -Uncommitted -.Sh SEE ALSO -.Xr close 2 , -.Xr fcntl 2 , -.Xr ioctl 2 , -.Xr mmap 2 , -.Xr open 2 , -.Xr poll 2 , -.Xr read 2 , -.Xr write 2 , -.Xr attributes 5 , -.Xr audio 7D , -.Xr mixer 7I |