share/man/man9/tc.9

   1 .\"     $NetBSD: tc.9,v 1.9 2004/10/04 19:12:52 rumble Exp $
   2 .\"
   3 .\" Copyright (c) 2001 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 October 7, 2001
  31 .Dt TC 9
  32 .Os
  33 .Sh NAME
  34 .Nm TC ,
  35 .Nm tc_intr_establish ,
  36 .Nm tc_intr_disestablish ,
  37 .Nm tc_intr_evcnt .
  38 .Nm tc_mb ,
  39 .Nm tc_wmb ,
  40 .Nm tc_syncbus ,
  41 .Nm tc_badaddr ,
  42 .Nm TC_DENSE_TO_SPARSE ,
  43 .Nm TC_PHYS_TO_UNCACHED
  44 .Nd TURBOchannel bus
  45 .Sh SYNOPSIS
  46 .In machine/bus.h
  47 .In dev/tc/tcvar.h
  48 .In dev/tc/tcdevs.h
  49 .Ft void
  50 .Fn tc_intr_establish "struct device *dev" "void *cookie" \
  51 "int level" "int (*handler)(void *)" "void *arg"
  52 .Ft void
  53 .Fn tc_intr_disestablish "struct device *dev" "void *cookie"
  54 .Ft const struct evcnt *
  55 .Fn tc_intr_evcnt "struct device *dev" "void *cookie"
  56 .Ft void
  57 .Fn tc_mb ""
  58 .Ft void
  59 .Fn tc_wmb ""
  60 .Ft void
  61 .Fn tc_syncbus ""
  62 .Ft int
  63 .Fn tc_badaddr "tc_addr_t tcaddr"
  64 .Ft tc_addr_t
  65 .Fn TC_DENSE_TO_SPARSE "tc_addr_t addr"
  66 .Ft tc_addr_t
  67 .Fn TC_PHYS_TO_UNCACHED "tc_addr_t addr"
  68 .Sh DESCRIPTION
  69 The
  70 .Nm
  71 device provides support for the DEC TURBOchannel bus found on all DEC
  72 TURBOchannel machines with MIPS (DECstation 5000 series, excluding the
  73 5000/200) and Alpha (3000-series) systems.
  74 TURBOchannel is a 32-bit wide synchronous DMA-capable bus, running
  75 at 25 MHz on higher-end machines and at 12.5 MHz on lower-end machines.
  76 .Sh DATA TYPES
  77 Drivers for devices attached to the TURBOchannel bus will make use of
  78 the following data types:
  79 .Bl -tag -width compact
  80 .It Fa struct tc_attach_args
  81 A structure use to inform the driver of TURBOchannel bus properties.
  82 It contains the following members:
  83 .Bd -literal
  84         bus_space_tag_t ta_memt;
  85         bus_dma_tag_t   ta_dmat;
  86         char            ta_modname[TC_ROM_LLEN+1];
  87         u_int           ta_slot;
  88         tc_offset_t     ta_offset;
  89         tc_addr_t       ta_addr;
  90         void            *ta_cookie;
  91         u_int           ta_busspeed;
  92 .Ed
  93 .Pp
  94 The
  95 .Em ta_busspeed
  96 member specifies the TURBOchannel bus speed and is useful for
  97 time-related functions.
  98 Values values are
  99 .Em TC_SPEED_12_5_MHZ
 100 for the 12.5 MHz bus and
 101 .Em TC_SPEED_25_MHZ
 102 for the 50 MHz bus.
 103 .El
 104 .Sh FUNCTIONS
 105 .Bl -tag -width compact
 106 .It Fn tc_intr_establish "dev" "cookie" "level" "handler" "arg"
 107 Establish an interrupt handler with device
 108 .Fa dev
 109 for the interrupt described completely by
 110 .Fa cookie ,
 111 the value passed to the driver in the
 112 .Em ta_cookie
 113 member of the
 114 .Em tc_attach_args
 115 structure.
 116 The priority of the interrupt is specified by
 117 .Fa level .
 118 When the interrupt occurs the function
 119 .Fa handler
 120 is called with argument
 121 .Fa arg .
 122 .It Fn tc_intr_disestablish "dev" "cookie"
 123 Dis-establish the interrupt handler with device
 124 .Fa dev
 125 for the interrupt described completely
 126 .Fa cookie .
 127 .It Fn tc_intr_evcnt "dev" "cookie"
 128 Do interrupt event counting with device
 129 .Fa dev
 130 for the event described completely by
 131 .Fa cookie .
 132 .It Fn tc_mb ""
 133 A read/write memory barrier.
 134 Any CPU-to-memory reads/writes before the barrier must complete before
 135 any CPU-to-memory reads/writes after it.
 136 .It Fn tc_wmb ""
 137 A write memory barrier.
 138 Any CPU-to-memory writes before the barrier must complete
 139 before any CPU-to-memory writes after it.
 140 .It Fn tc_syncbus ""
 141 Synchronise writes on the TURBOchannel bus by ensuring CPU writes are
 142 propagated across the TURBOchannel bus.
 143 .It Fn tc_badaddr "tcaddr"
 144 Returns non-zero if the given address
 145 .Fa tcaddr
 146 is invalid.
 147 .It Fn TC_DENSE_TO_SPARSE "addr"
 148 Convert the given physical address
 149 .Fa addr
 150 in TURBOchannel dense space to the corresponding address in
 151 TURBOchannel sparse space.
 152 .It Fn TC_PHYS_TO_UNCACHED "addr"
 153 Convert the given system memory physical address
 154 .Fa addr
 155 to the physical address of the corresponding region that is not
 156 cached.
 157 .El
 158 .Sh AUTOCONFIGURATION
 159 The TURBOchannel bus is a direct-connection bus.
 160 During autoconfiguration, the parent specifies the name of the found
 161 TURBOchannel module into the
 162 .Fa ta_modname
 163 member of the
 164 .Em tc_attach_args
 165 structure.
 166 Drivers should match on this name.
 167 .Sh DMA SUPPORT
 168 The TURBOchannel bus supports 32-bit, bidirectional DMA transfers.
 169 Support is provided by the standard
 170 .Xr bus_dma 9
 171 interface.
 172 .Sh CODE REFERENCES
 173 This section describes places within the
 174 .Nx
 175 source tree where actual code implementing or using the
 176 machine-independent TURBOchannel subsystem can be found.
 177 All pathnames are relative to
 178 .Pa /usr/src .
 179 .Pp
 180 The TURBOchannel subsystem itself is implemented within the file
 181 .Pa sys/dev/tc/tc_subr.c .
 182 Machine-dependent portions can be found in
 183 .Pa sys/arch/\*[Lt]arch\*[Gt]/tc/tcbus.c .
 184 .Sh SEE ALSO
 185 .Xr tc 4 ,
 186 .Xr autoconf 9 ,
 187 .Xr bus_dma 9 ,
 188 .Xr bus_space 9 ,
 189 .Xr driver 9