From owner-freebsd-doc Mon Dec 18 17:03:41 1995 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.3/8.7.3) id RAA03111 for doc-outgoing; Mon, 18 Dec 1995 17:03:41 -0800 (PST) Received: from fslg8.fsl.noaa.gov (fslg8.fsl.noaa.gov [137.75.131.171]) by freefall.freebsd.org (8.7.3/8.7.3) with SMTP id RAA03094 for ; Mon, 18 Dec 1995 17:03:30 -0800 (PST) Received: by fslg8.fsl.noaa.gov (5.57/Ultrix3.0-C) id AA25581; Mon, 18 Dec 95 19:03:25 -0600 Received: by emu.fsl.noaa.gov (1.38.193.4/SMI-4.1 (1.38.193.4)) id AA03992; Mon, 18 Dec 1995 18:03:20 -0700 Date: Mon, 18 Dec 1995 18:03:20 -0700 From: kelly@fsl.noaa.gov (Sean Kelly) Message-Id: <9512190103.AA03992@emu.fsl.noaa.gov> To: erich@lodgenet.com Cc: doc@freebsd.org In-Reply-To: <199512081633.KAA18163@jake.lodgenet.com> (erich@lodgenet.com) Subject: Re: new device driver doc Sender: owner-doc@freebsd.org Precedence: bulk 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: The FreeBSD kernel is very well documented, unfortunately it's all in `C'. 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 ... 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 and/or 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: 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 list instead of an unordered 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 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 heading? Alternatively, you could use the 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 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 list would work fine. The same applies to the references. Use a `` References'' heading but list each reference as a list 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