From sto@stat.Duke.EDU  Thu Jul 20 06:52:36 2000
Return-Path: <sto@stat.Duke.EDU>
Received: from isds.duke.edu (davinci.isds.duke.edu [152.3.22.1])
	by hub.freebsd.org (Postfix) with ESMTP id 933A437BFE4
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 20 Jul 2000 06:52:31 -0700 (PDT)
	(envelope-from sto@stat.Duke.EDU)
Received: from feta.isds.duke.edu (feta.isds.duke.edu [152.3.22.76])
	by isds.duke.edu (8.8.8/8.8.8) with ESMTP id JAA08374
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 20 Jul 2000 09:52:30 -0400 (EDT)
Received: (from sto@localhost)
	by feta.isds.duke.edu (8.9.3/8.9.3) id JAA68985;
	Thu, 20 Jul 2000 09:52:29 -0400 (EDT)
	(envelope-from sto)
Message-Id: <200007201352.JAA68985@feta.isds.duke.edu>
Date: Thu, 20 Jul 2000 09:52:29 -0400 (EDT)
From: "Sean O'Connell" <sto@stat.Duke.EDU>
Reply-To: sto@stat.Duke.EDU
To: FreeBSD-gnats-submit@freebsd.org
Subject: Add some mention of sound devices in the pcm manpage
X-Send-Pr-Version: 3.2

>Number:         20060
>Category:       docs
>Synopsis:       Add some mention of sound devices in the pcm manpage
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    sheldonh
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 20 07:00:04 PDT 2000
>Closed-Date:    Thu Jul 20 07:20:20 PDT 2000
>Last-Modified:  Thu Jul 20 10:30:01 PDT 2000
>Originator:     Sean O'Connell
>Release:        FreeBSD 4.0-STABLE i386
>Organization:
Institute of Statistics and Decision Sciences
>Environment:

	Both RELENG_4 and -CURRENT.

>Description:

	This is based on a conversation with a frustrated -STABLE user
	who couldn't figure out how to create the requisite devices for
	his sound card (which had kernel support ... device pcm was added
	as per LINT).  He had looked through the manpages and had done 
	some searching through the handbook and FAQ.  There does exist
	an entry in the FAQ (http://www.freebsd.org/FAQ/admin.html#AEN2508),
	but it doesn't hit all the right keywords.  It should contain more
	verbiage (something in reference to sound/pcm/MAKEDEV snd, etc).
	My initial instinct was to say RTFM, but when I went to the manpage
	for pcm, there was no reference to the requirment to do a
	cd /dev; sh MAKEDEV snd0 (for pcm0, snd1 for pcm1, etc).

>How-To-Repeat:

	man 4 pcm and try to find a reference to the relevant device files

>Fix:

	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.  Do other kernel devices make reference to their
	relevant /dev entries ... It might be a nice thing to add.


--- pcm.4.orig	Wed Mar 22 00:12:01 2000
+++ pcm.4	Wed Jul 19 17:54:30 2000
@@ -121,6 +121,24 @@
 
 .It NeoMagic 256AV/ZX (PCI)
 .Pp
+
+.El
+.Pp
+.Sh DEVICE FILES
+
+To create the proper device files for audio support,
+
+.Cd "cd /dev"
+.Cd "sh MAKEDEV snd0"
+
+for soundcards detected as
+.Em pcm0
+(similarly, if the card is detected as
+.Em "pcm1",
+it would require
+.Em "snd1",
+etc.).
+
 .El
 .Pp
 .Sh DIAGNOSTICS AND TROUBLESHOOTING


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->sheldonh 
Responsible-Changed-By: sheldonh 
Responsible-Changed-When: Thu Jul 20 07:10:23 PDT 2000 
Responsible-Changed-Why:  
I'll take this, although I think I'll take a different 
approach. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=20060 
State-Changed-From-To: open->closed 
State-Changed-By: sheldonh 
State-Changed-When: Thu Jul 20 07:20:20 PDT 2000 
State-Changed-Why:  
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. :-) 

http://www.freebsd.org/cgi/query-pr.cgi?pr=20060 

From: Udo Erdelhoff <ue@nathan.ruhr.de>
To: "Sean O'Connell" <sto@stat.Duke.EDU>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/20060: Add some mention of sound devices in the pcm manpage
Date: Thu, 20 Jul 2000 16:56:49 +0200

 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)
 

From: "Sean O'Connell" <sean@stat.Duke.EDU>
To: Udo Erdelhoff <ue@nathan.ruhr.de>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/20060: Add some mention of sound devices in the pcm manpage
Date: Thu, 20 Jul 2000 11:37:59 -0400

 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
 

From: Udo Erdelhoff <ue@nathan.ruhr.de>
To: "Sean O'Connell" <sean@stat.Duke.EDU>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/20060: Add some mention of sound devices in the pcm manpage
Date: Thu, 20 Jul 2000 18:26:19 +0200

 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.
 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: Udo Erdelhoff <ue@nathan.ruhr.de>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/20060: Add some mention of sound devices in the pcm manpage 
Date: Thu, 20 Jul 2000 18:54:27 +0200

 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.
 

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: cg@FreeBSD.org
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/20060: Add some mention of sound devices in the pcm manpage
Date: Thu, 20 Jul 2000 19:20:21 +0200

 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
 
>Unformatted:
