1 files changed, 191 insertions, 0 deletions

diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt
new file mode 100644
index 000000000000..25c5d648aef6
--- /dev/null
+++ b/Documentation/sound/alsa/Procfile.txt
@@ -0,0 +1,191 @@
+                Proc Files of ALSA Drivers
+                ==========================
+                Takashi Iwai <tiwai@suse.de>
+
+General
+-------
+
+ALSA has its own proc tree, /proc/asound.  Many useful information are
+found in this tree.  When you encounter a problem and need debugging,
+check the files listed in the following sections.
+
+Each card has its subtree cardX, where X is from 0 to 7. The
+card-specific files are stored in the card* subdirectories.
+
+
+Global Information
+------------------
+
+cards
+        Shows the list of currently configured ALSA drivers,
+        index, the id string, short and long descriptions.
+
+version
+        Shows the version string and compile date.
+
+modules
+        Lists the module of each card
+
+devices
+        Lists the ALSA native device mappings.
+
+meminfo
+        Shows the status of allocated pages via ALSA drivers.
+        Appears only when CONFIG_SND_DEBUG=y.
+
+hwdep
+        Lists the currently available hwdep devices in format of
+        <card>-<device>: <name>
+
+pcm
+        Lists the currently available PCM devices in format of
+        <card>-<device>: <id>: <name> : <sub-streams>
+
+timer
+        Lists the currently available timer devices
+
+
+oss/devices
+        Lists the OSS device mappings.
+
+oss/sndstat
+        Provides the output compatible with /dev/sndstat.
+        You can symlink this to /dev/sndstat.
+
+
+Card Specific Files
+-------------------
+
+The card-specific files are found in /proc/asound/card* directories.
+Some drivers (e.g. cmipci) have their own proc entries for the
+register dump, etc (e.g. /proc/asound/card*/cmipci shows the register
+dump).  These files would be really helpful for debugging.
+
+When PCM devices are available on this card, you can see directories
+like pcm0p or pcm1c.  They hold the PCM information for each PCM
+stream.  The number after 'pcm' is the PCM device number from 0, and
+the last 'p' or 'c' means playback or capture direction.  The files in
+this subtree is described later.
+
+The status of MIDI I/O is found in midi* files.  It shows the device
+name and the received/transmitted bytes through the MIDI device.
+
+When the card is equipped with AC97 codecs, there are codec97#*
+subdirectories (desribed later).
+
+When the OSS mixer emulation is enabled (and the module is loaded),
+oss_mixer file appears here, too.  This shows the current mapping of
+OSS mixer elements to the ALSA control elements.  You can change the
+mapping by writing to this device.  Read OSS-Emulation.txt for
+details.
+
+
+PCM Proc Files
+--------------
+
+card*/pcm*/info
+        The general information of this PCM device: card #, device #,
+        substreams, etc.
+
+card*/pcm*/xrun_debug
+        This file appears when CONFIG_SND_DEBUG=y.
+        This shows the status of xrun (= buffer overrun/xrun) debug of
+        ALSA PCM middle layer, as an integer from 0 to 2.  The value
+        can be changed by writing to this file, such as
+
+                 # cat 2 > /proc/asound/card0/pcm0p/xrun_debug
+
+        When this value is greater than 0, the driver will show the
+        messages to kernel log when an xrun is detected.  The debug
+        message is shown also when the invalid H/W pointer is detected
+        at the update of periods (usually called from the interrupt
+        handler).
+
+        When this value is greater than 1, the driver will show the
+        stack trace additionally.  This may help the debugging.
+
+card*/pcm*/sub*/info
+        The general information of this PCM sub-stream.
+
+card*/pcm*/sub*/status
+        The current status of this PCM sub-stream, elapsed time,
+        H/W position, etc.
+
+card*/pcm*/sub*/hw_params
+        The hardware parameters set for this sub-stream.
+
+card*/pcm*/sub*/sw_params
+        The soft parameters set for this sub-stream.
+
+card*/pcm*/sub*/prealloc
+        The buffer pre-allocation information.
+
+
+AC97 Codec Information
+----------------------
+
+card*/codec97#*/ac97#?-?
+        Shows the general information of this AC97 codec chip, such as
+        name, capabilities, set up.
+
+card*/codec97#0/ac97#?-?+regs
+        Shows the AC97 register dump.  Useful for debugging.
+
+        When CONFIG_SND_DEBUG is enabled, you can write to this file for
+        changing an AC97 register directly.  Pass two hex numbers.
+        For example,
+
+        # echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs
+
+
+Sequencer Information
+---------------------
+
+seq/drivers
+        Lists the currently available ALSA sequencer drivers.
+
+seq/clients
+        Shows the list of currently available sequencer clinets and
+        ports.  The connection status and the running status are shown
+        in this file, too.
+
+seq/queues
+        Lists the currently allocated/running sequener queues.
+
+seq/timer
+        Lists the currently allocated/running sequencer timers.
+
+seq/oss
+        Lists the OSS-compatible sequencer stuffs.
+
+
+Help For Debugging?
+-------------------
+
+When the problem is related with PCM, first try to turn on xrun_debug
+mode.  This will give you the kernel messages when and where xrun
+happened.
+
+If it's really a bug, report it with the following information
+
+  - the name of the driver/card, show in /proc/asound/cards
+  - the reigster dump, if available (e.g. card*/cmipci)
+
+when it's a PCM problem,
+
+  - set-up of PCM, shown in hw_parms, sw_params, and status in the PCM
+    sub-stream directory
+
+when it's a mixer problem,
+
+  - AC97 proc files, codec97#*/* files
+
+for USB audio/midi,
+
+  - output of lsusb -v
+  - stream* files in card directory
+
+
+The ALSA bug-tracking system is found at:
+
+    https://bugtrack.alsa-project.org/alsa-bug/