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.39.2.6 2007/05/23 19:45:49 brueffer Exp $
  27 .\" $DragonFly: src/share/man/man4/pcm.4,v 1.7 2007/06/16 17:44:33 hasso Exp $
  28 .\"
  29 .Dd November 26, 2006
  30 .Dt SOUND 4
  31 .Os
  32 .Sh NAME
  33 .Nm sound ,
  34 .Nm pcm ,
  35 .Nm snd
  36 .Nd
  37 .Dx
  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 The following
 147 .Xr sysctl 8
 148 variables are available:
 149 .Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
 150 .It Va hw.snd.pcm%d.buffersize
 151 Configure the amount of
 152 .Tn DMA
 153 bufferspace available for a device.
 154 .It Va hw.snd.targetirqrate
 155 Set the default block size such that continuous
 156 playback will achieve this
 157 .Tn IRQ
 158 rate.
 159 This value can be tuned to improve application performance.
 160 Increase this value when the sound lags and decrease
 161 it if sound stutters or breaks up.
 162 .It Va hw.snd.report_soft_formats
 163 Controls the internal format conversion if it is
 164 available transparently to the application software.
 165 When disabled or not available, the application will
 166 only be able to select formats the device natively supports.
 167 .It Va hw.snd.verbose
 168 Level of verbosity for the
 169 .Pa /dev/sndstat
 170 device.
 171 Higher values include more output and the highest level,
 172 three, should be used when reporting problems.
 173 Other options include:
 174 .Bl -tag -width 2n
 175 .It 0
 176 Installed devices and their allocated bus resources.
 177 .It 1
 178 The number of playback, record, virtual channels, and
 179 flags per device.
 180 .It 2
 181 Channel information per device including the channel's
 182 current format, speed, and pseudo device statistics such as
 183 buffer overruns and buffer underruns.
 184 .It 3
 185 File names and versions of the currently loaded sound modules.
 186 .El
 187 .It Va hw.snd.maxautovchans
 188 Global
 189 .Tn VCHAN
 190 setting that only affects devices with only one playback channel available.
 191 The sound system will dynamically create up this many
 192 .Tn VCHANs .
 193 Set to
 194 .Dq 0
 195 if no
 196 .Tn VCHANS
 197 are desired.
 198 .It Va hw.snd.pcm%d.vchans
 199 The current number of
 200 .Tn VCHANs
 201 allocated per device.
 202 This can be set to preallocate a certain number of
 203 .Tn VCHANs .
 204 Setting this value to
 205 .Dq 0
 206 will disable
 207 .Tn VCHANs
 208 for this device.
 209 .El
 210 .Ss Recording Channels
 211 On devices that have more than one recording source (ie: mic and line),
 212 there is a corresponding
 213 .Pa /dev/dspr%d.%d
 214 device.
 215 .Ss Statistics
 216 Channel statistics are only kept while the device is open.
 217 So with situations involving overruns and underruns, consider the output
 218 while the errant application is open and running.
 219 .Ss IOCTL Support
 220 The driver supports most of the
 221 .Tn OSS
 222 .Fn ioctl
 223 functions, and most applications work unmodified.
 224 A few differences exist, while memory mapped playback is
 225 supported natively and in
 226 .Tn Linux
 227 emulation, memory mapped recording is
 228 not due to
 229 .Tn VM
 230 system design.
 231 As a consequence, some applications may need to be recompiled
 232 with a slightly modified audio module.
 233 See
 234 .In sys/soundcard.h
 235 for a complete list of the supported
 236 .Fn ioctl
 237 functions.
 238 .Sh FILES
 239 The
 240 .Nm
 241 drivers may use the following
 242 device nodes:
 243 .Pp
 244 .Bl -tag -width ".Pa /dev/audio%d.%d" -compact
 245 .It Pa /dev/audio%d.%d
 246 Sparc-compatible audio device.
 247 .It Pa /dev/dsp%d.%d
 248 Digitized voice device.
 249 .It Pa /dev/dspW%d.%d
 250 Like
 251 .Pa /dev/dsp ,
 252 but 16 bits per sample.
 253 .It Pa /dev/dspr%d.%d
 254 Should be connected to a record codec.
 255 .It Pa /dev/sndstat
 256 Current
 257 .Nm
 258 status, including all channels and drivers.
 259 .El
 260 .Pp
 261 The first number in the device node
 262 represents the unit number of the
 263 .Nm
 264 device.
 265 All
 266 .Nm
 267 devices are listed
 268 in
 269 .Pa /dev/sndstat .
 270 Additional messages are sometimes recorded when the
 271 device is probed and attached, these messages can be viewed with the
 272 .Xr dmesg 8
 273 utility.
 274 .Sh DIAGNOSTICS
 275 .Bl -diag
 276 .It ac97: dac not ready
 277 AC97 codec is not likely to be accompanied with the sound card.
 278 .It unsupported subdevice XX
 279 A device node is not created properly.
 280 .El
 281 .Sh SEE ALSO
 282 .Xr snd_ad1816 4 ,
 283 .Xr snd_als4000 4 ,
 284 .Xr snd_atiixp 4 ,
 285 .Xr snd_cmi 4 ,
 286 .Xr snd_cs4281 4 ,
 287 .Xr snd_csa 4 ,
 288 .Xr snd_ds1 4 ,
 289 .Xr snd_emu10k1 4 ,
 290 .Xr snd_envy24 4 ,
 291 .Xr snd_envy24ht 4 ,
 292 .Xr snd_es137x 4 ,
 293 .Xr snd_ess 4 ,
 294 .Xr snd_fm801 4 ,
 295 .Xr snd_gusc 4 ,
 296 .Xr snd_hda 4 ,
 297 .Xr snd_ich 4 ,
 298 .Xr snd_maestro 4 ,
 299 .Xr snd_maestro3 4 ,
 300 .Xr snd_mss 4 ,
 301 .Xr snd_neomagic 4 ,
 302 .Xr snd_sbc 4 ,
 303 .Xr snd_solo 4 ,
 304 .Xr snd_spicds 4 ,
 305 .Xr snd_t4dwave 4 ,
 306 .Xr snd_uaudio 4 ,
 307 .Xr snd_via8233 4 ,
 308 .Xr snd_via82c686 4 ,
 309 .Xr snd_vibes 4 ,
 310 .Xr loader.conf 5 ,
 311 .Xr dmesg 8 ,
 312 .Xr kldload 8 ,
 313 .Xr sysctl 8
 314 .Rs
 315 .%T "The OSS API"
 316 .%O "http://www.opensound.com/pguide/oss.pdf"
 317 .Re
 318 .Sh HISTORY
 319 The
 320 .Nm
 321 device driver first appeared in
 322 .Fx 2.2.6
 323 as
 324 .Nm pcm ,
 325 written by
 326 .An Luigi Rizzo .
 327 It was later
 328 rewritten in
 329 .Fx 4.0
 330 by
 331 .An Cameron Grant .
 332 The API evolved from the VOXWARE
 333 standard which later became OSS standard.
 334 .Sh AUTHORS
 335 .An -nosplit
 336 .An Luigi Rizzo Aq luigi@iet.unipi.it
 337 initially wrote the
 338 .Nm pcm
 339 device driver and this manual page.
 340 .An Cameron Grant Aq gandalf@vilnya.demon.co.uk
 341 later revised the device driver for
 342 .Fx 4.0 .
 343 .An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
 344 revised this manual page.
 345 It was then rewritten for
 346 .Fx 5.2 .
 347 .Sh BUGS
 348 Some features of your sound card (e.g., global volume control) might not
 349 be supported on all devices.