driver - description of a device driver
#include <sys/param.h>
#include <sys/device.h>
#include <sys/error.h>
static int
foo_match(struct device *parent, struct cfdata *match, void *aux);
static void
foo_attach(struct device *parent, struct device *self, void *aux);
static int
foo_detach(struct device *self, int flags);
static int
foo_activate(struct device *self, enum devact act);
This page briefly describes the basic NetBSD autoconfiguration interface
utilised by device drivers. For a detailed overview of the autoconfiguration
framework see autoconf(9).
Each device driver must present to the system a standard autoconfiguration
interface. This interface is provided by the cfattach structure.
The interface to the driver is constant and is defined statically inside
the driver. For example, the interface to driver ``foo'' is defined
with:
struct cfattach foo_ca = {
sizeof(struct foo_softc), /* size of instance data */
foo_match, /* match/probe function */
foo_attach, /* attach function */
foo_detach, /* detach function */
foo_activate /* activate function */
};
The structure variable must be named foo_ca by appending the letters
``_ca'' to the driver's base name. This convention is mandated by the
autoconfiguration framework.
For each device instance controlled by the driver, the autoconfiguration
framework allocates a block of memory to record device-instance-specific
driver variables. The size of this memory block is specified by the
first field in the cfattach structure. The memory block is referred to
as the driver's softc structure. The softc structure is only accessed
within the driver, so its definition is local to the driver. Nevertheless,
the softc structure should adopt the standard NetBSD configuration
and naming conventions. For example, the softc structure for driver
``foo'' is defined with:
struct foo_softc {
struct device sc_dev; /* generic device info */
/* device-specific state */
};
The autoconfiguration framework mandates that the first member of the
softc structure must be the driver-independent struct device. Probably
its most useful aspect to the driver is that it contains the deviceinstance
name dv_xname.
During system bootstrap, the autoconfiguration framework searches the
system for devices. For each device driver, its match function is called
(via its cfattach structure) to match the driver with a device instance.
The match function is called with three arguments. This first argument
parent is a pointer to the driver's parent device structure. The second
argument match is a pointer to a data structure describing the autoconfiguration
framework's understanding of the driver. Both the parent and
match arguments are ignored by most drivers. The third argument aux contains
a pointer to a structure describing a potential device-instance.
It is passed to the driver from the parent. The match function would
type-cast the aux argument to its appropriate attachment structure and
use its contents to determine whether it supports the device. Depending
on the device hardware, the contents of the attachment structure may contain
``locators'' to locate the device instance so that the driver can
probe it for its identity. If the probe process identifies additional
device properties, it may modify the members of the attachment structure.
For these devices, the NetBSD convention is to call the match routine
foo_probe() instead of foo_match() to make this distinction clear.
Either way, the match function returns a nonzero integer indicating the
confidence of supporting this device and a value of 0 if the driver
doesn't support the device. Generally, only a single driver exists for a
device, so the match function returns 1 for a positive match.
The autoconfiguration framework will call the attach function (via its
cfattach structure) of the driver which returns the highest value from
its match function. The attach function is called with three arguments.
The attach function performs the necessary process to initialise the
device for operation. The first argument parent is a pointer to the
driver's parent device structure. The second argument self is a pointer
to the driver's device structure. It is also a pointer to our softc
structure since the device structure is its first member. The third
argument aux is a pointer to the attachment structure. The parent and
aux arguments are the same as passed to the match function.
The driver's attach function is called before system interrupts are
enabled. If interrupts are required during initialisation, then the
attach function should make use of config_interrupts() (see autoconf(9)).
Some devices can be removed from the system without requiring a system
reboot. The autoconfiguration framework calls the driver's detach function
(via its cfattach structure) during device detachment. If the
device does not support detachment, then the driver does not have to provide
a detach function. The detach function is used to relinquish
resources allocated to the driver which are no longer needed. The first
argument self is a pointer to the driver's device structure. It is the
same structure as passed to the attach function. The second argument
flags contains detachment flags. Valid values are DETACH_FORCE (force
detachment; hardware gone) and DETACH_QUIET (do not print a notice).
The autoconfiguration framework calls the driver's activate function to
notify the driver of a change in the resources that have been allocated
to it. For example, an Ethernet driver has to be notified if the network
stack is being added or removed from the kernel. The first argument to
the activate function self is a pointer to the driver's device structure.
It is the same argument as passed to the attach function. The second
argument act describes the action. Valid actions are DVACT_ACTIVATE
(activate the device) and DVACT_DEACTIVATE (deactivate the device). If
the action is not supported the activate function should return EOPNOSUPP.
The activate function is called in interrupt context.
Most drivers will want to make use of interrupt facilities. Interrupt
locators provided through the attachment structure should be used to
establish interrupts within the system. Generally, an interrupt interface
is provided by the parent. The interface will require a handler and
a driver-specific argument to be specified. This argument is usually a
pointer to the device-instance-specific softc structure. When a hardware
interrupt for the device occurs the handler is called with the argument.
Interrupt handlers should return 0 for ``interrupt not for me'', 1 for
``I took care of it'', or -1 for ``I guess it was mine, but I wasn't
expecting it''.
For a driver to be compiled into the kernel, config(8) must be aware of
its existence. This is done by including an entry in files.<bus> in the
directory containing the driver. For example, the driver ``foo'' attaching
to bus ``bar'' with dependency on kernel module ``baz'' has the
entry:
device foo: baz
attach foo at bar
file dev/bar/foo.c foo
An entry can now be added to the machine description file:
foo* at bar?
For a detailed description of the machine description file and the
``device definition'' language see config(9).
config(8), autoconf(9), config(9), powerhook_establish(9),
shutdownhook_establish(9)
BSD June 16, 2001 BSD
[ Back ] |
