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