man/man9/ioasic.9

.\"     $NetBSD: ioasic.9,v 1.5 2002/02/13 08:18:42 ross Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 6, 2000
.Dt IOASIC 9
.Os
.Sh NAME
.Nm IOASIC ,
.Nm ioasic_intr_establish ,
.Nm ioasic_intr_disestablish ,
.Nm ioasic_intr_evcnt ,
.Nm ioasic_attach_devs ,
.Nm ioasic_submatch
.Nd baseboard I/O control ASIC for DEC TURBOchannel systems
.Sh SYNOPSIS
.Fd #include \*[Lt]machine/bus.h\*[Gt]
.Fd #include \*[Lt]dev/tc/tcvar.h\*[Gt]
.Fd #include \*[Lt]dev/tc/ioasicreg.h\*[Gt]
.Fd #include \*[Lt]dev/tc/ioasicvar.h\*[Gt]
.Ft void
.Fn ioasic_intr_establish "struct device *dev" "void *cookie" "int level" \
"int (*handler)(void *)" "void *arg"
.Ft void
.Fn ioasic_intr_disestablish "struct device *dev" "void *cookie"
.Ft const struct evcnt *
.Fn ioasic_intr_evcnt "struct device *dev" "void *cookie"
.Ft void
.Fn ioasic_attach_devs "struct ioasic_softc *sc" \
"struct ioasic_dev *ioasic_devs" "int ioasic_ndevs"
.Ft int
.Fn ioasic_submatch "struct cfdata *match" "struct ioasicdev_attach_args *ia"
.Sh DESCRIPTION
The
.Nm
device provides support for the DEC proprietary IOCTL ASIC found on
all DEC TURBOchannel machines with MIPS (DECstation 5000 series,
excluding the 5000/200) and Alpha (3000-series) systems.  The
.Nm
is memory-mapped into the TURBOchannel system slot to interface up to
sixteen I/O devices.  It connects the TURBOchannel to a 16-bit wide
I/O bus and supplies various control signals to the devices that share
this bus.
.Pp
The
.Nm
provides hardware DMA channels and interrupt support.  DMA transfers
are between one and four 32-bit words (16 bytes) in length, depending
on the device.  The
.Nm
stores the data in internal data registers.  The data is transferred
to and from the registers in 16-bit words to the device.  Various
interrupts are signalled on DMA pointer-related conditions.
.Sh DATA TYPES
Drivers for devices attached to the
.Nm
will make use of the following data types:
.Bl -tag -width compact
.It Fa struct ioasicdev_attach_args
A structure used to inform the driver of the
.Nm
device properties.  It contains the following members:
.Bd -literal
	char			iada_modname
	tc_offset_t		iada_offset
	tc_addr_t		iada_addr
	void			*iada_cookie;
.Ed
.It Fa struct ioasic_softc
The parent structure which contains at the following members which are
useful for drivers:
.Bd -literal
	bus_space_tag_t		sc_bst;
	bus_space_handle_t	sc_bsh;
	bus_dma_tag_t		sc_dmat;
.Ed
.It Fa struct ioasic_dev
A structure describing the machine-dependent devices attached to the
.Nm
containing the following members:
.Bd -literal
	char			*iad_modname;
	tc_offset_t		iad_offset;
	void			*iad_cookie;
	u_int32_t		iad_intrbits;
.Ed
.El
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn ioasic_intr_establish "dev" "cookie" "level" "handler" "arg"
Establish an interrupt handler with device
.Fa dev
for the interrupt described completely by
.Fa cookie .
The priority of the interrupt is specified by
.Fa level .
When the interrupt occurs the function
.Fa handler
is called with argument
.Fa arg .
.It Fn ioasic_intr_disestablish "dev" "cookie"
Dis-establish the interrupt handler with device
.Fa dev
for the interrupt described complete ly
.Fa cookie .
.It Fn ioasic_intr_evcnt "dev" "cookie"
Do interrupt event counting with device
.Fa dev
for the event described completely by
.Fa cookie .
.It Fn ioasic_attach_devs "sc" "ioasic_devs" "ioasic_ndevs"
Configure each of the
.Fa ioasic_ndevs
devices in
.Fa ioasic_devs .
.It Fn ioasic_submatch "match" "ia"
Check that the device offset is not OASIC_OFFSET_UNKNOWN.
.El
.Pp
The
.Fn ioasic_intr_establish ,
.Fn ioasic_intr_disestablish ,
and
.Fn ioasic_intr_evcnt
functions are likely to used by all
.Nm
device drivers.  The
.Fn ioasic_attach_devs
function is used by ioasic driver internally and is of interest to
driver writers because it must be aware of your device for it to be
found during autoconfiguration.
.Sh AUTOCONFIGURATION
The IOASIC is a direct-connection bus.  During autoconfiguration,
machine-dependent code will provide an array of
.Fa struct ioasic_devs
describing devices attached to the
.Nm
to be used by the ioasic driver.  The ioasic driver will pass this array to
.Fn ioasic_attach_devs
to attach the drivers with the devices.
.Pp
Drivers match the device using
.Fa iada_modname .
.Pp
During attach, all drivers should use the parent's bus_space and
bus_dma resources, and map the appropriate bus_space region using
.Fn bus_space_subregion
with
.Fa iada_offset .
.Sh DMA SUPPORT
No additional support is provided for
.Nm
DMA beyond the facilities provided by the
.Xr bus_dma 9
interface.
.Pp
The
.Nm
provides two pairs of DMA address pointers (transmitting and
receiving) for each DMA-capable device.  The pair of address pointers
point to consecutive (but not necesarily contiguous) DMA blocks of
size IOASIC_DMA_BLOCKSIZE.  Upon successful transfer of the first
block, DMA continues to the next block and an interrupt is posted to
signal an address pointer update.  DMA transfers are enabled and
disabled by bits inside the
.Nm
status (CSR) register.
.Pp
The interrupt handler must update the address pointers to point to the
next block in the DMA transfer.  The address pointer update must be
completed before the completion of the second DMA block, otherwise a
DMA overrun error condition will occur.
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent IOASIC subsystem can be found.  All pathnames are
relative to
.Pa /usr/src .
.Pp
The IOASIC subsystem itself is implemented within the file
.Pa sys/dev/tc/ioasic_subr.c .
Machine-dependent portions can be found in
.Pa sys/arch/\*[Lt]arch\*[Gt]/tc/ioasic.c .
.Sh SEE ALSO
.Xr ioasic 4 ,
.Xr autoconf 9 ,
.Xr bus_dma 9 ,
.Xr bus_space 9 ,
.Xr driver 9