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 14, 2003
  29 .Dt PCM 4
  30 .Os
  31 .Sh NAME
  32 .Nm pcm ,
  33 .Nm snd
  34 .Nd FreeBSD PCM audio device infrastructure
  35 .Sh SYNOPSIS
  36 For a card with bridge driver support, and a PnP card:
  37 .Cd "device pcm"
  38 .Pp
  39 For a card without bridge driver support, and a non-PnP card,
  40 the following lines may be required in
  41 .Pa /boot/device.hints :
  42 .Cd hint.pcm.0.at="isa"
  43 .Cd hint.pcm.0.irq="5"
  44 .Cd hint.pcm.0.drq="1"
  45 .Cd hint.pcm.0.flags="0x0"
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 driver provides support for
  50 .Tn PCM
  51 audio play and capture.
  52 This driver also supports various
  53 .Tn PCI ,
  54 .Tn WSS/MSS
  55 compatible,
  56 .Tn ISA
  57 sound cards, and AC97 mixer.
  58 Once the
  59 .Nm
  60 driver attaches, supported devices provide audio record and
  61 playback channels.
  62 The
  63 .Fx
  64 sound system provides dynamic mixing
  65 .Dq VCHAN
  66 and rate conversion
  67 .Dq soft formats .
  68 True full duplex operation is available on most cards.
  69 .Pp
  70 If the sound card is supported by a bridge driver, the
  71 .Nm
  72 driver works in conjunction with the bridge driver.
  73 .Pp
  74 Apart from the usual parameters, the flags field is used to specify
  75 the secondary
  76 .Tn DMA
  77 channel (generally used for capture in full duplex cards).
  78 Flags are set to 0 for cards not using a secondary
  79 .Tn DMA
  80 channel, or to 0x10 + C to specify channel C.
  81 .Pp
  82 The driver works best with
  83 .Tn WSS/MSS
  84 cards, which have a very clean
  85 architecture and an orthogonal set of features.
  86 They also happen to be
  87 among the cheapest audio cards on the market.
  88 .Pp
  89 The driver does its best to recognize the installed hardware and drive
  90 it correctly so the user is not required to add several lines in
  91 .Pa /boot/device.hints .
  92 For
  93 .Tn PCI
  94 and
  95 .Tn ISA
  96 .Tn PnP
  97 cards this is actually easy
  98 since they identify themselves.
  99 For legacy
 100 .Tn ISA
 101 cards, the driver looks for
 102 .Tn MSS
 103 cards at addresses 0x530 and 0x604 (unless overridden
 104 in
 105 .Pa /boot/device.hints ) .
 106 .Ss Boot Variables
 107 In general, the module
 108 .Pa snd_foo
 109 corresponds to device foo and can be
 110 loaded by the boot loader via
 111 .Pa boot/loader.conf
 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 snd_emu10k1_load -offset indent
 119 .It Va snd_driver_load
 120 .Pq Dq NO
 121 If set to
 122 .Dq YES ,
 123 this option loads all available drivers.
 124 .It Va snd_emu10k1_load
 125 .Pq Dq NO
 126 If set to
 127 .Dq YES ,
 128 Only the SoundBlaster 5.1 driver and dependent modules will be loaded.
 129 .It Va snd_foo_load
 130 .Pq Dq NO
 131 If set to
 132 .Dq YES ,
 133 load driver for card/chipset foo.
 134 .El
 135 .Ss VCHANS
 136 Each device can optionally support more playback channels
 137 that 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 tunables are available:
 149 .Bl -tag -width ".It 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.unit
 163 When using
 164 .Xr devfs 5 ,
 165 the default device for
 166 .Pa /dev/dsp .
 167 Equivalent to a symlink from
 168 .Pa /dev/dsp
 169 to
 170 .Pa /dev/dsp${hw.snd.unit} .
 171 .It Va hw.snd.report_soft_formats
 172 Controls the internal format conversion if it is
 173 available transparently to the application software.
 174 When disabled or not available, the application will
 175 only be able to select formats the device natively supports.
 176 .It Va hw.snd.verbose
 177 Level of verbosity for the
 178 .Pa /dev/sndstat
 179 device.
 180 Higher values include more output and the highest level,
 181 three, should be used when reported problems.
 182 Other options include:
 183 0 - Installed devices and their allocated bus resources.
 184 1 - The number of playback, record, virtual channels, and
 185 flags per device.
 186 2 - Channel information per device including the channel's
 187 current format, speed, and pseudo device statistics such as
 188 buffer overruns and buffer underruns.
 189 3 - File names and versions of the currently sound loaded modules.
 190 .It Va hw.snd.maxautovchans
 191 Global
 192 .Tn VCHAN
 193 setting that only affects devices that have only one playback channel.
 194 The sound system will dynamically create up this many
 195 .Tn VCHANs .
 196 Set to
 197 .Dq 0
 198 if no
 199 .Tn VCHANS
 200 are desired.
 201 .It Va hw.snd.pcm%d.vchans
 202 The current number of
 203 .Tn VCHANs
 204 allocated per device.
 205 This can be set to preallocate a certain number of
 206 .Tn VCHANs .
 207 Setting this value to
 208 .Dq 0
 209 will disable
 210 .Tn VCHANs
 211 for this device.
 212 .El
 213 .Ss Recording Channels
 214 On devices that have more than one recording source (ie: mic and line),
 215 there is a corresponding
 216 .Pa /dev/dspr%d.%d
 217 device.
 218 .Ss Statistics
 219 Channel statistics are only kept while the device is open.
 220 So with situations involving overruns and underruns, consider the output
 221 while the errant application is open and running.
 222 .Ss IOCTL Support
 223 The driver supports most of the
 224 .Tn OSS
 225 .Fn ioctl
 226 functions, and most applications work unmodified.
 227 A few differences exist, while memory mapped playback is
 228 supported natively and in Linux emulation, memory mapped recording is
 229 not due to
 230 .Tn VM
 231 system design.
 232 As a consequence, some applications may need to be recompiled
 233 with a slightly modified audio module.
 234 See
 235 .In sys/soundcard.h
 236 for a complete list of the supported
 237 .Fn ioctl
 238 functions.
 239 .Ss SUPPORTED CARDS
 240 Below we include a list of supported codecs/cards.
 241 If your sound card
 242 is not listed here, it may be supported by a bridge driver.
 243 .Bl -tag -width 2m
 244 .It CS4237, CS4236, CS4232, CS4231 (ISA)
 245 All these cards work perfectly in full duplex using the MSS mode.
 246 This chipset is used, among others, on the A/Open AW35 and AW32, on
 247 some Intel motherboards, and (the CS4231) on some non-PnP cards.
 248 .Pp
 249 The CS4232 is reported as buggy in the Voxware documentation but
 250 I am not sure if this is true.
 251 On one of my Intel motherboards,
 252 capture does not work simply because the capture DMA channel is
 253 not wired to the ISA DMA controller.
 254 .It Yamaha OPL-SAx (ISA)
 255 Works perfectly in all modes.
 256 This chip is used in several PnP cards,
 257 but also (in non-PnP mode) on motherboards and laptops (e.g. the
 258 Toshiba Libretto).
 259 .It OPTi931 (ISA)
 260 The chip is buggy, but the driver has many workarounds to make it work
 261 in full duplex because for some time these were the only full duplex
 262 cards I could find. u-law formats uses U8 format internally because of
 263 a bug in the chip.
 264 .It Trident 4DWave DX/NX (PCI)
 265 .It ENSONIQ AudioPCI ES1370/1371 (PCI)
 266 Creative Labs SoundBlaster PCI is supported as well.
 267 .It ESS Solo-1/1E (PCI)
 268 .It NeoMagic 256AV/ZX (PCI)
 269 .El
 270 .Sh FILES
 271 The
 272 .Nm
 273 drivers may create the following
 274 device nodes:
 275 .Pp
 276 .Bl -tag -width "/dev/dspr%d.%dXXX" -compact
 277 .It Pa /dev/audio%d.%d
 278 Sparc-compatible audio device.
 279 .It Pa /dev/dsp%d.%d
 280 Digitized voice device.
 281 .It Pa /dev/dspW%d.%d
 282 Like
 283 .Pa /dev/dsp ,
 284 but 16 bits per sample.
 285 .It Pa /dev/dspr%d.%d
 286 Should be connected to a record codec.
 287 .It Pa /dev/sndstat
 288 Current
 289 .Nm
 290 status, including all channels and drivers.
 291 .El
 292 .Pp
 293 The first number in the device node
 294 represents the unit number of the
 295 .Nm PCM
 296 device.
 297 All
 298 .Nm
 299 PCM
 300 devices are listed
 301 in
 302 .Pa /dev/sndstat.
 303 Additional messages are sometimes recorded when the
 304 device is probed and attached, these messages can be viewed with the
 305 .Xr dmesg 8
 306 utility.
 307 .Sh DIAGNOSTICS
 308 .Bl -tag -width 2m
 309 .It ac97: dac not ready
 310 AC97 codec is not likely to be accompanied with the sound card.
 311 .It unsupported subdevice XX
 312 A device node is not created properly.
 313 .El
 314 .Sh BUGS
 315 Some features of your cards (e.g. global volume control) might not
 316 be supported on all devices.
 317 .Sh HISTORY
 318 The
 319 .Nm
 320 device driver first appeared in
 321 .Fx 2.2.6 written by Luigi Rizzo.
 322 It was later
 323 rewritten in
 324 .Fx 4.0 by Cameron Grant.
 325 The API evolved from the VOXWARE
 326 standard which later became OSS standard.
 327 .Sh SEE ALSO
 328 .Xr csa 4 ,
 329 .Xr gusc 4 ,
 330 .Xr sbc 4 ,
 331 .Xr devfs 5 ,
 332 .Xr loader.conf 5 ,
 333 .Xr dmesg 8 ,
 334 .Xr kldload 8 ,
 335 .Xr sysctl 8
 336 .Rs
 337 .%T "The OSS API"
 338 .%O "http://www.opensound.com/pguide/oss.pdf"
 339 .Re
 340 .Sh AUTHORS
 341 .An -nosplit
 342 .An Luigi Rizzo Aq luigi@iet.unipi.it
 343 initially wrote the
 344 .Nm
 345 device driver and this manual page.
 346 .An Cameron Grant Aq gandalf@vilnya.demon.co.uk
 347 later revised the device driver for
 348 .Fx 4.0 .
 349 .An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
 350 revised this manual page.
 351 It was then rewritten for
 352 .Fx 5.2 .