Contributing to FreeBSD documentation (was: Re: no ath0 on newsystem with good card)

Ted Mittelstaedt tedm at toybox.placo.com
Tue Jan 9 06:52:20 UTC 2007


----- Original Message ----- 
From: "Giorgos Keramidas" <keramida at ceid.upatras.gr>
To: "Steve Franks" <stevefranks at ieee.org>
Cc: <freebsd-questions at freebsd.org>
Sent: Sunday, January 07, 2007 8:25 AM
Subject: Contributing to FreeBSD documentation (was: Re: no ath0 on
newsystem with good card)


> On 2007-01-07 08:54, Steve Franks <stevefranks at ieee.org> wrote:
> > Apologies on not hitting the list.  Alyays forget to reply-all.
>
> No problem.  I just didn't copy the list because I wasn't sure I should.
>
> > So, I figured I'd try to fix the safe-mode end of things on my own,
> > and I found a post several years old (looked like it even could have
> > been yours) about safemode, which doesn't show up anywhere on the
> > freebsd site.  So I did what it said and grep'd boot/beastie.4th for
> > safemode, which came up with this suprisingly total solution:
> >
> > add apic.0.disabled="1" to boot/device.hints.  Not only does my system
> > come up in regular boot mode, but, as you suspected, the pccard works
> > too, so all appears well.
>
> Excellent news!   Thanks for sharing the answer :)
>
> > So my final question, what in all the land is an "apic",
>
> "Advanced Programmable Interrupt Controller".  This is the part of your
> system which assigns priorities to interrupt lines of a device.  The
> full details are probably too technical for some percentage of our user
> base, but more details can be found at the following pages:
>
>   http://en.wikipedia.org/wiki/Advanced_Programmable_Interrupt_Controller
>   http://en.wikipedia.org/wiki/Programmable_Interrupt_Controller
>   http://en.wikipedia.org/wiki/Intel_8259
>   http://en.wikipedia.org/wiki/Intel_APIC_Architecture
>
> > and why isn't apic or safemode mentioned in the handbook, manpages, or
> > even on the freebsd site?
>
> IIRC it is mentioned in the Developer's Handbook, but you are right that
> it should be in the main Handbook too.
>
> > Further, I'd like to write a handbook page on "freebsd and laptops",
> > because we're on my third one here now, and I'm starting to get the
> > drift of what could usefully be added to the handbook, namely a
> > thourough discussion of booting and device.hints.
>
> That would be great!  If you can help writing such a section for the
> Handbook, a lot of users will be highly indebted to you, for sure :)
>

I'll throw my $0.02 in here on this.

Years ago on the CD distributions there was a file in the root of the distro
labeled "hints" or some such.  It was also on the website.  It contained all
the little workarounds for SPECIFIC pieces of hardware.  I know as I wrote
several entries for it.  That apic problem was listed in there as were
several
others, I know some for laptops specifically.

Sometime during the FreeBSD 4.X series one of the developers got a bug
up their ass that somehow this was the wrong place for problems to be
listed.  Something along the lines of these problems aren't FreeBSD problems
they are sucky hardware problems and it makes FreeBSD look bad to have
the workarounds even listed at all, and we have the bug database and these
icky ugly things really ought to go into the bug database.  So this file
disappeared.
As did every other easily recognizable place for submitting hints.  As did
the
specific e-mail address for hints to go to.

These installation problems IMHO  PROPERLY belong in the README for the
distribution.  That is the FIRST place that someone BRAND NEW to FreeBSD
is going to look for them.  No FreeBSD newbie who has oddball hardware
that has bugs in it, is going to take the time spending hours reading the
Handbook
or searching the questions mailing list archives for tidbits, or querying
the bug
database for PR's for their gear.  Any newbie to FreeBSD
is going to do the same thing that they do to any other OS, they are going
to stick
the CD in their oddball hardware and boot it, and if it doesen't come up
they
will look at the README file that came with the ISO image they downloaded,
and if the hardware-specific workarounds for their machine aren't there,
they will
discard the ISO cd and move on to some other Open Source OS.

For all the huffing-and-puffing on peer-review for the Handbook, well
that is fine for that.  But an install hints file's very usefulness is junk
if a
committee is reviewing it.

Hardware-specific install hints are, by their very nature, NOT guarenteed
to work.  They may even make things worse.  All they are is user-developed
workarounds that may or may not be The FreeBSD Way of doing things.
The only thing that can be said about them is that at one time, one year,
with
one particular piece of gear, someone tried some off-the-wall thing and
it worked.  It might not ever work again in any future version of FreeBSD.
There might be manufacture-specific BIOS updates that fix things.  There
might be a driver update in a later FreeBSD version that fixed that specific
thing. But, it is a last-ditch suggestion to try when the 'normal' way of
installing
something doesen't work.

I don't see much support for recreating the install hints file, so I really
feel little incentive to contribute workarounds at this point, even though I
have a whole collection of them for the specific systems I've installed
FreeBSD
on over the years.  Submitting them to the PR database is worse then
useless,
because they invariably involve 2-3 year old hardware (or older) and the
developers have ZERO incentive to work on them.  So the PR's just get
stale and then do-gooders come along 2-3 years later asking the original
poster to verify if the problem still exists in current FreeBSD, and when
the OP says how the hell do I know, they get closed.

Sure, it might look strange to have a hint about installing on an old HP
Netserver to make an EISA change, in this day and age, in an install hints
file.  But, goddammit, where the hell else are you going to see that?  And
you just know that somewhere, there's some young pup that has dragged
one of those out of a Dumpster somewhere and is going to try loading FreeBSD
on it.

Ted



More information about the freebsd-questions mailing list