Update the "Setting Up the Sound Card" section to match 5.X

1 files changed, 145 insertions, 232 deletions

diff --git a/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml b/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml
index 70f7e6f1ed..6330df8c83 100644
--- a/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml
@@ -123,72 +123,31 @@
 	 <!-- 20 November 2000 -->
         </author>
       </authorgroup>
+      <authorgroup>
+        <author>
+	 <firstname>Marc</firstname>
+	 <surname>Fonvieille</surname>
+	 <contrib>Enhanced for &os;&nbsp;5.X by </contrib>
+	 <!-- 13 September 2004 -->
+        </author>
+      </authorgroup>
     </sect1info>
 
     <title>Setting Up the Sound Card</title>
     
   <sect2 id="sound-device">
-    <title>Locating the Correct Device</title>
+    <title>Configuring the System</title>
 
     <indexterm><primary>PCI</primary></indexterm>
     <indexterm><primary>ISA</primary></indexterm>
     <indexterm><primary>sound cards</primary></indexterm>
     <para>Before you begin, you should know the model of the card you
       have, the chip it uses, and whether it is a PCI or ISA card.
-      FreeBSD supports a wide variety of both PCI and ISA cards.  If
-      you do not see your card in the following list, check the
-      &man.pcm.4; manual page.  This is not a complete list; however,
-      it does list some of the most common cards.</para>
-
-    <itemizedlist>
-      <listitem>
-	<para>Crystal 4237, 4236, 4232, 4231</para>
-      </listitem>
-
-      <listitem>
-	<para>Yamaha OPL-SAx</para>
-      </listitem>
-
-      <listitem>
-	<para>OPTi931</para>
-      </listitem>
-
-      <listitem>
-	<para>Ensoniq AudioPCI 1370/1371</para>
-      </listitem>
-
-      <listitem>
-	<para>ESS Solo-1/1E</para>
-      </listitem>
-
-      <listitem>
-	<para>NeoMagic 256AV/ZX</para>
-      </listitem>
-
-      <listitem>
-	<para>&soundblaster; Pro, 16, 32, AWE64, AWE128, Live</para>
-      </listitem>
-
-      <listitem>
-	<para>Creative ViBRA16</para>
-      </listitem>
-
-      <listitem>
-	<para>Advanced Asound 100, 110, and Logic ALS120</para>
-      </listitem>
-
-      <listitem>
-	<para>ES 1868, 1869, 1879, 1888</para>
-      </listitem>
-
-      <listitem>
-	<para>Gravis UltraSound</para>
-      </listitem>
-
-      <listitem>
-	<para>Aureal Vortex 1 or 2</para>
-      </listitem>
-    </itemizedlist>
+      FreeBSD supports a wide variety of both PCI and ISA cards.
+      Check the supported audio devices list of the <ulink
+      url="&rel.current.hardware;">Hardware Notes</ulink> to see if
+      your card is supported.  This document will also mention which
+      driver supports your card.</para>
 
     <indexterm>
       <primary>kernel</primary>
@@ -201,7 +160,8 @@
       card with &man.kldload.8; which can either be done from the
       command line:</para>
 
-    <screen>&prompt.root; <userinput>kldload snd_emu10k1.ko</userinput></screen>
+    <screen>&prompt.root; <userinput>kldload snd_emu10k1</userinput></screen>
+
     <para>or by adding the appropriate line to the file
       <filename>/boot/loader.conf</filename> like this:</para>
 
@@ -211,223 +171,176 @@
       card.  Other available loadable sound modules are listed in
       <filename>/boot/defaults/loader.conf</filename>.
       If you are not sure which driver to use, you may try to load
-      <filename>snd_driver</filename>, which is a metadriver loading the most common
-      device drivers at once, this speeds up the search for the correct
-      driver.</para>
+      the <filename>snd_driver</filename> module:</para>
+
+    <screen>&prompt.root; <userinput>kldload snd_driver</userinput></screen>
 
-    <para>Alternatively, you may statically
+    <para>This is a metadriver loading the most common device drivers
+      at once.  This speeds up the search for the correct driver.  It
+      is also possible to load all sound drivers via the
+      <filename>/boot/loader.conf</filename> facility.</para>
+
+    <note>
+      <para>Under &os;&nbsp;4.X, to load all sound drivers, you have
+	to load the <filename>snd</filename> module instead of
+	<filename>snd_driver</filename>.</para>
+    </note>
+
+    <para>A second method is to statically
       compile in support for your sound card in your kernel.  The
