[PATCH] sound(4) related manpages 5.3 TODO item
Ruslan Ermilov
ru at FreeBSD.org
Sat Aug 28 07:25:05 PDT 2004
Gang,
[ Please keep me Cc:ed when replying. ]
I've picked up the "sound(4) related manual pages" item from
the 5.3-RELEASE TODO list.
While working on adopting the pcm(4) and related manpages to
the new world order, I have noticed some odds that I'd like
your comments on first, before I proceed further.
One and most important thing I'm not sure I understand, and
that's causing a lot of confusion, is why "device pcm" was
renamed to "device sound" in the first place? I believe the
reason is that "device sound" is a generic sound driver,
which has support for PCM playback, mixer, /dev/sndstat,
eventually MIDI, sequencer, and so on. Individual sound
drivers are free to implement either of these interfaces.
Most of them implement "pcm" nowadays, so saying that
"pcm was renamed to sound" is not quite correct. In other
words, the sound.ko module provides the infrastructure for
more than just PCM, and the sound(4) manpage should eventually
document more than just PCM. Does that sound correct?
Also, there seems to be some confusion between the modules,
drivers, and devices that they implement, which are different
beasties, and are often named differently, and this causes
some misunderstandings and bugs (see below).
Anyway, the attached patch adopts the sound(4) related man
pages to the new world order. How to proceed:
1. The following repo-copies in /home/ncvs/src/share/man/man4
should be made (there were made locally to produce the
patch):
pcm.4,v -> sound.4,v
csa.4,v -> snd_csa.4,v
gusc.4,v -> snd_gusc.4,v
maestro3.4,v -> snd_maestro3.4,v
sbc.4,v -> snd_sbc.4,v
uaudio.4,v -> snd_uaudio.4,v
2. The old manpages (on the left) were removed, and aren't
included in the patch.
3. After repo-copies and deletes, the attached patch should be
applied. It's mostly mechanical (foo -> snd_foo, pcm -> sound),
with the following notable exceptions:
- Note that non-PnP ISA cards, such as those handled by snd_mss(4)
and snd_ad1816(4), still require hints of the form
hint.pcm.0.at="isa"
hint.pcm.0.irq="5"
hint.pcm.0.drq="1"
hint.pcm.0.flags="0x0"
because they implement device "pcm". Granted, the difference
between module and driver name is confusing enough that Seigo
misspelled hints names in sys/conf/NOTES, and Simon misspelled
them in the new snd_ad1816(4) manpage. The patch corrects the
hints names in the snd_ad1816(4) manpage and NOTES. The patch
removes the "hint.snd_mss" from NOTES because (like was said)
the snd_mss(4) module implements the "pcm" device, hence the
hints start with "hint.pcm", and this is already documented
in the sound(4) manpage. Module snd_sbc(4) and snd_gusc(4)
are special in that they implement PCM support through the
bridge device ("sbc" and "gusc", respectively), with "pcm"
device as a child. For them, ISA hints should be spelled
"hint.sbc" and "hint.gusc", respectively. This is also fixed
in NOTES.
- The patch also fixes the SYNOPSIS section of the snd_maestro3(4)
manpage to align it with other sound drivers manpages, and adds
missing "device sound" to almost all of the snd_*(4) manpages.
Does that look sane? I'd be grateful is someone more fluent with
our sound subsystem could review this.
Cheers,
--
Ruslan Ermilov
ru at FreeBSD.org
FreeBSD committer
-------------- next part --------------
Index: sys/conf/NOTES
===================================================================
RCS file: /home/ncvs/src/sys/conf/NOTES,v
retrieving revision 1.1263
diff -u -r1.1263 NOTES
--- sys/conf/NOTES 19 Aug 2004 18:29:55 -0000 1.1263
+++ sys/conf/NOTES 28 Aug 2004 11:14:29 -0000
@@ -1900,20 +1900,16 @@
device snd_uaudio
# For non-pnp sound cards:
-hint.snd_mss.0.at="isa"
-hint.snd_mss.0.irq="10"
-hint.snd_mss.0.drq="1"
-hint.snd_mss.0.flags="0x0"
-hint.snd_sbc.0.at="isa"
-hint.snd_sbc.0.port="0x220"
-hint.snd_sbc.0.irq="5"
-hint.snd_sbc.0.drq="1"
-hint.snd_sbc.0.flags="0x15"
-hint.snd_gusc.0.at="isa"
-hint.snd_gusc.0.port="0x220"
-hint.snd_gusc.0.irq="5"
-hint.snd_gusc.0.drq="1"
-hint.snd_gusc.0.flags="0x13"
+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"
+hint.gusc.0.at="isa"
+hint.gusc.0.port="0x220"
+hint.gusc.0.irq="5"
+hint.gusc.0.drq="1"
+hint.gusc.0.flags="0x13"
#
# Miscellaneous hardware:
Index: share/man/man4/Makefile
===================================================================
RCS file: /home/ncvs/src/share/man/man4/Makefile,v
retrieving revision 1.277
diff -u -r1.277 Makefile
--- share/man/man4/Makefile 27 Aug 2004 22:06:56 -0000 1.277
+++ share/man/man4/Makefile 28 Aug 2004 11:58:10 -0000
@@ -40,7 +40,6 @@
ciss.4 \
cm.4 \
crypto.4 \
- csa.4 \
cue.4 \
cy.4 \
da.4 \
@@ -80,7 +79,6 @@
geom.4 \
gif.4 \
gre.4 \
- gusc.4 \
gx.4 \
harp.4 \
hatm.4 \
@@ -136,7 +134,6 @@
mac_seeotheruids.4 \
mac_stub.4 \
mac_test.4 \
- maestro3.4 \
md.4 \
mem.4 \
meteor.4 \
@@ -214,7 +211,6 @@
pccbb.4 \
pci.4 \
pcic.4 \
- pcm.4 \
pcn.4 \
pcvt.4 \
pim.4 \
@@ -239,7 +235,6 @@
sa.4 \
sab.4 \
safe.4 \
- sbc.4 \
sbp.4 \
sbp_targ.4 \
sbsh.4 \
@@ -261,11 +256,17 @@
snd_als4000.4 \
snd_cmi.4 \
snd_cs4281.4 \
+ snd_csa.4 \
snd_ds1.4 \
snd_emu10k1.4 \
snd_es137x.4 \
+ snd_gusc.4 \
+ snd_maestro3.4 \
+ snd_sbc.4 \
snd_solo.4 \
+ snd_uaudio.4 \
snp.4 \
+ sound.4 \
spic.4 \
splash.4 \
sppp.4 \
@@ -293,7 +294,6 @@
tx.4 \
txp.4 \
uart.4 \
- uaudio.4 \
ubsa.4 \
ubsec.4 \
ubser.4 \
@@ -393,9 +393,6 @@
MLINKS+=oldcard.4 card.4
MLINKS+=patm.4 if_patm.4
MLINKS+=pccbb.4 cbb.4
-MLINKS+=pcm.4 als4000.4 \
- pcm.4 emu10k1.4 \
- pcm.4 snd.4
MLINKS+=pcn.4 if_pcn.4
MLINKS+=pcvt.4 vt.4
MLINKS+=ppp.4 if_ppp.4
@@ -413,6 +410,8 @@
MLINKS+=sl.4 if_sl.4
MLINKS+=smp.4 SMP.4
MLINKS+=sn.4 if_sn.4
+MLINKS+=sound.4 pcm.4 \
+ sound.4 snd.4
MLINKS+=splash.4 screensaver.4
MLINKS+=ste.4 if_ste.4
MLINKS+=stf.4 if_stf.4
Index: share/man/man4/snd_ad1816.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_ad1816.4,v
retrieving revision 1.1
diff -u -r1.1 snd_ad1816.4
--- share/man/man4/snd_ad1816.4 27 Aug 2004 22:06:56 -0000 1.1
+++ share/man/man4/snd_ad1816.4 28 Aug 2004 12:39:43 -0000
@@ -31,12 +31,13 @@
.Nm snd_ad1816
.Nd "Analog Devices AD1816 ISA bridge device driver"
.Sh SYNOPSIS
+.Cd "device sound"
.Cd "device snd_ad1816"
.Pp
-.Cd hint.snd_ad1816.0.at="isa"
-.Cd hint.snd_ad1816.0.irq="10"
-.Cd hint.snd_ad1816.0.drq="1"
-.Cd hint.snd_ad1816.0.flags="0x0"
+.Cd hint.pcm.0.at="isa"
+.Cd hint.pcm.0.irq="10"
+.Cd hint.pcm.0.drq="1"
+.Cd hint.pcm.0.flags="0x0"
.Pp
.Sh DESCRIPTION
The
Index: share/man/man4/snd_als4000.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_als4000.4,v
retrieving revision 1.1
diff -u -r1.1 snd_als4000.4
--- share/man/man4/snd_als4000.4 27 Aug 2004 22:06:56 -0000 1.1
+++ share/man/man4/snd_als4000.4 28 Aug 2004 12:39:47 -0000
@@ -31,6 +31,7 @@
.Nm snd_als4000
.Nd "Avance Logic ALS4000 PCI bridge device driver"
.Sh SYNOPSIS
+.Cd "device sound"
.Cd "device snd_als4000"
.Pp
.Sh DESCRIPTION
Index: share/man/man4/snd_cmi.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_cmi.4,v
retrieving revision 1.1
diff -u -r1.1 snd_cmi.4
--- share/man/man4/snd_cmi.4 27 Aug 2004 22:06:56 -0000 1.1
+++ share/man/man4/snd_cmi.4 28 Aug 2004 12:39:48 -0000
@@ -31,6 +31,7 @@
.Nm snd_cmi
.Nd "CMedia CMI8338/CMI8738 PCI bridge device driver"
.Sh SYNOPSIS
+.Cd "device sound"
.Cd "device snd_cmi"
.Pp
.Sh DESCRIPTION
Index: share/man/man4/snd_cs4281.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_cs4281.4,v
retrieving revision 1.1
diff -u -r1.1 snd_cs4281.4
--- share/man/man4/snd_cs4281.4 27 Aug 2004 22:06:56 -0000 1.1
+++ share/man/man4/snd_cs4281.4 28 Aug 2004 12:39:50 -0000
@@ -31,6 +31,7 @@
.Nm snd_cs4281
.Nd "Crystal Semiconductor CS4281 PCI bridge device driver"
.Sh SYNOPSIS
+.Cd "device sound"
.Cd "device snd_cs4281"
.Pp
.Sh DESCRIPTION
Index: share/man/man4/snd_csa.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_csa.4,v
retrieving revision 1.9
diff -u -r1.9 snd_csa.4
--- share/man/man4/snd_csa.4 8 Jul 2002 20:57:19 -0000 1.9
+++ share/man/man4/snd_csa.4 28 Aug 2004 12:39:52 -0000
@@ -23,21 +23,22 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/share/man/man4/snd_csa.4,v 1.9 2002/07/08 20:57:19 blackend Exp $
+.\" $FreeBSD$
.\"
-.Dd December 18, 1999
-.Dt CSA 4
+.Dd August 28, 2004
+.Dt SND_CSA 4
.Os
.Sh NAME
-.Nm csa
+.Nm snd_csa
.Nd Crystal Semiconductor CS461x/462x/4280 PCI bridge device driver
.Sh SYNOPSIS
-.Cd "device csa"
+.Cd "device sound"
+.Cd "device snd_csa"
.Sh DESCRIPTION
The
.Nm
bridge driver allows the generic audio drivers including
-.Xr pcm 4
+.Xr sound 4
to attach to the following PCI sound cards:
.Bl -bullet -width 2m
.It
@@ -58,6 +59,6 @@
device driver first appeared in
.Fx 4.0 .
.Sh SEE ALSO
-.Xr pcm 4
+.Xr sound 4
.Sh AUTHORS
.An Seigo Tanimura Aq tanimura at r.dl.itc.u-tokyo.ac.jp
Index: share/man/man4/snd_ds1.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_ds1.4,v
retrieving revision 1.1
diff -u -r1.1 snd_ds1.4
--- share/man/man4/snd_ds1.4 27 Aug 2004 22:06:56 -0000 1.1
+++ share/man/man4/snd_ds1.4 28 Aug 2004 12:39:55 -0000
@@ -31,6 +31,7 @@
.Nm snd_ds1
.Nd "Yamaha DS-1 PCI bridge device driver"
.Sh SYNOPSIS
+.Cd "device sound"
.Cd "device snd_ds1"
.Pp
.Sh DESCRIPTION
Index: share/man/man4/snd_emu10k1.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_emu10k1.4,v
retrieving revision 1.1
diff -u -r1.1 snd_emu10k1.4
--- share/man/man4/snd_emu10k1.4 27 Aug 2004 22:06:56 -0000 1.1
+++ share/man/man4/snd_emu10k1.4 28 Aug 2004 12:39:56 -0000
@@ -31,6 +31,7 @@
.Nm snd_emu10k1
.Nd "SoundBlaster Live! and Audigy PCI bridge device driver"
.Sh SYNOPSIS
+.Cd "device sound"
.Cd "device snd_emu10k1"
.Pp
.Sh DESCRIPTION
Index: share/man/man4/snd_es137x.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_es137x.4,v
retrieving revision 1.1
diff -u -r1.1 snd_es137x.4
--- share/man/man4/snd_es137x.4 27 Aug 2004 22:06:56 -0000 1.1
+++ share/man/man4/snd_es137x.4 28 Aug 2004 12:39:58 -0000
@@ -31,6 +31,7 @@
.Nm snd_es137x
.Nd "Ensoniq AudioPCI ES137x bridge device driver"
.Sh SYNOPSIS
+.Cd "device sound"
.Cd "device snd_es137x"
.Pp
.Sh DESCRIPTION
Index: share/man/man4/snd_gusc.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_gusc.4,v
retrieving revision 1.8
diff -u -r1.8 snd_gusc.4
--- share/man/man4/snd_gusc.4 3 Jul 2004 18:29:20 -0000 1.8
+++ share/man/man4/snd_gusc.4 28 Aug 2004 12:40:00 -0000
@@ -23,17 +23,17 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/share/man/man4/snd_gusc.4,v 1.8 2004/07/03 18:29:20 ru Exp $
+.\" $FreeBSD$
.\"
-.Dd December 18, 1999
-.Dt GUSC 4
+.Dd August 28, 2004
+.Dt SND_GUSC 4
.Os
.Sh NAME
-.Nm gusc
+.Nm snd_gusc
.Nd Gravis UltraSound ISA bridge device driver
.Sh SYNOPSIS
-.Cd "device pcm"
-.Cd "device gusc"
+.Cd "device sound"
+.Cd "device snd_gusc"
.Pp
For non-PnP cards, add the following lines in
.Pa /boot/device.hints .
@@ -46,7 +46,7 @@
The
.Nm
bridge driver allows the generic audio drivers including
-.Xr pcm 4
+.Xr sound 4
to attach to the following ISA sound cards:
.Bl -bullet -width 2m
.It
@@ -71,7 +71,7 @@
device driver first appeared in
.Fx 4.0 .
.Sh SEE ALSO
-.Xr pcm 4
+.Xr sound 4
.Sh AUTHORS
.An Ville-Pertti Keinonen Aq will at iki.fi
.An Seigo Tanimura Aq tanimura at r.dl.itc.u-tokyo.ac.jp
Index: share/man/man4/snd_maestro3.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_maestro3.4,v
retrieving revision 1.3
diff -u -r1.3 snd_maestro3.4
--- share/man/man4/snd_maestro3.4 21 Nov 2001 17:12:31 -0000 1.3
+++ share/man/man4/snd_maestro3.4 28 Aug 2004 12:40:02 -0000
@@ -22,16 +22,17 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/share/man/man4/snd_maestro3.4,v 1.3 2001/11/21 17:12:31 ru Exp $
+.\" $FreeBSD$
.\"
-.Dd October 14, 2001
-.Dt MAESTRO3 4
+.Dd August 28, 2004
+.Dt SND_MAESTRO3 4
.Os
.Sh NAME
-.Nm maestro3
+.Nm snd_maestro3
.Nd FreeBSD audio sub-driver for ESS Maestro3/Allegro-1 hardware
.Sh SYNOPSIS
-.Li "kldload snd_maestro3"
+.Cd "device sound"
+.Cd "device snd_maestro3"
.Sh DESCRIPTION
The
.Nm
@@ -45,7 +46,7 @@
License, and thus this driver is not included in the default
.Pa GENERIC
kernel, nor is it compiled into the kernel when
-.Cd "device pcm"
+.Cd "device sound"
is specified in the kernel config file.
A convenient way to automatically load the driver is to add the line
.Pp
@@ -64,7 +65,7 @@
.Pa /boot/device.hints
to override the default setting.
.Sh SEE ALSO
-.Xr pcm 4 ,
+.Xr sound 4 ,
.Xr loader.conf 5
.Sh HISTORY
The
Index: share/man/man4/snd_sbc.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_sbc.4,v
retrieving revision 1.10
diff -u -r1.10 snd_sbc.4
--- share/man/man4/snd_sbc.4 3 Jul 2004 18:29:20 -0000 1.10
+++ share/man/man4/snd_sbc.4 28 Aug 2004 13:57:23 -0000
@@ -25,14 +25,15 @@
.\"
.\" $FreeBSD: src/share/man/man4/snd_sbc.4,v 1.10 2004/07/03 18:29:20 ru Exp $
.\"
-.Dd December 18, 1999
-.Dt SBC 4
+.Dd August 28, 2004
+.Dt SND_SBC 4
.Os
.Sh NAME
-.Nm sbc
+.Nm snd_sbc
.Nd Creative Sound Blaster ISA and compatible bridge device driver
.Sh SYNOPSIS
-.Cd "device sbc"
+.Cd "device sound"
+.Cd "device snd_sbc"
.Pp
Non-PnP cards require the following lines in
.Pa /boot/device.hints :
@@ -45,7 +46,7 @@
The
.Nm
bridge driver allows the generic audio drivers including
-.Xr pcm 4
+.Xr sound 4
to attach to the following ISA sound cards:
.Bl -bullet -width 2m
.It
@@ -75,6 +76,6 @@
device driver first appeared in
.Fx 4.0 .
.Sh SEE ALSO
-.Xr pcm 4
+.Xr sound 4
.Sh AUTHORS
.An Seigo Tanimura Aq tanimura at r.dl.itc.u-tokyo.ac.jp
Index: share/man/man4/snd_solo.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_solo.4,v
retrieving revision 1.1
diff -u -r1.1 snd_solo.4
--- share/man/man4/snd_solo.4 27 Aug 2004 22:06:56 -0000 1.1
+++ share/man/man4/snd_solo.4 28 Aug 2004 12:40:07 -0000
@@ -31,6 +31,7 @@
.Nm snd_solo
.Nd "ESS Solo-1/1E PCI bridge device driver"
.Sh SYNOPSIS
+.Cd "device sound"
.Cd "device snd_solo"
.Pp
.Sh DESCRIPTION
Index: share/man/man4/snd_uaudio.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/snd_uaudio.4,v
retrieving revision 1.3
diff -u -r1.3 snd_uaudio.4
--- share/man/man4/snd_uaudio.4 8 Jul 2004 12:36:20 -0000 1.3
+++ share/man/man4/snd_uaudio.4 28 Aug 2004 12:40:12 -0000
@@ -34,17 +34,18 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/share/man/man4/snd_uaudio.4,v 1.3 2004/07/08 12:36:20 ru Exp $
+.\" $FreeBSD$
.\"
-.Dd November 10, 2003
-.Dt UAUDIO 4
+.Dd August 28, 2004
+.Dt SND_UAUDIO 4
.Os
.Sh NAME
-.Nm uaudio
+.Nm snd_uaudio
.Nd USB audio device driver
.Sh SYNOPSIS
-.Cd "device pcm"
+.Cd "device sound"
.Cd "device usb"
+.Cd "device snd_uaudio"
.Sh DESCRIPTION
The
.Nm
@@ -62,7 +63,7 @@
.Ql USB Audio Class Specification
for more information.
.Sh SEE ALSO
-.Xr pcm 4 ,
+.Xr sound 4 ,
.Xr usb 4
.Rs
.%T "USB Audio Class Specifications"
Index: share/man/man4/sound.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/sound.4,v
retrieving revision 1.36
diff -u -r1.36 sound.4
--- share/man/man4/sound.4 7 Jul 2004 19:57:14 -0000 1.36
+++ share/man/man4/sound.4 28 Aug 2004 13:56:18 -0000
@@ -23,12 +23,13 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/share/man/man4/sound.4,v 1.36 2004/07/07 19:57:14 ru Exp $
+.\" $FreeBSD$
.\"
-.Dd June 24, 2004
-.Dt PCM 4
+.Dd August 18, 2004
+.Dt SOUND 4
.Os
.Sh NAME
+.Nm sound ,
.Nm pcm ,
.Nm snd
.Nd
@@ -36,7 +37,7 @@
PCM audio device infrastructure
.Sh SYNOPSIS
For a card with bridge driver support, and a PnP card:
-.Cd "device pcm"
+.Cd "device sound"
.Pp
For a card without bridge driver support, and a non-PnP card,
the following lines may be required in
@@ -109,7 +110,7 @@
In general, the module
.Pa snd_foo
corresponds to
-.Cd "device foo"
+.Cd "device snd_foo"
and can be
loaded by the boot
.Xr loader 8
@@ -338,6 +339,8 @@
.Nm
device driver first appeared in
.Fx 2.2.6
+as
+.Nm pcm ,
written by
.An Luigi Rizzo .
It was later
@@ -348,9 +351,9 @@
The API evolved from the VOXWARE
standard which later became OSS standard.
.Sh SEE ALSO
-.Xr csa 4 ,
-.Xr gusc 4 ,
-.Xr sbc 4 ,
+.Xr snd_csa 4 ,
+.Xr snd_gusc 4 ,
+.Xr snd_sbc 4 ,
.Xr devfs 5 ,
.Xr loader.conf 5 ,
.Xr dmesg 8 ,
@@ -364,7 +367,7 @@
.An -nosplit
.An Luigi Rizzo Aq luigi at iet.unipi.it
initially wrote the
-.Nm
+.Nm pcm
device driver and this manual page.
.An Cameron Grant Aq gandalf at vilnya.demon.co.uk
later revised the device driver for
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/freebsd-current/attachments/20040828/38c16d04/attachment.bin
More information about the freebsd-current
mailing list