1.\" $NetBSD: isapnp.9,v 1.11 2010/12/02 12:54:13 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd June 19, 2001 31.Dt ISAPNP 9 32.Os 33.Sh NAME 34.Nm ISAPNP , 35.Nm isapnp_devmatch , 36.Nm isapnp_config , 37.Nm isapnp_unconfig 38.Nd Plug 'n' Play ISA bus 39.Sh SYNOPSIS 40.In machine/bus.h 41.In dev/isa/isareg.h 42.In dev/isa/isavar.h 43.In dev/isapnp/isapnpreg.h 44.In dev/isapnp/isapnpvar.h 45.In dev/isapnp/isapnpdevs.h 46.Ft int 47.Fn isapnp_devmatch "const struct isapnp_attach_args *ipa" \ 48"const struct isapnp_devinfo *dinfo" "int *variant" 49.Ft int 50.Fn isapnp_config "bus_space_tag_t iot" "bus_space_tag_t memt" \ 51"struct isapnp_attach_args *ipa" 52.Ft void 53.Fn isapnp_unconfig "bus_space_tag_t iot" "bus_space_tag_t memt" \ 54"struct isapnp_attach_args *ipa" 55.Sh DESCRIPTION 56The machine-independent 57.Nm 58subsystem provides support for ISAPNP devices. 59ISAPNP devices were developed to support "plug and play" connection 60on the ISA bus. 61In all other aspects, the ISAPNP bus is same as the ISA bus (see 62.Xr isa 9 ) . 63.Pp 64Devices on the ISAPNP bus are uniquely identified by a 7-character 65string. 66Resources, such as I/O address space and interrupts, should 67be allocated to the devices by the machine firmware. 68On some machine the firmware seems doesn't work correctly and 69.Nx 70will attempt to allocate resources as necessary. 71.Sh DATA TYPES 72Drivers attached to the ISAPNP bus will make use of the following data 73types: 74.Bl -tag -width compact 75.It Fa struct isapnp_matchinfo 76.Nx 77kernel contains a database of known ISAPNP devices. 78Each entry in the database has a 79.Em struct isapnp_matchinfo . 80It contains the following members: 81.Bd -literal 82 const char *name; /* device id string */ 83 int variant; /* variant flag */ 84.Ed 85.It Fa struct isapnp_devinfo 86Defines the devices supported by a driver. 87It contains pointer to an array of supported 88.Em struct isapnp_matchinfo 89structures and a pointer to another array of compatibility devices. 90It contains the following members: 91.Bd -literal 92 struct isapnp_matchinfo *devlogic; 93 int nlogic; 94 struct isapnp_matchinfo *devcompat; 95 int ncompat; 96.Ed 97.It Fa struct isapnp_region 98Describes ISAPNP bus-space regions. 99It contains the following members: 100.Bd -literal 101 bus_space_handle_t h; 102 uint32_t base; 103 uint32_t length; 104.Ed 105.It Fa struct isapnp_pin 106Describes the wiring of interrupts and DMA pins from the ISAPNP bus 107onto the host processor. 108It contains the following members: 109.Bd -literal 110 uint8_t num; 111 uint8_t flags:4; 112 uint8_t type:4; 113 uint16_t bits; 114.Ed 115.It Fa struct isapnp_attach_args 116A structure used to inform the driver of the device properties. 117It contains the following members: 118.Bd -literal 119 bus_space_tag_t ipa_iot; /* isa i/o space tag */ 120 bus_space_tag_t ipa_memt; /* isa mem space tag */ 121 bus_dma_tag_t ipa_dmat; /* isa dma tag */ 122 isa_chipset_tag_t ipa_ic; 123 struct isapnp_region ipa_io[ISAPNP_NUM_IO]; 124 struct isapnp_region ipa_mem[ISAPNP_NUM_MEM]; 125 struct isapnp_region ipa_mem32[ISAPNP_NUM_MEM32]; 126 struct isapnp_pin ipa_irq[ISAPNP_NUM_IRQ]; 127 struct isapnp_pin ipa_drq[ISAPNP_NUM_DRQ]; 128.Ed 129.El 130.Sh FUNCTIONS 131.Bl -tag -width compact 132.It Fn isapnp_devmatch "ipa" "dinfo" "variant" 133Matches the device described by the attachment 134.Fa ipa 135with the device-match information in 136.Fa dinfo . 137If the device is matched, 138.Fn isapnp_devmatch 139returns a non-zero value and variant is the flag describing the device 140variant. 141.Fn isapnp_devmatch 142returns zero if the device is not found. 143.It Fn isapnp_config "iot" "memt" "ipa" 144Allocate device resources specified by 145.Fa ipa . 146The device is mapped into the I/O and memory bus spaces specified by 147bus-space tags 148.Fa iot 149and 150.Fa memt 151respectively. 152The 153.Fa ipa_io , 154.Fa ipa_mem , 155.Fa ipa_mem32 , 156.Fa ipa_irq , 157and 158.Fa ipa_drq 159members of 160.Fa ipa 161are updated to reflect the allocated and mapped resources. 162.Fn isapnp_config 163returns zero on success and non-zero on error. 164.It Fn isapnp_unconfig "iot" "memt" "ipa" 165Free the resources allocated by 166.Fn isapnp_config . 167.El 168.Sh AUTOCONFIGURATION 169During autoconfiguration, an ISAPNP driver will receive a pointer to 170.Fa struct isapnp_attach_args 171describing the device attached to the ISAPNP bus. 172Drivers match the device using 173.Fn ispnp_devmatch . 174.Pp 175During the driver attach step, driver should initially allocate and 176map resources using 177.Fn isapnp_config . 178The I/O (memory) bus-space resources can be accessed using the 179bus-space tag 180.Fa ipa_iot 181.Po 182.Fa ipa_memt 183.Pc 184and the bus-space handle 185.Fa ipa_io[0].h 186.Po 187.Fa ipa_mem[0].h 188.Pc 189members of 190.Fa ipa . 191.Pp 192Interrupts should be established using 193.Fn isa_intr_establish 194.Po 195see 196.Xr isa 9 197.Pc 198with the IRQ specified by the 199.Fa ipa_irq[0].num 200member of 201.Fa ipa . 202Similarly, the standard 203.Xr isa 9 204DMA interface should be used with the 205.Fa ipa_drq[0].num 206member of 207.Fa ipa . 208.Sh DMA SUPPORT 209Extensive DMA facilities are provided through the 210.Xr isa 9 211DMA facilities. 212.Sh CODE REFERENCES 213The 214.Nm 215subsystem itself is implemented within the file 216.Pa sys/dev/isapnp/isapnp.c . 217The database of the known devices exists within the file 218.Pa sys/dev/isapnp/isapnpdevs.c 219and is generated automatically from the file 220.Pa sys/dev/isapnp/isapnpdevs . 221New devices should be added to this file. 222The database can be regenerated using the Makefile 223.Pa sys/dev/isapnp/Makefile.isapnpdevs . 224.Sh SEE ALSO 225.Xr isa 4 , 226.Xr isapnp 4 , 227.Xr pnpbios 4 , 228.Xr autoconf 9 , 229.Xr bus_dma 9 , 230.Xr bus_space 9 , 231.Xr driver 9 , 232.Xr isa 9 233.Rs 234.%T "Plug and Play ISA Specification V1.0a" 235.%D May 5 1994 236.Re 237.Sh HISTORY 238The machine-independent ISAPNP subsystem appear in 239.Nx 1.3 . 240