.\"     $NetBSD: isapnp.9,v 1.9 2005/12/26 19:48:12 perry 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 19, 2001
.Dt ISAPNP 9
.Os
.Sh NAME
.Nm ISAPNP ,
.Nm isapnp_devmatch ,
.Nm isapnp_config ,
.Nm isapnp_unconfig
.Nd Plug 'n' Play ISA bus
.Sh SYNOPSIS
.In machine/bus.h
.In dev/isa/isareg.h
.In dev/isa/isavar.h
.In dev/isapnp/isapnpreg.h
.In dev/isapnp/isapnpvar.h
.In dev/isapnp/isapnpdevs.h
.Ft int
.Fn isapnp_devmatch "const struct isapnp_attach_args *ipa" \
"const struct isapnp_devinfo *dinfo" "int *variant"
.Ft int
.Fn isapnp_config "bus_space_tag_t iot" "bus_space_tag_t memt" \
"struct isapnp_attach_args *ipa"
.Ft void
.Fn isapnp_unconfig "bus_space_tag_t iot" "bus_space_tag_t memt" \
"struct isapnp_attach_args *ipa"
.Sh DESCRIPTION
The machine-independent
.Nm
subsystem provides support for ISAPNP devices.
ISAPNP devices were developed to support "plug and play" connection
on the ISA bus.
In all other aspects, the ISAPNP bus is same as the ISA bus (see
.Xr isa 9 ) .
.Pp
Devices on the ISAPNP bus are uniquely identified by a 7-character
string.
Resources, such as I/O address space and interrupts, should
be allocated to the devices by the machine firmware.
On some machine the firmware seems doesn't work correctly and
.Nx
will attempt to allocate resources as necessary.
.Sh DATA TYPES
Drivers attached to the ISAPNP bus will make use of the following data
types:
.Bl -tag -width compact
.It Fa struct isapnp_matchinfo
.Nx
kernel contains a database of known ISAPNP devices.
Each entry in the database has a
.Em struct isapnp_matchinfo .
It contains the following members:
.Bd -literal
	const char *name;		/* device id string */
	int variant;			/* variant flag */
.Ed
.It Fa struct isapnp_devinfo
Defines the devices supported by a driver.
It contains pointer to an array of supported
.Em struct isapnp_matchinfo
structures and a pointer to another array of compatibility devices.
It contains the following members:
.Bd -literal
	struct isapnp_matchinfo *devlogic;
	int nlogic;
	struct isapnp_matchinfo *devcompat;
	int ncompat;
.Ed
.It Fa struct isapnp_region
Describes ISAPNP bus-space regions.
It contains the following members:
.Bd -literal
	bus_space_handle_t h;
	uint32_t base;
	uint32_t length;
.Ed
.It Fa struct isapnp_pin
Describes the wiring of interrupts and DMA pins from the ISAPNP bus
onto the host processor.
It contains the following members:
.Bd -literal
	uint8_t  num;
	uint8_t  flags:4;
	uint8_t  type:4;
	uint16_t bits;
.Ed
.It Fa struct isapnp_attach_args
A structure used to inform the driver of the device properties.
It contains the following members:
.Bd -literal
	bus_space_tag_t	ipa_iot;	/* isa i/o space tag */
	bus_space_tag_t	ipa_memt;	/* isa mem space tag */
	bus_dma_tag_t	ipa_dmat;	/* isa dma tag */
	isa_chipset_tag_t	ipa_ic;
	struct isapnp_region    ipa_io[ISAPNP_NUM_IO];
	struct isapnp_region    ipa_mem[ISAPNP_NUM_MEM];
	struct isapnp_region    ipa_mem32[ISAPNP_NUM_MEM32];
	struct isapnp_pin       ipa_irq[ISAPNP_NUM_IRQ];
	struct isapnp_pin       ipa_drq[ISAPNP_NUM_DRQ];
.Ed
.El
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn isapnp_devmatch "ipa" "dinfo" "variant"
Matches the device described by the attachment
.Fa ipa
with the device-match information in
.Fa dinfo .
If the device is matched,
.Fn isapnp_devmatch
returns a non-zero value and variant is the flag describing the device
variant.
.Fn isapnp_devmatch
returns zero if the device is not found.
.It Fn isapnp_config "iot" "memt" "ipa"
Allocate device resources specified by
.Fa ipa .
The device is mapped into the I/O and memory bus spaces specified by
bus-space tags
.Fa iot
and
.Fa memt
respectively.
The
.Fa ipa_io ,
.Fa ipa_mem ,
.Fa ipa_mem32 ,
.Fa ipa_irq ,
and
.Fa ipa_drq
members of
.Fa ipa
are updated to reflect the allocated and mapped resources.
.Fn isapnp_config
returns zero on success and non-zero on error.
.It Fn isapnp_unconfig "iot" "memt" "ipa"
Free the resources allocated by
.Fn isapnp_config .
.El
.Sh AUTOCONFIGURATION
During autoconfiguration, an ISAPNP driver will receive a pointer to
.Fa struct isapnp_attach_args
describing the device attached to the ISAPNP bus.
Drivers match the device using
.Fn ispnp_devmatch .
.Pp
During the driver attach step, driver should initially allocate and
map resources using
.Fn isapnp_config .
The I/O (memory) bus-space resources can be accessed using the
bus-space tag
.Fa ipa_iot
.Po
.Fa ipa_memt
.Pc
and the bus-space handle
.Fa ipa_io[0].h
.Po
.Fa ipa_mem[0].h
.Pc
members of
.Fa ipa .
.Pp
Interrupts should be established using
.Fn isa_intr_establish
.Po
see
.Xr isa 9
.Pc
with the IRQ specified by the
.Fa ipa_irq[0].num
member of
.Fa ipa .
Similarly, the standard
.Xr isa 9
DMA interface should be used with the
.Fa ipa_drq[0].num
member of
.Fa ipa .
.Sh DMA SUPPORT
Extensive DMA facilities are provided through the
.Xr isa 9
DMA facilities.
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or using the
machine-independent
.Nm
subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The
.Nm
subsystem itself is implemented within the file
.Pa sys/dev/isapnp/isapnp.c .
The database of the known devices exists within the file
.Pa sys/dev/isapnp/isapnpdevs.c
and is generated automatically from the file
.Pa sys/dev/isapnp/isapnpdevs .
New devices should be added to this file.
The database can be regenerated using the Makefile
.Pa sys/dev/isapnp/Makefile.isapnpdevs .
.Sh SEE ALSO
.Xr isa 4 ,
.Xr isapnp 4 ,
.Xr pnpbios 4 ,
.Xr autoconf 9 ,
.Xr bus_dma 9 ,
.Xr bus_space 9 ,
.Xr driver 9 ,
.Xr isa 9
.Rs
.%T "Plug and Play ISA Specification V1.0a"
.%D May 5 1994
.Re
.Sh HISTORY
The machine-independent ISAPNP subsystem appear in
.Nx 1.3 .