472351e13d
.In header.h instead of .Fd #include \*[Lt]header.h\*[Gt] Much easier to read and write, and supported by groff for ages. Okayed by ross.
229 lines
7.4 KiB
Groff
229 lines
7.4 KiB
Groff
.\" $NetBSD: ioasic.9,v 1.8 2003/04/16 13:35:29 wiz 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
|
|
.In machine/bus.h
|
|
.In dev/tc/tcvar.h
|
|
.In dev/tc/ioasicreg.h
|
|
.In dev/tc/ioasicvar.h
|
|
.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 necessarily
|
|
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 using 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
|