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