314 lines
9.7 KiB
Groff
314 lines
9.7 KiB
Groff
.\" $NetBSD: driver.9,v 1.3 2001/12/26 00:21:57 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Gregory McGarry.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd June 16, 2001
|
|
.Dt DRIVER 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm driver
|
|
.Nd description of a device driver
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/param.h>
|
|
.Fd #include <sys/device.h>
|
|
.Fd #include <sys/error.h>
|
|
.Ft static int
|
|
.Fn foo_match "struct device *parent" "struct cfdata *match" "void *aux"
|
|
.Ft static void
|
|
.Fn foo_attach "struct device *parent" "struct device *self" "void *aux"
|
|
.Ft static int
|
|
.Fn foo_detach "struct device *self" "int flags"
|
|
.Ft static int
|
|
.Fn foo_activate "struct device *self" "enum devact act"
|
|
.Sh DESCRIPTION
|
|
This page briefly describes the basic
|
|
.Nx
|
|
autoconfiguration interface utilised by device drivers. For a detailed
|
|
overview of the autoconfiguration framework see
|
|
.Xr autoconf 9 .
|
|
.Pp
|
|
Each device driver must present to the system a standard
|
|
autoconfiguration interface. This interface is provided by the
|
|
.Em cfattach
|
|
structure. The interface to the driver is constant and is defined
|
|
statically inside the driver. For example, the interface to driver
|
|
.Do
|
|
foo
|
|
.Dc
|
|
is defined with:
|
|
.Pp
|
|
.Bd -literal
|
|
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 */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The structure variable must be named
|
|
.Va foo_ca
|
|
by appending the letters
|
|
.Do
|
|
_ca
|
|
.Dc
|
|
to the driver's base name. This convention is mandated by the
|
|
autoconfiguration framework.
|
|
.Pp
|
|
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
|
|
.Em cfattach
|
|
structure. The memory block is referred to as the driver's
|
|
.Em softc
|
|
structure. The
|
|
.Em softc
|
|
structure is only accessed within the driver, so its definition is
|
|
local to the driver. Nevertheless, the
|
|
.Em softc
|
|
structure should adopt the standard
|
|
.Nx
|
|
configuration and naming conventions. For example, the
|
|
.Em softc
|
|
structure for driver
|
|
.Do
|
|
foo
|
|
.Dc
|
|
is defined with:
|
|
.Pp
|
|
.Bd -literal
|
|
struct foo_softc {
|
|
struct device sc_dev; /* generic device info */
|
|
/* device-specific state */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The autoconfiguration framework mandates that the first member of the
|
|
.Em softc
|
|
structure must be the driver-independent
|
|
.Em struct device .
|
|
Probably its most useful aspect to the driver is that it contains the
|
|
device-instance name
|
|
.Em dv_xname .
|
|
.Pp
|
|
During system bootstrap, the autoconfiguration framework searches the
|
|
system for devices. For each device driver, its match function
|
|
is called
|
|
.Po
|
|
via its
|
|
.Em cfattach
|
|
structure
|
|
.Pc
|
|
to match the driver with a device instance. The match function is
|
|
called with three arguments. This first argument
|
|
.Fa parent
|
|
is a pointer to the driver's parent device structure. The second
|
|
argument
|
|
.Fa match
|
|
is a pointer to a data structure describing the autoconfiguration
|
|
framework's understanding of the driver. Both the
|
|
.Fa parent
|
|
and
|
|
.Fa match
|
|
arguments are ignored by most drivers. The third argument
|
|
.Fa 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
|
|
.Fa 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
|
|
.Do
|
|
locators
|
|
.Dc
|
|
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
|
|
.Nx
|
|
convention is to
|
|
call the match routine
|
|
.Fn foo_probe
|
|
instead of
|
|
.Fn 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.
|
|
.Pp
|
|
The autoconfiguration framework will call the attach function
|
|
.Po
|
|
via its
|
|
.Em cfattach
|
|
structure
|
|
.Pc
|
|
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
|
|
.Fa parent
|
|
is a pointer to the driver's parent device structure. The second
|
|
argument
|
|
.Fa self
|
|
is a pointer to the driver's device structure. It is also a pointer
|
|
to our
|
|
.Em softc
|
|
structure since the device structure is its first member. The third
|
|
argument
|
|
.Fa aux
|
|
is a pointer to the attachment structure. The
|
|
.Fa parent
|
|
and
|
|
.Fa aux
|
|
arguments are the same as the match function.
|
|
.Pp
|
|
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
|
|
.Fn config_interrupts
|
|
.Po
|
|
see
|
|
.Xr autoconf 9
|
|
.Pc .
|
|
.Pp
|
|
Some devices can be removed from the system without requiring a system
|
|
reboot. The autoconfiguration framework calls the driver's detach
|
|
function
|
|
.Po
|
|
via its
|
|
.Em cfattach
|
|
structure
|
|
.Pc
|
|
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
|
|
.Fa self
|
|
is a pointer to the driver's device structure. It is the same
|
|
structure as passed to the attach function. The second argument
|
|
.Fa flags
|
|
contains detachment flags. Valid values are DETACH_FORCE
|
|
.Po
|
|
force detachment; hardware gone
|
|
.Pc and DETACH_QUIET
|
|
.Po
|
|
do not print a notice
|
|
.Pc .
|
|
.Pp
|
|
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
|
|
.Fa self
|
|
is a pointer to the driver's device structure. It is the same
|
|
argument as passed to the attach function. The second argument
|
|
.Fa act
|
|
describes the action. Valid actions are DVACT_ACTIVATE
|
|
.Po
|
|
activate the device
|
|
.Pc and DVACT_DEACTIVATE
|
|
.Po
|
|
deactivate the device
|
|
.Pc .
|
|
If the action is not supported the activate function should return
|
|
EOPNOSUPP.
|
|
The activate function is called in interrupt context.
|
|
.Pp
|
|
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
|
|
.Do
|
|
interrupt not for me
|
|
.Dc ,
|
|
1 for
|
|
.Do
|
|
I took care of it
|
|
.Dc ,
|
|
or -1 for
|
|
.Do
|
|
I guess it was mine, but I wasn't expecting it
|
|
.Dc .
|
|
.Pp
|
|
For a driver to be compiled into the kernel,
|
|
.Xr 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
|
|
.Do
|
|
foo
|
|
.Dc
|
|
attaching to bus
|
|
.Do
|
|
bar
|
|
.Dc
|
|
with dependency on kernel module
|
|
.Do
|
|
baz
|
|
.Dc
|
|
has the entry:
|
|
.Bd -literal
|
|
device foo: baz
|
|
attach foo at bar
|
|
file dev/bar/foo.c foo
|
|
.Ed
|
|
.Pp
|
|
An entry can now be added to the machine description file:
|
|
.Bd -literal
|
|
foo* at bar?
|
|
.Ed
|
|
.Pp
|
|
For a detailed description of the machine description file and the
|
|
.Do
|
|
device definition
|
|
.Dc
|
|
language see
|
|
.Xr config 9 .
|
|
.Sh SEE ALSO
|
|
.Xr config 8 ,
|
|
.Xr autoconf 9 ,
|
|
.Xr config 9 ,
|
|
.Xr powerhook_establish 9 ,
|
|
.Xr shutdownhook_establish 9
|