Writing Drivers for NetBSD Jochen Kunz Version 1.0.1e August 25th, 2003 An introduction into NetBSD’s autoconfig(0) system and the basics of de- vice drivers under NetBSD. 1 CONTENTS 2 Contents 1 Preface 4 2 The autoconf(9) system 6 2.1 config(8) . 6 2.2 ioconf.c and cfdata . 6 2.3 sys/kern/subr autoconf.c . 8 2.4 Attributes and Locators . 9 2.5 Where are my children? . 10 2.6 bus space(9) and bus dma(9) . 12 3 The autoconf(9) part of the rf(4) driver 14 3.1 Configuration files . 14 3.1.1 The kernel configuration file . 14 3.1.2 sys/dev/qbus/files.uba . 14 3.1.3 The device numbers . 15 3.2 Data structures for autoconf(9) . 17 3.3 Functions for autoconf(9) . 18 3.3.1 rfc match() . 18 3.3.2 rfc attach() . 21 3.3.3 rf match() . 24 3.3.4 rf attach() . 25 4 The core of the driver 27 4.1 Data structures of the driver . 27 4.1.1 Data structures per controller . 27 4.1.2 Data structure per drive . 28 4.2 The necessary functions . 29 4.2.1 rfdump() . 31 4.2.2 rfsize() . 31 4.2.3 rfopen() . 31 4.2.4 rfclose() . 35 4.2.5 rfread() and rfwrite() . 36 4.2.6 rfstrategy() . 37 4.2.7 rfc intr() . 41 4.2.8 rfioctl() . 48 LIST OF FIGURES 3 A rf.c 51 B rfreg.h 80 C License 83 D Version History 84 E Bibliography 85 List of Figures 1 device tree . 8 2 calling chain of autoconf(9) functions . 11 3 rf(4)’s interal states. 41 1 PREFACE 4 1 Preface This document is intended to teach the basics of Unix-Kernelprogramming to a beginning Programmer with basic C knowledge. As an example, a device driver for a floppy drive under NetBSD was chosen, as the hardware and necessary doc- umentation was available but the driver itself missing. NetBSD was chosen as the target operating system, as it lends itself perfectly as a teaching example due to its clearly structured source code and well defined interfaces. Unfortunately, there is hardly any specific documentation on Unix- Kernelprogramming under NetBSD apart from references to the functions in sec- tion 9 of the NetBSD manual pages. These manual pages are however miss- ing an introduction, a document that clarifies the connection between the various functions. This document attempts to provide such an introduction, to act as the necessary glue between the individual parts. Therefore, I will reference external documents, particularly section 9 of the NetBSD manual pages in many places. This document is mainly based on the experiences I made when I wrote the driver rf(4)1 for the UnixBus / QBus RX211 8” floppy controller. 8” floppy? Those things existed? Yes. Those were the first floppies, built at the end of the 60s / beginning of the 70s. UniBus / QBus? Whatsdat? That’s the most common bus found in VAXen2. The VAX was the machine of the late 70s up until the beginning of the 90s. Then it was obsoleted by the Alpha architecture. BSD Unix has a long and glorious history on the VAX. [McK 99] But why am I writing a driver today for such antiquated technology? In the end, it doesn’t really matter if I explain the necessary steps using the latest 1GBit/s Ethernetcard for a PCIX Bus or anything else. The underlying principles are the same. Besides, the hardware used in this example is relatively simplistic, so that we can see the essential aspects instead of being hindered by PeeCee idiocrasy. The following chapter gives a short overview of the autoconf(9) concept in NetBSD. Some details have been omitted, and I refer to the according manual pages to avoid duplication of information. The third chapter documents the implementation of the autoconf(9) inter- face of rf(4). The fourth and last chapter covers the actual driver, i.e. the functionality of the driver carrying the data from and to the physical device. In the appendix, you will find the complete source code of the driver as well 1RX01/02 Floppy 2plural for VAX 1 PREFACE 5 as a copy of the referenced manual pages. Future prospects: In its current form, this document represents only a be- ginning. A description of a network device driver, the internal functionality of bus space(9) and bus dma(9) or what is required to port NetBSD to a new ar- chitecture would be possible extensions. Similarly, a discussion of the UVM / UBC internals or a file system interface would be of interest to implement a new file system for example. But at least the last example goes a bit too far away from the initial intent of giving an overview or an introduction to device driver pro- gramming and would be more suitable for a more extensive document on NetBSD Kernel internals, which one day may evolve out of this text. Thanks to Hubert Feyrer and Marc Balmer, who took the time to proof-read my mental outpourings and provided incitement for some diagrams. 2 THE AUTOCONF(9) SYSTEM 6 2 The autoconf(9) system The kernel configuration file is based on three pillars: ioconf.c / cfdata and sys/kern/subr autoconf.c. This concept has become known as autoconf . But what exactly is going on behind the curtain? 2.1 config(8) There is one central file which declares the kernel configuration for a BSD Unix Kernel. Under NetBSD, this file is located in sys/arch/<arch>/conf. <arch> represents the appropriate machine- / processor architecture. In our example, this is vax, i.e. d.h. sys/arch/vax/conf. In this folder, you can find the kernel con- figuration file GENERIC, which contains all the drivers and options supported by this architecture. You can create a user-defined configuration file by copying the file to a new name in this directory and editing it. Usually, this means commenting out all the drivers for devices not available in the particular machine. This process can be automated by using the tool pkgsrc/sysutils/adjustkernel. After calling config(8), it reads the kernel configuration file to determine which drivers / functionality should be included in the kernel. Some ”‘files.*”’ files assign the .c- and .h-files to the various drivers and functionality. Us- ing these dependencies, config(8) creates a compilation directory containing a Makefile as well as a range of .c- and .h-files. The .h-files usually contain defines with parameters such as the max. number of driver instances (for exam- ple PseudoTTYs, BPF, ...), kernel options such as KTRACE, ... The file param.c also falls into this category. The compilation directory is named after the kernel configuration file and is located in sys/arch/vax/compile. After changing into said directory, the actual compilation is started by the command make depend netbsd. See config(8) and http://www.netbsd.org/Documentation/kernel/ for details. 2.2 ioconf.c and cfdata The file ioconf.c in the compilation directory contains the data structure, marking the central point of access of the entire autoconf process. This configuration data table shows all the devices supported by the kernel. Let’s start with an excerpt of the kernels configuration file: mainbus0 at root 2 THE AUTOCONF(9) SYSTEM 7 ibus0 at mainbus0 # All MicroVAX sbi0 at mainbus0 # SBI, master bus on 11/780. vsbus0 at mainbus0 # All VAXstations uba0 at ibus0 # Qbus adapter ze0 at ibus0 # SGEC on-board ethernet le0 at ibus0 # LANCE ethernet (MV3400) le0 at vsbus0 csr 0x200e0000 # LANCE ethernet ze0 at vsbus0 csr 0x20008000 # SGEC ethernet si0 at vsbus0 csr 0x200c0080 # VS2000/3100 SCSI-ctlr asc0 at vsbus0 csr 0x200c0080 # VS4000/60 (or VLC) SCSI-ctlr asc0 at vsbus0 csr 0x26000080 # VS4000/90 SCSI-ctlr uda0 at uba? csr 0172150 # UDA50/RQDX? qe0 at uba? csr 0174440 # DEQNA/DELQA rlc0 at uba? csr 0174400 # RL11/RLV11 controller rl* at rlc? drive? # RL01/RL02 disk drive scsibus* at asc? scsibus* at si? sd* at scsibus? target? lun? st* at scsibus? target? lun? cd* at scsibus? target? lun? We quickly realize that the organization of the device drivers can be repre- sented in a treelike structure as in figure 1. Attached to the imaginary root (which appears “out of nowhere”) we find the first child, the abstract mainbus. This mainbus is parent to the children ibus, sbi and vsbus. These children in turn are parent to uba, le, asc, ... These relationships represent the above men- tioned cfdata table found in the file ioconf.c. The programmer does not need to know or care about this table, as it is automagically created by config(8) . It is important to realize that each device (node) has a parent (except for root, due to the old chicken-or-the-egg problem). A node that has children, is a Bus or a controller. The actual devices are the leaves of the tree. Each leaf and each node represent a device driver. That of course means, that there must be drivers for the 2 THE AUTOCONF(9) SYSTEM 8 uda0 uba0 qu0 rlc0 rl* ibus0 ze0 le0 root mainbus sbi0 le0 ze0 vsbus0 si0 sd* ... scsibus0 st* asc0 cd* Figure 1: device tree bus systems as well. The bus drivers are, especially in this context, responsible for locating the devices attached to the bus (i.e. the “busscan”). Another important realization lies in the fact that there are several different ways of arriving at the same driver! For example le0: root => mainbus0 => ibus0 => le0 or root => mainbus0 => vsbus0 => le0.