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 28, 2005
  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 For a card with bridge driver support, and a PnP card:
  40 .Cd "device sound"
  41 .Pp
  42 For a card without bridge driver support, and a non-PnP card,
  43 the following lines may be required in
  44 .Pa /boot/device.hints :
  45 .Cd hint.pcm.0.at="isa"
  46 .Cd hint.pcm.0.irq="5"
  47 .Cd hint.pcm.0.drq="1"
  48 .Cd hint.pcm.0.flags="0x0"
  49 .Sh DESCRIPTION
  50 .Bf -emphasis
  51 Note: There exists some ambiguity in the naming at the moment
  52 .Pq Nm sound , pcm , snd .
  53 It will be resolved soon by renaming
  54 .Cd "device sound"
  55 to
  56 .Cd "device snd" ,
  57 and doing associated changes.
  58 .Ef
  59 .Pp
  60 The
  61 .Nm
  62 driver provides support for
  63 .Tn PCM
  64 audio play and capture.
  65 This driver also supports various
  66 .Tn PCI ,
  67 .Tn WSS/MSS
  68 compatible,
  69 .Tn ISA
  70 sound cards, and AC97 mixer.
  71 Once the
  72 .Nm
  73 driver attaches, supported devices provide audio record and
  74 playback channels.
  75 The
  76 .Fx
  77 sound system provides dynamic mixing
  78 .Dq VCHAN
  79 and rate conversion
  80 .Dq soft formats .
  81 True full duplex operation is available on most cards.
  82 .Pp
  83 If the sound card is supported by a bridge driver, the
  84 .Nm
  85 driver works in conjunction with the bridge driver.
  86 .Pp
  87 Apart from the usual parameters, the flags field is used to specify
  88 the secondary
  89 .Tn DMA
  90 channel (generally used for capture in full duplex cards).
  91 Flags are set to 0 for cards not using a secondary
  92 .Tn DMA
  93 channel, or to 0x10 + C to specify channel C.
  94 .Pp
  95 The driver does its best to recognize the installed hardware and drive
  96 it correctly so the user is not required to add several lines in
  97 .Pa /boot/device.hints .
  98 For
  99 .Tn PCI
 100 and
 101 .Tn ISA
 102 .Tn PnP
 103 cards this is actually easy
 104 since they identify themselves.
 105 For legacy
 106 .Tn ISA
 107 cards, the driver looks for
 108 .Tn MSS
 109 cards at addresses 0x530 and 0x604 (unless overridden
 110 in
 111 .Pa /boot/device.hints ) .
 112 .Ss Boot Variables
 113 In general, the module
 114 .Pa snd_foo
 115 corresponds to
 116 .Cd "device snd_foo"
 117 and can be
 118 loaded by the boot
 119 .Xr loader 8
 120 via
 121 .Xr loader.conf 5
 122 or from the command line using the
 123 .Xr kldload 8
 124 utility.
 125 Options which can be specified in
 126 .Pa /boot/loader.conf
 127 include:
 128 .Bl -tag -width ".Va snd_emu10k1_load" -offset indent
 129 .It Va snd_driver_load
 130 .Pq Dq Li NO
 131 If set to
 132 .Dq Li YES ,
 133 this option loads all available drivers.
 134 .It Va snd_emu10k1_load
 135 .Pq Dq Li NO
 136 If set to
 137 .Dq Li YES ,
 138 only the SoundBlaster 5.1 driver and dependent modules will be loaded.
 139 .It Va snd_foo_load
 140 .Pq Dq Li NO
 141 If set to
 142 .Dq Li YES ,
 143 load driver for card/chipset foo.
 144 .El
 145 .Pp
 146 To define default values for the different mixer channels,
 147 set the channel to the preferred value using hints, e.g.:
 148 .Va hint.pcm.0.line Ns = Ns Qq Li 0 .
 149 This will mute the input channel per default.
 150 .Ss VCHANs
 151 Each device can optionally support more playback channels
 152 than physical hardware provides by using
 153 .Dq virtual channels
 154 or
 155 .Tn VCHANs .
 156 .Tn VCHAN
 157 options can be configured via the
 158 .Xr sysctl 8
 159 interface but can only be manipulated while the device is inactive.
 160 .Ss Runtime Configuration
 161 The following
 162 .Xr sysctl 8
 163 variables are available:
 164 .Bl -tag -width ".Va hw.snd.report_soft_formats" -offset indent
 165 .It Va hw.snd.pcm%d.buffersize
 166 Configure the amount of
 167 .Tn DMA
 168 bufferspace available for a device.
 169 .It Va hw.snd.targetirqrate
 170 Set the default block size such that continuous
 171 playback will achieve this
 172 .Tn IRQ
 173 rate.
 174 This value can be tuned to improve application performance.
 175 Increase this value when the sound lags and decrease
 176 it if sound stutters or breaks up.
 177 .It Va hw.snd.unit
 178 When using
 179 .Xr devfs 5 ,
 180 the default device for
 181 .Pa /dev/dsp .
 182 Equivalent to a symlink from
 183 .Pa /dev/dsp
 184 to
 185 .Pa /dev/dsp Ns Va ${hw.snd.unit} .
 186 .It Va hw.snd.report_soft_formats
 187 Controls the internal format conversion if it is
 188 available transparently to the application software.
 189 When disabled or not available, the application will
 190 only be able to select formats the device natively supports.
 191 .It Va hw.snd.verbose
 192 Level of verbosity for the
 193 .Pa /dev/sndstat
 194 device.
 195 Higher values include more output and the highest level,
 196 three, should be used when reporting problems.
 197 Other options include:
 198 .Bl -tag -width 2n
 199 .It 0
 200 Installed devices and their allocated bus resources.
 201 .It 1
 202 The number of playback, record, virtual channels, and
 203 flags per device.
 204 .It 2
 205 Channel information per device including the channel's
 206 current format, speed, and pseudo device statistics such as
 207 buffer overruns and buffer underruns.
 208 .It 3
 209 File names and versions of the currently sound loaded modules.
 210 .El
 211 .It Va hw.snd.maxautovchans
 212 Global
 213 .Tn VCHAN
 214 setting that only affects devices that have only one playback channel.
 215 The sound system will dynamically create up this many
 216 .Tn VCHANs .
 217 Set to
 218 .Dq 0
 219 if no
 220 .Tn VCHANS
 221 are desired.
 222 .It Va hw.snd.pcm%d.vchans
 223 The current number of
 224 .Tn VCHANs
 225 allocated per device.
 226 This can be set to preallocate a certain number of
 227 .Tn VCHANs .
 228 Setting this value to
 229 .Dq 0
 230 will disable
 231 .Tn VCHANs
 232 for this device.
 233 .El
 234 .Ss Recording Channels
 235 On devices that have more than one recording source (ie: mic and line),
 236 there is a corresponding
 237 .Pa /dev/dspr%d.%d
 238 device.
 239 .Ss Statistics
 240 Channel statistics are only kept while the device is open.
 241 So with situations involving overruns and underruns, consider the output
 242 while the errant application is open and running.
 243 .Ss IOCTL Support
 244 The driver supports most of the
 245 .Tn OSS
 246 .Fn ioctl
 247 functions, and most applications work unmodified.
 248 A few differences exist, while memory mapped playback is
 249 supported natively and in
 250 .Tn Linux
 251 emulation, memory mapped recording is
 252 not due to
 253 .Tn VM
 254 system design.
 255 As a consequence, some applications may need to be recompiled
 256 with a slightly modified audio module.
 257 See
 258 .In sys/soundcard.h
 259 for a complete list of the supported
 260 .Fn ioctl
 261 functions.
 262 .Sh FILES
 263 The
 264 .Nm
 265 drivers may create the following
 266 device nodes:
 267 .Pp
 268 .Bl -tag -width ".Pa /dev/audio%d.%d" -compact
 269 .It Pa /dev/audio%d.%d
 270 Sparc-compatible audio device.
 271 .It Pa /dev/dsp%d.%d
 272 Digitized voice device.
 273 .It Pa /dev/dspW%d.%d
 274 Like
 275 .Pa /dev/dsp ,
 276 but 16 bits per sample.
 277 .It Pa /dev/dspr%d.%d
 278 Should be connected to a record codec.
 279 .It Pa /dev/sndstat
 280 Current
 281 .Nm
 282 status, including all channels and drivers.
 283 .El
 284 .Pp
 285 The first number in the device node
 286 represents the unit number of the
 287 .Nm
 288 device.
 289 All
 290 .Nm
 291 devices are listed
 292 in
 293 .Pa /dev/sndstat .
 294 Additional messages are sometimes recorded when the
 295 device is probed and attached, these messages can be viewed with the
 296 .Xr dmesg 8
 297 utility.
 298 .Sh DIAGNOSTICS
 299 .Bl -diag
 300 .It ac97: dac not ready
 301 AC97 codec is not likely to be accompanied with the sound card.
 302 .It unsupported subdevice XX
 303 A device node is not created properly.
 304 .El
 305 .Sh SEE ALSO
 306 .Xr snd_ad1816 4 ,
 307 .Xr snd_als4000 4 ,
 308 .Xr snd_atiixp 4 ,
 309 .Xr snd_audiocs 4 ,
 310 .Xr snd_cmi 4 ,
 311 .Xr snd_cs4281 4 ,
 312 .Xr snd_csa 4 ,
 313 .Xr snd_ds1 4 ,
 314 .Xr snd_emu10k1 4 ,
 315 .Xr snd_es137x 4 ,
 316 .Xr snd_ess 4 ,
 317 .Xr snd_fm801 4 ,
 318 .Xr snd_gusc 4 ,
 319 .Xr snd_ich 4 ,
 320 .Xr snd_maestro 4 ,
 321 .Xr snd_maestro3 4 ,
 322 .Xr snd_mss 4 ,
 323 .Xr snd_neomagic 4 ,
 324 .Xr snd_sbc 4 ,
 325 .Xr snd_solo 4 ,
 326 .Xr snd_t4dwave 4 ,
 327 .Xr snd_uaudio 4 ,
 328 .Xr snd_via8233 4 ,
 329 .Xr snd_via82c686 4 ,
 330 .Xr snd_vibes 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 HISTORY
 341 The
 342 .Nm
 343 device driver first appeared in
 344 .Fx 2.2.6
 345 as
 346 .Nm pcm ,
 347 written by
 348 .An Luigi Rizzo .
 349 It was later
 350 rewritten in
 351 .Fx 4.0
 352 by
 353 .An Cameron Grant .
 354 The API evolved from the VOXWARE
 355 standard which later became OSS standard.
 356 .Sh AUTHORS
 357 .An -nosplit
 358 .An Luigi Rizzo Aq luigi@iet.unipi.it
 359 initially wrote the
 360 .Nm pcm
 361 device driver and this manual page.
 362 .An Cameron Grant Aq gandalf@vilnya.demon.co.uk
 363 later revised the device driver for
 364 .Fx 4.0 .
 365 .An Seigo Tanimura Aq tanimura@r.dl.itc.u-tokyo.ac.jp
 366 revised this manual page.
 367 It was then rewritten for
 368 .Fx 5.2 .
 369 .Sh BUGS
 370 Some features of your cards (e.g., global volume control) might not
 371 be supported on all devices.