-      sections below provide the information you need to add support
+      section below provides the information you need to add support
       for your hardware in this manner.  For more information about
       recompiling your kernel, please see <xref
       linkend="kernelconfig">.</para>
 
     <sect3>
-      <title>Creative, Advance, and ESS Sound Cards</title>
+      <title>Configuring a Custom Kernel with Sound Support</title>
 
-      <para>If you have one of the above cards, you will need to
-	add:</para>
-	
-      <programlisting>device pcm</programlisting>
+      <para>The first thing to do is adding the generic audio driver
+	&man.sound.4; to the kernel, for that you will need to
+	add the following line to the kernel configuration file:</para>
 
-      <para>to your kernel configuration file.  If you have a PnP ISA
-	card, you will also need to add:</para>
+      <programlisting>device sound</programlisting>
 
-      <programlisting>device sbc</programlisting>
-
-      <para>For a non-PnP ISA card, add:</para>
-
-      <programlisting>device pcm
-device sbc0 at isa? port 0x220 irq 5 drq 1 flags 0x15</programlisting>
-
-      <para>to your kernel configuration file.  The settings shown
-	above are the defaults.  You may need to change the IRQ or the
-	other settings to match your card.  See the &man.sbc.4; manual
-	page for more information.</para>
+      <para>Under &os;&nbsp;4.X, you would use the following
+	line:</para>
 
-      <note>
-	<para>The Sound Blaster Live is not supported under FreeBSD&nbsp;4.0
-	  without a patch, which this section will not cover.  It is
-	  recommended that you update to the latest -STABLE before
-	  trying to use this card.</para>
-      </note>
-    </sect3>
+      <programlisting>device pcm</programlisting>
 
-    <sect3>
-      <title>Gravis UltraSound Cards</title>
+      <para>Then we have to add the support for our sound card.
+	Therefore, we need to know which driver supports the card.
+	Check the supported audio devices list of the <ulink
+	url="&rel.current.hardware;">Hardware Notes</ulink>, to
+	determine the correct driver for your sound card.  For
+	example, a Creative &soundblaster; Live! sound card is
+	supported by the &man.snd.emu10k1.4; driver.  To add the support
+	for this card, use the following:</para>
+
+      <programlisting>device snd_emu10k1</programlisting>
+
+      <para>Be sure to read the manual page of the driver for the
+	syntax to use.  Informations regarding the syntax of sound
+	drivers in the kernel configuration can also be found in the
+	<filename>/usr/src/sys/conf/NOTES</filename> file
+	(<filename>/usr/src/sys/i386/conf/LINT</filename> for
+	&os;&nbsp;4.X).</para>
+
+      <para>Non-PnP ISA cards may require you to provide the kernel
+	with information on the sound card settings (IRQ, I/O port,
+	etc).  This is done via the
+	<filename>/boot/device.hints</filename> file.  At system boot,
+	the &man.loader.8; will read this file and pass the settings
+	to the kernel.  For example, an old
+	Creative &soundblaster; 16 ISA non-PnP card will use the
+	&man.snd.sbc.4; driver, with the following line added to
+	the kernel configuration file:</para>
 
-      <para>For a PnP ISA card, you will need to add:</para>
+      <programlisting>device sbc</programlisting>
 
-      <programlisting>device pcm
-device gusc</programlisting>
+      <para>as well as the following in
+	<filename>/boot/device.hints</filename>:</para>
 
-      <para>to your kernel configuration file.  If you have a non-PnP
-	ISA card, you will need to add:</para>
+      <programlisting>hint.sbc.0.at="isa"
+hint.sbc.0.port="0x220"
+hint.sbc.0.irq="5"
+hint.sbc.0.drq="1"
+hint.sbc.0.flags="0x15"</programlisting>
 
-      <programlisting>device pcm
-device gus0 at isa? port 0x220 irq 5 drq 1 flags 0x13</programlisting>
+      <para>In this case, the card uses the <literal>0x220</literal>
+	I/O port and the IRQ <literal>5</literal>.</para>
 
-      <para>to your kernel configuration file.  You may need to change
-	the IRQ or the other settings to match your card. See the
-	&man.gusc.4; manual page for more information.</para>
-    </sect3>
+      <para>The syntax used in the
+	<filename>/boot/device.hints</filename> file is covered in the
+	sound driver manual page.  On &os;&nbsp;4.X, these settings
+	are directly written in the kernel configuration file.  In the
+	case of our ISA card, we would only use this line:</para>
 
