From owner-freebsd-doc Tue May 28 15:09:55 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id PAA05918 for doc-outgoing; Tue, 28 May 1996 15:09:55 -0700 (PDT) Received: from who.cdrom.com (who.cdrom.com [204.216.27.3]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id PAA05892 for ; Tue, 28 May 1996 15:09:49 -0700 (PDT) Received: from relay-2.mail.demon.net (disperse.demon.co.uk [158.152.1.77]) by who.cdrom.com (8.6.12/8.6.11) with SMTP id KAA06978 for ; Tue, 28 May 1996 10:56:57 -0700 Received: from post.demon.co.uk ([158.152.1.72]) by relay-2.mail.demon.net id ab27817; 28 May 96 18:34 +0100 Received: from jraynard.demon.co.uk ([158.152.42.77]) by relay-3.mail.demon.net id aa03998; 28 May 96 18:32 +0100 Received: (from fdocs@localhost) by jraynard.demon.co.uk (8.7.5/8.6.12) id RAA09291; Tue, 28 May 1996 17:37:25 GMT Date: Tue, 28 May 1996 17:37:25 GMT Message-Id: <199605281737.RAA09291@jraynard.demon.co.uk> From: James Raynard To: jfieber@indiana.edu CC: doc@freebsd.org In-reply-to: (message from John Fieber on Mon, 27 May 1996 10:12:13 -0500 (EST)) Subject: Re: tutorial device witers guide Sender: owner-doc@freebsd.org X-Loop: FreeBSD.org Precedence: bulk > http://www.freebsd.org/tutorials/ddwg/ddwg.sgml Here's a diff which corrects a number of typos in this document, as well as inserting a few "pauses for breath" where appropriate. One thing I left out, as it's really a matter of style, but shouldn't acronyms, such as ide and scsi, be capitalised? *** ddwg.sgml.orig Tue May 28 16:34:58 1996 --- ddwg.sgml Tue May 28 17:18:55 1996 *************** *** 113,119 **** XXioctl()

! It's argument list is as follows: int XXioctl(dev_t dev, int cmd, caddr_t arg, int flag, struct proc *p) --- 113,119 ---- XXioctl()

! Its argument list is as follows: int XXioctl(dev_t dev, int cmd, caddr_t arg, int flag, struct proc *p) *************** *** 136,148 **** Header Files --- 163,169 ---- io. It is most common in a block device. This is significantly different than the System V model, where only the block driver performs scatter-gather io. Under BSD, character devices are sometimes requested to perform ! scatter-gather io via the readv() and writev() system calls. Header Files *************** *** 279,289 **** This is the structure used by the probe/attach code to detect and ! initialize your device. The This is the structure used by the probe/attach code to detect and ! initialize your device. The XXprobe()

XXprobe() takes a XXattach() --- 297,307 ---- XXprobe()

XXprobe() takes a XXattach() *************** *** 333,339 **** Header Files ! PCI -- Peripheral Computer Interconect Data Structures

Header Files ! PCI -- Peripheral Computer Interconnect Data Structures

A typical driver has the source code in one c-file, say dev.c. The ! driver also can have some include files devreg.h contains device public device register declarations, macros, and other driver specific declarations. Some drivers call this devvar.h instead. Some drivers, such as the dgb (for the Digiboard PC/Xe), --- 419,425 ----

A typical driver has the source code in one c-file, say dev.c. The ! driver also can have some include files; devreg.h contains public device register declarations, macros, and other driver specific declarations. Some drivers call this devvar.h instead. Some drivers, such as the dgb (for the Digiboard PC/Xe), *************** *** 467,473 ****

The standard model for adding a device driver to the Berkeley kernel is to add your driver to the list of known devices. This list is ! dependant on the cpu architecture. If the device is not i386 specific (pccard, pci, scsi), the file is in ``/usr/src/sys/conf/files''. If the device is i386 specific, use ``/usr/src/sys/i386/conf/files.i386''. A typical line looks like: --- 467,473 ----

The standard model for adding a device driver to the Berkeley kernel is to add your driver to the list of known devices. This list is ! dependent on the cpu architecture. If the device is not i386 specific (pccard, pci, scsi), the file is in ``/usr/src/sys/conf/files''. If the device is i386 specific, use ``/usr/src/sys/i386/conf/files.i386''. A typical line looks like: *************** *** 494,501 **** Make room in conf.c

! Now you must edit ``/usr/src/sys/i386/i386/conf.c`` to make an entry ! for your driver. Somewhere near the top, you need to delcare your entry points. The entry for the joystick driver is: #include "joy.h" --- 494,501 ---- Make room in conf.c

! Now you must edit ``/usr/src/sys/i386/i386/conf.c'' to make an entry ! for your driver. Somewhere near the top, you need to declare your entry points. The entry for the joystick driver is: #include "joy.h" *************** *** 547,555 **** Order is what determines the major number of your device. Which is why there will always be an entry for your driver, either null entry points, or actual entry points. It is probably worth noting that this ! is significantly different from SCO and other system V derrivatives, where any device can (in theory) have any major number. This is ! largley a convenience on FreeBSD, due to the way device nodes are created. More on this later. Adding your device to the config file. --- 547,555 ---- Order is what determines the major number of your device. Which is why there will always be an entry for your driver, either null entry points, or actual entry points. It is probably worth noting that this ! is significantly different from SCO and other system V derivatives, where any device can (in theory) have any major number. This is ! largely a convenience on FreeBSD, due to the way device nodes are created. More on this later. Adding your device to the config file. *************** *** 565,578 **** A slightly more complicated entry is for the ``ix'' driver: ! device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixint ! r This says that we have a device called `ix0' on the isa bus. It uses ! io-port 0x300. It's interrupt will be masked with other devices in the network class. It uses interrupt 10. It uses 32k of shared memory at physical address 0xd0000. It also defines ! it's interrupt handler to be ``ixintr()'' config(8) the kernel.

--- 565,577 ---- A slightly more complicated entry is for the ``ix'' driver: ! device ix0 at isa? port 0x300 net irq 10 iomem 0xd0000 iosiz 32768 vector ixintr This says that we have a device called `ix0' on the isa bus. It uses ! io-port 0x300. Its interrupt will be masked with other devices in the network class. It uses interrupt 10. It uses 32k of shared memory at physical address 0xd0000. It also defines ! its interrupt handler to be ``ixintr()''. config(8) the kernel.

*************** *** 600,606 ****

On FreeBSD, you are responsible for making your own device nodes. The major number of your device is determined by the slot number in the ! device switch. Minor number is driver dependant, of course. You can either run the mknod's from the command line, or add a section to /dev/MAKEDEV.local, or even /dev/MAKEDEV to do the work. I sometimes create a MAKEDEV.dev script that can be run stand-alone or pasted --- 599,605 ----

On FreeBSD, you are responsible for making your own device nodes. The major number of your device is determined by the slot number in the ! device switch. Minor number is driver dependent, of course. You can either run the mknod's from the command line, or add a section to /dev/MAKEDEV.local, or even /dev/MAKEDEV to do the work. I sometimes create a MAKEDEV.dev script that can be run stand-alone or pasted *************** *** 674,680 **** -- Declares the device driver entry points as external. 38 /* ! 39 * delcare your entry points as externs 40 */ 41 42 extern int pcaprobe(struct isa_device *); --- 673,679 ---- -- Declares the device driver entry points as external. 38 /* ! 39 * declare your entry points as externs 40 */ 41 42 extern int pcaprobe(struct isa_device *); *************** *** 692,698 **** Lines 52 - 70 -- This is creates the device switch entry table for your driver. ! This table gets wholesale swapped into the system device switch at the location specified by your major number. In the standard model, these are in /usr/src/sys/i386/i386/conf.c. NOTE: you cannot pick a device major number higher than what exists in conf.c, for example at --- 691,697 ---- Lines 52 - 70 -- This is creates the device switch entry table for your driver. ! This table gets swapped wholesale into the system device switch at the location specified by your major number. In the standard model, these are in /usr/src/sys/i386/i386/conf.c. NOTE: you cannot pick a device major number higher than what exists in conf.c, for example at *************** *** 725,731 **** -- This section is analogous to the config file declaration of your device. The members of the isa_device structure are filled in by what ! is known about your device, I/O port, shared memory segment, etc. we will probably never have a need for two pcaudio devices in the kernel, but this example shows how multiple devices can be supported. --- 724,730 ---- -- This section is analogous to the config file declaration of your device. The members of the isa_device structure are filled in by what ! is known about your device, I/O port, shared memory segment, etc. We will probably never have a need for two pcaudio devices in the kernel, but this example shows how multiple devices can be supported. *************** *** 798,806 **** driver, as opposed to an lkm filesystem, or an lkm system call. 132 /* ! 133 * this macro maps to a funtion which 134 * sets the lkm up for a driver ! 135 * as opposed to a filesystem, systemcall, or misc 136 * lkm. 137 */ 138 MOD_DEV("pcaudio_mod", LM_DT_CHAR, 24, &pcacdevsw); --- 797,805 ---- driver, as opposed to an lkm filesystem, or an lkm system call. 132 /* ! 133 * this macro maps to a function which 134 * sets the lkm up for a driver ! 135 * as opposed to a filesystem, system call, or misc 136 * lkm. 137 */ 138 MOD_DEV("pcaudio_mod", LM_DT_CHAR, 24, &pcacdevsw); *************** *** 826,832 **** 140 /* 141 * this function is called when the module is ! 142 * loaded, it tries to mimic the behavior 143 * of the standard probe/attach stuff from 144 * isa.c 145 */ --- 825,831 ---- 140 /* 141 * this function is called when the module is ! 142 * loaded; it tries to mimic the behavior 143 * of the standard probe/attach stuff from 144 * isa.c 145 */ *************** *** 857,863 **** Lines 169 - 179 ! -- This is the function called when your driver is unloaded, it just displays a message to that effect. 169 /* --- 856,862 ---- Lines 169 - 179 ! -- This is the function called when your driver is unloaded; it just displays a message to that effect. 169 /* *************** *** 898,910 **** 191 #endif /* NICP > 0 */ ! Device Type Idiosyncracies Character Block Network Line Discipline ! Bus Type Idiosyncracies ISA EISA PCI --- 897,909 ---- 191 #endif /* NICP > 0 */ ! Device Type Idiosyncrasies Character Block Network Line Discipline ! Bus Type Idiosyncrasies ISA EISA PCI *************** *** 950,957 **** * control, known in UN*X as a process; it has references to substructures * containing descriptions of things that the process uses, but may share * with related processes. The process structure and the substructures ! * are always addressible except for those marked "(PROC ONLY)" below, ! * which might be addressible only on a processor on which the process * is running. */ struct proc { --- 949,956 ---- * control, known in UN*X as a process; it has references to substructures * containing descriptions of things that the process uses, but may share * with related processes. The process structure and the substructures ! * are always addressable except for those marked "(PROC ONLY)" below, ! * which might be addressable only on a processor on which the process * is running. */ struct proc {