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 June 23, 2007
  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 To compile this driver into the kernel, place the following line in your
  40 kernel configuration file:
  41 .Bd -ragged -offset indent
  42 .Cd "device sound"
  43 .Ed
  44 .Pp
  45 Non-PnP sound cards require the following lines in
  46 .Xr device.hints 5 :
  47 .Bd -literal -offset indent
  48 hint.pcm.0.at="isa"
  49 hint.pcm.0.irq="5"
  50 hint.pcm.0.drq="1"
  51 hint.pcm.0.flags="0x0"
  52 .Ed
  53 .Sh DESCRIPTION
  54 .Bf -emphasis
  55 Note: There exists some ambiguity in the naming at the moment
  56 .Pq Nm sound , pcm , snd .
  57 It will be resolved soon by renaming
  58 .Cd "device sound"
  59 to
  60 .Cd "device snd" ,
  61 and doing associated changes.
  62 .Ef
  63 .Pp
  64 The
  65 .Nm
  66 driver provides support for
  67 .Tn PCM
  68 audio play and capture.
  69 This driver also supports various
  70 .Tn PCI ,
  71 .Tn ISA ,
  72 .Tn WSS/MSS
  73 compatible
  74 sound cards, AC97 mixer and High Definition Audio.
  75 Once the
  76 .Nm
  77 driver attaches, supported devices provide audio record and
  78 playback channels.
  79 The
  80 .Fx
  81 sound system provides dynamic mixing
  82 .Dq VCHAN
  83 and rate conversion
  84 .Dq soft formats .
  85 True full duplex operation is available on most sound cards.
  86 .Pp
  87 If the sound card is supported by a bridge driver, the
  88 .Nm
  89 driver works in conjunction with the bridge driver.
  90 .Pp
  91 Apart from the usual parameters, the flags field is used to specify
  92 the secondary
  93 .Tn DMA
  94 channel (generally used for capture in full duplex cards).
  95 Flags are set to 0 for cards not using a secondary
  96 .Tn DMA
  97 channel, or to 0x10 + C to specify channel C.
  98 .Pp
  99 The driver does its best to recognize the installed hardware and drive
 100 it correctly so the user is not required to add several lines in
 101 .Pa /boot/device.hints .
 102 For
 103 .Tn PCI
 104 and
 105 .Tn ISA
 106 .Tn PnP
 107 cards this is actually easy
 108 since they identify themselves.
 109 For legacy
 110 .Tn ISA
 111 cards, the driver looks for
 112 .Tn MSS
 113 cards at addresses 0x530 and 0x604 (unless overridden
 114 in
 115 .Pa /boot/device.hints ) .
 116 .Ss Boot Variables
 117 In general, the module
 118 .Pa snd_foo
 119 corresponds to
 120 .Cd "device snd_foo"
 121 and can be
 122 loaded by the boot
 123 .Xr loader 8
 124 via
 125 .Xr loader.conf 5
 126 or from the command line using the
 127 .Xr kldload 8
 128 utility.
 129 Options which can be specified in
 130 .Pa /boot/loader.conf
 131 include:
 132 .Bl -tag -width ".Va snd_emu10k1_load" -offset indent
 133 .It Va snd_driver_load
 134 .Pq Dq Li NO
 135 If set to
 136 .Dq Li YES ,
 137 this option loads all available drivers.
 138 .It Va snd_emu10k1_load
 139 .Pq Dq Li NO
 140 If set to
 141 .Dq Li YES ,
 142 only the SoundBlaster 5.1 driver and dependent modules will be loaded.
 143 .It Va snd_foo_load
 144 .Pq Dq Li NO
 145 If set to
 146 .Dq Li YES ,
 147 load driver for card/chipset foo.
 148 .El
 149 .Pp
 150 To define default values for the different mixer channels,
 151 set the channel to the preferred value using hints, e.g.:
 152 .Va hint.pcm.0.line Ns = Ns Qq Li 0 .
 153 This will mute the input channel per default.
 154 .Ss VCHANs
 155 Each device can optionally support more playback and recording channels
 156 than physical hardware provides by using
 157 .Dq virtual channels
 158 or
 159 .Tn VCHANs .
 160 .Tn VCHAN
 161 options can be configured via the
 162 .Xr sysctl 8
 163 interface but can only be manipulated while the device is inactive.
 164 .Ss Runtime Configuration
 165 There are a number of
 166 .Xr sysctl 8
 167 variables available.
 168 .Va hw.snd.*
 169 tunables are global settings and
 170 .Va dev.pcm.*
 171 are device specific.
 172 .Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
 173 .It Va hw.snd.latency_profile
 174 Define sets of buffering latency conversion tables for the
 175 .Va hw.snd.latency
 176 tunable.
 177 A value of 0 will use a low and aggressive latency profile which can result
 178 in possible underruns if the application cannot keep up with a rapid irq
 179 rate, especially during high workload.
 180 The default value is 1, which is considered a moderate/safe latency profile.
 181 .It Va hw.snd.latency
 182 Configure the buffering latency.
 183 Only affects applications that do not explicitly request
 184 blocksize / fragments.
 185 This tunable provides finer granularity than the
 186 .Va hw.snd.latency_profile
 187 tunable.
 188 Possible values range between 0 (lowest latency) and 10 (highest latency).
 189 .It Va hw.snd.report_soft_formats
 190 Controls the internal format conversion if it is
 191 available transparently to the application software.
 192 When disabled or not available, the application will
 193 only be able to select formats the device natively supports.
 194 .It Va hw.snd.compat_linux_mmap
 195 Enable to allow PROT_EXEC page mappings.
 196 All Linux applications using sound and
 197 .Xr mmap 2
 198 require this.
 199 .It Va hw.snd.feeder_rate_round
 200 Sample rate rounding threshold, to avoid large prime division at the
 201 cost of accuracy.
 202 All requested sample rates will be rounded to the nearest threshold value.
 203 Possible values range between 0 (disabled) and 500.
 204 Default is 25.
 205 .It Va hw.snd.feeder_rate_max
 206 Maximum allowable sample rate.
 207 .It Va hw.snd.feeder_rate_min
 208 Minimum allowable sample rate.
 209 .It Va hw.snd.verbose
 210 Level of verbosity for the
 211 .Pa /dev/sndstat
 212 device.
 213 Higher values include more output and the highest level,
 214 four, should be used when reporting problems.
 215 Other options include:
 216 .Bl -tag -width 2n
 217 .It 0
 218 Installed devices and their allocated bus resources.
 219 .It 1
 220 The number of playback, record, virtual channels, and
 221 flags per device.
 222 .It 2
 223 Channel information per device including the channel's
 224 current format, speed, and pseudo device statistics such as
 225 buffer overruns and buffer underruns.
 226 .It 3
 227 File names and versions of the currently loaded sound modules.
 228 .It 4
 229 Various messages intended for debugging.
 230 .El
 231 .It Va hw.snd.maxautovchans
 232 Global
 233 .Tn VCHAN
 234 setting that only affects devices with at least one playback or recording channel available.
 235 The sound system will dynamically create up this many
 236 .Tn VCHANs .
 237 Set to
 238 .Dq 0
 239 if no
 240 .Tn VCHANS
 241 are desired.
 242 Maximum value is 256.
 243 .It Va hw.snd.default_unit
 244 Default sound card for systems with multiple sound cards.
 245 When using
 246 .Xr devfs 5 ,
 247 the default device for
 248 .Pa /dev/dsp .
 249 Equivalent to a symlink from
 250 .Pa /dev/dsp
 251 to
 252 .Pa /dev/dsp Ns Va ${hw.snd.default_unit} .
 253 .It Va hw.snd.default_auto
 254 Enable to automatically assign default sound unit to the most recent
 255 attached device.
 256 .It Va dev.pcm.%d.[play|rec].vchans
 257 The current number of
 258 .Tn VCHANs
 259 allocated per device.
 260 This can be set to preallocate a certain number of
 261 .Tn VCHANs .
 262 Setting this value to
 263 .Dq 0
 264 will disable
 265 .Tn VCHANs
 266 for this device.
 267 .It Va dev.pcm.%d.[play|rec].vchanrate
 268 Sample rate speed for
 269 .Tn VCHAN
 270 mixing.
 271 All playback paths will be converted to this sample rate before the mixing
 272 process begins.
 273 .It Va dev.pcm.%d.[play|rec].vchanformat
 274 Format for
 275 .Tn VCHAN
 276 mixing.
 277 All playback paths will be converted to this format before the mixing
 278 process begins.
 279 .It Va dev.pcm.%d.polling
 280 Experimental polling mode support where the driver operates by querying the
 281 device state on each tick using a
 282 .Xr callout 9
 283 mechanism.
 284 Disabled by default and currently only available for a few device drivers.
 285 .El
 286 .Ss Recording Channels
 287 On devices that have more than one recording source (ie: mic and line),
 288 there is a corresponding
 289 .Pa /dev/dsp%d.r%d
 290 device.
 291 .Ss Statistics
 292 Channel statistics are only kept while the device is open.
 293 So with situations involving overruns and underruns, consider the output
 294 while the errant application is open and running.
 295 .Ss IOCTL Support
 296 The driver supports most of the
 297 .Tn OSS
 298 .Fn ioctl
 299 functions, and most applications work unmodified.
 300 A few differences exist, while memory mapped playback is
 301 supported natively and in
 302 .Tn Linux
 303 emulation, memory mapped recording is
 304 not due to
 305 .Tn VM
 306 system design.
 307 As a consequence, some applications may need to be recompiled
 308 with a slightly modified audio module.
 309 See
 310 .In sys/soundcard.h
 311 for a complete list of the supported
 312 .Fn ioctl
 313 functions.
 314 .Sh FILES
 315 The
 316 .Nm
 317 drivers may create the following
 318 device nodes:
 319 .Pp
 320 .Bl -tag -width ".Pa /dev/audio%d.%d" -compact
 321 .It Pa /dev/audio%d.%d
 322 Sparc-compatible audio device.
 323 .It Pa /dev/dsp%d.%d
 324 Digitized voice device.
 325 .It Pa /dev/dspW%d.%d
 326 Like
 327 .Pa /dev/dsp ,
 328 but 16 bits per sample.
 329 .It Pa /dev/dsp%d.p%d
 330 Playback channel.
 331 .It Pa /dev/dsp%d.r%d
 332 Record channel.
 333 .It Pa /dev/dsp%d.vp%d
 334 Virtual playback channel.
 335 .It Pa /dev/dsp%d.vr%d
 336 Virtual recording channel.
 337 .It Pa /dev/sndstat
 338 Current
 339 .Nm
 340 status, including all channels and drivers.
 341 .El
 342 .Pp
 343 The first number in the device node
 344 represents the unit number of the
 345 .Nm
 346 device.
 347 All
 348 .Nm
 349 devices are listed
 350 in
 351 .Pa /dev/sndstat .
 352 Additional messages are sometimes recorded when the
 353 device is probed and attached, these messages can be viewed with the
 354 .Xr dmesg 8
 355 utility.
 356 .Pp
 357 The above device nodes are only created on demand through the dynamic
 358 .Xr devfs 5
 359 clone handler.
 360 Users are strongly discouraged to access them directly.
 361 For specific sound card access, please instead use
 362 .Pa /dev/dsp
 363 or
 364 .Pa /dev/dsp%d .
 365 .Sh DIAGNOSTICS
 366 .Bl -diag
 367 .It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead
 368 The hardware does not generate interrupts to serve incoming (play)
 369 or outgoing (record) data.
 370 .It unsupported subdevice XX
 371 A device node is not created properly.
 372 .El
 373 .Sh SEE ALSO
 374 .Xr snd_ad1816 4 ,
 375 .Xr snd_als4000 4 ,
 376 .Xr snd_atiixp 4 ,
 377 .Xr snd_audiocs 4 ,
 378 .Xr snd_cmi 4 ,
 379 .Xr snd_cs4281 4 ,
 380 .Xr snd_csa 4 ,
 381 .Xr snd_ds1 4 ,
 382 .Xr snd_emu10k1 4 ,
 383 .Xr snd_emu10kx 4 ,
 384 .Xr snd_envy24 4 ,
 385 .Xr snd_envy24ht 4 ,
 386 .Xr snd_es137x 4 ,
 387 .Xr snd_ess 4 ,
 388 .Xr snd_fm801 4 ,
 389 .Xr snd_gusc 4 ,
 390 .Xr snd_hda 4 ,
 391 .Xr snd_ich 4 ,
 392 .Xr snd_maestro 4 ,
 393 .Xr snd_maestro3 4 ,
 394 .Xr snd_mss 4 ,
 395 .Xr snd_neomagic 4 ,
 396 .Xr snd_sbc 4 ,
 397 .Xr snd_solo 4 ,
 398 .Xr snd_spicds 4 ,
 399 .Xr snd_t4dwave 4 ,
 400 .Xr snd_uaudio 4 ,
 401 .Xr snd_via8233 4 ,
 402 .Xr snd_via82c686 4 ,
 403 .Xr snd_vibes 4 ,
 404 .Xr devfs 5 ,
 405 .Xr device.hints 5 ,
 406 .Xr loader.conf 5 ,
 407 .Xr dmesg 8 ,
 408 .Xr kldload 8 ,
 409 .Xr sysctl 8
 410 .Rs
 411 .%T "The OSS API"
 412 .%O "http://www.opensound.com/pguide/oss.pdf"
 413 .Re
 414 .Sh HISTORY
 415 The
 416 .Nm
 417 device driver first appeared in
 418 .Fx 2.2.6
 419 as
 420 .Nm pcm ,
 421 written by
 422 .An Luigi Rizzo .
 423 It was later
 424 rewritten in
 425 .Fx 4.0
 426 by
 427 .An Cameron Grant .
 428 The API evolved from the VOXWARE
 429 standard which later became OSS standard.
 430 .Sh AUTHORS
 431 .An -nosplit
 432 .An Luigi Rizzo Aq luigi@iet.unipi.it
 433 initially wrote the
 434 .Nm pcm
 435 device driver and this manual page.
 436 .An Cameron Grant Aq gandalf@vilnya.demon.co.uk
 437 later revised the device driver for
 438 .Fx 4.0 .
 439 .An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
 440 revised this manual page.
 441 It was then rewritten for
 442 .Fx 5.2 .
 443 .Sh BUGS
 444 Some features of your sound card (e.g., global volume control) might not
 445 be supported on all devices.