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.
92	This shows the status of xrun (= buffer overrun/xrun) debug of
93	ALSA PCM middle layer, as an integer from 0 to 2.  The value
94	can be changed by writing to this file, such as
95
96		 # cat 2 > /proc/asound/card0/pcm0p/xrun_debug
97
98	When this value is greater than 0, the driver will show the
99	messages to kernel log when an xrun is detected.  The debug
100	message is shown also when the invalid H/W pointer is detected
101	at the update of periods (usually called from the interrupt
102	handler).
103
104	When this value is greater than 1, the driver will show the
105	stack trace additionally.  This may help the debugging.
106
107card*/pcm*/sub*/info
108	The general information of this PCM sub-stream.
109
110card*/pcm*/sub*/status
111	The current status of this PCM sub-stream, elapsed time,
112	H/W position, etc.
113
114card*/pcm*/sub*/hw_params
115	The hardware parameters set for this sub-stream.
116
117card*/pcm*/sub*/sw_params
118	The soft parameters set for this sub-stream.
119
120card*/pcm*/sub*/prealloc
121	The buffer pre-allocation information.
122
123
124AC97 Codec Information
125----------------------
126
127card*/codec97#*/ac97#?-?
128	Shows the general information of this AC97 codec chip, such as
129	name, capabilities, set up.
130
131card*/codec97#0/ac97#?-?+regs
132	Shows the AC97 register dump.  Useful for debugging.
133
134	When CONFIG_SND_DEBUG is enabled, you can write to this file for
135	changing an AC97 register directly.  Pass two hex numbers.
136	For example,
137
138	# echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs
139
140
141USB Audio Streams
142-----------------
143
144card*/stream*
145	Shows the assignment and the current status of each audio stream
146	of the given card.  This information is very useful for debugging.
147
148
149HD-Audio Codecs
150---------------
151
152card*/codec#*
153	Shows the general codec information and the attribute of each
154	widget node.
155
156
157Sequencer Information
158---------------------
159
160seq/drivers
161	Lists the currently available ALSA sequencer drivers.
162
163seq/clients
164	Shows the list of currently available sequencer clients and
165	ports.  The connection status and the running status are shown
166	in this file, too.
167
168seq/queues
169	Lists the currently allocated/running sequencer queues.
170
171seq/timer
172	Lists the currently allocated/running sequencer timers.
173
174seq/oss
175	Lists the OSS-compatible sequencer stuffs.
176
177
178Help For Debugging?
179-------------------
180
181When the problem is related with PCM, first try to turn on xrun_debug
182mode.  This will give you the kernel messages when and where xrun
183happened.
184
185If it's really a bug, report it with the following information:
186
187  - the name of the driver/card, show in /proc/asound/cards
188  - the register dump, if available (e.g. card*/cmipci)
189
190when it's a PCM problem,
191
192  - set-up of PCM, shown in hw_parms, sw_params, and status in the PCM
193    sub-stream directory
194
195when it's a mixer problem,
196
197  - AC97 proc files, codec97#*/* files
198
199for USB audio/midi,
200
201  - output of lsusb -v
202  - stream* files in card directory
203
204
205The ALSA bug-tracking system is found at:
206
207    https://bugtrack.alsa-project.org/alsa-bug/
208