.\"     $NetBSD: tc.9,v 1.6 2002/10/14 13:43:34 wiz Exp $
.\"
.\" Copyright (c) 2001 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 October 7, 2001
.Dt TC 9
.Os
.Sh NAME
.Nm TC ,
.Nm tc_intr_establish ,
.Nm tc_intr_disestablish ,
.Nm tc_intr_evcnt .
.Nm tc_mb ,
.Nm tc_wmb ,
.Nm tc_syncbus ,
.Nm tc_badaddr ,
.Nm TC_DENSE_TO_SPARSE ,
.Nm TC_PHYS_TO_UNCACHED
.Nd TURBOchannel bus
.Sh SYNOPSIS
.Fd #include \*[Lt]machine/bus.h\*[Gt]
.Fd #include \*[Lt]dev/tc/tcvar.h\*[Gt]
.Fd #include \*[Lt]dev/tc/tcdevs.h\*[Gt]
.Ft void
.Fn tc_intr_establish "struct device *dev" "void *cookie" \
"int level" "int (*handler)(void *)" "void *arg"
.Ft void
.Fn tc_intr_disestablish "struct device *dev" "void *cookie"
.Ft const struct evcnt *
.Fn tc_intr_evcnt "struct device *dev" "void *cookie"
.Ft void
.Fn tc_mb ""
.Ft void
.Fn tc_wmb ""
.Ft void
.Fn tc_syncbus ""
.Ft int
.Fn tc_badaddr "tc_addr_t tcaddr"
.Ft tc_addr_t
.Fn TC_DENSE_TO_SPARSE "tc_addr_t addr"
.Ft tc_addr_t
.Fn TC_PHYS_TO_UNCACHED "tc_addr_t addr"
.Sh DESCRIPTION
The
.Nm
device provides support for the DEC TURBOchannel bus found on all DEC
TURBOchannel machines with MIPS (DECstation 5000 series, excluding the
5000/200) and Alpha (3000-series) systems.
TURBOchannel is a 32-bit wide synchronous DMA-capable bus, running
at 25 MHz on higher-end machines and at 12.5 MHz on lower-end machines.
.Sh DATA TYPES
Drivers for devices attached to the TURBOchannel bus will make use of
the following data types:
.Bl -tag -width compact
.It Fa struct tc_attach_args
A structure use to inform the driver of TURBOchannel bus properties.
It contains the following members:
.Bd -literal
	bus_space_tag_t	ta_memt;
	bus_dma_tag_t	ta_dmat;
	char		ta_modname[TC_ROM_LLEN+1];
	u_int		ta_slot;
	tc_offset_t	ta_offset;
	tc_addr_t	ta_addr;
	void		*ta_cookie;
	u_int		ta_busspeed;
.Ed
.Pp
The
.Em ta_busspeed
member specifies the TURBOchannel bus speed and is useful for
time-related functions.
Values values are
.Em TC_SPEED_12_5_MHZ
for the 12.5 MHz bus and
.Em TC_SPEED_25_MHZ
for the 50 MHz bus.
.El
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn tc_intr_establish "dev" "cookie" "level" "handler" "arg"
Establish an interrupt handler with device
.Fa dev
for the interrupt described completely by
.Fa cookie ,
the value passed to the driver in the
.Em ta_cookie
member of the
.Em tc_attach_args
structure.
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 tc_intr_disestablish "dev" "cookie"
Dis-establish the interrupt handler with device
.Fa dev
for the interrupt described completely
.Fa cookie .
.It Fn tc_intr_evcnt "dev" "cookie"
Do interrupt event counting with device
.Fa dev
for the event described completely by
.Fa cookie .
.It Fn tc_mb ""
A read/write memory barrier.
Any CPU-to-memory reads/writes before the barrier must complete before
any CPU-to-memory reads/writes after it.
.It Fn tc_wmb ""
A write memory barrier.
Any CPU-to-memory writes before before the barrier must complete
before any CPU-to-memory writes after it.
.It Fn tc_syncbus ""
Synchronise writes on the TURBOchannel bus by ensuring CPU writes are
propagated across the TURBOchannel bus.
.It Fn tc_badaddr "tcaddr"
Returns non-zero if the given address
.Fa tcaddr
is invalid.
.It Fn TC_DENSE_TO_SPARSE "addr"
Convert the given physical address
.Fa addr
in TURBOchannel dense space to the corresponding address in
TURBOchannel sparse space.
.It Fn TC_PHYS_TO_UNCACHED "addr"
Convert the given system memory physical address
.Fa addr
to the physical address of the corresponding region that is not
cached.
.El
.Sh AUTOCONFIGURATION
The TURBOchannel bus is a direct-connection bus.
During autoconfiguration, the parent specifies the name of the found
TURBOchannel module into the
.Fa ta_modname
member of the
.Em tc_attach_args
structure.
Drivers should match on this name.
.Sh DMA SUPPORT
The TURBOchannel bus supports 32-bit, bidirectional DMA transfers.
Support is provided by the standard
.Xr bus_dma 9
interface.
.Sh CODE REFERENCES
This section describes places within the
.Nx
source tree where actual code implementing or utilising the
machine-independent TURBOchannel subsystem can be found.
All pathnames are relative to
.Pa /usr/src .
.Pp
The TURBOchannel subsystem itself is implemented within the file
.Pa sys/dev/tc/tc_subr.c .
Machine-dependent portions can be found in
.Pa sys/arch/\*[Lt]arch\*[Gt]/tc/tcbus.c .
.Sh SEE ALSO
.Xr tc 4 ,
.Xr autoconf 9 ,
.Xr bus_dma 9 ,
.Xr bus_space 9 ,
.Xr driver 9