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