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