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