Date: Mon, 18 Dec 1995 18:03:20 -0700 From: kelly@fsl.noaa.gov (Sean Kelly) To: erich@lodgenet.com Cc: doc@freebsd.org Subject: Re: new device driver doc Message-ID: <9512190103.AA03992@emu.fsl.noaa.gov> In-Reply-To: <199512081633.KAA18163@jake.lodgenet.com> (erich@lodgenet.com)
next in thread | previous in thread | raw e-mail | index | archive | help
Sorry I took so long! I'm sure you know how it goes.
As author, you have the right to ignore as much of this as you desire:
------------------------------------------------------------------------
Line 28: <it> The FreeBSD kernel is very well documented,
unfortunately it's all in `C'. </it>
I'm not sure what this statement has to do with the rest of the
document ... it seems editorial, and might not add much to the
usefulness of the instruction.
Line 39: source form reside in /usr/src/sys/i386/isa.
Consider putting the pathname in <tt>...</tt> font. Also, not all the
device drivers are in this subdirectory, right?
Line 40: NetBSD uses something like sys/arch/dev for drivers.
Big deal. This should be an instructional FreeBSD-related document;
I'd just remove this sentence.
Line 42: FreeBSD currently has support for several bus architectures.
Reword to introduce the list: ``... for the following bus
architectures:''
Line 51: In FreeBSD, support for the isa and eisa busses is i386 specific.
Insert hyphen: i386-specific.
Line 57: /usr/src/sys/{pci,pccard,scsi}. The i386 specific code for these
Insert hyphen: i386-specific.
Line 61: no ``official'' place for binary drivers to reside. BSD/OS uses
Again, what BSD/OS uses isn't of concern for this document. Perhaps
we should standardize on a location soon so we can document it.
Line 67: [filenames]
Consider using <tt> and/or <it> to show that these are filenames and
to show the variable parts of each.
Line 73: compiled and dumped into a header file ala file2c(1).
Replace `ala' with `using a utility like'.
Line 91: the lkm model. The first method is fairly standard across
lkm is an acronym, so make it all-caps everywhere it appears. Also,
spell it out just the first time: ``... the Loadable Kernel Module
(LKM) model.''
Line 91: The first method is fairly standard across the *BSD family.
Nay, across most all UNIXes, eh?
Line 94: I don't believe that the current implementation uses any Sun code.
Not important to audience, so consider removing it.
Line 96: <sect1>Standard Device Driver
The previous paragraph introduced two models: the static model and the
LKM model. Which is the standard model? You could say so in the
previous paragraph or reword this section title by saying something
like ``Standard (Static) Device Driver.''
Line 99: The steps required to add your driver to the standard ...
Since the steps that follow should be done (more or less) in order,
use a <enum> list instead of an unordered <itemize> list.
Line 113: dependant on the cpu ... If the device is not i386 specific
Spelling: dependent. Hypne: i386-specific
Line 123: something like ``i386/OBJ/joy.o''.
Consider <tt> font for pathnames. Also applies to lines 132, 135,
136, 140, and 161.
Line 125: Some devices are required for the kernel to even be built.
A bit clumsy; try: ``Though many devices are listed as optional, they
are required to build a working kernel.''
Line 191: there will always be an entry for your driver, either null entry
Introduce the alternatives with a colon: ``... for you driver: either
...''
Line 246: Minor number is driver dependant, of course. You can
Hyphen & spelling: driver-dependent.
Line 266: the lkm specific
Hyphen & caps: ``the LKM-specific.'' Line 270 as well.
Line 278: Lines 17 - 26
Why not make this a <sect3> heading? Alternatively, you could use the
<descrip> list mechanism.
Line 281: whether or not we have a pcaudio device defined. This
``or not'' is implicit from ``whether'' so you could delete it.
Line 525: Note: this has gone through <em/many/ revisions from
Until we get a standard ``note'' style in our DTD, I might suggest
putting the word <em/Note:/ in emphasis like that, as a typographic
aid to the reader.
Line 545:
There should always be some text after each heading, even if it's just
introductory. Try to be as nontrivial as you can. For example:
``<p>This section describes the entry points you'll use while
developing your driver. FreeBSD provides these functions and uses
these structures to communicate information to and from your device.''
I'm not suggesting you use exactly that, just something like it.
The same applies to line 1034.
Also, in this section beginning around line 1034, having a separate
heading for these functions is probably overkill. Another <descrip>
list would work fine.
The same applies to the references. Use a ``<sect> References''
heading but list each reference as a <descrip> list <tag> item.
------------------------------------------------------------------------
--
Sean Kelly
NOAA Forecast Systems Laboratory, Boulder Colorado USA
In weight lifting, I don't think sudden, uncontrolled urination should
automatically disqualify you. -- Jack Handey
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?9512190103.AA03992>