Documentation/sound/designs/procfile.rst

   1 ==========================
   2 Proc Files of ALSA Drivers
   3 ==========================
   4
   5 Takashi Iwai <tiwai@suse.de>
   6
   7 General
   8 =======
   9
  10 ALSA has its own proc tree, /proc/asound.  Many useful information are
  11 found in this tree.  When you encounter a problem and need debugging,
  12 check the files listed in the following sections.
  13
  14 Each card has its subtree cardX, where X is from 0 to 7. The
  15 card-specific files are stored in the ``card*`` subdirectories.
  16
  17
  18 Global Information
  19 ==================
  20
  21 cards
  22         Shows the list of currently configured ALSA drivers,
  23         index, the id string, short and long descriptions.
  24
  25 version
  26         Shows the version string and compile date.
  27
  28 modules
  29         Lists the module of each card
  30
  31 devices
  32         Lists the ALSA native device mappings.
  33
  34 meminfo
  35         Shows the status of allocated pages via ALSA drivers.
  36         Appears only when ``CONFIG_SND_DEBUG=y``.
  37
  38 hwdep
  39         Lists the currently available hwdep devices in format of
  40         ``<card>-<device>: <name>``
  41
  42 pcm
  43         Lists the currently available PCM devices in format of
  44         ``<card>-<device>: <id>: <name> : <sub-streams>``
  45
  46 timer
  47         Lists the currently available timer devices
  48
  49
  50 oss/devices
  51         Lists the OSS device mappings.
  52
  53 oss/sndstat
  54         Provides the output compatible with /dev/sndstat.
  55         You can symlink this to /dev/sndstat.
  56
  57
  58 Card Specific Files
  59 ===================
  60
  61 The card-specific files are found in ``/proc/asound/card*`` directories.
  62 Some drivers (e.g. cmipci) have their own proc entries for the
  63 register dump, etc (e.g. ``/proc/asound/card*/cmipci`` shows the register
  64 dump).  These files would be really helpful for debugging.
  65
  66 When PCM devices are available on this card, you can see directories
  67 like pcm0p or pcm1c.  They hold the PCM information for each PCM
  68 stream.  The number after ``pcm`` is the PCM device number from 0, and
  69 the last ``p`` or ``c`` means playback or capture direction.  The files in
  70 this subtree is described later.
  71
  72 The status of MIDI I/O is found in ``midi*`` files.  It shows the device
  73 name and the received/transmitted bytes through the MIDI device.
  74
  75 When the card is equipped with AC97 codecs, there are ``codec97#*``
  76 subdirectories (described later).
  77
  78 When the OSS mixer emulation is enabled (and the module is loaded),
  79 oss_mixer file appears here, too.  This shows the current mapping of
  80 OSS mixer elements to the ALSA control elements.  You can change the
  81 mapping by writing to this device.  Read OSS-Emulation.txt for
  82 details.
  83
  84
  85 PCM Proc Files
  86 ==============
  87
  88 ``card*/pcm*/info``
  89         The general information of this PCM device: card #, device #,
  90         substreams, etc.
  91
  92 ``card*/pcm*/xrun_debug``
  93         This file appears when ``CONFIG_SND_DEBUG=y`` and
  94         ``CONFIG_PCM_XRUN_DEBUG=y``.
  95         This shows the status of xrun (= buffer overrun/xrun) and
  96         invalid PCM position debug/check of ALSA PCM middle layer.
  97         It takes an integer value, can be changed by writing to this
  98         file, such as::
  99
 100                  # echo 5 > /proc/asound/card0/pcm0p/xrun_debug
 101
 102         The value consists of the following bit flags:
 103
 104         * bit 0 = Enable XRUN/jiffies debug messages
 105         * bit 1 = Show stack trace at XRUN / jiffies check
 106         * bit 2 = Enable additional jiffies check
 107
 108         When the bit 0 is set, the driver will show the messages to
 109         kernel log when an xrun is detected.  The debug message is
 110         shown also when the invalid H/W pointer is detected at the
 111         update of periods (usually called from the interrupt
 112         handler).
 113
 114         When the bit 1 is set, the driver will show the stack trace
 115         additionally.  This may help the debugging.
 116
 117         Since 2.6.30, this option can enable the hwptr check using
 118         jiffies.  This detects spontaneous invalid pointer callback
 119         values, but can be lead to too much corrections for a (mostly
 120         buggy) hardware that doesn't give smooth pointer updates.
 121         This feature is enabled via the bit 2.
 122
 123 ``card*/pcm*/sub*/info``
 124         The general information of this PCM sub-stream.
 125
 126 ``card*/pcm*/sub*/status``
 127         The current status of this PCM sub-stream, elapsed time,
 128         H/W position, etc.
 129
 130 ``card*/pcm*/sub*/hw_params``
 131         The hardware parameters set for this sub-stream.
 132
 133 ``card*/pcm*/sub*/sw_params``
 134         The soft parameters set for this sub-stream.
 135
 136 ``card*/pcm*/sub*/prealloc``
 137         The buffer pre-allocation information.
 138
 139 ``card*/pcm*/sub*/xrun_injection``
 140         Triggers an XRUN to the running stream when any value is
 141         written to this proc file.  Used for fault injection.
 142         This entry is write-only.
 143
 144 AC97 Codec Information
 145 ======================
 146
 147 ``card*/codec97#*/ac97#?-?``
 148         Shows the general information of this AC97 codec chip, such as
 149         name, capabilities, set up.
 150
 151 ``card*/codec97#0/ac97#?-?+regs``
 152         Shows the AC97 register dump.  Useful for debugging.
 153
 154         When CONFIG_SND_DEBUG is enabled, you can write to this file for
 155         changing an AC97 register directly.  Pass two hex numbers.
 156         For example,
 157
 158 ::
 159
 160         # echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs
 161
 162
 163 USB Audio Streams
 164 =================
 165
 166 ``card*/stream*``
 167         Shows the assignment and the current status of each audio stream
 168         of the given card.  This information is very useful for debugging.
 169
 170
 171 HD-Audio Codecs
 172 ===============
 173
 174 ``card*/codec#*``
 175         Shows the general codec information and the attribute of each
 176         widget node.
 177
 178 ``card*/eld#*``
 179         Available for HDMI or DisplayPort interfaces.
 180         Shows ELD(EDID Like Data) info retrieved from the attached HDMI sink,
 181         and describes its audio capabilities and configurations.
 182
 183         Some ELD fields may be modified by doing ``echo name hex_value > eld#*``.
 184         Only do this if you are sure the HDMI sink provided value is wrong.
 185         And if that makes your HDMI audio work, please report to us so that we
 186         can fix it in future kernel releases.
 187
 188
 189 Sequencer Information
 190 =====================
 191
 192 seq/drivers
 193         Lists the currently available ALSA sequencer drivers.
 194
 195 seq/clients
 196         Shows the list of currently available sequencer clients and
 197         ports.  The connection status and the running status are shown
 198         in this file, too.
 199
 200 seq/queues
 201         Lists the currently allocated/running sequencer queues.
 202
 203 seq/timer
 204         Lists the currently allocated/running sequencer timers.
 205
 206 seq/oss
 207         Lists the OSS-compatible sequencer stuffs.
 208
 209
 210 Help For Debugging?
 211 ===================
 212
 213 When the problem is related with PCM, first try to turn on xrun_debug
 214 mode.  This will give you the kernel messages when and where xrun
 215 happened.
 216
 217 If it's really a bug, report it with the following information:
 218
 219 - the name of the driver/card, show in ``/proc/asound/cards``
 220 - the register dump, if available (e.g. ``card*/cmipci``)
 221
 222 when it's a PCM problem,
 223
 224 - set-up of PCM, shown in hw_parms, sw_params, and status in the PCM
 225   sub-stream directory
 226
 227 when it's a mixer problem,
 228
 229 - AC97 proc files, ``codec97#*/*`` files
 230
 231 for USB audio/midi,
 232
 233 - output of ``lsusb -v``
 234 - ``stream*`` files in card directory
 235
 236
 237 The ALSA bug-tracking system is found at:
 238 https://bugtrack.alsa-project.org/alsa-bug/