1.\" $NetBSD: driver.9,v 1.13 2004/05/16 16:56:01 wiz Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 6, 2002 38.Dt DRIVER 9 39.Os 40.Sh NAME 41.Nm driver 42.Nd description of a device driver 43.Sh SYNOPSIS 44.In sys/param.h 45.In sys/device.h 46.In sys/errno.h 47.Ft static int 48.Fn foo_match "struct device *parent" "struct cfdata *match" "void *aux" 49.Ft static void 50.Fn foo_attach "struct device *parent" "struct device *self" "void *aux" 51.Ft static int 52.Fn foo_detach "struct device *self" "int flags" 53.Ft static int 54.Fn foo_activate "struct device *self" "enum devact act" 55.Sh DESCRIPTION 56This page briefly describes the basic 57.Nx 58autoconfiguration interface used by device drivers. 59For a detailed overview of the autoconfiguration framework see 60.Xr autoconf 9 . 61.Pp 62Each device driver must present to the system a standard 63autoconfiguration interface. 64This interface is provided by the 65.Em cfattach 66structure. 67The interface to the driver is constant and is defined 68statically inside the driver. 69For example, the interface to driver 70.Dq foo 71is defined with: 72.Pp 73.Bd -literal 74CFATTACH_DECL(foo, /* driver name */ 75 sizeof(struct foo_softc), /* size of instance data */ 76 foo_match, /* match/probe function */ 77 foo_attach, /* attach function */ 78 foo_detach, /* detach function */ 79 foo_activate); /* activate function */ 80.Ed 81.Pp 82For each device instance controlled by the driver, the 83autoconfiguration framework allocates a block of memory to record 84device-instance-specific driver variables. 85The size of this memory block is specified by the second argument in the 86.Em CFATTACH_DECL 87macro. 88The memory block is referred to as the driver's 89.Em softc 90structure. 91The 92.Em softc 93structure is only accessed within the driver, so its definition is 94local to the driver. 95Nevertheless, the 96.Em softc 97structure should adopt the standard 98.Nx 99configuration and naming conventions. 100For example, the 101.Em softc 102structure for driver 103.Dq foo 104is defined with: 105.Pp 106.Bd -literal 107struct foo_softc { 108 struct device sc_dev; /* generic device info */ 109 /* device-specific state */ 110}; 111.Ed 112.Pp 113The autoconfiguration framework mandates that the first member of the 114.Em softc 115structure must be the driver-independent 116.Em struct device . 117Probably its most useful aspect to the driver is that it contains the 118device-instance name 119.Em dv_xname . 120.Pp 121If a driver has character device interfaces accessed from userland, the driver 122must define the 123.Em cdevsw 124structure. 125The structure is constant and is defined inside the driver. 126For example, the 127.Em cdevsw 128structure for driver 129.Dq foo 130is defined with: 131.Pp 132.Bd -literal 133const struct cdevsw foo_cdevsw { 134 int (*d_open)(dev_t, int, int, struct proc *); 135 int (*d_close)(dev_t, int, int, struct proc *); 136 int (*d_read)(dev_t, struct uio *, int); 137 int (*d_write)(dev_t, struct uio *, int); 138 int (*d_ioctl)(dev_t, u_long, caddr_t, int, struct proc *); 139 struct tty *(*d_tty)(dev_t); 140 int (*d_poll)(dev_t, int, struct proc *); 141 paddr_t (*d_mmap)(dev_t, off_t, int); 142 int d_type; 143}; 144.Ed 145.Pp 146The structure variable must be named foo_cdevsw by appending the letters 147.Dq _cdevsw 148to the driver's base name. 149This convention is mandated by the autoconfiguration framework. 150.Pp 151If the driver 152.Dq foo 153has also block device interfaces, the driver must define the 154.Em bdevsw 155structure. 156The structure is constant and is defined inside the driver. 157For example, the 158.Em bdevsw 159structure for driver 160.Dq foo 161is defined with: 162.Pp 163.Bd -literal 164const struct bdevsw foo_bdevsw { 165 int (*d_open)(dev_t, int, int, struct proc *); 166 int (*d_close)(dev_t, int, int, struct proc *); 167 void (*d_strategy)(struct buf *); 168 int (*d_ioctl)(dev_t, u_long, caddr_t, int, struct proc *); 169 int (*d_dump)(dev_t, daddr_t, caddr_t, size_t); 170 int (*d_psize)(dev_t); 171 int d_type; 172}; 173.Ed 174.Pp 175The structure variable must be named foo_bdevsw by appending the letters 176.Dq _bdevsw 177to the driver's base name. 178This convention is mandated by the autoconfiguration framework. 179.Pp 180During system bootstrap, the autoconfiguration framework searches the 181system for devices. 182For each device driver, its match function is called 183.Po 184via its 185.Em cfattach 186structure 187.Pc 188to match the driver with a device instance. 189The match function is called with three arguments. 190This first argument 191.Fa parent 192is a pointer to the driver's parent device structure. 193The second argument 194.Fa match 195is a pointer to a data structure describing the autoconfiguration 196framework's understanding of the driver. 197Both the 198.Fa parent 199and 200.Fa match 201arguments are ignored by most drivers. 202The third argument 203.Fa aux 204contains a pointer to a structure describing a potential 205device-instance. 206It is passed to the driver from the parent. 207The match function would type-cast the 208.Fa aux 209argument to its appropriate attachment structure and use its contents 210to determine whether it supports the device. 211Depending on the device hardware, the contents of the attachment 212structure may contain 213.Dq locators 214to locate the device instance so that the driver can probe it for its 215identity. 216If the probe process identifies additional device properties, it may 217modify the members of the attachment structure. 218For these devices, the 219.Nx 220convention is to 221call the match routine 222.Fn foo_probe 223instead of 224.Fn foo_match 225to make this distinction clear. 226Either way, the match function returns a nonzero integer indicating the 227confidence of supporting this device and a value of 0 if the driver 228doesn't support the device. 229Generally, only a single driver exists for a device, so the match 230function returns 1 for a positive match. 231.Pp 232The autoconfiguration framework will call the attach function 233.Po 234via its 235.Em cfattach 236structure 237.Pc 238of the driver which returns the highest value from its match function. 239The attach function is called with three arguments. 240The attach function performs the necessary process to initialise the 241device for operation. 242The first argument 243.Fa parent 244is a pointer to the driver's parent device structure. 245The second argument 246.Fa self 247is a pointer to the driver's device structure. 248It is also a pointer to our 249.Em softc 250structure since the device structure is its first member. 251The third argument 252.Fa aux 253is a pointer to the attachment structure. 254The 255.Fa parent 256and 257.Fa aux 258arguments are the same as passed to the match function. 259.Pp 260The driver's attach function is called before system interrupts are 261enabled. 262If interrupts are required during initialisation, then the attach 263function should make use of 264.Fn config_interrupts 265.Po 266see 267.Xr autoconf 9 268.Pc . 269.Pp 270Some devices can be removed from the system without requiring a system 271reboot. 272The autoconfiguration framework calls the driver's detach function 273.Po 274via its 275.Em cfattach 276structure 277.Pc 278during device detachment. 279If the device does not support detachment, then the driver does not 280have to provide a detach function. 281The detach function is used to relinquish resources allocated to the 282driver which are no longer needed. 283The first argument 284.Fa self 285is a pointer to the driver's device structure. 286It is the same structure as passed to the attach function. 287The second argument 288.Fa flags 289contains detachment flags. 290Valid values are DETACH_FORCE 291.Po 292force detachment; hardware gone 293.Pc and DETACH_QUIET 294.Po 295do not print a notice 296.Pc . 297.Pp 298The autoconfiguration framework calls the driver's activate function 299to notify the driver of a change in the resources that have been 300allocated to it. 301For example, an Ethernet driver has to be notified if the network stack 302is being added or removed from the kernel. 303The first argument to the activate function 304.Fa self 305is a pointer to the driver's device structure. 306It is the same argument as passed to the attach function. 307The second argument 308.Fa act 309describes the action. 310Valid actions are DVACT_ACTIVATE 311.Po 312activate the device 313.Pc and DVACT_DEACTIVATE 314.Po 315deactivate the device 316.Pc . 317If the action is not supported the activate function should return 318EOPNOTSUPP. 319The activate function is called in interrupt context. 320.Pp 321Most drivers will want to make use of interrupt facilities. 322Interrupt locators provided through the attachment structure should be 323used to establish interrupts within the system. 324Generally, an interrupt interface is provided by the parent. 325The interface will require a handler and a driver-specific argument 326to be specified. 327This argument is usually a pointer to the device-instance-specific 328softc structure. 329When a hardware interrupt for the device occurs the handler is called 330with the argument. 331Interrupt handlers should return 0 for 332.Dq interrupt not for me , 3331 for 334.Dq I took care of it , 335or -1 for 336.Do 337I guess it was mine, but I wasn't expecting it 338.Dc . 339.Pp 340For a driver to be compiled into the kernel, 341.Xr config 8 342must be aware of its existence. 343This is done by including an entry in files.\*[Lt]bus\*[Gt] in the 344directory containing the driver. 345For example, the driver 346.Dq foo 347attaching to bus 348.Dq bar 349with dependency on kernel module 350.Dq baz 351has the entry: 352.Bd -literal 353device foo: baz 354attach foo at bar 355file dev/bar/foo.c foo 356.Ed 357.Pp 358An entry can now be added to the machine description file: 359.Bd -literal 360foo* at bar? 361.Ed 362.Pp 363For device interfaces of a driver to be compiled into the kernel, 364.Xr config 8 365must be aware of its existence. 366This is done by including an entry in majors.<arch>. 367For example, the driver 368.Dq foo 369with character device interfaces, a character major device number 370.Dq cmaj , 371block device interfaces, a block device major number 372.Dq bmaj 373and dependency on kernel module 374.Dq baz 375has the entry: 376.Bd -literal 377device-major foo char cmaj block bmaj baz 378.Ed 379.Pp 380For a detailed description of the machine description file and the 381.Dq device definition 382language see 383.Xr config 9 . 384.Sh SEE ALSO 385.Xr config 8 , 386.Xr autoconf 9 , 387.Xr config 9 , 388.Xr powerhook_establish 9 , 389.Xr shutdownhook_establish 9 390