1==========================
2Proc Files of ALSA Drivers
3==========================
4
5Takashi Iwai <tiwai@suse.de>
6
7General
8=======
9
10ALSA has its own proc tree, /proc/asound.  Many useful information are
11found in this tree.  When you encounter a problem and need debugging,
12check the files listed in the following sections.
13
14Each card has its subtree cardX, where X is from 0 to 7. The
15card-specific files are stored in the ``card*`` subdirectories.
16
17
18Global Information
19==================
20
21cards
22	Shows the list of currently configured ALSA drivers,
23	index, the id string, short and long descriptions.
24
25version
26	Shows the version string and compile date.
27
28modules
29	Lists the module of each card
30
31devices
32	Lists the ALSA native device mappings.
33
34meminfo
35	Shows the status of allocated pages via ALSA drivers.
36	Appears only when ``CONFIG_SND_DEBUG=y``.
37
38hwdep
39	Lists the currently available hwdep devices in format of
40	``<card>-<device>: <name>``
41
42pcm
43	Lists the currently available PCM devices in format of
44	``<card>-<device>: <id>: <name> : <sub-streams>``
45
46timer
47	Lists the currently available timer devices
48
49
50oss/devices
51	Lists the OSS device mappings.
52
53oss/sndstat
54	Provides the output compatible with /dev/sndstat.
55	You can symlink this to /dev/sndstat.
56
57
58Card Specific Files
59===================
60
61The card-specific files are found in ``/proc/asound/card*`` directories.
62Some drivers (e.g. cmipci) have their own proc entries for the
63register dump, etc (e.g. ``/proc/asound/card*/cmipci`` shows the register
64dump).  These files would be really helpful for debugging.
65
66When PCM devices are available on this card, you can see directories
67like pcm0p or pcm1c.  They hold the PCM information for each PCM
68stream.  The number after ``pcm`` is the PCM device number from 0, and
69the last ``p`` or ``c`` means playback or capture direction.  The files in
70this subtree is described later.
71
72The status of MIDI I/O is found in ``midi*`` files.  It shows the device
73name and the received/transmitted bytes through the MIDI device.
74
75When the card is equipped with AC97 codecs, there are ``codec97#*``
76subdirectories (described later).
77
78When the OSS mixer emulation is enabled (and the module is loaded),
79oss_mixer file appears here, too.  This shows the current mapping of
80OSS mixer elements to the ALSA control elements.  You can change the
81mapping by writing to this device.  Read OSS-Emulation.txt for
82details.
83
84
85PCM 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_SND_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
144AC97 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
163USB 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
171HD-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
189Sequencer Information
190=====================
191
192seq/drivers
193	Lists the currently available ALSA sequencer drivers.
194
195seq/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
200seq/queues
201	Lists the currently allocated/running sequencer queues.
202
203seq/timer
204	Lists the currently allocated/running sequencer timers.
205
206seq/oss
207	Lists the OSS-compatible sequencer stuffs.
208
209
210Help For Debugging?
211===================
212
213When the problem is related with PCM, first try to turn on xrun_debug
214mode.  This will give you the kernel messages when and where xrun
215happened.
216
217If 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
222when 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
227when it's a mixer problem,
228
229- AC97 proc files, ``codec97#*/*`` files
230
231for USB audio/midi,
232
233- output of ``lsusb -v``
234- ``stream*`` files in card directory
235
236
237The ALSA bug-tracking system is found at:
238https://bugtrack.alsa-project.org/alsa-bug/
239