| blob | 9a991efb0ba853b7d12e4cc3faff56fc6bc414e1 |
1 .\" $NetBSD: isa.9,v 1.17 2008/04/30 13:10:58 martin Exp $
2 .\"
3 .\" Copyright (c) 2001, 2005, 2006 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 January 29, 2006
31 .Dt ISA 9
32 .Os
33 .Sh NAME
34 .Nm ISA ,
35 .Nm isa_intr_alloc ,
36 .Nm isa_intr_establish ,
37 .Nm isa_intr_disestablish ,
38 .Nm isa_intr_evcnt ,
39 .Nm isa_dmamap_create ,
40 .Nm isa_dmamap_destroy ,
41 .Nm isa_dmamem_alloc ,
42 .Nm isa_dmamem_free ,
43 .Nm isa_dmamem_map ,
44 .Nm isa_dmamem_unmap ,
45 .Nm isa_malloc ,
46 .Nm isa_free ,
47 .Nm isa_dmastart ,
48 .Nm isa_dmaabort ,
49 .Nm isa_dmacount ,
50 .Nm isa_dmadone ,
51 .Nm isa_dmamaxsize ,
52 .Nm isa_drq_alloc ,
53 .Nm isa_drq_free ,
54 .Nm isa_drq_isfree ,
55 .Nm isa_dmacascade ,
56 .Nm isa_mappage
57 .Nd Industry-standard Architecture
58 .Sh SYNOPSIS
59 .In machine/bus.h
60 .In dev/isa/isareg.h
61 .In dev/isa/isavar.h
62 .Ft int
63 .Fn isa_intr_alloc "isa_chipset_tag_t ic" "int mask" "int type" \
64 "int *irq"
65 .Ft const struct evcnt *
66 .Fn isa_intr_evcnt "isa_chipset_tag_t ic" "int irq"
67 .Ft void *
68 .Fn isa_intr_establish "isa_chipset_tag_t ic" "int irq" "int type" \
69 "int level" "int (*handler)(void *)" "void *arg"
70 .Ft void
71 .Fn isa_intr_disestablish "isa_chipset_tag_t ic" "void *ih"
72 .In dev/isa/isadmareg.h
73 .In dev/isa/isadmavar.h
74 .Ft int
75 .Fn isa_dmamap_create "isa_chipset_tag_t ic" "int chan" "bus_size_t size" \
76 "int flags"
77 .Ft void
78 .Fn isa_dmamap_destroy "isa_chipset_tag_t ic" "int chan"
79 .Ft int
80 .Fn isa_dmamem_alloc "isa_chipset_tag_t ic" "int chan" "bus_size_t size" \
81 "bus_addr_t *addrp" "int flags"
82 .Ft void
83 .Fn isa_dmamem_free "isa_chipset_tag_t ic" "int chan" "bus_addr_t addr" \
84 "bus_size_t size"
85 .Ft int
86 .Fn isa_dmamem_map "isa_chipset_tag_t ic" "int chan" "bus_addr_t addr" \
87 "bus_size_t size" "void **kvap" "int flags"
88 .Ft void
89 .Fn isa_dmamem_unmap "isa_chipset_tag_t ic" "int chan" "void *kva" \
90 "size_t size"
91 .Ft void *
92 .Fn isa_malloc "isa_chipset_tag_t ic" "int chan" "size_t size" \
93 "int pool" "int flags"
94 .Ft void
95 .Fn isa_free "void *addrp" "int pool"
96 .Ft int
97 .Fn isa_dmastart "isa_chipset_tag_t ic" "int chan" "bus_addr_t addr" \
98 "bus_size_t size" "struct lwp *lwp" "int flags" "int bf"
99 .Ft void
100 .Fn isa_dmaabort "isa_chipset_tag_t ic" "int chan"
101 .Ft bus_size_t
102 .Fn isa_dmacount "isa_chipset_tag_t ic" "int chan"
103 .Ft void
104 .Fn isa_dmadone "isa_chipset_tag_t ic" "int chan"
105 .Ft bus_size_t
106 .Fn isa_dmamaxsize "isa_chipset_tag_t ic" "int chan"
107 .Ft int
108 .Fn isa_drq_alloc "isa_chipset_tag_t ic" "int chan"
109 .Ft int
110 .Fn isa_drq_free "isa_chipset_tag_t ic" "int chan"
111 .Ft int
112 .Fn isa_drq_isfree "isa_chipset_tag_t ic" "int chan"
113 .Ft int
114 .Fn isa_dmacascade "isa_chipset_tag_t ic" "int chan"
115 .Ft paddr_t
116 .Fn isa_mappage "void *mem" "off_t offset" "int prot"
117 .Sh DESCRIPTION
118 The machine-independent
119 .Nm
120 subsystem provides support for the ISA bus.
121 .Pp
122 The ISA bus was introduced on the IBM PC/AT.
123 It is an extension to the original bus found on the original IBM PC.
124 The ISA bus is essentially the host bus of the Intel 80286 processor,
125 however the widespread acceptance of the bus as a de facto standard has
126 seen it appear on systems without Intel processors.
127 .Pp
128 The ISA bus has a 16-bit data bus, a 24-bit memory address bus, a
129 16-bit I/O address bus, and operates at 8MHz.
130 It provides 15 interrupt lines and 8 DMA channels supporting DMA transfers
131 of 64KB or 128KB transfers depending on the width of the channel being used.
132 Historically, some devices only decoded the 10 lowest bits of
133 the I/O address bus, preventing use of the full 16-bit address space.
134 .Pp
135 On newer machines, the ISA bus is no longer connected directly to the
136 host bus, and is usually connected via a PCI-ISA bridge.
137 Either way, the bus looks the same to the device driver.
138 .Sh DATA TYPES
139 Drivers for devices attached to the
140 .Nm
141 bus will make use of the following data types:
142 .Bl -tag -width compact
143 .It Fa isa_chipset_tag_t
144 Chipset tag for the ISA bus.
145 .It Fa struct isa_attach_args
146 Location hints for devices are recorded in this structure.
147 It contains the following members:
148 .Bd -literal
149 bus_space_tag_t ia_iot; /* isa i/o space tag */
150 bus_space_tag_t ia_memt; /* isa mem space tag */
151 bus_dma_tag_t ia_dmat; /* DMA tag */
152 isa_chipset_tag_t ia_ic;
153 int ia_iobase; /* base i/o address */
154 int ia_iosize; /* span of ports used */
155 int ia_maddr; /* physical mem addr */
156 u_int ia_msize; /* size of memory */
157 int ia_irq; /* interrupt request */
158 int ia_drq; /* DMA request */
159 int ia_drq2; /* second DMA request */
160 void *ia_aux; /* driver specific */
161 .Ed
162 .El
163 .Sh FUNCTIONS
164 .Bl -tag -width compact
165 .It Fn isa_intr_alloc "ic" "mask" "type" "irq"
166 This function is generally not required by device drivers.
167 It is used by bridges attaching other busses to the ISA bus.
168 .It Fn isa_intr_evcnt "ic" "irq"
169 Returns the event counter associated with interrupt line
170 .Fa irq .
171 .It Fn isa_intr_establish "ic" "irq" "type" "level" "handler" "arg"
172 To establish an ISA interrupt handler, a driver calls
173 .Fn isa_intr_establish
174 with the interrupt number
175 .Fa irq ,
176 type
177 .Fa type ,
178 and level
179 .Fa level .
180 When the interrupt occurs the function
181 .Fa handler
182 is called with argument
183 .Fa arg .
184 Valid values for
185 .Fa type
186 are:
187 .Bl -tag -width compact
188 .It IST_NONE
189 Reserve interrupt, but don't actually establish.
190 .It IST_EDGE
191 Edge-triggered interrupt.
192 .It IST_LEVEL
193 Level-triggered interrupt.
194 .It IST_PULSE
195 Pulse-triggered interrupt.
196 .El
197 .Pp
198 .Fn isa_intr_establish
199 returns an opaque handle to an event descriptor if it succeeds, and
200 returns NULL on failure.
201 .Pp
202 .It Fn isa_intr_disestablish "ic" "ih"
203 Dis-establish the interrupt handler with handle
204 .Fa ih .
205 The handle was returned from
206 .Fn isa_intr_establish .
207 .It Fn isa_drq_alloc "ic" "chan"
208 Reserves the DMA channel
209 .Fa chan
210 for future use.
211 Normally, this call precedes an
212 .Fn isa_dmamap_create
213 call.
214 It is an error to start DMA on a channel that has not been reserved with
215 .Fn isa_drq_alloc .
216 .It Fn isa_drq_free "ic" "chan"
217 Marks the DMA channel
218 .Fa chan
219 as available again.
220 .It Fn isa_dmamap_create "ic" "chan" "size" "flags"
221 Creates a DMA map for channel
222 .Fa chan .
223 It is initialised to accept maximum DMA transfers of size
224 .Fa size .
225 Valid values for the
226 .Fa flags
227 argument are the same as for
228 .Fn bus_dmamap_create
229 (see
230 .Xr bus_dma 9 ) .
231 This function returns zero on success or an error value on failure.
232 .It Fn isa_dmamap_destroy "ic" "chan"
233 Destroy the DMA map for DMA channel
234 .Fa chan .
235 .It Fn isa_dmamem_alloc "ic" "chan" "size" "addrp" "flags"
236 Allocate DMA-safe memory of size
237 .Fa size
238 for channel
239 .Fa chan .
240 Valid values for the
241 .Fa flags
242 argument are the same as for
243 .Fn bus_dmamem_alloc
244 (see
245 .Xr bus_dma 9 ) .
246 The bus-address of the memory is returned in
247 .Fa addrp .
248 This function returns zero on success or an error value on failure.
249 .It Fn isa_dmamem_free "ic" "chan" "addr" "size"
250 Frees memory previously allocated by
251 .Fn isa_dmamem_alloc
252 for channel
253 .Fa chan .
254 The bus-address and size of the memory are specified by
255 .Fa addr
256 and
257 .Fa size
258 respectively.
259 .It Fn isa_dmamem_map "ic" "chan" "addr" "size" "kvap" "flags"
260 Maps DMA-safe memory (allocated with
261 .Fn isa_dmamem_alloc )
262 specified by bus-address
263 .Fa addr
264 and of size
265 .Fa size
266 into kernel virtual address space for DMA channel
267 .Fa chan .
268 Valid values for the
269 .Fa flags
270 argument are the same as for
271 .Fn bus_dmamem_map
272 (see
273 .Xr bus_dma 9 ) .
274 The kernel virtual address is returned in
275 .Fa kvap .
276 This function returns zero on success or an error value on failure.
277 .It Fn isa_dmamem_unmap "ic" "chan" "kva" "size"
278 Unmaps memory (previously mapped with
279 .Fn isa_dmamem_map )
280 of size
281 .Fa size
282 for channel
283 .Fa chan .
284 The kernel virtual address space used by the mapping is freed.
285 .It Fn isa_malloc "ic" "chan" "size" "pool" "flags"
286 This function is a shortcut for allocating and mapping DMA-safe memory
287 in a single step.
288 The arguments correspond with the arguments to
289 .Fn isa_dmamem_alloc
290 and
291 .Fn isa_dmamem_map .
292 The argument
293 .Fa pool
294 is a pool to record the memory allocation.
295 This function returns a pointer to the DMA-safe memory.
296 .It Fn isa_free "addrp" "pool"
297 This function is a shortcut for unmapping and deallocating DMA-safe
298 memory in a single step.
299 It replaces
300 .Fn isa_dmamem_unmap
301 and
302 .Fn isa_dmamem_free .
303 The argument
304 .Fa addrp
305 is the pointer to the DMA-safe memory returned by
306 .Fn isa_malloc .
307 The argument
308 .Fa pool
309 is the same as the value passed to
310 .Fn isa_malloc .
311 .It Fn isa_dmastart "ic" "chan" "addr" "size" "lwp" "flags" "bf"
312 Load DMA memory specified by address
313 .Fa addr
314 of size
315 .Fa size
316 into the DMA controller at channel
317 .Fa chan
318 and set it in motion.
319 The argument
320 .Fa lwp
321 is used to indicate the address space in which the buffer is located.
322 If NULL, the buffer is assumed to be in kernel space.
323 Otherwise, the buffer is assumed to be in lwp
324 .Fa lwp 's
325 address space.
326 The argument
327 .Fa flags
328 describes the type of ISA DMA.
329 Valid values are:
330 .Bl -tag -width compact
331 .It DMAMODE_WRITE
332 DMA transfer from host to device.
333 .It DMAMODE_READ
334 DMA transfer to host from device.
335 .It DMAMODE_SINGLE
336 Transfer buffer once and stop.
337 .It DMAMODE_DEMAND
338 Demand mode.
339 .It DMAMODE_LOOP
340 Transfer buffer continuously in loop until notified to stop.
341 .It DMAMODE_LOOPDEMAND
342 Transfer buffer continuously in loop and demand mode.
343 .El
344 .Pp
345 The argument
346 .Fa bf
347 is the bus-space flags.
348 Valid values are the same as for
349 .Fn bus_dmamap_load
350 (see
351 .Xr bus_dma 9 ) .
352 .It Fn isa_dmaabort "ic" "chan"
353 Abort a DMA transfer on channel
354 .Fa chan .
355 .It Fn isa_dmacount "ic" "chan"
356 Returns the offset in the DMA memory of the current DMA transfer on
357 channel
358 .Fa chan .
359 .It Fn isa_dmadone "ic" "chan"
360 Unloads the DMA memory
361 on channel
362 .Fa chan
363 after a DMA transfer has completed.
364 .It Fn isa_dmamaxsize "ic" "chan"
365 Returns the maximum allowable DMA transfer size for channel
366 .Fa chan .
367 .It Fn isa_drq_isfree "ic" "chan"
368 If the
369 .Fa ia_drq
370 or
371 .Fa ia_drq2
372 members of
373 .Fa struct isa_attach_args
374 are wildcarded, then the driver is expected to probe the hardware for
375 valid DMA channels.
376 In this case, the driver can check to see if the hardware-supported
377 DMA channel
378 .Fa chan
379 is available for use.
380 .It Fn isa_dmacascade "ic" "chan"
381 Programs the 8237 DMA controller channel
382 .Fa chan
383 to accept external DMA control by the device hardware.
384 .It Fn isa_mappage "mem" "offset" "prot"
385 Provides support for user
386 .Xr mmap 2 Ns 'ing
387 of DMA-safe memory.
388 .El
389 .Sh AUTOCONFIGURATION
390 The ISA bus is an indirect-connection bus.
391 During autoconfiguration each driver is required to probe the bus
392 for the presence of a device.
393 An ISA driver will receive a pointer to
394 .Fa struct isa_attach_args
395 hinting at "locations" on the ISA bus where the device may be located.
396 They should use the
397 .Em ia_iobase ,
398 .Em ia_iosize ,
399 .Em ia_maddr ,
400 and
401 .Em ia_msize
402 members.
403 Not all of these hints will be necessary; locators may be wildcarded
404 with IOBASEUNK and MADDRUNK for
405 .Em ia_iobase
406 and
407 .Em ia_maddr
408 respectively.
409 If a driver can probe the device for configuration information at default
410 locations, it may update the members of
411 .Fa struct isa_attach_args .
412 The IRQ and DMA locators can also be wildcarded with IRQUNK and DRQUNK
413 respectively.
414 .Pp
415 During the driver attach step, the I/O and memory address spaces
416 should be mapped (see
417 .Xr bus_space 9 ) .
418 .Sh DMA SUPPORT
419 Extensive DMA facilities are provided for the ISA bus.
420 A driver can use up to two DMA channels simultaneously.
421 The DMA channels allocated during autoconfiguration are passed to the
422 driver during the driver attach using the
423 .Fa ia_drq
424 and
425 .Fa ia_drq2
426 members of
427 .Fa struct isa_attach_args .
428 .Pp
429 Before allocating resources for DMA transfers on the ISA bus, a driver
430 should check the maximum allowable DMA transfer size for the DMA
431 channel using
432 .Fn isa_dmamaxsize .
433 .Pp
434 A DMA map should be created first using
435 .Fn isa_dmamap_create .
436 A DMA map describes how DMA memory is loaded into the DMA controllers.
437 Only DMA-safe memory can be used for DMA transfers.
438 DMA-safe memory is allocated using
439 .Fn isa_dmamem_alloc .
440 The memory allocated by
441 .Fn isa_dmamem_alloc
442 must now be mapped into kernel virtual address space by
443 .Fn isa_dmamem_map
444 so that it can be accessed by the driver.
445 .Pp
446 For a DMA transfer from the host to the device, the driver will fill
447 the DMA memory with the data to be transferred.
448 The DMA-transfer of the memory is started using
449 .Fn isa_dmastart
450 with
451 .Fa flags
452 containing DMAMODE_WRITE.
453 When the DMA transfer is completed, a call to
454 .Fn isa_dmadone
455 cleans up the DMA transfer by unloading the memory from the
456 controller.
457 .Pp
458 For a DMA transfer from the device to the host, the DMA-transfer is
459 started using
460 .Fn isa_dmastart
461 with
462 .Fa flags
463 containing DMAMODE_READ.
464 When the DMA transfer is completed, a call to
465 .Fn isa_dmadone
466 cleans up the DMA transfer by unloading the memory from the
467 controller.
468 The memory can now be access by the driver.
469 .Pp
470 When the DMA resources are no longer required they should be released
471 using
472 .Fn isa_dmamem_unmap ,
473 .Fn isa_dmamem_free
474 and
475 .Fn isa_dmamap_destroy .
476 .Sh CODE REFERENCES
477 This section describes places within the
478 .Nx
479 source tree where actual code implementing or using the
480 machine-independent ISA subsystem can be found.
481 All pathnames are relative to
482 .Pa /usr/src .
483 .Pp
484 The ISA subsystem itself is implemented within the files
485 .Pa sys/dev/isa/isa.c
486 and
487 .Pa sys/dev/isa/isadma.c .
488 .Sh SEE ALSO
489 .Xr isa 4 ,
490 .Xr autoconf 9 ,
491 .Xr bus_dma 9 ,
492 .Xr bus_space 9 ,
493 .Xr driver 9 ,
494 .Xr isapnp 9
495 .Sh HISTORY
496 The machine-independent
497 .Nm
498 subsystem appeared in
499 .Nx 1.2 .
500 .Sh BUGS
501 The previous behaviour of
502 .Fn isa_intr_establish
503 was to invoke
504 .Fn panic
505 on failure.
506 .Fn isa_intr_establish
507 now returns NULL on failure.
508 Some old drivers written for the former behaviour discard the return value.