Jarommr <jdolecek@netbsd.org> wrote:
[snip]
>The autoconf machinery is quite simple once you figure out the way
>it works.
[sniping a whole lot of useful stuff]


If I may chime in here, the problem that I perceive here is
that autoconf is arguably one of the most esoteric parts of
NetBSD.  This is because it is spread over a utility, the
kernel subroutines, and of course, all sorts of neat drivers.
There is also a very esoteric requirement to support some
configuration environments, the likes of which many of us have
never had to experience (Torek alludes to VAX).

First of all, most of us mortals conceptualize configuration
as a tree such as:

                        root
                          |
                          V
            ----------------------------------
            |                                |
            V                                V
        device A                        device B

In actual fact, what is wanted by the autoconfig cartel is more
like the following:

           root1                          root2
             |                              |
             V                              |
             ---------------------          |
             |                   |          |
             |   ----------------------------
             |   |               |          |
             |   |               -------    |
             |   |                     |    |
             V   V                     V    V
            device A                  device B

In other words, more than one root is possible, and I believe the
data structure is actually a DAG.  This data structure is stored
based on the following assertions:

      "the parents of device A are root1 and root2"
      "the parents of device B are root1 and root2"

Because autoconfiguration (at boot time) proceeds from the root to
the devices, you would think the data structure would reflect:

      "the children of root1 are device A and device B"
      "the children of root2 are device A and device B"

This is a natural, but false, assumption on the part of the code reader.
In other words, to traverse from, say, root1 to its children we must
set up a loop structure such as

       for d of all configured devices in the config-utility-generated data
            for p of all parents of d
                   if p == current node
                          then <whatever>

This is the type of loop that kern/subr_autoconf.c sets up for us
with the config_search et al functions.  If it weren't for the
upside-down data structure, this file might not exist.  But more
importantly, once you understand this data structure, you really do
start to understand all of autoconfig.

I have to wonder why so many of us have had to stubble through learning
how all this works, without even so much as a hint in the source code
that there is something "unexpected" at foot.  By comparison, the weird
happenings in sys/umv and sys/vm are very well explained in the source.

Personally, I think the original statement that "autoconf ... is quite
simple" is absolutely true, but I would add "autoconf ... is under
documented".  Can we fix this?  I don't really know how to effect
such a change, but I would certainly volunteer my verbiage.