Bug 20060

Comment 1 Sheldon Hearn 2000-07-20 15:10:23 UTC

Responsible Changed
From-To: freebsd-doc->sheldonh

I'll take this, although I think I'll take a different 
approach.

Comment 2 Sheldon Hearn 2000-07-20 15:20:20 UTC

State Changed
From-To: open->closed

I've added a traditional FILES section in HEAD and merged 
the delta onto RELENG_4 as rev 1.12.2.2 . 

Just in time for 4.1-RELEASE.  I'd like to revisit this page 
after 4.1-RELEASE. :-)

On Thu, Jul 20, 2000 at 09:52:29AM -0400, Sean O'Connell wrote:
> 	The following is a patch to /usr/src/share/man/man4/pcm.4 that 
> 	adds a DEVICE FILES section (probably nonstandard) to reward the
> 	industrious user.

What about using .Sh FILES instead? This section should contain "Files
which are used or created by the man page subject" (mdoc.samples(7)).

> 	relevant /dev entries ... It might be a nice thing to add.

After a conversation with another frustrated -stable user:
1) Install this manpage as snd.4, as well (there is no snd man page on
   -current right now, you may have an old copy)
2) Add a warning that FreeBSD uses the concept of a default sound device
   and that sh MAKEDEV sndX changes this, too. <quote>I couldn't believe
   that MAKEDEV has a memory</quote>
3) Add a hint that users with more than one sound card in their system 
   should create the device for their most sound card last.

/s/Udo (sorry, I don't speak mdoc)

Udo Erdelhoff stated:
: On Thu, Jul 20, 2000 at 09:52:29AM -0400, Sean O'Connell wrote:
: > 	The following is a patch to /usr/src/share/man/man4/pcm.4 that 
: > 	adds a DEVICE FILES section (probably nonstandard) to reward the
: > 	industrious user.
: 
: What about using .Sh FILES instead? This section should contain "Files
: which are used or created by the man page subject" (mdoc.samples(7)).

Sheldon committed it with FILES.  I goofed and didn't fully read the
mdoc.samples manpage... my bad!  I guess that I hadn't come across a
FILES section before.  My other thought was to put it under BUGS :-)

: > 	relevant /dev entries ... It might be a nice thing to add.

: 1) Install this manpage as snd.4, as well (there is no snd man page on
:    -current right now, you may have an old copy)

I am not sure since there is a snd device in the Voxware stuff... it
might lead to some confusion (I'll leave this to the experts).

: 2) Add a warning that FreeBSD uses the concept of a default sound device
:    and that sh MAKEDEV sndX changes this, too. <quote>I couldn't believe
:    that MAKEDEV has a memory</quote>

This would be a nice addition to the FAQ section along with point 3.

: 3) Add a hint that users with more than one sound card in their system 
:    should create the device for their most sound card last.

By this, you mean "primary/favorite" sound card?

: /s/Udo (sorry, I don't speak mdoc)


-----------------------------------------------------------------------
Sean O'Connell                                Email: sean@stat.Duke.EDU
Institute of Statistics and Decision Sciences Phone: (919) 684-5419
Duke University                               Fax:   (919) 684-8594

On Thu, Jul 20, 2000 at 11:37:59AM -0400, Sean O'Connell wrote:
> : 3) Add a hint that users with more than one sound card in their system 
> :    should create the device for their most sound card last.
> 
> By this, you mean "primary/favorite" sound card?
Exactly.

/s/Udo
-- 
Cocaine is nature's way of telling you you have too much money.

On Thu, 20 Jul 2000 18:41:36 +0200, Udo Erdelhoff wrote:

> sh MAKEDEV sndX does two things
> a) it creates the device nodes audioX, dspX, mixerX, ...
> b) it creates a set of symbolic links:
> audio -> audioX
> dspX -> dspX
> mixer -> mixerX
> ...

Duh, of course!

I've asked Jordan for extra time to add descriptions about the symbolic
links to the manual page, even though 4.1-RELEASE code freeze starts in
an hour.  If he's okay with that, I'll address this tomorrow.

Ciao,
Sheldon.

Hi Cameron,

I'd like to apply this for 4.1-RELEASE.  I've already sent Jordan mail
asking for permission.  Note that the patch is relative to my recent rev
1.15.

Ciao,
Sheldon.

Index: pcm.4
===================================================================
RCS file: /home/ncvs/src/share/man/man4/pcm.4,v
retrieving revision 1.15
diff -u -d -r1.15 pcm.4
--- pcm.4	2000/07/20 15:47:45	1.15
+++ pcm.4	2000/07/20 17:17:59
@@ -124,19 +124,60 @@
 .Pp
 .El
 .Sh FILES
-.Bl -tag -width /dev/snd* -compact
-.It Pa /dev/snd*
-Device nodes created with the shell commands
-.Bk -words
-.Ql cd /dev; sh MAKEDEV snd0
-.Ek
-for the pcm0 device,
-.Bk -words
-.Ql cd /dev; sh MAKEDEV snd1
-.Ek
-for the pcm1 device,
-etc.
+The following commonly used symbolic links to real device nodes
+should be present:
+.Pp
+.Bl -tag -width /dev/sequencer -compact
+.It Pa /dev/audio
+Sparc-compatible audio device
+.It Pa /dev/dsp
+Digitized voice device
+.It Pa /dev/dspW
+Like
+.Pa /dev/dsp ,
+but 16 bits per sample
+.It Pa /dev/midi
+Raw midi access device
+.It Pa /dev/mixer
+Control port mixer device
+.It Pa /dev/music
+Level 2 sequencer interface
+.It Pa /dev/sequencer
+Sequencer device
+.It Pa /dev/pss
+Programmable device interface
 .El
+.Pp
+Each symbolic link refers to a device node of the same name,
+but with a unit number appended.
+The unit number for each device matches the unit number of the
+device probed at boot time.
+Device probe messages can be examined with the
+.Xr dmesg 8
+utility.
+.Pp
+All the appropriate device nodes and symbolic links
+for the
+.Ql pcm0
+device would created with the following commands:
+.Bd -literal -offset indent
+cd /dev; sh MAKEDEV snd0
+.Ed
+.Pp
+Similarly, the device nodes and symbolic links for the
+.Ql pcm1
+device would be created as follows:
+.Bd -literal -offset indent
+cd /dev; sh MAKEDEV snd1
+.Ed
+.Pp
+Since the
+.Pa /dev/MAKEDEV
+utility creates symbolic links that will be used by
+many utilities by default,
+the device nodes and symbolic links for the
+preferred audio device in systems with multiple audio devices
+should be created last.
 .Sh DIAGNOSTICS AND TROUBLESHOOTING
 .Bl -tag -width 2m
 .It ac97: dac not ready