-    <sect3>
-      <title>Crystal Sound Cards</title>
+      <programlisting>device sbc0 at isa? port 0x220 irq 5 drq 1 flags 0x15</programlisting>
 
-      <para>For Crystal cards, you will need to add:</para>
+      <para>The settings shown above are the defaults.  In some
+	cases, you may need to change the IRQ or the other settings to
+	match your card.  See the &man.snd.sbc.4; manual page for more
+	information.</para>
 
-      <programlisting>device pcm
-device csa</programlisting>
+      <note>
+	<para>Under &os;&nbsp;4.X, some systems with built-in
+	  motherboard sound devices may require the following option in
+	  the kernel configuration:</para>
 
-      <para>to your kernel configuration file.</para>
+	<programlisting>options PNPBIOS</programlisting>
+      </note>
     </sect3>
+  </sect2>
 
-    <sect3>
-      <title>Generic Support</title>
-
-      <para>For PnP ISA or PCI cards, you will need to add:</para>
-
-      <programlisting>device pcm</programlisting>
-
-      <para>to your kernel configuration file.  If you have a non-PnP
-	ISA sound card that does not have a bridge driver, you will
-	need to add:</para>
-
-      <programlisting>device pcm0 at isa? irq 10 drq 1 flags 0x0</programlisting>
+  <sect2 id="sound-testing">
+    <title>Testing the Sound Card</title>
 
-      <para>to your kernel configuration file.  You may need to change
-	the IRQ or the other settings to match your card.</para>
+    <para>After rebooting with the modified kernel, or after loading
+      the required module, the sound card should appear in your system
+      message buffer (&man.dmesg.8;) as something like:</para>
 
-    </sect3>
+    <screen>pcm0: &lt;Intel ICH3 (82801CA)&gt; port 0xdc80-0xdcbf,0xd800-0xd8ff irq 5 at device 31.5 on pci0
+pcm0: [GIANT-LOCKED]
+pcm0: &lt;Cirrus Logic CS4205 AC97 Codec&gt;</screen>
 
-    <sect3>
-      <title>Onboard Sound</title>
+    <para>The status of the sound card may be checked via the
+      <filename>/dev/sndstat</filename> file:</para>
 
-      <para>Some systems with built-in motherboard sound devices may
-	require the following option in your kernel
-	configuration:</para>
+    <screen>&prompt.root; <userinput>cat /dev/sndstat</userinput>
+FreeBSD Audio Driver (newpcm)
+Installed devices:
+pcm0: &lt;Intel ICH3 (82801CA)&gt; at io 0xd800, 0xdc80 irq 5 bufsz 16384
+kld snd_ich (1p/2r/0v channels duplex default)</screen>
 
-      <programlisting>options PNPBIOS</programlisting>
+    <para>The output from your system may vary.  If no
+      <devicename>pcm</devicename> devices show up, go back and review
+      what was done earlier.  Go through your kernel
+      configuration file again and make sure the correct
+      device is chosen.  Common problems are listed in <xref
+      linkend="troubleshooting">.</para>
 
-      <note>
-	<para>If you are running &os;&nbsp;5.0 or later the
-	  <literal>PNPBIOS</literal> option is not needed.  The option
-	  has been removed and the functionality is now always
-	  enabled.</para>
-      </note>
-    </sect3>
-  </sect2>
+    <para>If all goes well, you should now have a functioning sound
+      card.  If your CD-ROM or DVD-ROM drive is properly coupled to
+      your sound card, you can put a CD in the drive and play it
+      with &man.cdcontrol.1;:</para>
 
-  <sect2 id="sound-devicenodes">
-    <title>Creating and Testing the Device Nodes</title>
+      <screen>&prompt.user; <userinput>cdcontrol -f /dev/acd0 play 1</userinput></screen>
 
-    <indexterm><primary>device nodes</primary></indexterm>
-    <para>After you reboot, log in and check for the device in the
-      <filename>/var/run/dmesg.boot</filename> file, as shown below:</para>
+    <para>Various applications, such as <filename
+      role="package">audio/workman</filename> can provide a friendlier
+      interface.  You may want to install an application such as
+      <filename role="package">audio/mpg123</filename> to listen to
+      MP3 audio files.  A quick way to test the card is sending data
+      to the <filename>/dev/dsp</filename>, like this:</para>
 
-    <screen>&prompt.root; <userinput>grep pcm /var/run/dmesg.boot</userinput>
-pcm0: &lt;SB16 DSP 4.11&gt; on sbc0</screen>
+    <screen>&prompt.user; <userinput>cat <replaceable>filename</replaceable> &gt; /dev/dsp</userinput></screen>
 
