1.\" $NetBSD: ioasic.9,v 1.13 2017/07/03 21:28:48 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.\" 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 sys/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 59The 60.Nm 61device provides support for the DEC proprietary IOCTL ASIC found on 62all DEC TURBOchannel machines with MIPS (DECstation 5000 series, 63excluding the 5000/200) and Alpha (3000-series) systems. 64The 65.Nm 66is memory-mapped into the TURBOchannel system slot to interface up to 67sixteen I/O devices. 68It connects the TURBOchannel to a 16-bit wide I/O bus and supplies 69various control signals to the devices that share this bus. 70.Pp 71The 72.Nm 73provides hardware DMA channels and interrupt support. 74DMA transfers are between one and four 32-bit words (16 bytes) in 75length, depending on the device. 76The 77.Nm 78stores the data in internal data registers. 79The data is transferred to and from the registers in 16-bit words 80to the device. 81Various interrupts are signalled on DMA pointer-related conditions. 82.Sh DATA TYPES 83Drivers for devices attached to the 84.Nm 85will make use of the following data types: 86.Bl -tag -width compact 87.It Fa struct ioasicdev_attach_args 88A structure used to inform the driver of the 89.Nm 90device properties. 91It 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 99The parent structure which contains at the following members which are 100useful 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 107A structure describing the machine-dependent devices attached to the 108.Nm 109containing 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" 120Establish an interrupt handler with device 121.Fa dev 122for the interrupt described completely by 123.Fa cookie . 124The priority of the interrupt is specified by 125.Fa level . 126When the interrupt occurs the function 127.Fa handler 128is called with argument 129.Fa arg . 130.It Fn ioasic_intr_disestablish "dev" "cookie" 131Dis-establish the interrupt handler with device 132.Fa dev 133for the interrupt described complete ly 134.Fa cookie . 135.It Fn ioasic_intr_evcnt "dev" "cookie" 136Do interrupt event counting with device 137.Fa dev 138for the event described completely by 139.Fa cookie . 140.It Fn ioasic_attach_devs "sc" "ioasic_devs" "ioasic_ndevs" 141Configure each of the 142.Fa ioasic_ndevs 143devices in 144.Fa ioasic_devs . 145.It Fn ioasic_submatch "match" "ia" 146Check that the device offset is not OASIC_OFFSET_UNKNOWN. 147.El 148.Pp 149The 150.Fn ioasic_intr_establish , 151.Fn ioasic_intr_disestablish , 152and 153.Fn ioasic_intr_evcnt 154functions are likely to used by all 155.Nm 156device drivers. 157The 158.Fn ioasic_attach_devs 159function is used by ioasic driver internally and is of interest to 160driver writers because it must be aware of your device for it to be 161found during autoconfiguration. 162.Sh AUTOCONFIGURATION 163The IOASIC is a direct-connection bus. 164During autoconfiguration, machine-dependent code will provide an array of 165.Fa struct ioasic_devs 166describing devices attached to the 167.Nm 168to be used by the ioasic driver. 169The ioasic driver will pass this array to 170.Fn ioasic_attach_devs 171to attach the drivers with the devices. 172.Pp 173Drivers match the device using 174.Fa iada_modname . 175.Pp 176During attach, all drivers should use the parent's bus_space and 177bus_dma resources, and map the appropriate bus_space region using 178.Fn bus_space_subregion 179with 180.Fa iada_offset . 181.Sh DMA SUPPORT 182No additional support is provided for 183.Nm 184DMA beyond the facilities provided by the 185.Xr bus_dma 9 186interface. 187.Pp 188The 189.Nm 190provides two pairs of DMA address pointers (transmitting and 191receiving) for each DMA-capable device. 192The pair of address pointers point to consecutive (but not necessarily 193contiguous) DMA blocks of size IOASIC_DMA_BLOCKSIZE. 194Upon successful transfer of the first block, DMA continues to the next 195block and an interrupt is posted to signal an address pointer update. 196DMA transfers are enabled and disabled by bits inside the 197.Nm 198status (CSR) register. 199.Pp 200The interrupt handler must update the address pointers to point to the 201next block in the DMA transfer. 202The address pointer update must be completed before the completion of 203the second DMA block, otherwise a DMA overrun error condition will occur. 204.Sh CODE REFERENCES 205The IOASIC subsystem itself is implemented within the file 206.Pa sys/dev/tc/ioasic_subr.c . 207Machine-dependent portions can be found in 208.Pa sys/arch/<arch>/tc/ioasic.c . 209.Sh SEE ALSO 210.Xr ioasic 4 , 211.Xr autoconf 9 , 212.Xr bus_dma 9 , 213.Xr bus_space 9 , 214.Xr driver 9 215