NetBSD/share/man/man9/mca.9

.\"     $NetBSD: mca.9,v 1.4 2002/02/13 08:18:45 ross 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 \*[Lt]machine/bus.h\*[Gt]
.Fd #include \*[Lt]dev/mca/mcavar.h\*[Gt]
.Fd #include \*[Lt]dev/mca/mcadevs.h\*[Gt]
.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/\*[Lt]arch\*[Gt]/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.