xref: /netbsd-src/share/man/man9/isa.9 (revision 9a37c59cd70e745696f394973a56646ce4c9d814)
1.\"     $NetBSD: isa.9,v 1.20 2011/05/30 01:48:40 dyoung 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 sys/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
118The machine-independent
119.Nm
120subsystem provides support for the ISA bus.
121.Pp
122The ISA bus was introduced on the IBM PC/AT.
123It is an extension to the original bus found on the original IBM PC.
124The ISA bus is essentially the host bus of the Intel 80286 processor,
125however the widespread acceptance of the bus as a de facto standard has
126seen it appear on systems without Intel processors.
127.Pp
128The ISA bus has a 16-bit data bus, a 24-bit memory address bus, a
12916-bit I/O address bus, and operates at 8MHz.
130It provides 15 interrupt lines and 8 DMA channels supporting DMA transfers
131of 64KB or 128KB transfers depending on the width of the channel being used.
132Historically, some devices only decoded the 10 lowest bits of
133the I/O address bus, preventing use of the full 16-bit address space.
134.Pp
135On newer machines, the ISA bus is no longer connected directly to the
136host bus, and is usually connected via a PCI-ISA bridge.
137Either way, the bus looks the same to the device driver.
138.Sh DATA TYPES
139Drivers for devices attached to the
140.Nm
141bus will make use of the following data types:
142.Bl -tag -width compact
143.It Fa isa_chipset_tag_t
144Chipset tag for the ISA bus.
145.It Fa struct isa_attach_args
146Location hints for devices are recorded in this structure.
147It 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"
166This function is generally not required by device drivers.
167It is used by bridges attaching other busses to the ISA bus.
168.It Fn isa_intr_evcnt "ic" "irq"
169Returns the event counter associated with interrupt line
170.Fa irq .
171.It Fn isa_intr_establish "ic" "irq" "type" "level" "handler" "arg"
172To establish an ISA interrupt handler, a driver calls
173.Fn isa_intr_establish
174with the interrupt number
175.Fa irq ,
176type
177.Fa type ,
178and level
179.Fa level .
180When the interrupt occurs the function
181.Fa handler
182is called with argument
183.Fa arg .
184Valid values for
185.Fa type
186are:
187.Bl -tag -width compact
188.It IST_NONE
189Reserve interrupt, but don't actually establish.
190.It IST_EDGE
191Edge-triggered interrupt.
192.It IST_LEVEL
193Level-triggered interrupt.
194.It IST_PULSE
195Pulse-triggered interrupt.
196.El
197.Pp
198.Fn isa_intr_establish
199returns an opaque handle to an event descriptor if it succeeds, and
200returns NULL on failure.
201.Pp
202.It Fn isa_intr_disestablish "ic" "ih"
203Dis-establish the interrupt handler with handle
204.Fa ih .
205The handle was returned from
206.Fn isa_intr_establish .
207.It Fn isa_drq_alloc "ic" "chan"
208Reserves the DMA channel
209.Fa chan
210for future use.
211Normally, this call precedes an
212.Fn isa_dmamap_create
213call.
214It 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"
217Marks the DMA channel
218.Fa chan
219as available again.
220.It Fn isa_dmamap_create "ic" "chan" "size" "flags"
221Creates a DMA map for channel
222.Fa chan .
223It is initialised to accept maximum DMA transfers of size
224.Fa size .
225Valid values for the
226.Fa flags
227argument are the same as for
228.Fn bus_dmamap_create
229(see
230.Xr bus_dma 9 ) .
231This function returns zero on success or an error value on failure.
232.It Fn isa_dmamap_destroy "ic" "chan"
233Destroy the DMA map for DMA channel
234.Fa chan .
235.It Fn isa_dmamem_alloc "ic" "chan" "size" "addrp" "flags"
236Allocate DMA-safe memory of size
237.Fa size
238for channel
239.Fa chan .
240Valid values for the
241.Fa flags
242argument are the same as for
243.Fn bus_dmamem_alloc
244(see
245.Xr bus_dma 9 ) .
246The bus-address of the memory is returned in
247.Fa addrp .
248This function returns zero on success or an error value on failure.
249.It Fn isa_dmamem_free "ic" "chan" "addr" "size"
250Frees memory previously allocated by
251.Fn isa_dmamem_alloc
252for channel
253.Fa chan .
254The bus-address and size of the memory are specified by
255.Fa addr
256and
257.Fa size
258respectively.
259.It Fn isa_dmamem_map "ic" "chan" "addr" "size" "kvap" "flags"
260Maps DMA-safe memory (allocated with
261.Fn isa_dmamem_alloc )
262specified by bus-address
263.Fa addr
264and of size
265.Fa size
266into kernel virtual address space for DMA channel
267.Fa chan .
268Valid values for the
269.Fa flags
270argument are the same as for
271.Fn bus_dmamem_map
272(see
273.Xr bus_dma 9 ) .
274The kernel virtual address is returned in
275.Fa kvap .
276This function returns zero on success or an error value on failure.
277.It Fn isa_dmamem_unmap "ic" "chan" "kva" "size"
278Unmaps memory (previously mapped with
279.Fn isa_dmamem_map )
280of size
281.Fa size
282for channel
283.Fa chan .
284The kernel virtual address space used by the mapping is freed.
285.It Fn isa_malloc "ic" "chan" "size" "pool" "flags"
286This function is a shortcut for allocating and mapping DMA-safe memory
287in a single step.
288The arguments correspond with the arguments to
289.Fn isa_dmamem_alloc
290and
291.Fn isa_dmamem_map .
292The argument
293.Fa pool
294is a pool to record the memory allocation.
295This function returns a pointer to the DMA-safe memory.
296.It Fn isa_free "addrp" "pool"
297This function is a shortcut for unmapping and deallocating DMA-safe
298memory in a single step.
299It replaces
300.Fn isa_dmamem_unmap
301and
302.Fn isa_dmamem_free .
303The argument
304.Fa addrp
305is the pointer to the DMA-safe memory returned by
306.Fn isa_malloc .
307The argument
308.Fa pool
309is the same as the value passed to
310.Fn isa_malloc .
311.It Fn isa_dmastart "ic" "chan" "addr" "size" "lwp" "flags" "bf"
312Load DMA memory specified by address
313.Fa addr
314of size
315.Fa size
316into the DMA controller at channel
317.Fa chan
318and set it in motion.
319The argument
320.Fa lwp
321is used to indicate the address space in which the buffer is located.
322If NULL, the buffer is assumed to be in kernel space.
323Otherwise, the buffer is assumed to be in lwp
324.Fa lwp 's
325address space.
326The argument
327.Fa flags
328describes the type of ISA DMA.
329Valid values are:
330.Bl -tag -width compact
331.It DMAMODE_WRITE
332DMA transfer from host to device.
333.It DMAMODE_READ
334DMA transfer to host from device.
335.It DMAMODE_SINGLE
336Transfer buffer once and stop.
337.It DMAMODE_DEMAND
338Demand mode.
339.It DMAMODE_LOOP
340Transfer buffer continuously in loop until notified to stop.
341.It DMAMODE_LOOPDEMAND
342Transfer buffer continuously in loop and demand mode.
343.El
344.Pp
345The argument
346.Fa bf
347is the bus-space flags.
348Valid 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"
353Abort a DMA transfer on channel
354.Fa chan .
355.It Fn isa_dmacount "ic" "chan"
356Returns the offset in the DMA memory of the current DMA transfer on
357channel
358.Fa chan .
359.It Fn isa_dmadone "ic" "chan"
360Unloads the DMA memory
361on channel
362.Fa chan
363after a DMA transfer has completed.
364.It Fn isa_dmamaxsize "ic" "chan"
365Returns the maximum allowable DMA transfer size for channel
366.Fa chan .
367.It Fn isa_drq_isfree "ic" "chan"
368If the
369.Fa ia_drq
370or
371.Fa ia_drq2
372members of
373.Fa struct isa_attach_args
374are wildcarded, then the driver is expected to probe the hardware for
375valid DMA channels.
376In this case, the driver can check to see if the hardware-supported
377DMA channel
378.Fa chan
379is available for use.
380.It Fn isa_dmacascade "ic" "chan"
381Programs the 8237 DMA controller channel
382.Fa chan
383to accept external DMA control by the device hardware.
384.It Fn isa_mappage "mem" "offset" "prot"
385Provides support for user
386.Xr mmap 2 Ns 'ing
387of DMA-safe memory.
388.El
389.Sh AUTOCONFIGURATION
390The ISA bus is an indirect-connection bus.
391During autoconfiguration each driver is required to probe the bus
392for the presence of a device.
393An ISA driver will receive a pointer to
394.Fa struct isa_attach_args
395hinting at "locations" on the ISA bus where the device may be located.
396They should use the
397.Em ia_iobase ,
398.Em ia_iosize ,
399.Em ia_maddr ,
400and
401.Em ia_msize
402members.
403Not all of these hints will be necessary; locators may be wildcarded
404with IOBASEUNK and MADDRUNK for
405.Em ia_iobase
406and
407.Em ia_maddr
408respectively.
409If a driver can probe the device for configuration information at default
410locations, it may update the members of
411.Fa struct isa_attach_args .
412The IRQ and DMA locators can also be wildcarded with IRQUNK and DRQUNK
413respectively.
414.Pp
415During the driver attach step, the I/O and memory address spaces
416should be mapped (see
417.Xr bus_space 9 ) .
418.Sh DMA SUPPORT
419Extensive DMA facilities are provided for the ISA bus.
420A driver can use up to two DMA channels simultaneously.
421The DMA channels allocated during autoconfiguration are passed to the
422driver during the driver attach using the
423.Fa ia_drq
424and
425.Fa ia_drq2
426members of
427.Fa struct isa_attach_args .
428.Pp
429Before allocating resources for DMA transfers on the ISA bus, a driver
430should check the maximum allowable DMA transfer size for the DMA
431channel using
432.Fn isa_dmamaxsize .
433.Pp
434A DMA map should be created first using
435.Fn isa_dmamap_create .
436A DMA map describes how DMA memory is loaded into the DMA controllers.
437Only DMA-safe memory can be used for DMA transfers.
438DMA-safe memory is allocated using
439.Fn isa_dmamem_alloc .
440The memory allocated by
441.Fn isa_dmamem_alloc
442must now be mapped into kernel virtual address space by
443.Fn isa_dmamem_map
444so that it can be accessed by the driver.
445.Pp
446For a DMA transfer from the host to the device, the driver will fill
447the DMA memory with the data to be transferred.
448The DMA-transfer of the memory is started using
449.Fn isa_dmastart
450with
451.Fa flags
452containing DMAMODE_WRITE.
453When the DMA transfer is completed, a call to
454.Fn isa_dmadone
455cleans up the DMA transfer by unloading the memory from the
456controller.
457.Pp
458For a DMA transfer from the device to the host, the DMA-transfer is
459started using
460.Fn isa_dmastart
461with
462.Fa flags
463containing DMAMODE_READ.
464When the DMA transfer is completed, a call to
465.Fn isa_dmadone
466cleans up the DMA transfer by unloading the memory from the
467controller.
468The memory can now be access by the driver.
469.Pp
470When the DMA resources are no longer required they should be released
471using
472.Fn isa_dmamem_unmap ,
473.Fn isa_dmamem_free
474and
475.Fn isa_dmamap_destroy .
476.Sh CODE REFERENCES
477The ISA subsystem itself is implemented within the files
478.Pa sys/dev/isa/isa.c
479and
480.Pa sys/dev/isa/isadma.c .
481.Sh SEE ALSO
482.Xr isa 4 ,
483.Xr autoconf 9 ,
484.Xr bus_dma 9 ,
485.Xr bus_space 9 ,
486.Xr driver 9 ,
487.Xr isapnp 9
488.Sh HISTORY
489The machine-independent
490.Nm
491subsystem appeared in
492.Nx 1.2 .
493.Sh BUGS
494The previous behaviour of
495.Fn isa_intr_establish
496was to invoke
497.Fn panic
498on failure.
499.Fn isa_intr_establish
500now returns NULL on failure.
501Some old drivers written for the former behaviour discard the return value.
502