Recipie for CPU souffle'

[Ronald F. Guilmette]

In message <20130402231522.71cb7352.freebsd at edvax.de>, 
Polytropon <freebsd at edvax.de> wrote:

>> First order question:  Why is it that in FreeBSD there are so many man
>> pages like this one, _purporting_ to describe some low level interface
>> to some sort of hardware, and the man page _doesn't_ include a clear
>> and explicit description of the relevant ioctls ?
>
>Discovering those usually involved using the driver sources.

Like I said, that was *not* true back in the old days.

Somewhere along the line, somebody decided to get lazy when it came to
writing man pages for device files.

Here is a good example that is not even that old:

http://linux.die.net/man/4/tty_ioctl

(Of course, all of this information _should_ be in the tty(4) man page
itself... NOT in a separate man page.)

Here are two even better examples:

http://www.s-gms.ms.edus.si/cgi-bin/man-cgi?uscsi+7I
http://www.manpages.info/sunos/fdio.7.html

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.

>The driver description provided in the manpage doesn't cover
>everything,

It doesn't have to cover "everything".  But it _should_ completely describe
the programatic interface.

I mean seriously, imagine if the man page for (for example) sem_init(3)
failed to clearly specific the programatic interfece (aka the "C language
binding").  You would think that is was ridiculous if everybody who just
wanted to write some code to use sem_init was forced to go grunging around
in the kernel sources, just to find out the proper way to call this
premitice function.

>but it says: "definitions for the ioctl(2)
>interface are in <dev/speaker/speaker.h>".

See above.  One should not have to look beyond the (properly written) man
page just in order to write some client code.

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

>> 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.

>However, try this example (cw.sh):
>
>#!/bin/sh
>
>read -p "CW ===> " TEXT
>echo ${TEXT} | morse | awk '{
>	if(length($0) == 0)
>		printf("P4\n");
>	else {
>		gsub(" dit", "P32L32E", $0);
>		gsub(" di",  "P32L32E", $0);
>		gsub(" dah", "P32L8E",  $0);
>		printf("%sP16\n", $0);
>	}
>}' | dd bs=256 of=/dev/speaker > /dev/null 2>&1

Ummm....

% /tmp/beeps.sh
CW ===> xxxxx
/tmp/beeps.sh: morse: not found

>But probably not required, because the simplest test you could
>construct is something like
>
>	% echo "c" > /dev/speaker

Humm... now _that_ is both interesting and enlightening.

Thank you.

>Can you hear a sound?

Yes.

>> 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.
>> :-(
>
>Is it really that bad already?

Haven't you noticed?

Jeezzze.  Go to Google News and search for the word "copyright" and look
at how many stories there are in the news JUST TODAY about various
copyright lawsuits.

There is one about an attorney named "John Steele, Who Has Sued More Than
20,000 People".

There is another one about (the artist formerly known as) Prince.

There is another one about Angelina Jolie.

There is another one about St. Louis University... which is apparently
threatening its own faculty with copyright suits.

Oh yea, and another one about an ongoing battle between Viacom and YouTube.

And another story about textbook rentals in the Sydney Morning Herald.

In the future, there will be no more engineers... only lawyers.