1.\" $NetBSD: driver.9,v 1.9 2002/10/14 13:43:22 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.Fd #include \*[Lt]sys/param.h\*[Gt] 45.Fd #include \*[Lt]sys/device.h\*[Gt] 46.Fd #include \*[Lt]sys/errno.h\*[Gt] 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 utilised 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 74struct cfattach foo_ca = { 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}; 81.Ed 82.Pp 83The structure variable must be named 84.Va foo_ca 85by appending the letters 86.Dq _ca 87to the driver's base name. 88This convention is mandated by the autoconfiguration framework. 89.Pp 90For each device instance controlled by the driver, the 91autoconfiguration framework allocates a block of memory to record 92device-instance-specific driver variables. 93The size of this memory block is specified by the first field in the 94.Em cfattach 95structure. 96The memory block is referred to as the driver's 97.Em softc 98structure. 99The 100.Em softc 101structure is only accessed within the driver, so its definition is 102local to the driver. 103Nevertheless, the 104.Em softc 105structure should adopt the standard 106.Nx 107configuration and naming conventions. 108For example, the 109.Em softc 110structure for driver 111.Dq foo 112is defined with: 113.Pp 114.Bd -literal 115struct foo_softc { 116 struct device sc_dev; /* generic device info */ 117 /* device-specific state */ 118}; 119.Ed 120.Pp 121The autoconfiguration framework mandates that the first member of the 122.Em softc 123structure must be the driver-independent 124.Em struct device . 125Probably its most useful aspect to the driver is that it contains the 126device-instance name 127.Em dv_xname . 128.Pp 129If a driver has character device interfaces accessed from userland, the driver 130must define the 131.Em cdevsw 132structure. 133The structure is constant and is defined inside the driver. 134For example, the 135.Em cdevsw 136structure for driver 137.Dq foo 138is defined with: 139.Pp 140.Bd -literal 141const struct cdevsw foo_cdevsw { 142 int (*d_open)(dev_t, int, int, struct proc *); 143 int (*d_close)(dev_t, int, int, struct proc *); 144 int (*d_read)(dev_t, struct uio *, int); 145 int (*d_write)(dev_t, struct uio *, int); 146 int (*d_ioctl)(dev_t, u_long, caddr_t, int, struct proc *); 147 struct tty *(*d_tty)(dev_t); 148 int (*d_poll)(dev_t, int, struct proc *); 149 paddr_t (*d_mmap)(dev_t, off_t, int); 150 int d_type; 151}; 152.Ed 153.Pp 154The structure variable must be named foo_cdevsw by appending the letters 155.Dq _cdevsw 156to the driver's base name. 157This convention is mandated by the autoconfiguration framework. 158.Pp 159If the driver 160.Dq foo 161has also block device interfaces, the driver must define the 162.Em bdevsw 163structure. 164The structure is constant and is defined inside the driver. 165For example, the 166.Em bdevsw 167structure for driver 168.Dq foo 169is defined with: 170.Pp 171.Bd -literal 172const struct bdevsw foo_bdevsw { 173 int (*d_open)(dev_t, int, int, struct proc *); 174 int (*d_close)(dev_t, int, int, struct proc *); 175 void (*d_strategy)(struct buf *); 176 int (*d_ioctl)(dev_t, u_long, caddr_t, int, struct proc *); 177 int (*d_dump)(dev_t, daddr_t, caddr_t, size_t); 178 int (*d_psize)(dev_t); 179 int d_type; 180}; 181.Ed 182.Pp 183The structure variable must be named foo_bdevsw by appending the letters 184.Dq _bdevsw 185to the driver's base name. 186This convention is mandated by the autoconfiguration framework. 187.Pp 188During system bootstrap, the autoconfiguration framework searches the 189system for devices. 190For each device driver, its match function is called 191.Po 192via its 193.Em cfattach 194structure 195.Pc 196to match the driver with a device instance. 197The match function is called with three arguments. 198This first argument 199.Fa parent 200is a pointer to the driver's parent device structure. 201The second argument 202.Fa match 203is a pointer to a data structure describing the autoconfiguration 204framework's understanding of the driver. 205Both the 206.Fa parent 207and 208.Fa match 209arguments are ignored by most drivers. 210The third argument 211.Fa aux 212contains a pointer to a structure describing a potential 213device-instance. 214It is passed to the driver from the parent. 215The match function would type-cast the 216.Fa aux 217argument to its appropriate attachment structure and use its contents 218to determine whether it supports the device. 219Depending on the device hardware, the contents of the attachment 220structure may contain 221.Dq locators 222to locate the device instance so that the driver can probe it for its 223identity. 224If the probe process identifies additional device properties, it may 225modify the members of the attachment structure. 226For these devices, the 227.Nx 228convention is to 229call the match routine 230.Fn foo_probe 231instead of 232.Fn foo_match 233to make this distinction clear. 234Either way, the match function returns a nonzero integer indicating the 235confidence of supporting this device and a value of 0 if the driver 236doesn't support the device. 237Generally, only a single driver exists for a device, so the match 238function returns 1 for a positive match. 239.Pp 240The autoconfiguration framework will call the attach function 241.Po 242via its 243.Em cfattach 244structure 245.Pc 246of the driver which returns the highest value from its match function. 247The attach function is called with three arguments. 248The attach function performs the necessary process to initialise the 249device for operation. 250The first argument 251.Fa parent 252is a pointer to the driver's parent device structure. 253The second argument 254.Fa self 255is a pointer to the driver's device structure. 256It is also a pointer to our 257.Em softc 258structure since the device structure is its first member. 259The third argument 260.Fa aux 261is a pointer to the attachment structure. 262The 263.Fa parent 264and 265.Fa aux 266arguments are the same as passed to the match function. 267.Pp 268The driver's attach function is called before system interrupts are 269enabled. 270If interrupts are required during initialisation, then the attach 271function should make use of 272.Fn config_interrupts 273.Po 274see 275.Xr autoconf 9 276.Pc . 277.Pp 278Some devices can be removed from the system without requiring a system 279reboot. 280The autoconfiguration framework calls the driver's detach function 281.Po 282via its 283.Em cfattach 284structure 285.Pc 286during device detachment. 287If the device does not support detachment, then the driver does not 288have to provide a detach function. 289The detach function is used to relinquish resources allocated to the 290driver which are no longer needed. 291The first argument 292.Fa self 293is a pointer to the driver's device structure. 294It is the same structure as passed to the attach function. 295The second argument 296.Fa flags 297contains detachment flags. 298Valid values are DETACH_FORCE 299.Po 300force detachment; hardware gone 301.Pc and DETACH_QUIET 302.Po 303do not print a notice 304.Pc . 305.Pp 306The autoconfiguration framework calls the driver's activate function 307to notify the driver of a change in the resources that have been 308allocated to it. 309For example, an Ethernet driver has to be notified if the network stack 310is being added or removed from the kernel. 311The first argument to the activate function 312.Fa self 313is a pointer to the driver's device structure. 314It is the same argument as passed to the attach function. 315The second argument 316.Fa act 317describes the action. 318Valid actions are DVACT_ACTIVATE 319.Po 320activate the device 321.Pc and DVACT_DEACTIVATE 322.Po 323deactivate the device 324.Pc . 325If the action is not supported the activate function should return 326EOPNOTSUPP. 327The activate function is called in interrupt context. 328.Pp 329Most drivers will want to make use of interrupt facilities. 330Interrupt locators provided through the attachment structure should be 331used to establish interrupts within the system. 332Generally, an interrupt interface is provided by the parent. 333The interface will require a handler and a driver-specific argument 334to be specified. 335This argument is usually a pointer to the device-instance-specific 336softc structure. 337When a hardware interrupt for the device occurs the handler is called 338with the argument. 339Interrupt handlers should return 0 for 340.Dq interrupt not for me , 3411 for 342.Dq I took care of it , 343or -1 for 344.Do 345I guess it was mine, but I wasn't expecting it 346.Dc . 347.Pp 348For a driver to be compiled into the kernel, 349.Xr config 8 350must be aware of its existence. 351This is done by including an entry in files.\*[Lt]bus\*[Gt] in the 352directory containing the driver. 353For example, the driver 354.Dq foo 355attaching to bus 356.Dq bar 357with dependency on kernel module 358.Dq baz 359has the entry: 360.Bd -literal 361device foo: baz 362attach foo at bar 363file dev/bar/foo.c foo 364.Ed 365.Pp 366An entry can now be added to the machine description file: 367.Bd -literal 368foo* at bar? 369.Ed 370.Pp 371For device interfaces of a driver to be compiled into the kernel, 372.Xr config 8 373must be aware of its existence. 374his is done by including an entry in majors.<arch>. 375For example, the driver 376.Dq foo 377with character device interfaces, a character major device number 378.Dq cmaj , 379block device interfaces, a block device major number 380.Dq bmaj 381and dependency on kernel module 382.Dq baz 383has the entry: 384.Bd -literal 385device-major foo char cmaj block bmaj baz 386.Ed 387.Pp 388For a detailed description of the machine description file and the 389.Dq device definition 390language see 391.Xr config 9 . 392.Sh SEE ALSO 393.Xr config 8 , 394.Xr autoconf 9 , 395.Xr config 9 , 396.Xr powerhook_establish 9 , 397.Xr shutdownhook_establish 9 398