1.\" $NetBSD: ioasic.9,v 1.6 2002/10/14 13:34:41 wiz 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd August 6, 2000 38.Dt IOASIC 9 39.Os 40.Sh NAME 41.Nm IOASIC , 42.Nm ioasic_intr_establish , 43.Nm ioasic_intr_disestablish , 44.Nm ioasic_intr_evcnt , 45.Nm ioasic_attach_devs , 46.Nm ioasic_submatch 47.Nd baseboard I/O control ASIC for DEC TURBOchannel systems 48.Sh SYNOPSIS 49.Fd #include \*[Lt]machine/bus.h\*[Gt] 50.Fd #include \*[Lt]dev/tc/tcvar.h\*[Gt] 51.Fd #include \*[Lt]dev/tc/ioasicreg.h\*[Gt] 52.Fd #include \*[Lt]dev/tc/ioasicvar.h\*[Gt] 53.Ft void 54.Fn ioasic_intr_establish "struct device *dev" "void *cookie" "int level" \ 55"int (*handler)(void *)" "void *arg" 56.Ft void 57.Fn ioasic_intr_disestablish "struct device *dev" "void *cookie" 58.Ft const struct evcnt * 59.Fn ioasic_intr_evcnt "struct device *dev" "void *cookie" 60.Ft void 61.Fn ioasic_attach_devs "struct ioasic_softc *sc" \ 62"struct ioasic_dev *ioasic_devs" "int ioasic_ndevs" 63.Ft int 64.Fn ioasic_submatch "struct cfdata *match" "struct ioasicdev_attach_args *ia" 65.Sh DESCRIPTION 66The 67.Nm 68device provides support for the DEC proprietary IOCTL ASIC found on 69all DEC TURBOchannel machines with MIPS (DECstation 5000 series, 70excluding the 5000/200) and Alpha (3000-series) systems. 71The 72.Nm 73is memory-mapped into the TURBOchannel system slot to interface up to 74sixteen I/O devices. 75It connects the TURBOchannel to a 16-bit wide I/O bus and supplies 76various control signals to the devices that share this bus. 77.Pp 78The 79.Nm 80provides hardware DMA channels and interrupt support. 81DMA transfers are between one and four 32-bit words (16 bytes) in 82length, depending on the device. 83The 84.Nm 85stores the data in internal data registers. 86The data is transferred to and from the registers in 16-bit words 87to the device. 88Various interrupts are signalled on DMA pointer-related conditions. 89.Sh DATA TYPES 90Drivers for devices attached to the 91.Nm 92will make use of the following data types: 93.Bl -tag -width compact 94.It Fa struct ioasicdev_attach_args 95A structure used to inform the driver of the 96.Nm 97device properties. 98It contains the following members: 99.Bd -literal 100 char iada_modname 101 tc_offset_t iada_offset 102 tc_addr_t iada_addr 103 void *iada_cookie; 104.Ed 105.It Fa struct ioasic_softc 106The parent structure which contains at the following members which are 107useful for drivers: 108.Bd -literal 109 bus_space_tag_t sc_bst; 110 bus_space_handle_t sc_bsh; 111 bus_dma_tag_t sc_dmat; 112.Ed 113.It Fa struct ioasic_dev 114A structure describing the machine-dependent devices attached to the 115.Nm 116containing the following members: 117.Bd -literal 118 char *iad_modname; 119 tc_offset_t iad_offset; 120 void *iad_cookie; 121 u_int32_t iad_intrbits; 122.Ed 123.El 124.Sh FUNCTIONS 125.Bl -tag -width compact 126.It Fn ioasic_intr_establish "dev" "cookie" "level" "handler" "arg" 127Establish an interrupt handler with device 128.Fa dev 129for the interrupt described completely by 130.Fa cookie . 131The priority of the interrupt is specified by 132.Fa level . 133When the interrupt occurs the function 134.Fa handler 135is called with argument 136.Fa arg . 137.It Fn ioasic_intr_disestablish "dev" "cookie" 138Dis-establish the interrupt handler with device 139.Fa dev 140for the interrupt described complete ly 141.Fa cookie . 142.It Fn ioasic_intr_evcnt "dev" "cookie" 143Do interrupt event counting with device 144.Fa dev 145for the event described completely by 146.Fa cookie . 147.It Fn ioasic_attach_devs "sc" "ioasic_devs" "ioasic_ndevs" 148Configure each of the 149.Fa ioasic_ndevs 150devices in 151.Fa ioasic_devs . 152.It Fn ioasic_submatch "match" "ia" 153Check that the device offset is not OASIC_OFFSET_UNKNOWN. 154.El 155.Pp 156The 157.Fn ioasic_intr_establish , 158.Fn ioasic_intr_disestablish , 159and 160.Fn ioasic_intr_evcnt 161functions are likely to used by all 162.Nm 163device drivers. 164The 165.Fn ioasic_attach_devs 166function is used by ioasic driver internally and is of interest to 167driver writers because it must be aware of your device for it to be 168found during autoconfiguration. 169.Sh AUTOCONFIGURATION 170The IOASIC is a direct-connection bus. 171During autoconfiguration, machine-dependent code will provide an array of 172.Fa struct ioasic_devs 173describing devices attached to the 174.Nm 175to be used by the ioasic driver. 176The ioasic driver will pass this array to 177.Fn ioasic_attach_devs 178to attach the drivers with the devices. 179.Pp 180Drivers match the device using 181.Fa iada_modname . 182.Pp 183During attach, all drivers should use the parent's bus_space and 184bus_dma resources, and map the appropriate bus_space region using 185.Fn bus_space_subregion 186with 187.Fa iada_offset . 188.Sh DMA SUPPORT 189No additional support is provided for 190.Nm 191DMA beyond the facilities provided by the 192.Xr bus_dma 9 193interface. 194.Pp 195The 196.Nm 197provides two pairs of DMA address pointers (transmitting and 198receiving) for each DMA-capable device. 199The pair of address pointers point to consecutive (but not necessarily 200contiguous) DMA blocks of size IOASIC_DMA_BLOCKSIZE. 201Upon successful transfer of the first block, DMA continues to the next 202block and an interrupt is posted to signal an address pointer update. 203DMA transfers are enabled and disabled by bits inside the 204.Nm 205status (CSR) register. 206.Pp 207The interrupt handler must update the address pointers to point to the 208next block in the DMA transfer. 209The address pointer update must be completed before the completion of 210the second DMA block, otherwise a DMA overrun error condition will occur. 211.Sh CODE REFERENCES 212This section describes places within the 213.Nx 214source tree where actual code implementing or utilising the 215machine-independent IOASIC subsystem can be found. 216All pathnames are relative to 217.Pa /usr/src . 218.Pp 219The IOASIC subsystem itself is implemented within the file 220.Pa sys/dev/tc/ioasic_subr.c . 221Machine-dependent portions can be found in 222.Pa sys/arch/\*[Lt]arch\*[Gt]/tc/ioasic.c . 223.Sh SEE ALSO 224.Xr ioasic 4 , 225.Xr autoconf 9 , 226.Xr bus_dma 9 , 227.Xr bus_space 9 , 228.Xr driver 9 229