Recipie for CPU souffle'

[Ian Smith]

In freebsd-questions Digest, Vol 461, Issue 6, Message: 1
(sorry about the threading)
On Wed, 3 Apr 2013 15:12:17 +0200 Polytropon <freebsd at edvax.de> wrote:
 > On Tue, 02 Apr 2013 19:10:59 -0700, Ronald F. Guilmette wrote:
 > > See how the entire ioctl() interface for these device types is completely
 > > documented IN THE MAN PAGE?  That's the way it should be... None of this
 > > rooting around in the sources for something that should have been documented
 > > properly, external to the kernel sources.
 > 
 > I agree that especially to developers, that sounds logical
 > and very helpful. Seems that manpages do not aim for that
 > goal anymore...

Well I can't help but feel this is being taken a tad more seriously than 
speaker(4) deserves - but it was first committed to FreeBSD 1.0 in '93, 
19 years and 9 months ago in what is now SVN revision 4 (!), originally 
written by Eric Raymond in '90 then modified by ache(@) from "386bsd 
only clean version, all SYSV stuff removed", suggesting more ancient 
origins.  So I'm not sure this doesn't rather predate 'anymore' :)

One's referred to the source in /sys/dev/speaker/speaker.h (a few lines) 
and it's not a long jump to peek at /sys/dev/speaker/spkr.c

http://svnweb.freebsd.org/base/head/sys/dev/speaker/spkr.c?annotate=4

This original one is easier to follow at the bare metal level, with 
direct inb() and outb() to the PIT (i8254) timer #2, functions later 
moved into clock.c, making one have to refer to all of 4 source files 
for the 'machine independent' modern version, though I wonder if anyone 
not on x86/pc98 is/was actually using spkr(4)?

With r177648 5 years ago, phk@ said "If somebody cleaned this code up to 
proper style(9), it could become a great educational starting point for 
aspiring kernel hackers."  2 months later: "Move speaker a lot closer to 
style(9)".  It was one of the first devices I could follow, at any rate.

 > > It doesn't have to cover "everything".  But it _should_ completely describe
 > > the programatic interface.
 > 
 > At least is leaves questions, like stating "use the syscalls
 > in order to...", and the reader is left with the most obvious
 > question: _which_ syscalls?

Sometimes examples are the best teachers.  spkrtest(8) is just a sh 
script that writes to the device.  For more sophisticated use (!) spkr.c 
is overcommented, if anything, and it's only ~550 well-spaced lines.

 > > But like I said, somewher along the line, a lot of man page writers
 > > apparently got lazy... VERY lazy.

Mmm, and a few man page readers too?  It's really not rocket science ..

 > But keep in mind they're still alive! Judging from the manpages
 > of... *cough* can I say this? YOu know, more prominent open
 > source operating systems for desktops... they're usually much
 > worse _if_ there is a manpage. In most cases, there's none.

True.  And I can usually get little more sense out of info(1) than from 
windows 'troubleshooter' :)

 > > >> Second order question:  Why can't I just pipe a .wav file to the
 > > >> /dev/speaker device file and have it play?  Wouldn't that make quite
 > > >> a lot of sense?
 > > >
 > > >No, that does not work.
 > > 
 > > Apparently not.
 > > 
 > > Why it doesn't work (or couldn't work) is less clear.
 > 
 > The speaker interface to the _PC speaker_ is not a DSP. It's
 > programming is much simpler. The "note language" that it
 > uses on FreeBSD is much more than other interfaces offer.
 > Better ones have stuff like pitch, duration, turn off.

Not to mention staccato, legato, dotted notes - sophisticated stuff!

[..]

 > > >	% echo "c" > /dev/speaker
 > > 
 > > Humm... now _that_ is both interesting and enlightening.
 > 
 > I actually remember having used something comparable on
 > BASIC, when my brain wasn't fully developed yet. :-)

The note language is _from_ BASIC .. do read the source, Luke(s)!

 > 	echo "cdefgab>c" > /dev/speaker
 > 
 > It's still a nice interface to "generate attention sounds"
 > in case you want to make an audible alarm or signal for
 > some specific action, like a program which has aborted,
 > an unverified backup or the successful completition of
 > a task.

Indeed it is.  On an old laptop using APM I used to play little tunes as 
the battery got down to 30, 20, 10%, noiser just before forced suspend,
which saved me not a few times.  A nice little chirp when fully charged.

[..]

 > > >> I wonder if whoever write and distributed this realized that he/she could
 > > >> be sued for copyright infringement for about 5 of the simple tunes that are
 > > >> embedded in that thing.  Sad but true.
 > > >> :-(

I hope noone's losing too much sleep, after ~20 uneventful years :)

cheers, Ian