From owner-freebsd-hackers Sun Jan 23 3:55:35 2000 Delivered-To: freebsd-hackers@freebsd.org Received: from smtp01.wxs.nl (smtp01.wxs.nl [195.121.6.61]) by hub.freebsd.org (Postfix) with ESMTP id BBBF414DD7; Sun, 23 Jan 2000 03:55:23 -0800 (PST) (envelope-from asmodai@wxs.nl) Received: from daemon.ninth-circle.org ([195.121.196.211]) by smtp01.wxs.nl (Netscape Messaging Server 3.61) with ESMTP id AAA65F2; Sun, 23 Jan 2000 12:55:01 +0100 Received: (from asmodai@localhost) by daemon.ninth-circle.org (8.9.3/8.9.3) id MAA22582; Sun, 23 Jan 2000 12:54:39 +0100 (CET) (envelope-from asmodai) Date: Sun, 23 Jan 2000 12:54:39 +0100 From: Jeroen Ruigrok/Asmodai To: Bill Maniatty Cc: FreeBSD-doc@FreeBSD.org, maniatty@cs.albany.edu, freebsd-hackers@FreeBSD.org, Greg Lehey Subject: Re: Learning the FreeBSD Kernel Message-ID: <20000123125439.A20851@daemon.ninth-circle.org> References: <200001230406.XAA43423@cs.rpi.edu> <20000123153526.I930@mojave.worldwide.lemis.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0i In-Reply-To: <20000123153526.I930@mojave.worldwide.lemis.com>; from grog@lemis.com on Sun, Jan 23, 2000 at 03:35:26PM +0800 Organisation: Ninth-Circle Enterprises Sender: owner-freebsd-hackers@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG -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 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. 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 >> 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. >> 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. >> 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? Definately not an ethernet card. *g* Seems no-one can keep up with Bill Paul in that aspect. =) You could try usb devices and contact Nick Hibma for his expertise on that area. 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. >> 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. >> 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 -- Jeroen Ruigrok vd W/Asmodai asmodai@[wxs.nl|bart.nl|freebsd.org] Documentation nutter/B-rated Coder BSD: Technical excellence at its best The BSD Programmer's Documentation Project Ain't gonna spend the rest of my Life, quietly fading away... To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-hackers" in the body of the message