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