share/man/man9/mca.9

   1 .\"     $NetBSD: mca.9,v 1.7 2003/04/16 13:35:30 wiz 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 MCA 9
  32 .Os
  33 .Sh NAME
  34 .Nm MCA ,
  35 .Nm mca_intr_establish ,
  36 .Nm mca_intr_disestablish ,
  37 .Nm mca_intr_evcnt ,
  38 .Nm mca_conf_read ,
  39 .Nm mca_conf_write
  40 .Nd MicroChannel Architecture bus
  41 .Sh SYNOPSIS
  42 .In machine/bus.h
  43 .In dev/mca/mcavar.h
  44 .In dev/mca/mcadevs.h
  45 .Ft void *
  46 .Fn mca_intr_establish "mca_chipset_tag_t mc" "mca_intr_handle_t hdl" \
  47 "int level" "int (*handler)(void *)" "void *arg"
  48 .Ft void
  49 .Fn mca_intr_disestablish "mca_chipset_tag_t mc" "mca_intr_handle_t hdl"
  50 .Ft const struct evcnt *
  51 .Fn mca_intr_evcnt "mca_chipset_tag_t mc" "mca_intr_handle_t hdl"
  52 .Ft int
  53 .Fn mca_conf_read "mca_chipset_tag_t mc" "int slot" "int reg"
  54 .Ft void
  55 .Fn mca_conf_write "mca_chipset_tag_t mc" "int slot" "int reg" \
  56 "int data"
  57 .Sh DESCRIPTION
  58 The
  59 .Nm
  60 device provides support for IBM's MicroChannel Architecture bus found
  61 on IBM PS/2 systems and selected workstations.
  62 It was designed as a replacement bus for the ISA bus found on IBM's
  63 older machines.
  64 However, the bus specifications were only available under license, so
  65 MCA did not achieve widespread acceptance in the industry.
  66 .Pp
  67 Being a replacement for the ISA bus, the MCA bus does share some
  68 similar aspects with the ISA bus.
  69 Some MCA devices can be detected via the usual ISA-style probing.
  70 However, most device detection is done through the Programmable Option
  71 Select (POS) registers.
  72 These registers provide a window into a device to determine device-specific
  73 properties and configuration.
  74 The configuration of devices and their POS registers is performed using
  75 IBM's system configuration software.
  76 .Pp
  77 The MCA bus uses level-triggered interrupts while the ISA bus uses
  78 edge-triggered interrupts.
  79 Level triggered interrupts have the advantage that they can be shared
  80 among multiple device.
  81 Therefore, most MCA-specific devices should be coded with shared
  82 interrupts in mind.
  83 .Sh DATA TYPES
  84 Drivers for devices attached to the MCA bus will make use of the
  85 following data types:
  86 .Bl -tag -width compact
  87 .It Fa mca_chipset_tag_t
  88 Chipset tag for the MCA bus.
  89 .It Fa mca_intr_handle_t
  90 The opaque handle describing an established interrupt handler.
  91 .It Fa struct mca_attach_args
  92 A structure use to inform the driver of MCA bus properties.
  93 It contains the following members:
  94 .Bd -literal
  95         bus_space_tag_t ma_iot;         /* MCA I/O space tag */
  96         bus_space_tag_t ma_memt;        /* MCA mem space tag */
  97         bus_dma_tag_t ma_dmat;          /* MCA DMA tag */
  98         int ma_slot;                    /* MCA slot number */
  99         int ma_pos[8];                  /* MCA POS values */
 100         int ma_id;                      /* MCA device */
 101 .Ed
 102 .El
 103 .Sh FUNCTIONS
 104 .Bl -tag -width compact
 105 .It Fn mca_intr_establish "mc" "hdl" "level" "handler" "arg"
 106 Establish a MCA interrupt handler on the MCA bus specified by
 107 .Fa mc
 108 for the interrupt described completely by
 109 .Fa hdl .
 110 The priority of the interrupt is specified by
 111 .Fa level .
 112 When the interrupt occurs the function
 113 .Fa handler
 114 is called with argument
 115 .Fa arg .
 116 .It Fn mca_intr_disestablish "mc" "hdl"
 117 Dis-establish the interrupt handler on the MCA bus specified by
 118 .Fa mc
 119 for the interrupt described completely
 120 .Fa hdl .
 121 .It Fn mca_intr_evcnt "mc" "hdl"
 122 Do interrupt event counting on the MCA bus specified by
 123 .Fa mc
 124 for the event described completely by
 125 .Fa hdl .
 126 .It Fn mca_conf_read "mc" "slot" "reg"
 127 Read the POS register
 128 .Fa reg
 129 for the device in slot
 130 .Fa slot
 131 on the MCA bus specified by
 132 .Fa mc .
 133 .It Fn mca_conf_write "mc" "slot" "reg" "data"
 134 Write data
 135 .Fa data
 136 to the POS register
 137 .Fa reg
 138 for the device in slot
 139 .Fa slot
 140 on the MCA bus specified by
 141 .Fa mc .
 142 .El
 143 .Sh AUTOCONFIGURATION
 144 The MCA bus is a direct-connection bus.
 145 During autoconfiguration, the parent specifies the MCA device ID for the
 146 found device in the
 147 .Fa ma_id
 148 member of the
 149 .Em mca_attach_args
 150 structure.
 151 Drivers should match on the device ID.
 152 Device capabilities and configuration information should be read from
 153 device POS registers using
 154 .Fn mca_conf_read .
 155 Some important configuration information found in the POS registers
 156 include the I/O base address, memory base address and interrupt
 157 number.
 158 The location of these configurable options with the POS registers are
 159 device specific.
 160 .Sh DMA SUPPORT
 161 The MCA bus supports 32-bit, bidirectional DMA transfers.
 162 Currently, no machine-independent support for MCA DMA is available.
 163 .Sh CODE REFERENCES
 164 This section describes places within the
 165 .Nx
 166 source tree where actual code implementing or using the
 167 machine-independent MCA subsystem can be found.
 168 All pathnames are relative to
 169 .Pa /usr/src .
 170 .Pp
 171 The MCA subsystem itself is implemented within the file
 172 .Pa sys/dev/mca/mca_subr.c .
 173 Machine-dependent portions can be found in
 174 .Pa sys/arch/\*[Lt]arch\*[Gt]/mca/mca_machdep.c .
 175 The database of known devices exists within the file
 176 .Fa sys/dev/mca/mcadevs_data.h
 177 and is generated automatically from the file
 178 .Pa sys/dev/mca/mcadevs .
 179 New vendor and product identifiers should be added to this file.
 180 The database can be regenerated using the Makefile
 181 .Pa sys/dev/mca/Makefile.mcadevs .
 182 .Pp
 183 A good source of information about MCA devices is IBM's system
 184 configuration disk.
 185 The disk contains .adf files which describe the location of device
 186 configuration options in the POS registers.
 187 .Sh SEE ALSO
 188 .Xr mca 4 ,
 189 .Xr autoconf 9 ,
 190 .Xr bus_dma 9 ,
 191 .Xr bus_space 9 ,
 192 .Xr driver 9 ,
 193 .Xr isa 9
 194 .Sh BUGS
 195 The machine-independent
 196 .Nm
 197 driver does not currently support DMA.
 198 MCA devices which require DMA operation currently access the DMA
 199 capabilities directly.