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

Steve Franks stevefranks at
Tue Jan 16 22:47:52 UTC 2007

On 1/7/07, Giorgos Keramidas <keramida at> wrote:
> 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 presume someone 'peer-reviews' handbook submissions for correctness
> > and format?  I recall reading somewhere about contributing, but I get
> > the impression you are involved enough to tell me whether it's a bad
> > idea or not.
> Yes, you are right.  We have peer reviews.  A lot of the documentation
> changes are filtered through the freebsd-doc mailing list, where
> documentation people hang out.  Patches are mailed back and forth;
> edited; fixed for technical accuracy, syntax and grammar correctness;
> adapted to our writing style; expanded as necessary; and eventually
> committed to our documentation source code.
> You can definitely contribute as much as you feel, whenever you feel you
> have the time, and in any way you consider appropriate.  We have a short
> article which describes how you can contribute to the FreeBSD Project,
> in general:
> Most of it applies directly to documentation too.  Please skim through
> this article; it should be a good start.
> About your last question now...
> Yes, it's a good idea.  Not just a good idea, though.  It's an
> *excellent* idea.
> One of the "chicken and egg" problems documentation writing usually has
> to face is that:
>   * New users don't know enough about the system, so they frequently
>     pose good questions.  These questions would result in higher quality
>     documentation if properly channeled through experienced
>     documentation writers, but you have to convince the new users that
>     they can actually *help* by not knowing it all.
>   * Once new users step over the thin line between being newcomers to
>     the system and being experienced in some area, we have lost all the
>     "insight" they can provide about how a new user thinks.
> As a result, it's easier to write documentation if we are targetting a
> very experienced, very technical audience.  But, IMHO, the contributions
> of new users -- in the form of "interesting" questions" -- are at least
> as valuable, if not more :)
> Regards,
> Giorgos
So, this is what I have so for.  It was a bit late at night, so I appologise
if my tone is a bit silly at times...where do we go from here?  Steve

So, you've burned the latest FreeBSD .iso file, pop it in your drive,
anticipation rising, and *freeze*!!

Hopes & Dreams go tricking away...what next?

Well, the first thing is to realize that alot of people
have worked very hard in their spare time to get things
to the point where they are.  Unfortunately, new hardware
is always one step ahead.  All FreeBSD drivers are written
by the users - not the paid engineers of the hardware
companies, so some delay at times is inevitable - there are
many exceptions, however!  Just compare the sata & raid support in
FreeBSD to that in Windows XP.

But back to moving forward: one of those new or imcompatible
pieces of hardware (in most cases) has just frozen up your
fresh install - what to do?

First, restart the computer, and choose "3 - safe mode" from
the "FreeBSD" logo boot-menu.  If your computer still
will not reach the installation screen, you can still
send email to questions at

In most cases you are now at the install screen.  Proceed
to install FreeBSD as per the instructions in the handbook.
Remove the cdrom, reboot, and again choose safe mode to avoid a freeze

Now you have some sleuthing to do.  First, you may look
at the safe-mode section of boot/beastie.4th.  You'll see
it does very few opertations.  These have far-reaching
implicatoins however (insert explanation of how safemode
disables serial ports and other nasty drivers, because I
have no idea - appears to me it only disables apic, acpi,
and dma).

To make your system boot normally, you have to determine
the source of the freeze, and disable the offending driver.
First, if you have read the acpi section of the handbook, you
may suspect acpi.  It is frequently not the culprit, as
the handbook would have you believe, but
may be a safe starting point in any event.

A word of caution at this point: You want to disable the minumum
number of drivers to yield a usable system, and leave
as much hardware in a funtional point as possible.  As
any good scientist will tell you, though it may become
tedious quite quickly, only change one item at a time -
this is the only way to avoid ambiguity about what
is your real solution.

The primary (and non-destructive) method of disabling drivers
in FreeBSD is to edit /boot/device.hints
To disable an item, add a line,
Don't forget the "."! Many other FreeBSD configuration files
(i.e. rc.conf) use a "<device>0" nomenclature, and once
you become used to it, you may forget the dot.

Things to try disabling:
    first, any hardware you know you don't have: such
    as usb(ohci, ehci) on older systems, floppies and ports on newer
    systems, pcmcia on desktops, etc.
    sio.0 and sio.1 are the first two serial ports
    ppc.0 is the paralell port
    apic.0, the advanced programmable interrupt controller

Things *not* to disable in any event:

    sc.0: this is the system console, otherwise known
    as the main user interface.  Disabling this will
    force you to do a picky login, without the help of
    man pages to remember syntax, and it may be easier to
    simply reinstall on a fresh system!

You may also want to try physically
removing hardware, one piece at a time, to see if this
yields a working system.  Things to try are:
    anything usb
    pcmcia and flash cards
    network cards
    special funtion boards, such as video capture or data
acquisition/engineering boards
    extra harddisks & cdroms

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

More information about the freebsd-questions mailing list