| blob | 569dd406c2382c0fffd7958d7ec91b1d33071f04 |
1 .\" $NetBSD: ioasic.9,v 1.9 2005/12/26 19:48:12 perry Exp $
2 .\"
3 .\" Copyright (c) 2000 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 August 6, 2000
31 .Dt IOASIC 9
32 .Os
33 .Sh NAME
34 .Nm IOASIC ,
35 .Nm ioasic_intr_establish ,
36 .Nm ioasic_intr_disestablish ,
37 .Nm ioasic_intr_evcnt ,
38 .Nm ioasic_attach_devs ,
39 .Nm ioasic_submatch
40 .Nd baseboard I/O control ASIC for DEC TURBOchannel systems
41 .Sh SYNOPSIS
42 .In machine/bus.h
43 .In dev/tc/tcvar.h
44 .In dev/tc/ioasicreg.h
45 .In dev/tc/ioasicvar.h
46 .Ft void
47 .Fn ioasic_intr_establish "struct device *dev" "void *cookie" "int level" \
48 "int (*handler)(void *)" "void *arg"
49 .Ft void
50 .Fn ioasic_intr_disestablish "struct device *dev" "void *cookie"
51 .Ft const struct evcnt *
52 .Fn ioasic_intr_evcnt "struct device *dev" "void *cookie"
53 .Ft void
54 .Fn ioasic_attach_devs "struct ioasic_softc *sc" \
55 "struct ioasic_dev *ioasic_devs" "int ioasic_ndevs"
56 .Ft int
57 .Fn ioasic_submatch "struct cfdata *match" "struct ioasicdev_attach_args *ia"
58 .Sh DESCRIPTION
59 The
60 .Nm
61 device provides support for the DEC proprietary IOCTL ASIC found on
62 all DEC TURBOchannel machines with MIPS (DECstation 5000 series,
63 excluding the 5000/200) and Alpha (3000-series) systems.
64 The
65 .Nm
66 is memory-mapped into the TURBOchannel system slot to interface up to
67 sixteen I/O devices.
68 It connects the TURBOchannel to a 16-bit wide I/O bus and supplies
69 various control signals to the devices that share this bus.
70 .Pp
71 The
72 .Nm
73 provides hardware DMA channels and interrupt support.
74 DMA transfers are between one and four 32-bit words (16 bytes) in
75 length, depending on the device.
76 The
77 .Nm
78 stores the data in internal data registers.
79 The data is transferred to and from the registers in 16-bit words
80 to the device.
81 Various interrupts are signalled on DMA pointer-related conditions.
82 .Sh DATA TYPES
83 Drivers for devices attached to the
84 .Nm
85 will make use of the following data types:
86 .Bl -tag -width compact
87 .It Fa struct ioasicdev_attach_args
88 A structure used to inform the driver of the
89 .Nm
90 device properties.
91 It contains the following members:
92 .Bd -literal
93 char iada_modname
94 tc_offset_t iada_offset
95 tc_addr_t iada_addr
96 void *iada_cookie;
97 .Ed
98 .It Fa struct ioasic_softc
99 The parent structure which contains at the following members which are
100 useful for drivers:
101 .Bd -literal
102 bus_space_tag_t sc_bst;
103 bus_space_handle_t sc_bsh;
104 bus_dma_tag_t sc_dmat;
105 .Ed
106 .It Fa struct ioasic_dev
107 A structure describing the machine-dependent devices attached to the
108 .Nm
109 containing the following members:
110 .Bd -literal
111 char *iad_modname;
112 tc_offset_t iad_offset;
113 void *iad_cookie;
114 uint32_t iad_intrbits;
115 .Ed
116 .El
117 .Sh FUNCTIONS
118 .Bl -tag -width compact
119 .It Fn ioasic_intr_establish "dev" "cookie" "level" "handler" "arg"
120 Establish an interrupt handler with device
121 .Fa dev
122 for the interrupt described completely by
123 .Fa cookie .
124 The priority of the interrupt is specified by
125 .Fa level .
126 When the interrupt occurs the function
127 .Fa handler
128 is called with argument
129 .Fa arg .
130 .It Fn ioasic_intr_disestablish "dev" "cookie"
131 Dis-establish the interrupt handler with device
132 .Fa dev
133 for the interrupt described complete ly
134 .Fa cookie .
135 .It Fn ioasic_intr_evcnt "dev" "cookie"
136 Do interrupt event counting with device
137 .Fa dev
138 for the event described completely by
139 .Fa cookie .
140 .It Fn ioasic_attach_devs "sc" "ioasic_devs" "ioasic_ndevs"
141 Configure each of the
142 .Fa ioasic_ndevs
143 devices in
144 .Fa ioasic_devs .
145 .It Fn ioasic_submatch "match" "ia"
146 Check that the device offset is not OASIC_OFFSET_UNKNOWN.
147 .El
148 .Pp
149 The
150 .Fn ioasic_intr_establish ,
151 .Fn ioasic_intr_disestablish ,
152 and
153 .Fn ioasic_intr_evcnt
154 functions are likely to used by all
155 .Nm
156 device drivers.
157 The
158 .Fn ioasic_attach_devs
159 function is used by ioasic driver internally and is of interest to
160 driver writers because it must be aware of your device for it to be
161 found during autoconfiguration.
162 .Sh AUTOCONFIGURATION
163 The IOASIC is a direct-connection bus.
164 During autoconfiguration, machine-dependent code will provide an array of
165 .Fa struct ioasic_devs
166 describing devices attached to the
167 .Nm
168 to be used by the ioasic driver.
169 The ioasic driver will pass this array to
170 .Fn ioasic_attach_devs
171 to attach the drivers with the devices.
172 .Pp
173 Drivers match the device using
174 .Fa iada_modname .
175 .Pp
176 During attach, all drivers should use the parent's bus_space and
177 bus_dma resources, and map the appropriate bus_space region using
178 .Fn bus_space_subregion
179 with
180 .Fa iada_offset .
181 .Sh DMA SUPPORT
182 No additional support is provided for
183 .Nm
184 DMA beyond the facilities provided by the
185 .Xr bus_dma 9
186 interface.
187 .Pp
188 The
189 .Nm
190 provides two pairs of DMA address pointers (transmitting and
191 receiving) for each DMA-capable device.
192 The pair of address pointers point to consecutive (but not necessarily
193 contiguous) DMA blocks of size IOASIC_DMA_BLOCKSIZE.
194 Upon successful transfer of the first block, DMA continues to the next
195 block and an interrupt is posted to signal an address pointer update.
196 DMA transfers are enabled and disabled by bits inside the
197 .Nm
198 status (CSR) register.
199 .Pp
200 The interrupt handler must update the address pointers to point to the
201 next block in the DMA transfer.
202 The address pointer update must be completed before the completion of
203 the second DMA block, otherwise a DMA overrun error condition will occur.
204 .Sh CODE REFERENCES
205 This section describes places within the
206 .Nx
207 source tree where actual code implementing or using the
208 machine-independent IOASIC subsystem can be found.
209 All pathnames are relative to
210 .Pa /usr/src .
211 .Pp
212 The IOASIC subsystem itself is implemented within the file
213 .Pa sys/dev/tc/ioasic_subr.c .
214 Machine-dependent portions can be found in
215 .Pa sys/arch/\*[Lt]arch\*[Gt]/tc/ioasic.c .
216 .Sh SEE ALSO
217 .Xr ioasic 4 ,
218 .Xr autoconf 9 ,
219 .Xr bus_dma 9 ,
220 .Xr bus_space 9 ,
221 .Xr driver 9