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