Programmer's guide for MicroChannel.

2001-10-22 03:25:26 +00:00 · 2001-10-22 03:25:26 +00:00 · 4d4c103867
parent 83a2424500
commit 4d4c103867
1 changed files with 197 additions and 0 deletions
--- a/share/man/man9/mca.9
+++ b/share/man/man9/mca.9
@ -0,0 +1,197 @@
+.\"     $NetBSD: mca.9,v 1.1 2001/10/22 03:25:26 gmcgarry 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 MCA 9
+.Os
+.Sh NAME
+.Nm MCA ,
+.Nm mca_intr_establish ,
+.Nm mca_intr_disestablish ,
+.Nm mca_intr_evcnt ,
+.Nm mca_conf_read ,
+.Nm mca_conf_write
+.Nd MicroChannel Architecture bus
+.Sh SYNOPSIS
+.Fd #include <machine/bus.h>
+.Fd #include <dev/mca/mcavar.h>
+.Fd #include <dev/tc/mcadevs.h>
+.Ft void *
+.Fn mca_intr_establish "mca_chipset_tag_t mc" "mca_intr_handle_t hdl" \
+"int level" "int (*handler)(void *)" "void *arg"
+.Ft void
+.Fn mca_intr_disestablish "mca_chipset_tag_t mc" "mca_intr_handle_t hdl"
+.Ft const struct evcnt *
+.Fn mca_intr_evcnt "mca_chipset_tag_t mc" "mca_intr_handle_t hdl"
+.Ft int
+.Fn mca_conf_read "mca_chipset_tag_t mc" "int slot" "int reg"
+.Ft void
+.Fn mca_conf_write "mca_chipset_tag_t mc" "int slot" "int reg" \
+"int data"
+.Sh DESCRIPTION
+The
+.Nm
+device provides support for IBM's MicroChannel Architecture bus found
+on IBM PS/2 systems and selected workstations.  It was designed as a
+replacement bus for the ISA bus found on IBM's older machines.
+However, the bus specifications were only available under license, so
+MCA did not achieve widespread acceptance in the industry.
+.Pp
+Being a replacement for the ISA bus, the MCA bus does share some
+similar aspects with the ISA bus.  Some MCA devices can be detected
+via the usual ISA-style probing.  However, most device detection is
+done through the Programmable Option Select (POS) registers.  These
+registers provide a window into a device to determine device-specific
+properties and configuration.  The configuration of devices and their
+POS registers is performed using IBM's system configuration software.
+.Pp
+The MCA bus uses level-triggered interrupts while the ISA bus uses
+edge-triggered interrupts.  Level triggered interrupts have the
+advantage that they can be shared among multiple device.  Therefore,
+most MCA-specific devices should be coded with shared interrupts in
+mind.
+.Sh DATA TYPES
+Drivers for devices attached to the MCA bus will make use of the
+following data types:
+.Bl -tag -width compact
+.It Fa mca_chipset_tag_t
+Chipset tag for the MCA bus.
+.It Fa mca_intr_handle_t
+The opaque handle describing an established interrupt handler.
+.It Fa struct mca_attach_args
+A structure use to inform the driver of MCA bus properties.
+It contains the following members:
+.Bd -literal
+	bus_space_tag_t ma_iot;		/* MCA I/O space tag */
+	bus_space_tag_t ma_memt;	/* MCA mem space tag */
+	bus_dma_tag_t ma_dmat;		/* MCA DMA tag */
+	int ma_slot;			/* MCA slot number */
+	int ma_pos[8];			/* MCA POS values */
+	int ma_id;			/* MCA device */
+.Ed
+.El
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn mca_intr_establish "mc" "hdl" "level" "handler" "arg"
+Establish a MCA interrupt handler on the MCA bus specified by
+.Fa mc
+for the interrupt described completely by
+.Fa hdl .
+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 mca_intr_disestablish "mc" "hdl"
+Dis-establish the interrupt handler on the MCA bus specified by
+.Fa mc
+for the interrupt described completely
+.Fa hdl .
+.It Fn mca_intr_evcnt "mc" "hdl"
+Do interrupt event counting on the MCA bus specified by
+.Fa mc
+for the event described completely by
+.Fa hdl .
+.It Fn mca_conf_read "mc" "slot" "reg"
+Read the POS register
+.Fa reg
+for the device in slot
+.Fa slot
+on the MCA bus specified by
+.Fa mc .
+.It Fn mca_conf_write "mc" "slot" "reg" "data"
+Write data
+.Fa data
+to the POS register
+.Fa reg
+for the device in slot
+.Fa slot
+on the MCA bus specified by
+.Fa mc .
+.El
+.Sh AUTOCONFIGURATION
+The MCA bus is a direct-connection bus.  During autoconfiguration, the
+parent specifies the MCA device ID for the found device in the
+.Fa ma_id
+member of the 
+.Em mca_attach_args
+structure.  Drivers should match on the device ID.  Device
+capabilities and configuration information should be read from device
+POS registers using
+.Fn mca_conf_read .
+Some important configuration information found in the POS registers
+include the I/O base address, memory base address and interrupt
+number.  The location of these configurable options with the POS
+registers are device specific.
+.Sh DMA SUPPORT
+The MCA bus supports 32-bit, bidirectional DMA transfers.  Currently,
+no machine-independent support for MCA DMA is available.
+.Sh CODE REFERENCES
+This section describes places within the
+.Nx
+source tree where actual code implementing or utilising the
+machine-independent MCA subsystem can be found.  All pathnames are
+relative to
+.Pa /usr/src.
+.Pp
+The MCA subsystem itself is implemented within the file
+.Pa sys/dev/mca/mca_subr.c .
+Machine-dependent portions can be found in
+.Pa sys/arch/<arch>/mca/mca_machdep.c .
+The database of known devices exists within the file
+.Fa sys/dev/mca/mcadevs_data.h
+and is generated automatically from the file
+.Pa sys/dev/mca/mcadevs .
+New vendor and product identifiers should be added to this
+file.  The database can be regenerated using the Makefile
+.Pa sys/dev/mca/Makefile.mcadevs .
+.Pp
+A good source of information about MCA devices is IBM's system
+configuration disk.  The disk contains .adf files which describe the
+location of device configuration options in the POS registers.
+.Sh SEE ALSO
+.Xr mca 4 ,
+.Xr autoconf 9 ,
+.Xr bus_dma 9 ,
+.Xr bus_space 9 ,
+.Xr driver 9 ,
+.Xr isa 9
+.Sh BUGS
+The machine-independent
+.Nm
+driver does not currently support DMA.  MCA devices which require DMA
+operation currently access the DMA capabilities directly.