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