164 lines
4.9 KiB
Groff
164 lines
4.9 KiB
Groff
.\" $NetBSD: pcilkm.4,v 1.2 2004/07/02 13:38:14 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2004 The NetBSD Foundation.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to the NetBSD Foundation
|
|
.\" by Quentin Garnier.
|
|
.\"
|
|
.\" 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 July 2, 2004
|
|
.Dt PCILKM 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pcilkm
|
|
.Nd Loadable Kernel Module that can load PCI device drivers
|
|
.Sh SYNOPSIS
|
|
.In sys/lkm.h
|
|
.In lkm/dev/pcilkm/pcilkm.h
|
|
.Fn PCILKM_DECLARE name class attrs
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is meant to be a layer between the kernel and loadable PCI device drivers,
|
|
making the necessary operations to glue the driver to
|
|
.Xr autoconf 9 .
|
|
.Pp
|
|
It works by catching the usual load/unload calls of the LKM framework.
|
|
The
|
|
.Xr autoconf 9
|
|
structures are updated to reflect the addition of the new driver.
|
|
Then
|
|
.Nm
|
|
performs a scan of the PCI buses that will call the
|
|
.Fn match
|
|
and
|
|
.Fn attach
|
|
functions of the driver as it would be the case for a compiled-in
|
|
PCI device driver.
|
|
.Pp
|
|
.Nm
|
|
was designed to minimize the difference between a regular compiled-in
|
|
driver and a loadable driver.
|
|
The programmer only has to add the required
|
|
.Em MOD_*
|
|
directive, depending on the type of the driver,
|
|
and then attach the driver to the
|
|
.Nm
|
|
framework by using the
|
|
.Fn PCILKM_DECLARE
|
|
macro.
|
|
.Pp
|
|
The
|
|
.Em name
|
|
argument is used to build various structure names and must match the name
|
|
given to the
|
|
.Fn CFATTACH_DECL
|
|
macro.
|
|
Since the
|
|
.Em struct cfattach
|
|
variable is referenced by
|
|
.Fn PCILKM_DECLARE ,
|
|
the
|
|
.Fn CFATTACH_DECL
|
|
directive must appear earlier in the source file.
|
|
.Pp
|
|
The
|
|
.Em class
|
|
and
|
|
.Em attrs
|
|
arguments are the ones
|
|
.Xr config 8
|
|
would write down in the
|
|
.Fn CFDRIVER_DECL
|
|
directive of that driver if it was compiled-in and properly referenced in
|
|
the kernel configuration file.
|
|
The values
|
|
.Em DV_DULL
|
|
and
|
|
.Em NULL
|
|
will fit in most cases, unless you want to have other devices attached to
|
|
the managed device, in which case a properly built
|
|
.Em attrs
|
|
structure has to be passed.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
module must be loaded along with its symbol table to be useful,
|
|
since actual device driver loaded afterwards reference an exported
|
|
function.
|
|
Therefore,
|
|
.Xr ksyms 4
|
|
support is required in the kernel.
|
|
.Sh EXAMPLES
|
|
The following piece of code shows the basic skeleton of a loadable PCI
|
|
device driver:
|
|
.Bd -literal -offset indent -compact
|
|
#include \*[Lt]sys/cdefs.h\*[Gt]
|
|
#include \*[Lt]sys/param.h\*[Gt]
|
|
#include \*[Lt]sys/systm.h\*[Gt]
|
|
#include \*[Lt]sys/conf.h\*[Gt]
|
|
#include \*[Lt]sys/device.h\*[Gt]
|
|
#include \*[Lt]sys/lkm.h\*[Gt]
|
|
#include \*[Lt]dev/pci/pcivar.h\*[Gt]
|
|
#include \*[Lt]lkm/dev/pcilkm/pcilkm.h\*[Gt]
|
|
|
|
static int foo_attach(struct device *, struct cfdata *, void *);
|
|
static void foo_attach(struct device *, struct device *, void *);
|
|
static int foo_detach(struct device *, int);
|
|
|
|
MOD_MISC("foo");
|
|
CFATTACH_DECL(foo, sizeof(struct device), foo_match,
|
|
foo_attach, foo_detach, NULL);
|
|
PCILKM_DECLARE(foo, DV_DULL, NULL);
|
|
|
|
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)
|
|
{
|
|
...
|
|
}
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr ksyms 4 ,
|
|
.Xr lkm 4 ,
|
|
.Xr pci 4 ,
|
|
.Xr autoconf 9
|