xref: /netbsd/share/man/man9/driver.9 (revision bf9ec67e) 
1.\"     $NetBSD: driver.9,v 1.5 2002/04/02 14:16:34 heinz 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 June 16, 2001
38.Dt DRIVER 9
39.Os
40.Sh NAME
41.Nm driver
42.Nd description of a device driver
43.Sh SYNOPSIS
44.Fd #include \*[Lt]sys/param.h\*[Gt]
45.Fd #include \*[Lt]sys/device.h\*[Gt]
46.Fd #include \*[Lt]sys/error.h\*[Gt]
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 utilised by device drivers.  For a detailed
59overview of the autoconfiguration framework see
60.Xr autoconf 9 .
61.Pp
62Each device driver must present to the system a standard
63autoconfiguration interface.  This interface is provided by the
64.Em cfattach
65structure.  The interface to the driver is constant and is defined
66statically inside the driver.  For example, the interface to driver
67.Do
68foo
69.Dc
70is defined with:
71.Pp
72.Bd -literal
73struct cfattach foo_ca = {
74	sizeof(struct foo_softc),	/* size of instance data */
75	foo_match,			/* match/probe function */
76	foo_attach,			/* attach function */
77	foo_detach,			/* detach function */
78	foo_activate			/* activate function */
79};
80.Ed
81.Pp
82The structure variable must be named
83.Va foo_ca
84by appending the letters
85.Do
86_ca
87.Dc
88to the driver's base name.  This convention is mandated by the
89autoconfiguration framework.
90.Pp
91For each device instance controlled by the driver, the
92autoconfiguration framework allocates a block of memory to record
93device-instance-specific driver variables.  The size of this memory
94block is specified by the first field in the
95.Em cfattach
96structure.  The memory block is referred to as the driver's
97.Em softc
98structure.  The
99.Em softc
100structure is only accessed within the driver, so its definition is
101local to the driver.  Nevertheless, the
102.Em softc
103structure should adopt the standard
104.Nx
105configuration and naming conventions.  For example, the
106.Em softc
107structure for driver
108.Do
109foo
110.Dc
111is defined with:
112.Pp
113.Bd -literal
114struct foo_softc {
115	struct device sc_dev;		/* generic device info */
116	/* device-specific state */
117};
118.Ed
119.Pp
120The autoconfiguration framework mandates that the first member of the
121.Em softc
122structure must be the driver-independent
123.Em struct device .
124Probably its most useful aspect to the driver is that it contains the
125device-instance name
126.Em dv_xname .
127.Pp
128During system bootstrap, the autoconfiguration framework searches the
129system for devices.  For each device driver, its match function
130is called
131.Po
132via its
133.Em cfattach
134structure
135.Pc
136to match the driver with a device instance.  The match function is
137called with three arguments.  This first argument
138.Fa parent
139is a pointer to the driver's parent device structure.  The second
140argument
141.Fa match
142is a pointer to a data structure describing the autoconfiguration
143framework's understanding of the driver.  Both the
144.Fa parent
145and
146.Fa match
147arguments are ignored by most drivers.  The third argument
148.Fa aux
149contains a pointer to a structure describing a potential
150device-instance.  It is passed to the driver from the parent.
151The match function would type-cast the
152.Fa aux
153argument to its appropriate attachment structure and use its contents
154to determine whether it supports the device.  Depending on the device
155hardware, the contents of the attachment structure may contain
156.Do
157locators
158.Dc
159to locate the device instance so that the driver can probe it for its
160identity.  If the probe process identifies additional device
161properties, it may modify the members of the attachment structure.
162For these devices, the
163.Nx
164convention is to
165call the match routine
166.Fn foo_probe
167instead of
168.Fn foo_match
169to make this distinction clear.  Either way, the match function
170returns a nonzero integer indicating the confidence of supporting this
171device and a value of 0 if the driver doesn't support the device.
172Generally, only a single driver exists for a device, so the match
173function returns 1 for a positive match.
174.Pp
175The autoconfiguration framework will call the attach function
176.Po
177via its
178.Em cfattach
179structure
180.Pc
181of the driver which returns the highest value from its match function.
182The attach function is called with three arguments.  The attach
183function performs the necessary process to initialise the device for
184operation.  The first argument
185.Fa parent
186is a pointer to the driver's parent device structure.  The second
187argument
188.Fa self
189is a pointer to the driver's device structure.  It is also a pointer
190to our
191.Em softc
192structure since the device structure is its first member.  The third
193argument
194.Fa aux
195is a pointer to the attachment structure.  The
196.Fa parent
197and
198.Fa aux
199arguments are the same as passed to the match function.
200.Pp
201The driver's attach function is called before system interrupts are
202enabled.  If interrupts are required during initialisation, then
203the attach function should make use of
204.Fn config_interrupts
205.Po
206see
207.Xr autoconf 9
208.Pc .
209.Pp
210Some devices can be removed from the system without requiring a system
211reboot.  The autoconfiguration framework calls the driver's detach
212function
213.Po
214via its
215.Em cfattach
216structure
217.Pc
218during device detachment.  If the device does not support detachment,
219then the driver does not have to provide a detach function.  The
220detach function is used to relinquish resources allocated to the
221driver which are no longer needed.  The first argument
222.Fa self
223is a pointer to the driver's device structure.  It is the same
224structure as passed to the attach function.  The second argument
225.Fa flags
226contains detachment flags.  Valid values are DETACH_FORCE
227.Po
228force detachment; hardware gone
229.Pc and DETACH_QUIET
230.Po
231do not print a notice
232.Pc .
233.Pp
234The autoconfiguration framework calls the driver's activate function
235to notify the driver of a change in the resources that have been
236allocated to it.  For example, an Ethernet driver has to be notified
237if the network stack is being added or removed from the kernel.  The
238first argument to the activate function
239.Fa self
240is a pointer to the driver's device structure.  It is the same
241argument as passed to the attach function.  The second argument
242.Fa act
243describes the action.  Valid actions are DVACT_ACTIVATE
244.Po
245activate the device
246.Pc and DVACT_DEACTIVATE
247.Po
248deactivate the device
249.Pc .
250If the action is not supported the activate function should return
251EOPNOSUPP.
252The activate function is called in interrupt context.
253.Pp
254Most drivers will want to make use of interrupt facilities.  Interrupt
255locators provided through the attachment structure should be used to
256establish interrupts within the system.  Generally, an interrupt
257interface is provided by the parent.  The interface will require a
258handler and a driver-specific argument to be specified.  This argument
259is usually a pointer to the device-instance-specific softc structure.
260When a hardware interrupt for the device occurs the handler is called
261with the argument.  Interrupt handlers should return 0 for
262.Do
263interrupt not for me
264.Dc ,
2651 for
266.Do
267I took care of it
268.Dc ,
269or -1 for
270.Do
271I guess it was mine, but I wasn't expecting it
272.Dc .
273.Pp
274For a driver to be compiled into the kernel,
275.Xr config 8
276must be aware of its existence.  This is done by including an entry in
277files.\*[Lt]bus\*[Gt] in the directory containing the driver.  For example, the
278driver
279.Do
280foo
281.Dc
282attaching to bus
283.Do
284bar
285.Dc
286with dependency on kernel module
287.Do
288baz
289.Dc
290has the entry:
291.Bd -literal
292device	foo: baz
293attach	foo at bar
294file	dev/bar/foo.c		foo
295.Ed
296.Pp
297An entry can now be added to the machine description file:
298.Bd -literal
299foo*	at bar?
300.Ed
301.Pp
302For a detailed description of the machine description file and the
303.Do
304device definition
305.Dc
306language see
307.Xr config 9 .
308.Sh SEE ALSO
309.Xr config 8 ,
310.Xr autoconf 9 ,
311.Xr config 9 ,
312.Xr powerhook_establish 9 ,
313.Xr shutdownhook_establish 9
314