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