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

Steve Franks stevefranks at
Tue Jan 9 20:27:33 UTC 2007

Yes, and in today's world, it is likely to be some young sub-saharan african
pup who can't just go down to the local retailer and drop $400 on a new
system if his won't install...


On 1/8/07, Ted Mittelstaedt <tedm at> wrote:
> ----- Original Message -----
> From: "Giorgos Keramidas" <keramida at>
> To: "Steve Franks" <stevefranks at>
> Cc: <freebsd-questions at>
> 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> 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:
> >
> >
> >
> >
> >
> >
> > > 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
> _______________________________________________
> freebsd-questions at mailing list
> To unsubscribe, send any mail to "
> freebsd-questions-unsubscribe at"

Steve Franks, KE7BTE
Staff Engineer
La Palma Devices, LLC
(520) 312-0089

More information about the freebsd-questions mailing list