/[gentoo]/xml/htdocs/doc/en/alsa-guide.xml
Gentoo

Diff of /xml/htdocs/doc/en/alsa-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.80 Revision 1.81
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/alsa-guide.xml,v 1.80 2007/05/19 03:00:29 nightmorph Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/alsa-guide.xml,v 1.81 2008/03/05 09:16:49 nightmorph Exp $ -->
3 3
4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 5
6<guide link="/doc/en/alsa-guide.xml"> 6<guide link="/doc/en/alsa-guide.xml">
7<title>Gentoo Linux ALSA Guide</title> 7<title>Gentoo Linux ALSA Guide</title>
22 22
23<!-- The content of this document is licensed under the CC-BY-SA license --> 23<!-- The content of this document is licensed under the CC-BY-SA license -->
24<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 24<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
25<license/> 25<license/>
26 26
27<version>2.22</version> 27<version>2.23</version>
28<date>2007-05-07</date> 28<date>2008-03-05</date>
29 29
30<chapter> 30<chapter>
31<title>Introduction</title> 31<title>Introduction</title>
32<section> 32<section>
33<title>What is ALSA?</title> 33<title>What is ALSA?</title>
54<section> 54<section>
55<title>ALSA on Gentoo</title> 55<title>ALSA on Gentoo</title>
56<body> 56<body>
57 57
58<p> 58<p>
59One of Gentoo's main strengths lies in giving the user maximum control over 59Historically, Gentoo offered two ways to get ALSA up and running: the
60how a system is installed/configured. ALSA on Gentoo follows the same 60<e>in-kernel</e> driver and the external <c>alsa-driver</c> package. The two
61principle. There are two ways you can get ALSA support up and running on your 61solutions essentially do the same thing; this made supporting the external
62system. We shall look at them in detail in the next chapter. 62package extremely difficult and time-consuming. The Gentoo maintainers decided
63to discontinue support for the <c>alsa-driver</c> package, concentrating their
64resources on the ALSA drivers available within the Linux kernel. This guide will
65focus solely on configuring ALSA via the in-kernel driver.
66</p>
67
68<p>
69If you still require the <c>alsa-driver</c> package, please email the <mail
70link="alsa-bugs@gentoo.org">Gentoo ALSA maintainers</mail> with why the
71in-kernel drivers don't work for you. Be sure to include detailed error logs.
63</p> 72</p>
64 73
65</body> 74</body>
66</section> 75</section>
67</chapter> 76</chapter>
68 77
69<chapter> 78<chapter>
70<title>Installing ALSA</title> 79<title>Installing ALSA</title>
71<section>
72<title>Options</title>
73<body>
74
75<warn>
76The methods shown below are mutually exclusive. You cannot have ALSA compiled
77in your kernel and use <c>media-sound/alsa-driver</c>. It <e>will</e> fail.
78</warn>
79
80<p>
81The two options are:
82</p>
83
84<ol>
85 <li>
86 Use ALSA provided by your kernel. This is the preferred/recommended method.
87 </li>
88 <li>Use Gentoo's <c>media-sound/alsa-driver</c> package.</li>
89</ol>
90
91<p>
92The in-kernel drivers and the <c>alsa-driver</c> package can vary a little; it's
93possible that features and fixes found in one might not yet be incorporated into
94the other. The upstream developers are aware of this, but the two drivers are
95effectively separate branches of the ALSA project; they are not entirely
96identical. You should be aware that they might function slightly differently, so
97if one doesn't work for you, try the other! We shall take a peek into both
98before finally deciding on one.
99</p>
100
101<p>
102If you were to use ALSA provided by the kernel, the following are the pros and
103cons:
104</p>
105
106<table>
107<tr>
108 <th>Kernel ALSA</th>
109 <th>Pros and Cons</th>
110</tr>
111<tr>
112 <th>+</th>
113 <ti>
114 No need to emerge yet another package; drivers are integrated into kernel.
115 </ti>
116</tr>
117<tr>
118 <th>+</th>
119 <ti>One shot solution, no repeating emerges.</ti>
120</tr>
121<tr>
122 <th>-</th>
123 <ti>Might be a slightly different version than <c>alsa-driver</c>.</ti>
124</tr>
125</table>
126
127<p>
128And, if you were to use <c>alsa-driver</c>,
129</p>
130
131<table>
132<tr>
133 <th>alsa-driver</th>
134 <th>Pros and Cons</th>
135</tr>
136<tr>
137 <th>+</th>
138 <ti>Possibly the latest drivers from the ALSA Project.</ti>
139</tr>
140<tr>
141 <th>+</th>
142 <ti>Useful if you intend to develop audio drivers.</ti>
143</tr>
144<tr>
145 <th>-</th>
146 <ti>Every kernel recompile requires a re-emerge of <c>alsa-driver</c>.</ti>
147</tr>
148<tr>
149 <th>-</th>
150 <ti>Needs certain kernel config options disabled to work correctly.</ti>
151</tr>
152</table>
153
154</body>
155</section>
156<section>
157<title>So...</title>
158<body>
159
160<p>
161The differences between <c>alsa-driver</c> and the in-kernel ALSA drivers are
162quite subtle, as mentioned earlier. Since there are not any huge differences,
163you are encouraged to go through the process of using the ALSA provided by the
164kernel <e>first</e> for ease of use. Before reporting any sound related issues
165to <uri link="https://bugs.gentoo.org">Gentoo Bugzilla</uri>, please try to
166reproduce them using <c>alsa-driver</c> and file the bug report no matter what
167the result.
168</p>
169
170</body>
171</section>
172<section id="lspci"> 80<section id="lspci">
173<title>Before you proceed</title> 81<title>Before you proceed</title>
174<body> 82<body>
175 83
176<p> 84<p>
177Whichever method of install you choose, you need to know what drivers your 85First, you need to know what drivers your sound card uses. In most cases, sound
178sound card uses. In most cases, sound cards (onboard and otherwise) are PCI 86cards (onboard and otherwise) are PCI based and <c>lspci</c> will help you in
179based and <c>lspci</c> will help you in digging out the required information. 87digging out the required information. Please <c>emerge sys-apps/pciutils</c> to
180Please <c>emerge sys-apps/pciutils</c> to get <c>lspci</c>, if you don't have it 88get <c>lspci</c>, if you don't have it installed already. In case you have a USB
181installed already. In case you have a USB sound card, <c>lsusb</c> from 89sound card, <c>lsusb</c> from <c>sys-apps/usbutils</c> <e>might</e> be of help.
182<c>sys-apps/usbutils</c> <e>might</e> be of help. For ISA cards, try using 90For ISA cards, try using <c>sys-apps/isapnptools</c>. Also, the following pages
183<c>sys-apps/isapnptools</c>. Also, the following pages <e>may</e> help users 91<e>may</e> help users with ISA based sound cards:
184with ISA based sound cards:
185</p> 92</p>
186 93
187<ul> 94<ul>
188 <li> 95 <li>
189 <uri link="http://www.roestock.demon.co.uk/isapnptools/">The ISAPNPTOOLS 96 <uri link="http://www.roestock.demon.co.uk/isapnptools/">The ISAPNPTOOLS
231</p> 138</p>
232 139
233</body> 140</body>
234</section> 141</section>
235<section id="kernel"> 142<section id="kernel">
236<title>Using ALSA provided by your Kernel</title> 143<title>Configuring the kernel</title>
237<body> 144<body>
238
239<p>
240If you're a person who likes to keep things simple, then this is the way to go.
241</p>
242 145
243<note> 146<note>
244Since the 2005.0 release, Gentoo Linux uses 2.6 as the default kernel. Please 147Since the 2005.0 release, Gentoo Linux uses 2.6 as the default kernel. Please
245check that your kernel is a 2.6 series kernel. This method will <e>not</e> work 148check that your kernel is a 2.6 series kernel. This method will <e>not</e> work
246on a 2.4 kernel. 149on a 2.4 kernel.
335see if everything is working as it should. 238see if everything is working as it should.
336</p> 239</p>
337 240
338</body> 241</body>
339</section> 242</section>
340<section id="alsa-driver">
341<title>Using the ALSA Driver package</title>
342<body>
343
344<p>
345So you've decided to go the <c>alsa-driver</c> way. Let's get started then.
346There are a few minor things to be done to ensure only the drivers for your
347sound card are compiled. Although this is not really necessary, it cuts down
348on the unnecessary drivers that will be compiled otherwise.
349</p>
350
351<p>
352If you don't have an idea of what drivers your sound card might need, please
353take a look at the <uri link="#lspci">lspci</uri> section of this guide. Once
354you have your driver name (<c>emu10k1</c> in our example), edit
355<path>/etc/make.conf</path> and add a variable, <c>ALSA_CARDS</c>.
356</p>
357
358<pre caption="Adding ALSA_CARDS to make.conf">
359<comment>(For one sound card)</comment>
360ALSA_CARDS="emu10k1"
361<comment>(For more than one, separate names with spaces)</comment>
362ALSA_CARDS="emu10k1 via82xx"
363</pre>
364
365<p>
366If you have compiled your kernel and want to use <c>alsa-driver</c>, please
367ensure the following before proceeding, else <c>alsa-driver</c> is likely to
368fail. The next code listing gives you one way of performing the checks.
369</p>
370
371<note>
372<c>genkernel</c> users can proceed with <uri link="#doc_chap2_pre6">Installing
373alsa-driver</uri> as their configuration is in sync with the one shown below by
374default.
375</note>
376
377<ol>
378 <li>
379 <c>CONFIG_SOUND</c> is set. (Basic Sound support enabled)
380 </li>
381 <li>
382 <c>CONFIG_SOUND_PRIME</c> is not set. (In-built OSS support disabled)
383 </li>
384 <li>
385 <c>CONFIG_SND</c> is not set. (In-built ALSA support disabled)
386 </li>
387 <li>
388 <path>/usr/src/linux</path> points to the kernel you want ALSA working on.
389 </li>
390</ol>
391
392<pre caption=".config checks">
393<comment>(Assuming the linux symlink points to the correct kernel)</comment>
394# <i>cd /usr/src/linux</i>
395# <i>grep SOUND .config</i>
396<comment>(1. is true)</comment>
397CONFIG_SOUND=y
398<comment>(2. is true)</comment>
399CONFIG_SOUND_PRIME is not set
400# <i>grep SND .config</i>
401<comment>(and 3. is true)</comment>
402CONFIG_SND is not set
403</pre>
404
405<p>
406Now all you have to do is type the magic words... and no, it's not abracadabra.
407</p>
408
409<pre caption="Installing alsa-driver">
410# <i>emerge alsa-driver</i>
411</pre>
412
413<impo>
414Please note that you will have to run <c>emerge alsa-driver</c> after every
415kernel (re)compile, as the earlier drivers are deleted. To make this task
416easier, you may want to emerge the <c>module-rebuild</c> package, which will
417keep track of module packages and rebuild them for you. First run
418<c>module-rebuild populate</c> to create the list, and then after every kernel
419(re)compile, you just run <c>module-rebuild rebuild</c>, and your external
420modules will be rebuilt.
421</impo>
422
423</body>
424</section>
425</chapter> 243</chapter>
426 244
427<chapter> 245<chapter>
428<title>Configuring/Testing ALSA</title> 246<title>Configuring/Testing ALSA</title>
429<section id="alsa-utilities"> 247<section id="alsa-utilities">
439<pre caption="Install alsa-utils"> 257<pre caption="Install alsa-utils">
440# <i>emerge alsa-utils</i> 258# <i>emerge alsa-utils</i>
441</pre> 259</pre>
442 260
443<note> 261<note>
444If you activated ALSA in your <uri link="#kernel">kernel</uri> <e>and</e> did
445not compile ALSA as modules, please proceed to the 262If you did <e>not</e> compile ALSA as modules, please proceed to the <uri
446<uri link="#initscript">ALSA Initscript</uri> section. The rest of you need 263link="#initscript">ALSA Initscript</uri> section. The rest of you need to
447to configure ALSA. This is made very easy by the existence of the 264configure ALSA. This is made very easy by the existence of the <c>alsaconf</c>
448<c>alsaconf</c> tool provided by <c>alsa-utils</c>. 265tool provided by <c>alsa-utils</c>.
449</note> 266</note>
450 267
451</body> 268</body>
452</section> 269</section>
453<section id="alsa-config"> 270<section id="alsa-config">
7327: system timer 5497: system timer
733 550
734Mixers: 551Mixers:
7350: SigmaTel STAC9721/23 5520: SigmaTel STAC9721/23
736</pre> 553</pre>
554
555<!-- TODO: remove this a few months after alsa-driver leaves the tree -->
737 556
738<p> 557<p>
739The other most common issue users face is the dreaded "Unknown symbol in module" 558The other most common issue users face is the dreaded "Unknown symbol in module"
740error. An example of the same is shown below. 559error. An example of the same is shown below.
741</p> 560</p>
785snd_mixer_oss: Unknown symbol snd_mixer_oss_notify_callback 604snd_mixer_oss: Unknown symbol snd_mixer_oss_notify_callback
786snd_mixer_oss: Unknown symbol snd_oss_info_register 605snd_mixer_oss: Unknown symbol snd_oss_info_register
787</pre> 606</pre>
788 607
789<p> 608<p>
790The above issue is caused when you switch from <c>alsa-driver</c> to in-kernel 609The above issue is caused when you switch from the <c>alsa-driver</c> to in-kernel
791ALSA because when you unmerge <c>alsa-driver</c> the module files are config 610ALSA because when you unmerge <c>alsa-driver</c> the module files are config
792protected and hence get left behind. So, when you switch to in-kernel 611protected and hence get left behind. So, when you switch to in-kernel
793drivers, running <c>modprobe</c> gives you a mix of <c>alsa-driver</c> and 612drivers, running <c>modprobe</c> gives you a mix of <c>alsa-driver</c> and
794in-kernel modules thus causing the above errors. 613in-kernel modules thus causing the above errors.
795</p> 614</p>
819# <i>grep device_mode /etc/modules.d/*</i> 638# <i>grep device_mode /etc/modules.d/*</i>
820</pre> 639</pre>
821 640
822<p> 641<p>
823Usually it is a file called <path>alsa</path> with the line <c>options snd 642Usually it is a file called <path>alsa</path> with the line <c>options snd
824device_mode=0666</c>. Remove this line and restart the alsasound service and 643device_mode=0666</c>. Remove this line and restart the <c>alsasound</c> service
825that should take care of this issue. 644and that should take care of this issue.
826</p> 645</p>
646
647<!-- End of removal notice -->
827 648
828</body> 649</body>
829</section> 650</section>
830</chapter> 651</chapter>
831 652
837 658
838<p> 659<p>
839First, check to make sure that you enabled the <c>midi</c> USE flag in 660First, check to make sure that you enabled the <c>midi</c> USE flag in
840<path>/etc/make.conf</path>. If you didn't, go ahead and add it now. You will 661<path>/etc/make.conf</path>. If you didn't, go ahead and add it now. You will
841also need to re-emerge any ALSA packages that use the <c>midi</c> flag, such as 662also need to re-emerge any ALSA packages that use the <c>midi</c> flag, such as
842<c>alsa-lib</c>, <c>alsa-utils</c>, and <c>alsa-driver</c>. 663<c>alsa-lib</c> and <c>alsa-utils</c>.
843</p> 664</p>
844 665
845<p> 666<p>
846If your sound card is one of those that come with on-board MIDI synthesizers 667If your sound card is one of those that come with on-board MIDI synthesizers
847and you would like to listen to some .mid files, you have to install 668and you would like to listen to some .mid files, you have to install
967<title>Multiple sound cards</title> 788<title>Multiple sound cards</title>
968<body> 789<body>
969 790
970<p> 791<p>
971You can have more than one sound card in your system simultaneously, provided 792You can have more than one sound card in your system simultaneously, provided
972that you have built ALSA as modules in your kernel (or have installed 793that you have built ALSA as modules in your kernel. You just need to specify
973<c>alsa-driver</c> instead). You just need to specify which should be started 794which should be started first in <path>/etc/modules.d/alsa</path>. Your cards
974first in <path>/etc/modules.d/alsa</path>. Your cards are identified by their 795are identified by their driver names inside this file. 0 is the first card, 1 is
975driver names inside this file. 0 is the first card, 1 is the second, and so on.
976Here's an example for a system with two sound cards. 796the second, and so on. Here's an example for a system with two sound cards.
977</p> 797</p>
978 798
979<pre caption="Two sound cards in /etc/modules.d/alsa"> 799<pre caption="Two sound cards in /etc/modules.d/alsa">
980options snd-emu10k1 index=0 800options snd-emu10k1 index=0
981options snd-via82xx index=1 801options snd-via82xx index=1

Legend:
Removed from v.1.80  
changed lines
  Added in v.1.81

  ViewVC Help
Powered by ViewVC 1.1.20