share/man/man4/pcm.4

   1 .\"
   2 .\" Copyright (c) 1998, Luigi Rizzo
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd May 22, 2005
  29 .Dt SOUND 4
  30 .Os
  31 .Sh NAME
  32 .Nm sound ,
  33 .Nm pcm ,
  34 .Nm snd
  35 .Nd
  36 .Fx
  37 PCM audio device infrastructure
  38 .Sh SYNOPSIS
  39 For a card with bridge driver support, and a PnP card:
  40 .Cd "device sound"
  41 .Pp
  42 For a card without bridge driver support, and a non-PnP card,
  43 the following lines may be required in
  44 .Pa /boot/device.hints :
  45 .Cd hint.pcm.0.at="isa"
  46 .Cd hint.pcm.0.irq="5"
  47 .Cd hint.pcm.0.drq="1"
  48 .Cd hint.pcm.0.flags="0x0"
  49 .Sh DESCRIPTION
  50 .Bf -emphasis
  51 Note: There exists some ambiguity in the naming at the moment
  52 .Pq Nm sound , pcm , snd .
  53 It will be resolved soon by renaming
  54 .Cd "device sound"
  55 to
  56 .Cd "device snd" ,
  57 and doing associated changes.
  58 .Ef
  59 .Pp
  60 The
  61 .Nm
  62 driver provides support for
  63 .Tn PCM
  64 audio play and capture.
  65 This driver also supports various
  66 .Tn PCI ,
  67 .Tn WSS/MSS
  68 compatible,
  69 .Tn ISA
  70 sound cards, and AC97 mixer.
  71 Once the
  72 .Nm
  73 driver attaches, supported devices provide audio record and
  74 playback channels.
  75 The
  76 .Fx
  77 sound system provides dynamic mixing
  78 .Dq VCHAN
  79 and rate conversion
  80 .Dq soft formats .
  81 True full duplex operation is available on most cards.
  82 .Pp
  83 If the sound card is supported by a bridge driver, the
  84 .Nm
  85 driver works in conjunction with the bridge driver.
  86 .Pp
  87 Apart from the usual parameters, the flags field is used to specify
  88 the secondary
  89 .Tn DMA
  90 channel (generally used for capture in full duplex cards).
  91 Flags are set to 0 for cards not using a secondary
  92 .Tn DMA
  93 channel, or to 0x10 + C to specify channel C.
  94 .Pp
  95 The driver works best with
  96 .Tn WSS/MSS
  97 cards, which have a very clean
  98 architecture and an orthogonal set of features.
  99 They also happen to be
 100 among the cheapest audio cards on the market.
 101 .Pp
 102 The driver does its best to recognize the installed hardware and drive
 103 it correctly so the user is not required to add several lines in
 104 .Pa /boot/device.hints .
 105 For
 106 .Tn PCI
 107 and
 108 .Tn ISA
 109 .Tn PnP
 110 cards this is actually easy
 111 since they identify themselves.
 112 For legacy
 113 .Tn ISA
 114 cards, the driver looks for
 115 .Tn MSS
 116 cards at addresses 0x530 and 0x604 (unless overridden
 117 in
 118 .Pa /boot/device.hints ) .
 119 .Ss Boot Variables
 120 In general, the module
 121 .Pa snd_foo
 122 corresponds to
 123 .Cd "device snd_foo"
 124 and can be
 125 loaded by the boot
 126 .Xr loader 8
 127 via
 128 .Xr loader.conf 5
 129 or from the command line using the
 130 .Xr kldload 8
 131 utility.
 132 Options which can be specified in
 133 .Pa /boot/loader.conf
 134 include:
 135 .Bl -tag -width ".Va snd_emu10k1_load" -offset indent
 136 .It Va snd_driver_load
 137 .Pq Dq Li NO
 138 If set to
 139 .Dq Li YES ,
 140 this option loads all available drivers.
 141 .It Va snd_emu10k1_load
 142 .Pq Dq Li NO
 143 If set to
 144 .Dq Li YES ,
 145 only the SoundBlaster 5.1 driver and dependent modules will be loaded.
 146 .It Va snd_foo_load
 147 .Pq Dq Li NO
 148 If set to
 149 .Dq Li YES ,
 150 load driver for card/chipset foo.
 151 .El
 152 .Pp
 153 To define default values for the different mixer channels,
 154 set the channel to the prefered value using hints, e.g.:
 155 .Va hint.pcm.0.line Ns = Ns Qq Li 0 .
 156 This will mute the input channel per default.
 157 .Ss VCHANs
 158 Each device can optionally support more playback channels
 159 that physical hardware provides by using
 160 .Dq virtual channels
 161 or
 162 .Tn VCHANs .
 163 .Tn VCHAN
 164 options can be configured via the
 165 .Xr sysctl 8
 166 interface but can only be manipulated while the device is inactive.
 167 .Ss Runtime Configuration
 168 The following
 169 .Xr sysctl 8
 170 variables are available:
 171 .Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
 172 .It Va hw.snd.pcm%d.buffersize
 173 Configure the amount of
 174 .Tn DMA
 175 bufferspace available for a device.
 176 .It Va hw.snd.targetirqrate
 177 Set the default block size such that continuous
 178 playback will achieve this
 179 .Tn IRQ
 180 rate.
 181 This value can be tuned to improve application performance.
 182 Increase this value when the sound lags and decrease
 183 it if sound stutters or breaks up.
 184 .It Va hw.snd.unit
 185 When using
 186 .Xr devfs 5 ,
 187 the default device for
 188 .Pa /dev/dsp .
 189 Equivalent to a symlink from
 190 .Pa /dev/dsp
 191 to
 192 .Pa /dev/dsp Ns Va ${hw.snd.unit} .
 193 .It Va hw.snd.report_soft_formats
 194 Controls the internal format conversion if it is
 195 available transparently to the application software.
 196 When disabled or not available, the application will
 197 only be able to select formats the device natively supports.
 198 .It Va hw.snd.verbose
 199 Level of verbosity for the
 200 .Pa /dev/sndstat
 201 device.
 202 Higher values include more output and the highest level,
 203 three, should be used when reporting problems.
 204 Other options include:
 205 .Bl -tag -width 2n
 206 .It 0
 207 Installed devices and their allocated bus resources.
 208 .It 1
 209 The number of playback, record, virtual channels, and
 210 flags per device.
 211 .It 2
 212 Channel information per device including the channel's
 213 current format, speed, and pseudo device statistics such as
 214 buffer overruns and buffer underruns.
 215 .It 3
 216 File names and versions of the currently sound loaded modules.
 217 .El
 218 .It Va hw.snd.maxautovchans
 219 Global
 220 .Tn VCHAN
 221 setting that only affects devices that have only one playback channel.
 222 The sound system will dynamically create up this many
 223 .Tn VCHANs .
 224 Set to
 225 .Dq 0
 226 if no
 227 .Tn VCHANS
 228 are desired.
 229 .It Va hw.snd.pcm%d.vchans
 230 The current number of
 231 .Tn VCHANs
 232 allocated per device.
 233 This can be set to preallocate a certain number of
 234 .Tn VCHANs .
 235 Setting this value to
 236 .Dq 0
 237 will disable
 238 .Tn VCHANs
 239 for this device.
 240 .El
 241 .Ss Recording Channels
 242 On devices that have more than one recording source (ie: mic and line),
 243 there is a corresponding
 244 .Pa /dev/dspr%d.%d
 245 device.
 246 .Ss Statistics
 247 Channel statistics are only kept while the device is open.
 248 So with situations involving overruns and underruns, consider the output
 249 while the errant application is open and running.
 250 .Ss IOCTL Support
 251 The driver supports most of the
 252 .Tn OSS
 253 .Fn ioctl
 254 functions, and most applications work unmodified.
 255 A few differences exist, while memory mapped playback is
 256 supported natively and in
 257 .Tn Linux
 258 emulation, memory mapped recording is
 259 not due to
 260 .Tn VM
 261 system design.
 262 As a consequence, some applications may need to be recompiled
 263 with a slightly modified audio module.
 264 See
 265 .In sys/soundcard.h
 266 for a complete list of the supported
 267 .Fn ioctl
 268 functions.
 269 .Sh HARDWARE
 270 The
 271 .Nm
 272 driver supports the following sound cards:
 273 .Pp
 274 .Bl -bullet -compact
 275 .It
 276 CS4231, CS4232, CS4236, CS4237 (ISA)
 277 .It
 278 Creative Labs SoundBlaster PCI
 279 .It
 280 ENSONIQ AudioPCI ES1370/1371
 281 .It
 282 ESS Solo-1/1E (PCI)
 283 .It
 284 Intel 443MX, 810, 815, and 815E integrated sound devices
 285 .It
 286 MSS/WSS Compatible DSPs
 287 .It
 288 NeoMagic 256AV/ZK (PCI)
 289 .It
 290 OPTi931/82C931 (ISA)
 291 .It
 292 Trident 4DWave DX/NX (PCI)
 293 .It
 294 Yamaha OPL-SAx (ISA)
 295 .El
 296 .Sh FILES
 297 The
 298 .Nm
 299 drivers may create the following
 300 device nodes:
 301 .Pp
 302 .Bl -tag -width ".Pa /dev/audio%d.%d" -compact
 303 .It Pa /dev/audio%d.%d
 304 Sparc-compatible audio device.
 305 .It Pa /dev/dsp%d.%d
 306 Digitized voice device.
 307 .It Pa /dev/dspW%d.%d
 308 Like
 309 .Pa /dev/dsp ,
 310 but 16 bits per sample.
 311 .It Pa /dev/dspr%d.%d
 312 Should be connected to a record codec.
 313 .It Pa /dev/sndstat
 314 Current
 315 .Nm
 316 status, including all channels and drivers.
 317 .El
 318 .Pp
 319 The first number in the device node
 320 represents the unit number of the
 321 .Nm
 322 device.
 323 All
 324 .Nm
 325 devices are listed
 326 in
 327 .Pa /dev/sndstat .
 328 Additional messages are sometimes recorded when the
 329 device is probed and attached, these messages can be viewed with the
 330 .Xr dmesg 8
 331 utility.
 332 .Sh DIAGNOSTICS
 333 .Bl -diag
 334 .It ac97: dac not ready
 335 AC97 codec is not likely to be accompanied with the sound card.
 336 .It unsupported subdevice XX
 337 A device node is not created properly.
 338 .El
 339 .Sh SEE ALSO
 340 .Xr snd_ad1816 4 ,
 341 .Xr snd_als4000 4 ,
 342 .Xr snd_audiocs 4 ,
 343 .Xr snd_cmi 4 ,
 344 .Xr snd_cs4281 4 ,
 345 .Xr snd_csa 4 ,
 346 .Xr snd_ds1 4 ,
 347 .Xr snd_emu10k1 4 ,
 348 .Xr snd_es137x 4 ,
 349 .Xr snd_ess 4 ,
 350 .Xr snd_fm801 4 ,
 351 .Xr snd_gusc 4 ,
 352 .Xr snd_ich 4 ,
 353 .Xr snd_maestro 4 ,
 354 .Xr snd_maestro3 4 ,
 355 .Xr snd_neomagic 4 ,
 356 .Xr snd_sbc 4 ,
 357 .Xr snd_solo 4 ,
 358 .Xr snd_uaudio 4 ,
 359 .Xr snd_via8233 4 ,
 360 .Xr snd_via82c686 4 ,
 361 .Xr snd_vibes 4 ,
 362 .Xr devfs 5 ,
 363 .Xr loader.conf 5 ,
 364 .Xr dmesg 8 ,
 365 .Xr kldload 8 ,
 366 .Xr sysctl 8
 367 .Rs
 368 .%T "The OSS API"
 369 .%O "http://www.opensound.com/pguide/oss.pdf"
 370 .Re
 371 .Sh HISTORY
 372 The
 373 .Nm
 374 device driver first appeared in
 375 .Fx 2.2.6
 376 as
 377 .Nm pcm ,
 378 written by
 379 .An Luigi Rizzo .
 380 It was later
 381 rewritten in
 382 .Fx 4.0
 383 by
 384 .An Cameron Grant .
 385 The API evolved from the VOXWARE
 386 standard which later became OSS standard.
 387 .Sh AUTHORS
 388 .An -nosplit
 389 .An Luigi Rizzo Aq luigi@iet.unipi.it
 390 initially wrote the
 391 .Nm pcm
 392 device driver and this manual page.
 393 .An Cameron Grant Aq gandalf@vilnya.demon.co.uk
 394 later revised the device driver for
 395 .Fx 4.0 .
 396 .An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
 397 revised this manual page.
 398 It was then rewritten for
 399 .Fx 5.2 .
 400 .Sh BUGS
 401 Some features of your cards (e.g., global volume control) might not
 402 be supported on all devices.