1.\" $NetBSD: isapnp.9,v 1.8 2003/04/16 13:35:29 wiz 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 19, 2001 38.Dt ISAPNP 9 39.Os 40.Sh NAME 41.Nm ISAPNP , 42.Nm isapnp_devmatch , 43.Nm isapnp_config , 44.Nm isapnp_unconfig 45.Nd Plug 'n' Play ISA bus 46.Sh SYNOPSIS 47.In machine/bus.h 48.In dev/isa/isareg.h 49.In dev/isa/isavar.h 50.In dev/isapnp/isapnpreg.h 51.In dev/isapnp/isapnpvar.h 52.In dev/isapnp/isapnpdevs.h 53.Ft int 54.Fn isapnp_devmatch "const struct isapnp_attach_args *ipa" \ 55"const struct isapnp_devinfo *dinfo" "int *variant" 56.Ft int 57.Fn isapnp_config "bus_space_tag_t iot" "bus_space_tag_t memt" \ 58"struct isapnp_attach_args *ipa" 59.Ft void 60.Fn isapnp_unconfig "bus_space_tag_t iot" "bus_space_tag_t memt" \ 61"struct isapnp_attach_args *ipa" 62.Sh DESCRIPTION 63The machine-independent 64.Nm 65subsystem provides support for ISAPNP devices. 66ISAPNP devices were developed to support "plug and play" connection 67on the ISA bus. 68In all other aspects, the ISAPNP bus is same as the ISA bus (see 69.Xr isa 9 ) . 70.Pp 71Devices on the ISAPNP bus are uniquely identified by a 7-character 72string. 73Resources, such as I/O address space and interrupts, should 74be allocated to the devices by the machine firmware. 75On some machine the firmware seems doesn't work correctly and 76.Nx 77will attempt to allocate resources as necessary. 78.Sh DATA TYPES 79Drivers attached to the ISAPNP bus will make use of the following data 80types: 81.Bl -tag -width compact 82.It Fa struct isapnp_matchinfo 83.Nx 84kernel contains a database of known ISAPNP devices. 85Each entry in the database has a 86.Em struct isapnp_matchinfo . 87It contains the following members: 88.Bd -literal 89 const char *name; /* device id string */ 90 int variant; /* variant flag */ 91.Ed 92.It Fa struct isapnp_devinfo 93Defines the devices supported by a driver. 94It contains pointer to an array of supported 95.Em struct isapnp_matchinfo 96structures and a pointer to another array of compatibility devices. 97It contains the following members: 98.Bd -literal 99 struct isapnp_matchinfo *devlogic; 100 int nlogic; 101 struct isapnp_matchinfo *devcompat; 102 int ncompat; 103.Ed 104.It Fa struct isapnp_region 105Describes ISAPNP bus-space regions. 106It contains the following members: 107.Bd -literal 108 bus_space_handle_t h; 109 u_int32_t base; 110 u_int32_t length; 111.Ed 112.It Fa struct isapnp_pin 113Describes the wiring of interrupts and DMA pins from the ISAPNP bus 114onto the host processor. 115It contains the following members: 116.Bd -literal 117 u_int8_t num; 118 u_int8_t flags:4; 119 u_int8_t type:4; 120 u_int16_t bits; 121.Ed 122.It Fa struct isapnp_attach_args 123A structure used to inform the driver of the device properties. 124It contains the following members: 125.Bd -literal 126 bus_space_tag_t ipa_iot; /* isa i/o space tag */ 127 bus_space_tag_t ipa_memt; /* isa mem space tag */ 128 bus_dma_tag_t ipa_dmat; /* isa dma tag */ 129 isa_chipset_tag_t ipa_ic; 130 struct isapnp_region ipa_io[ISAPNP_NUM_IO]; 131 struct isapnp_region ipa_mem[ISAPNP_NUM_MEM]; 132 struct isapnp_region ipa_mem32[ISAPNP_NUM_MEM32]; 133 struct isapnp_pin ipa_irq[ISAPNP_NUM_IRQ]; 134 struct isapnp_pin ipa_drq[ISAPNP_NUM_DRQ]; 135.Ed 136.El 137.Sh FUNCTIONS 138.Bl -tag -width compact 139.It Fn isapnp_devmatch "ipa" "dinfo" "variant" 140Matches the device described by the attachment 141.Fa ipa 142with the device-match information in 143.Fa dinfo . 144If the device is matched, 145.Fn isapnp_devmatch 146returns a non-zero value and variant is the flag describing the device 147variant. 148.Fn isapnp_devmatch 149returns zero if the device is not found. 150.It Fn isapnp_config "iot" "memt" "ipa" 151Allocate device resources specified by 152.Fa ipa . 153The device is mapped into the I/O and memory bus spaces specified by 154bus-space tags 155.Fa iot 156and 157.Fa memt 158respectively. 159The 160.Fa ipa_io , 161.Fa ipa_mem , 162.Fa ipa_mem32 , 163.Fa ipa_irq , 164and 165.Fa ipa_drq 166members of 167.Fa ipa 168are updated to reflect the allocated and mapped resources. 169.Fn isapnp_config 170returns zero on success and non-zero on error. 171.It Fn isapnp_unconfig "iot" "memt" "ipa" 172Free the resources allocated by 173.Fn isapnp_config . 174.El 175.Sh AUTOCONFIGURATION 176During autoconfiguration, an ISAPNP driver will receive a pointer to 177.Fa struct isapnp_attach_args 178describing the device attached to the ISAPNP bus. 179Drivers match the device using 180.Fn ispnp_devmatch . 181.Pp 182During the driver attach step, driver should initially allocate and 183map resources using 184.Fn isapnp_config . 185The I/O (memory) bus-space resources can be accessed using the 186bus-space tag 187.Fa ipa_iot 188.Po 189.Fa ipa_memt 190.Pc 191and the bus-space handle 192.Fa ipa_io[0].h 193.Po 194.Fa ipa_mem[0].h 195.Pc 196members of 197.Fa ipa . 198.Pp 199Interrupts should be established using 200.Fn isa_intr_establish 201.Po 202see 203.Xr isa 9 204.Pc 205with the IRQ specified by the 206.Fa ipa_irq[0].num 207member of 208.Fa ipa . 209Similarly, the standard 210.Xr isa 9 211DMA interface should be used with the 212.Fa ipa_drq[0].num 213member of 214.Fa ipa . 215.Sh DMA SUPPORT 216Extensive DMA facilities are provided through the 217.Xr isa 9 218DMA facilities. 219.Sh CODE REFERENCES 220This section describes places within the 221.Nx 222source tree where actual code implementing or using the 223machine-independent 224.Nm 225subsystem can be found. 226All pathnames are relative to 227.Pa /usr/src . 228.Pp 229The 230.Nm 231subsystem itself is implemented within the file 232.Pa sys/dev/isapnp/isapnp.c . 233The database of the known devices exists within the file 234.Pa sys/dev/isapnp/isapnpdevs.c 235and is generated automatically from the file 236.Pa sys/dev/isapnp/isapnpdevs . 237New devices should be added to this file. 238The database can be regenerated using the Makefile 239.Pa sys/dev/isapnp/Makefile.isapnpdevs . 240.Sh SEE ALSO 241.Xr isa 4 , 242.Xr isapnp 4 , 243.Xr pnpbios 4 , 244.Xr autoconf 9 , 245.Xr bus_dma 9 , 246.Xr bus_space 9 , 247.Xr driver 9 , 248.Xr isa 9 249.Rs 250.%T "Plug and Play ISA Specification V1.0a" 251.%D May 5 1994 252.Re 253.Sh HISTORY 254The machine-independent ISAPNP subsystem appear in 255.Nx 1.3 . 256