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