| blob | a0c638e45a0e2995d6a8e4e4475ee3235c858fa7 |
1 .\" $NetBSD: isapnp.9,v 1.9 2005/12/26 19:48:12 perry 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
56 The machine-independent
57 .Nm
58 subsystem provides support for ISAPNP devices.
59 ISAPNP devices were developed to support "plug and play" connection
60 on the ISA bus.
61 In all other aspects, the ISAPNP bus is same as the ISA bus (see
62 .Xr isa 9 ) .
63 .Pp
64 Devices on the ISAPNP bus are uniquely identified by a 7-character
65 string.
66 Resources, such as I/O address space and interrupts, should
67 be allocated to the devices by the machine firmware.
68 On some machine the firmware seems doesn't work correctly and
69 .Nx
70 will attempt to allocate resources as necessary.
71 .Sh DATA TYPES
72 Drivers attached to the ISAPNP bus will make use of the following data
73 types:
74 .Bl -tag -width compact
75 .It Fa struct isapnp_matchinfo
76 .Nx
77 kernel contains a database of known ISAPNP devices.
78 Each entry in the database has a
79 .Em struct isapnp_matchinfo .
80 It 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
86 Defines the devices supported by a driver.
87 It contains pointer to an array of supported
88 .Em struct isapnp_matchinfo
89 structures and a pointer to another array of compatibility devices.
90 It 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
98 Describes ISAPNP bus-space regions.
99 It 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
106 Describes the wiring of interrupts and DMA pins from the ISAPNP bus
107 onto the host processor.
108 It 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
116 A structure used to inform the driver of the device properties.
117 It 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"
133 Matches the device described by the attachment
134 .Fa ipa
135 with the device-match information in
136 .Fa dinfo .
137 If the device is matched,
138 .Fn isapnp_devmatch
139 returns a non-zero value and variant is the flag describing the device
140 variant.
141 .Fn isapnp_devmatch
142 returns zero if the device is not found.
143 .It Fn isapnp_config "iot" "memt" "ipa"
144 Allocate device resources specified by
145 .Fa ipa .
146 The device is mapped into the I/O and memory bus spaces specified by
147 bus-space tags
148 .Fa iot
149 and
150 .Fa memt
151 respectively.
152 The
153 .Fa ipa_io ,
154 .Fa ipa_mem ,
155 .Fa ipa_mem32 ,
156 .Fa ipa_irq ,
157 and
158 .Fa ipa_drq
159 members of
160 .Fa ipa
161 are updated to reflect the allocated and mapped resources.
162 .Fn isapnp_config
163 returns zero on success and non-zero on error.
164 .It Fn isapnp_unconfig "iot" "memt" "ipa"
165 Free the resources allocated by
166 .Fn isapnp_config .
167 .El
168 .Sh AUTOCONFIGURATION
169 During autoconfiguration, an ISAPNP driver will receive a pointer to
170 .Fa struct isapnp_attach_args
171 describing the device attached to the ISAPNP bus.
172 Drivers match the device using
173 .Fn ispnp_devmatch .
174 .Pp
175 During the driver attach step, driver should initially allocate and
176 map resources using
177 .Fn isapnp_config .
178 The I/O (memory) bus-space resources can be accessed using the
179 bus-space tag
180 .Fa ipa_iot
181 .Po
182 .Fa ipa_memt
183 .Pc
184 and the bus-space handle
185 .Fa ipa_io[0].h
186 .Po
187 .Fa ipa_mem[0].h
188 .Pc
189 members of
190 .Fa ipa .
191 .Pp
192 Interrupts should be established using
193 .Fn isa_intr_establish
194 .Po
195 see
196 .Xr isa 9
197 .Pc
198 with the IRQ specified by the
199 .Fa ipa_irq[0].num
200 member of
201 .Fa ipa .
202 Similarly, the standard
203 .Xr isa 9
204 DMA interface should be used with the
205 .Fa ipa_drq[0].num
206 member of
207 .Fa ipa .
208 .Sh DMA SUPPORT
209 Extensive DMA facilities are provided through the
210 .Xr isa 9
211 DMA facilities.
212 .Sh CODE REFERENCES
213 This section describes places within the
214 .Nx
215 source tree where actual code implementing or using the
216 machine-independent
217 .Nm
218 subsystem can be found.
219 All pathnames are relative to
220 .Pa /usr/src .
221 .Pp
222 The
223 .Nm
224 subsystem itself is implemented within the file
225 .Pa sys/dev/isapnp/isapnp.c .
226 The database of the known devices exists within the file
227 .Pa sys/dev/isapnp/isapnpdevs.c
228 and is generated automatically from the file
229 .Pa sys/dev/isapnp/isapnpdevs .
230 New devices should be added to this file.
231 The database can be regenerated using the Makefile
232 .Pa sys/dev/isapnp/Makefile.isapnpdevs .
233 .Sh SEE ALSO
234 .Xr isa 4 ,
235 .Xr isapnp 4 ,
236 .Xr pnpbios 4 ,
237 .Xr autoconf 9 ,
238 .Xr bus_dma 9 ,
239 .Xr bus_space 9 ,
240 .Xr driver 9 ,
241 .Xr isa 9
242 .Rs
243 .%T "Plug and Play ISA Specification V1.0a"
244 .%D May 5 1994
245 .Re
246 .Sh HISTORY
247 The machine-independent ISAPNP subsystem appear in
248 .Nx 1.3 .