1.\" $NetBSD: driver.9,v 1.25 2011/01/05 17:02:03 jmcneill 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 January 5, 2011 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_flag; 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_flag; 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 (via its 178.Em cfattach 179structure) to match the driver with a device instance. 180The match function is called with three arguments. 181This first argument 182.Fa parent 183is a pointer to the driver's parent device structure. 184The second argument 185.Fa match 186is a pointer to a data structure describing the autoconfiguration 187framework's understanding of the driver. 188Both the 189.Fa parent 190and 191.Fa match 192arguments are ignored by most drivers. 193The third argument 194.Fa aux 195contains a pointer to a structure describing a potential 196device-instance. 197It is passed to the driver from the parent. 198The match function would type-cast the 199.Fa aux 200argument to its appropriate attachment structure and use its contents 201to determine whether it supports the device. 202Depending on the device hardware, the contents of the attachment 203structure may contain 204.Dq locators 205to locate the device instance so that the driver can probe it for its 206identity. 207If the probe process identifies additional device properties, it may 208modify the members of the attachment structure. 209For these devices, the 210.Nx 211convention is to 212call the match routine 213.Fn foo_probe 214instead of 215.Fn foo_match 216to make this distinction clear. 217Either way, the match function returns a nonzero integer indicating the 218confidence of supporting this device and a value of 0 if the driver 219doesn't support the device. 220Generally, only a single driver exists for a device, so the match 221function returns 1 for a positive match. 222.Pp 223The autoconfiguration framework will call the attach function 224(via its 225.Em cfattach 226structure) 227of the driver which returns the highest value from its match function. 228The attach function is called with three arguments. 229The attach function performs the necessary process to initialise the 230device for operation. 231The first argument 232.Fa parent 233is a pointer to the driver's parent device structure. 234The second argument 235.Fa self 236is a pointer to the driver's device structure. 237It is also a pointer to our 238.Em softc 239structure since the device structure is its first member. 240The third argument 241.Fa aux 242is a pointer to the attachment structure. 243The 244.Fa parent 245and 246.Fa aux 247arguments are the same as passed to the match function. 248.Pp 249The driver's attach function is called before system interrupts are 250enabled. 251If interrupts are required during initialisation, then the attach 252function should make use of 253.Fn config_interrupts 254(see 255.Xr autoconf 9 ) . 256.Pp 257Some devices can be removed from the system without requiring a system 258reboot. 259The autoconfiguration framework calls the driver's detach function 260(via its 261.Em cfattach 262structure) during device detachment. 263If the device does not support detachment, then the driver does not 264have to provide a detach function. 265The detach function is used to relinquish resources allocated to the 266driver which are no longer needed. 267The first argument 268.Fa self 269is a pointer to the driver's device structure. 270It is the same structure as passed to the attach function. 271The second argument 272.Fa flags 273contains detachment flags. 274Valid values are 275.Dv DETACH_FORCE 276(force detachment; hardware gone) and 277.Dv DETACH_QUIET 278(do not print a notice). 279.Pp 280The autoconfiguration framework may call the driver's activate function 281to notify the driver of a change in the resources that have been 282allocated to it. 283For example, an Ethernet driver has to be notified if the network stack 284is being added or removed from the kernel. 285The first argument to the activate function 286.Fa self 287is a pointer to the driver's device structure. 288It is the same argument as passed to the attach function. 289The second argument 290.Fa act 291describes the action. 292Valid actions are 293.Dv DVACT_ACTIVATE 294(activate the device) and 295.Dv DVACT_DEACTIVATE 296(deactivate the device). 297If the action is not supported the activate function should return 298.Er EOPNOTSUPP . 299The 300.Dv DVACT_DEACTIVATE 301call will only be made if the 302.Dv DVACT_ACTIVATE 303call was successful. 304The activate function is called in interrupt context. 305.Pp 306Most drivers will want to make use of interrupt facilities. 307Interrupt locators provided through the attachment structure should be 308used to establish interrupts within the system. 309Generally, an interrupt interface is provided by the parent. 310The interface will require a handler and a driver-specific argument 311to be specified. 312This argument is usually a pointer to the device-instance-specific 313softc structure. 314When a hardware interrupt for the device occurs the handler is called 315with the argument. 316Interrupt handlers should return 0 for 317.Dq interrupt not for me , 3181 for 319.Dq I took care of it , 320or -1 for 321.Do 322I guess it was mine, but I wasn't expecting it 323.Dc . 324.Pp 325For a driver to be compiled into the kernel, 326.Xr config 1 327must be aware of its existence. 328This is done by including an entry in files.\*[Lt]bus\*[Gt] in the 329directory containing the driver. 330For example, the driver 331.Dq foo 332attaching to bus 333.Dq bar 334with dependency on kernel module 335.Dq baz 336has the entry: 337.Bd -literal 338device foo: baz 339attach foo at bar 340file dev/bar/foo.c foo 341.Ed 342.Pp 343An entry can now be added to the machine description file: 344.Bd -literal 345foo* at bar? 346.Ed 347.Pp 348For device interfaces of a driver to be compiled into the kernel, 349.Xr config 1 350must be aware of its existence. 351This is done by including an entry in majors.\*[Lt]arch\*[Gt]. 352For example, the driver 353.Dq foo 354with character device interfaces, a character major device number 355.Dq cmaj , 356block device interfaces, a block device major number 357.Dq bmaj 358and dependency on kernel module 359.Dq baz 360has the entry: 361.Bd -literal 362device-major foo char cmaj block bmaj baz 363.Ed 364.Pp 365For a detailed description of the machine description file and the 366.Dq device definition 367language see 368.Xr config 9 . 369.Sh SEE ALSO 370.Xr config 1 , 371.Xr autoconf 9 , 372.Xr config 9 , 373.Xr pmf 9 374