[ Sent to -doc, for info, -current for some expert advice on the feasability
of this approach with FreeBSD's migration to a kernel consisting only of
aggregated devices. ]
We have a problem with keeping our documentation up to date. One of the
most glaring examples of this is the hardware compatability list. We
currently list hardware information in LINT, HARDWARE.TXT, the FAQ, and the
Handbook. Any time this information changes it has to be updated in all
these places (and possibly more). This does not always happen.
I'm thinking of abstracting out our list of supported hardware in to one
file, marked up according to an XML DTD. Something like
[...]
<device>
<class>keyboard controller</class>
<config>device atkbdc0 at isa? port IO_KBD</config>
<comment>The keyboard controller; it controls the keyboard and the PS/2
mouse.</comment>
</device>
<device>
<class>keyboard</class>
<config>device atkbd0 at atkbdc? irq 1</config>
<comment>The AT keyboard</command>
<options>
<option>ATKBD_DFLT_KEYMAP</option>
<comment>Specify the built-in keymap</comment>
<option>KBD_DISABLE_KEYMAP_LOAD</option>
<comment>Refuse to load a keymap</comment>
<option>KBD_INSTALL_CDEV</option>
<comment>Install a CDEV entry in /dev</comment>
</options>
<flags>
<flag>0x01</flag>
<comment>Force detection of keyboard, else we always assume a
keyboard</comment>
<flag>0x02</flag>
<comment>Don't reset keyboard, useful for some new ThinkPads</comment>
<flag>0x04</flag>
<comment>Old-style (XT) keyboard support, useful for older
ThinkPads</comment>
</flags>
</device>
[ That schema is not set in stone, and certainly requires more work. In
particular, we probably need "lang" and "encoding" options on the
<comment> element, to support comments in more than one language. ]
LINT would then become a skeletal file for things which don't fit this
sort of pattern, and the full LINT would be generated by a script which
parsed the above and the skeletal file to generate the full LINT.
Another script would parse the above and generate HARDWARE.TXT. And another
could parse the above and spit out DocBook for the Handbook and FAQ.
Still another (CGI) script could sit on the website. I'm enamoured of
BSDi's hardware selection CGI script on their website. You can choose from
a drop down list of supported hardware and/or manufacturers, or do a free
text search, and get back a formatted list of all the matching hardware,
entries for the kernel config file, links back to the manufacturer's website
where necessary, and comments about the suitability or otherwise of specific
hardware for specific tasks.
We could do something similar today without the above, XML stuff, but it
would require duplicating the hardware list in yet another place, which
would be a bad thing.
The solution I'm proposing would keep all the hardware information in one
place, where it would be the driver developer's responsibility to maintain.
What I don't know is how this scheme fits in with FreeBSD's future
direction. From scanning -current I know that the aim is to have a kernel
with very few devices compiled in to it -- devices will be probed once, and
if the probe runs true the rest of the device driver will be loaded in. In
particular, the phrase "config(8) must die" is bandied about with increasing
frequency.
I assume, however, that there will still be a place for a statically
compiled and configured FreeBSD kernel -- embedded devices, or where you
don't want the kernel to load certain devices, or whatever.
Can -current provide -doc with a roadmap of where we're heading in this
respect, and how a scheme like the above should fit in.
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
To Unsubscribe: send mail to [EMAIL PROTECTED]
with "unsubscribe freebsd-current" in the body of the message
