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 November 29, 2006
  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 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.feeder_rate_round
 195 Sample rate rounding threshold, to avoid large prime division at the
 196 cost of accuracy.
 197 All requested sample rates will be rounded to the nearest threshold value.
 198 Possible values range between 0 (disabled) and 500.
 199 Default is 25.
 200 .It Va hw.snd.feeder_rate_max
 201 Maximum allowable sample rate.
 202 .It Va hw.snd.feeder_rate_min
 203 Minimum allowable sample rate.
 204 .It Va hw.snd.verbose
 205 Level of verbosity for the
 206 .Pa /dev/sndstat
 207 device.
 208 Higher values include more output and the highest level,
 209 four, should be used when reporting problems.
 210 Other options include:
 211 .Bl -tag -width 2n
 212 .It 0
 213 Installed devices and their allocated bus resources.
 214 .It 1
 215 The number of playback, record, virtual channels, and
 216 flags per device.
 217 .It 2
 218 Channel information per device including the channel's
 219 current format, speed, and pseudo device statistics such as
 220 buffer overruns and buffer underruns.
 221 .It 3
 222 File names and versions of the currently loaded sound modules.
 223 .It 4
 224 Various messages intended for debugging.
 225 .El
 226 .It Va hw.snd.maxautovchans
 227 Global
 228 .Tn VCHAN
 229 setting that only affects devices with only one playback channel available.
 230 The sound system will dynamically create up this many
 231 .Tn VCHANs .
 232 Set to
 233 .Dq 0
 234 if no
 235 .Tn VCHANS
 236 are desired.
 237 Maximum value is 255.
 238 .It Va hw.snd.default_unit
 239 Default sound card for systems with multiple sound cards.
 240 When using
 241 .Xr devfs 5 ,
 242 the default device for
 243 .Pa /dev/dsp .
 244 Equivalent to a symlink from
 245 .Pa /dev/dsp
 246 to
 247 .Pa /dev/dsp Ns Va ${hw.snd.default_unit} .
 248 .It Va dev.pcm.%d.vchans
 249 The current number of
 250 .Tn VCHANs
 251 allocated per device.
 252 This can be set to preallocate a certain number of
 253 .Tn VCHANs .
 254 Setting this value to
 255 .Dq 0
 256 will disable
 257 .Tn VCHANs
 258 for this device.
 259 .It Va dev.pcm.%d.vchanrate
 260 Sample rate speed for
 261 .Tn VCHAN
 262 mixing.
 263 All playback paths will be converted to this sample rate before the mixing
 264 process begins.
 265 .It Va dev.pcm.%d.vchanformat
 266 Format for
 267 .Tn VCHAN
 268 mixing.
 269 All playback paths will be converted to this format before the mixing
 270 process begins.
 271 .It Va dev.pcm.%d.polling
 272 Experimental polling mode support where the driver operates by querying the
 273 device state on each tick using a
 274 .Xr callout 9
 275 mechanism.
 276 Disabled by default and currently only available for a few device drivers.
 277 .El
 278 .Ss Recording Channels
 279 On devices that have more than one recording source (ie: mic and line),
 280 there is a corresponding
 281 .Pa /dev/dsp%d.r%d
 282 device.
 283 .Ss Statistics
 284 Channel statistics are only kept while the device is open.
 285 So with situations involving overruns and underruns, consider the output
 286 while the errant application is open and running.
 287 .Ss IOCTL Support
 288 The driver supports most of the
 289 .Tn OSS
 290 .Fn ioctl
 291 functions, and most applications work unmodified.
 292 A few differences exist, while memory mapped playback is
 293 supported natively and in
 294 .Tn Linux
 295 emulation, memory mapped recording is
 296 not due to
 297 .Tn VM
 298 system design.
 299 As a consequence, some applications may need to be recompiled
 300 with a slightly modified audio module.
 301 See
 302 .In sys/soundcard.h
 303 for a complete list of the supported
 304 .Fn ioctl
 305 functions.
 306 .Sh FILES
 307 The
 308 .Nm
 309 drivers may create the following
 310 device nodes:
 311 .Pp
 312 .Bl -tag -width ".Pa /dev/audio%d.%d" -compact
 313 .It Pa /dev/audio%d.%d
 314 Sparc-compatible audio device.
 315 .It Pa /dev/dsp%d.%d
 316 Digitized voice device.
 317 .It Pa /dev/dspW%d.%d
 318 Like
 319 .Pa /dev/dsp ,
 320 but 16 bits per sample.
 321 .It Pa /dev/dsp%d.p%d
 322 Playback channel.
 323 .It Pa /dev/dsp%d.r%d
 324 Record channel.
 325 .It Pa /dev/dsp%d.v%d
 326 Virtual channel.
 327 .It Pa /dev/sndstat
 328 Current
 329 .Nm
 330 status, including all channels and drivers.
 331 .El
 332 .Pp
 333 The first number in the device node
 334 represents the unit number of the
 335 .Nm
 336 device.
 337 All
 338 .Nm
 339 devices are listed
 340 in
 341 .Pa /dev/sndstat .
 342 Additional messages are sometimes recorded when the
 343 device is probed and attached, these messages can be viewed with the
 344 .Xr dmesg 8
 345 utility.
 346 .Sh DIAGNOSTICS
 347 .Bl -diag
 348 .It pcm%d:play:%d:dsp%d.p%d: play interrupt timeout, channel dead
 349 The hardware does not generate interrupts to serve incoming (play)
 350 or outgoing (record) data.
 351 .It unsupported subdevice XX
 352 A device node is not created properly.
 353 .El
 354 .Sh SEE ALSO
 355 .Xr snd_ad1816 4 ,
 356 .Xr snd_als4000 4 ,
 357 .Xr snd_atiixp 4 ,
 358 .Xr snd_audiocs 4 ,
 359 .Xr snd_cmi 4 ,
 360 .Xr snd_cs4281 4 ,
 361 .Xr snd_csa 4 ,
 362 .Xr snd_ds1 4 ,
 363 .Xr snd_emu10k1 4 ,
 364 .Xr snd_emu10kx 4 ,
 365 .Xr snd_envy24 4 ,
 366 .Xr snd_envy24ht 4 ,
 367 .Xr snd_es137x 4 ,
 368 .Xr snd_ess 4 ,
 369 .Xr snd_fm801 4 ,
 370 .Xr snd_gusc 4 ,
 371 .Xr snd_hda 4 ,
 372 .Xr snd_ich 4 ,
 373 .Xr snd_maestro 4 ,
 374 .Xr snd_maestro3 4 ,
 375 .Xr snd_mss 4 ,
 376 .Xr snd_neomagic 4 ,
 377 .Xr snd_sbc 4 ,
 378 .Xr snd_solo 4 ,
 379 .Xr snd_spicds 4 ,
 380 .Xr snd_t4dwave 4 ,
 381 .Xr snd_uaudio 4 ,
 382 .Xr snd_via8233 4 ,
 383 .Xr snd_via82c686 4 ,
 384 .Xr snd_vibes 4 ,
 385 .Xr devfs 5 ,
 386 .Xr device.hints 5 ,
 387 .Xr loader.conf 5 ,
 388 .Xr dmesg 8 ,
 389 .Xr kldload 8 ,
 390 .Xr sysctl 8
 391 .Rs
 392 .%T "The OSS API"
 393 .%O "http://www.opensound.com/pguide/oss.pdf"
 394 .Re
 395 .Sh HISTORY
 396 The
 397 .Nm
 398 device driver first appeared in
 399 .Fx 2.2.6
 400 as
 401 .Nm pcm ,
 402 written by
 403 .An Luigi Rizzo .
 404 It was later
 405 rewritten in
 406 .Fx 4.0
 407 by
 408 .An Cameron Grant .
 409 The API evolved from the VOXWARE
 410 standard which later became OSS standard.
 411 .Sh AUTHORS
 412 .An -nosplit
 413 .An Luigi Rizzo Aq luigi@iet.unipi.it
 414 initially wrote the
 415 .Nm pcm
 416 device driver and this manual page.
 417 .An Cameron Grant Aq gandalf@vilnya.demon.co.uk
 418 later revised the device driver for
 419 .Fx 4.0 .
 420 .An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
 421 revised this manual page.
 422 It was then rewritten for
 423 .Fx 5.2 .
 424 .Sh BUGS
 425 Some features of your sound card (e.g., global volume control) might not
 426 be supported on all devices.