Date: Sun, 23 Jan 2000 11:48:39 -0500 From: Bill Maniatty <maniattb@cs.rpi.edu> To: Jeroen Ruigrok/Asmodai <asmodai@wxs.nl> Cc: Bill Maniatty <maniattb@cs.rpi.edu>, FreeBSD-doc@FreeBSD.ORG, maniatty@cs.albany.edu, freebsd-hackers@FreeBSD.ORG, Greg Lehey <grog@lemis.com>, maniattb@cs.rpi.edu Subject: Re: Learning the FreeBSD Kernel Message-ID: <200001231648.LAA53658@cs.rpi.edu> In-Reply-To: Your message of "Sun, 23 Jan 2000 12:54:39 %2B0100." <20000123125439.A20851@daemon.ninth-circle.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Hello Jeroen: Jeroen Ruigrok (in response to Greg Lehey and myself): > -On [20000123 11:11], Greg Lehey (grog@lemis.com) wrote: > >[adding -doc, which is more appropriate for some of the questions] > > > >On Saturday, 22 January 2000 at 23:06:41 -0500, Bill Maniatty wrote: > > >> I have a student this semester in my Operating Systems class who would like > >> to become a bit more knowledgeable about systems software. I suggested > >> that he learn a bit about how device drivers are written in FreeBSD > >> as a minor project. My questions are: > >> > >> 1) Does any current documentation of how to write and/or install a > >> device driver exist in English (note C != English)? > > > >Yes, with reservations. > > Big reservations. The main question is, are you going to use the > default (old) style of Unix drivers (based on character and block > devices with their appropriate cdevsw and bdevsw), or are you willing to > have the student participate in the new style busspace/newbus system > which is present in CURRENT (soon to be released 4.0)? > > >> We would love to have a level of documentation like the document by > >> Pragmatic at http://thc.pimmel.com/files/thc/bsdkern.html, we are > >> looking for a how to guide. > > > >Somewhere we have a tutorial. I think it's been retired because it's > >out of date, but it could be a very rewarding starting point for > >somebody who wanted to work his way into the material and either > >update it or bring out a new document based on the structure. This > >would also give the student good visibility in the (Free)BSD > >community. > > The Device Driver Writers Guide (DDWG) was retired because the contents > were too old to apply to modern day FreeBSD. The document that I seem to remember FreeBSD having on line at one point had problems in my eyes: 1) It was too preliminary IMHO, the person who started it did not give enough detail to first time driver writers. 2) As you mentioned it became obsolete. 3) It was meant as a reference, not as a tutorial. Again I think Pragmatic's documentation exemplifies the style I am looking for, I want people to have an exercise to learn stepwise how to build a driver (my goal is to cultivate local expertise first). Actually the lack a reference or tutorial document is kind of damning in a way, since it gives hardware vendors a powerful excuse not to support FreeBSD in the way that say Lin*x is supported. > I am getting more and more > progress to get the relevant background information to: > > a) write the busspace and newbus manpages > b) write a new DDWG which will include migration paths for old > drivers to the new style These are good things. > >> 2) If no existing documentation exists, would it be a good idea to > >> put together a sort of how to guide for a simple driver (with an > >> eye to generalization later if warranted)? > > Heh, I am working on that, except things keep interrupting my work. > > I was thinking of making a small document for the time being which gives > some general clue to the community for the new type drivers, or at least > summarises what has changed. In /usr/src/sys/pci there is meteor.c > which still uses some old style driver code. You can compare that to > most of the if_XYZ.c files by Bill Paul which make extensive use of the > new system. Or take a look at Matthew N. Dodd's files and see even more > examples. If you have something for us to look at we would appreciate it, otherwise we may wind up rolling our own (in which event we would keep you informed). > >> 3) If the answer to 2 is yes, can we get constructive help from the FreeBSD > >> community? > > > >Definitely. -hackers would be the right forum there. I would also > >personally commit to helping within the constraints of my other work. > > I'll second Greg here. I am here to write the documentation for this > subject (on voluntarily basis of course) and I think that questions > coming from your student, or from others for that matter, will make sure > I keep on top of things and document them. Aside from -hackers, you > might want to consider -newbus, which is the forum to discuss newbus in > depth. Thanks, will do. > >> Assuming that this constitutes an interesting project, what would be > >> a good initial approach? I was considering: > >> 1) Get and build the FreeBSD kernel (4.0?) > > Please use this yes. 4.0 has IMHO better bus architecture code to look > into for writing drivers. > > >> 2) Choose a non-essential device with a simple preexisting driver. > >> 3) Remove all trace of the driver from the kernel source. > >> 4) Reapply the changes used to install the driver (perhaps one step at a time). > >> We could suggest some simple sanity checks to support stepwise refinement. > > > >(1) and (2) are a good start. You don't need to remove the old > >driver; it would in fact make it easier for debugging purposes if it > >remained. Instead, choose another major number and name, and write a > >new driver. This procedure is definitely *not* documented, but it's > >the way we introduce new drivers, and I think a couple of other people > >who have done it would be pleased to help. > > *nod* There are certainly people who are be able and willing to help. > > >A possibly better alternative is to find a device which isn't > >currently supported by FreeBSD and write a driver for it. This would > >have the advantage that the work would also be a contribution to > >FreeBSD. The question that I can't answer here is: what would be an > >appropriate device? First we want to get the mechanism of driver installation down, then try our hands at writing our own driver. I fear that if we roll our own driver software we may find that if we have errors (not that we ever have errors mind you :-) we may not be able to isolate the cause. This is why I was leaning towards reinstalling a working driver first. > Definately not an ethernet card. *g* > Seems no-one can keep up with Bill Paul in that aspect. =) We probably could not compete :-), but we are interested in ethernet card drivers (at some point) and would like to learn. > You could try usb devices and contact Nick Hibma for his expertise on > that area. How mature is the USB driver technology? If it is pretty preliminary we may wish to visit that later. Please recall that we are on a learning curve here. > Also make sure the vendor is not problematic with handing out > documentation. Intel and Motorola are good examples of companies who > have pdf's available for download. Very good idea. > >> If this is a good idea, I would like the following help from the FreeBSD > >> community: > >> 1) Identify a simple driver (perhaps something like a joystick > >> driver?) > > > >I don't know if anybody uses it any more. > > The driver database (URL doesn't come to mind, it's on the freebsd.org > site under project IIRC) has an entry from someone working on getting > the joystick device to work under 4.0 and being compatible with the > Linux one. Thanks, I only suggested the joystick driver because I thought it would be one of the least difficult drivers (and perhaps easy to test). > >> 2) Identify all source code associated with the driver (including configuration > >> files, makefiles etc...). Some files may have only one or two lines > >> devoted to the driver, so we will need to know how to recognize such lines > >> and would appreciate pointers to such lines. > > > >That should be relatively straightforward after examination of the old > >tutorial, the sources and hier(7). If not, ask away. Important > >directories are: > > > > /sys symlink to /usr/src/sys; I'll use it below > > /sys/config generic configuration files > > /sys/i386/config configuration files for i386 > > /sys/dev sources for generic device drivers > > /sys/isa sources for generic ISA device drivers > > /sys/i386/isa sources for i386-only ISA device drivers > > Of course, in addition: > > /sys/pci > > Noteworthy header files: > > /usr/include/machine/bus.h > /usr/include/machine/bus_memio.h > /usr/include/machine/bus_pio.h > /usr/include/machine/resource.h > /usr/include/sys/bus.h > /usr/include/sys/rman.h > /sys/kern/subr_bus.c Thanks for your help Jeroen (and Greg), this kind of input is very constructive. Regards; Bill Maniatty To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200001231648.LAA53658>