-    <para>The output from your system may look different.  If no
-      <devicename>pcm</devicename> devices show up, something went
-      wrong earlier.  If that happens, go through your kernel
-      configuration file again and make sure you chose the correct
-      device.  Common problems are listed in <xref
-      linkend="troubleshooting">.</para>
+    <para>where <replaceable>filename</replaceable> can be any file.
+      This command line should produce some noise, confirming the
+      sound card is actually working.</para>
 
     <note>
-      <para>If you are running FreeBSD&nbsp;5.0 or later, you can
-	safely skip the rest of this section.  These versions use
-	&man.devfs.5; to automatically create devices nodes.</para>
-    </note>
+      <para>&os;&nbsp;4.X users need to create the sound card device
+	nodes before being able to use it.  If the card showed up in
+	message buffer as <devicename>pcm0</devicename>, you will have
+	to run the following as <username>root</username>:</para>
 
-    <para>If the previous command returned
-      <devicename>pcm0</devicename>, you will have to run the
-      following as <username>root</username>:</para>
-
-    <screen>&prompt.root; <userinput>cd /dev</userinput>
+      <screen>&prompt.root; <userinput>cd /dev</userinput>
 &prompt.root; <userinput>sh MAKEDEV snd0</userinput></screen>
 
-    <para>If the command returned <devicename>pcm1</devicename>,
-      follow the same steps as shown above, replacing
-      <devicename>snd0</devicename> with
-      <devicename>snd1</devicename>.</para>
+      <para>If the card detection returned <devicename>pcm1</devicename>,
+	follow the same steps as shown above, replacing
+	<devicename>snd0</devicename> with
+	<devicename>snd1</devicename>.</para>
 
-    <note>
-      <para>The above commands will <emphasis>not</emphasis> create a
-	<filename>/dev/snd</filename> device!</para>
+      <para><command>MAKEDEV</command> will create a group of device
+	nodes that will be used by the different sound related
+	applications.</para>
     </note>
 
-    <para><command>MAKEDEV</command> will create a group of device
-      nodes, including:</para>
-
-    <informaltable frame="none">
-      <tgroup cols="2">
-	<thead>
-	  <row>
-	    <entry>Device</entry>
-	    <entry>Description</entry>
-	  </row>
-	</thead>
-
-	<tbody>
-	  <row>
-	    <entry><filename>/dev/audio</filename></entry>
-	    <entry>&sparc; compatible audio device</entry>
-	  </row>
-
-	  <row>
-	    <entry><filename>/dev/dsp</filename></entry>
-	    <entry>Digitized voice device</entry>
-	  </row>
-
-	  <row>
-	    <entry><filename>/dev/dspW</filename></entry>
-	    <entry>Like <filename>/dev/dsp</filename>, but 16 bits
-	      per sample</entry>
-	  </row>
-
-	  <row>
-	    <entry><filename>/dev/midi</filename></entry>
-	    <entry>Raw midi access device</entry>
-	  </row>
-
-	  <row>
-	    <entry><filename>/dev/mixer</filename></entry>
-	    <entry>Control port mixer device</entry>
-	  </row>
-
-	  <row>
-	    <entry><filename>/dev/music</filename></entry>
-	    <entry>Level 2 sequencer interface</entry>
-	  </row>
-
-	  <row>
-	    <entry><filename>/dev/sequencer</filename></entry>
-	    <entry>Sequencer device</entry>
-	  </row>
-
-	  <row>
-	    <entry><filename>/dev/pss</filename></entry>
-	    <entry>Programmable device interface</entry>
-	  </row>
-	</tbody>
-      </tgroup>
-    </informaltable>
-
-    <para>If all goes well, you should now have a functioning sound
-      card.  If your CD-ROM or DVD-ROM drive is properly coupled to
-      your sound card, you can put a CD in the drive and play it
-      with &man.cdcontrol.1;:</para>
-
-      <screen>&prompt.user; <userinput>cdcontrol -f /dev/acd0c play 1</userinput></screen>
-
-    <para>Various applications, such as <filename
-      role="package">audio/workman</filename> offer a better
-      interface.  You may want to install an application such as
-      <filename role="package">audio/mpg123</filename> to listen to
-      MP3 audio files.</para>
+    <para>Sound card mixer levels can be changed via the &man.mixer.8;
+      command.  More details can be found in the &man.mixer.8; manual
+      page.</para>
 
     <sect3 id="troubleshooting">
       <title>Common Problems</title>