.\"     $NetBSD: vme.9,v 1.13 2011/07/01 17:34:44 dyoung 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.
.\"
.\" 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 June 12, 2001
.Dt VME 9
.Os
.Sh NAME
.Nm VME ,
.Nm vme_probe ,
.Nm vme_space_map ,
.Nm vme_space_unmap ,
.Nm vme_intr_map ,
.Nm vme_intr_establish ,
.Nm vme_intr_disestablish ,
.Nm vme_intr_evcnt ,
.Nm vme_dmamap_create ,
.Nm vme_dmamap_destroy ,
.Nm vme_dmamem_alloc ,
.Nm vme_dmamem_free ,
.Nm vme_space_alloc ,
.Nm vme_space_free ,
.Nm vme_space_get
.Nd Versa Module Euroboard bus
.Sh SYNOPSIS
.In sys/bus.h
.In dev/vme/vmereg.h
.In dev/vme/vmevar.h
.Ft int
.Fn vme_probe "void *vc" "vme_addr_t vmeaddr" "vme_size_t len" "vme_am_t am" \
"vme_datasize_t datasize" \
"int (*callback)()" "void *arg"
.Ft int
.Fo vme_space_map
.Fa "void *vc" "vme_addr_t vmeaddr" "vme_size_t len" \
"vme_am_t am" "vme_datasize_t datasize" "vme_swap_t swap" \
"bus_space_tag_t *tag" "bus_space_handle_t *handle" "vme_mapresc_t *resc"
.Fc
.Ft void
.Fn vme_space_unmap "void *vc" "vme_mapresc_t resc"
.Ft int
.Fn vme_intr_map "void *vc" "int level" "int vector" \
"vme_intr_handle_t *handlep"
.Ft void *
.Fn vme_intr_establish "void *vc" "vme_intr_handle_t handle" "int prio" \
"int (*func)(void *)" "void *arg"
.Ft void
.Fn vme_intr_disestablish "void *vc" "void *cookie"
.Ft const struct evcnt *
.Fn vme_intr_evcnt "void *vc" "vme_intr_handle_t handle"
.Ft int
.Fo vme_dmamap_create
.Fa "void *vc" "vme_size_t size" "vme_am_t am" "vme_datasize_t datasize"
.Fa "vme_swap_t swap" "int nsegs" "vme_size_t segsz" "vme_addr_t bound"
.Fa  "int flags" "bus_dmamap_t *map"
.Fc
.Ft void
.Fn vme_dmamap_destroy "void *vc" "bus_dmamap_t map"
.Ft int
.Fo vme_dmamem_alloc
.Fa "void *vc" "vme_size_t size" "vme_am_t am" \
"vme_datasize_t datasize" "vme_swap_t swap" "bus_dma_segment_t *segs" \
"int nsegs" "int *rsegs" "int flags"
.Fc
.Ft void
.Fn vme_dmamem_free "void *vc" "bus_dma_segment_t *segs" "int nsegs"
.Ft int
.Fn vme_space_alloc "struct vmebus_softc *tag" "vme_addr_t addr" "vme_size_t size" "vme_am_t ams"
.Ft void
.Fn vme_space_free "void *vc" "vme_addr_t addr" "vme_size_t size" \
"vme_am_t ams"
.Ft int
.Fn vme_space_get "void *vc" "vme_size_t size" "vme_am_t ams" \
"u_long align" "vme_addr_t *addr"
.Sh DESCRIPTION
The
.Nm
bus provides support for VME devices.
The VME bus is a high-performance backplane bus for use in computer systems.
It is based on the VMEbus specification initially released by the VMEbus
International Trade Association (VITA) in August of 1982.
It has since undergone IEC and IEEE standardisation.
.Pp
The VME bus supports 8, 16, and 32-bit transfers over non-multiplexed
32-bit data and address paths.
The latest revisions allow 64-bit, multiplexed transfers.
It supports asynchronous, fully handshaken transfers at speeds
up to 80 MB/sec.
It has a master-slave architecture, encouraging multiprocessing and
supports up to seven interrupt levels.
.Sh DATA TYPES
Drivers attached to the
.Nm
bus will make use of the following data types:
.Bl -tag -width compact
.It Fa vme_chipset_tag_t
An opaque type identifying the bus controller.
.It Fa vme_addr_t
Addresses on the bus.
.It Fa vme_am_t
Address modifiers.
Valid values are VME_AM_A32, VME_AM_A16, VME_AM_A24, VME_AM_USERDEF
(user/vendor definable), VME_AM_MBO, VME_AM_SUPER, VME_AM_USER,
VME_AM_DATA, VME_AM_PRG, VME_AM_BLT32 and VME_AM_BLT64.
.It Fa vme_datasize_t
The datasize of the address space.
Valid values are VME_D8, VME_D16, and VME_D32.
.It Fa vme_mapresc_t
Generic placeholder for any resources needed for a mapping.
.It Fa vme_intr_handle_t
An opaque type describing an interrupt mapping.
.It Fa vme_swap_t
Hardware swap capabilities for controlling data endianness.
Valid values have not been specified yet.
.It Fa struct vme_range
A structure used to describe an address range on the VME bus.
It contains the following members:
.Bd -literal
	vme_addr_t offset;
	vme_size_t size;
	vme_am_t am;
.Ed
.It Fa struct vme_attach_args
A structure used to inform the driver of the
device properties.
It contains the following members:
.Bd -literal
	vme_chipset_tag_t va_vct;
	bus_dma_tag_t va_bdt;
	int ivector;
	int ilevel;
	int numcfranges;
	struct vme_range r[VME_MAXCFRANGES];
.Ed
.El
.Sh FUNCTIONS
.Bl -tag -width compact
.It Fn vme_probe "vc" "vmeaddr" "len" "am" "datasize" "callback" "arg"
Probes the VME space managed by controller
.Fa vc
at address
.Fa vmeaddr ,
length
.Fa len ,
with address modifiers
.Fa am
and datasize
.Fa datasize
for a device.
If a VME device is found, the function
.Fa callback()
(if it is not NULL) is called to perform device-specific
identification.
.Fa callback()
is called with the argument
.Fa arg ,
and the bus-space tag and bus-space handle for accessing the VME space
mapping and should return a nonzero positive integer for a positive
device match.
.It Fn vme_space_map "vc" "vmeaddr" "len" "am" "datasize" "swap" "tag" "handle" "resc"
Maps the VME space managed by controller
.Fa vc
at address
.Fa vmeaddr ,
length
.Fa len ,
with address modifiers
.Fa am ,
datasize
.Fa datasize
and endianness
.Fa swap
for a device.
If the mapping is successful
.Fa tag
contains the bus-space tag and
.Fa handle
contains the bus-space handle for accessing the VME space mapping.
.Fa resc
contains the resources for the mappings.
.Fn vme_space_map
returns 0 on success, and nonzero on error.
.It Fn vme_space_unmap "vc" "resc"
Unmaps the VME space mapping managed by controller
.Fa vc
and resources
.Fa resc .
.It Fn vme_intr_map "vc" "level" "vector" "handlep"
Sets
.Fa handlep
to a machine-dependent value which identifies a particular interrupt
source at level
.Fa level
and vector
.Fa vector
on the controller
.Fa vc .
.Fn vme_intr_map
returns zero on success, and nonzero on failure.
.It Fn vme_intr_establish "vc" "handle" "prio" "func" "arg"
Establishes the interrupt handler
.Fa handlep .
When the device interrupts,
.Fa func()
will be called with a single argument
.Fa arg
and will run at the interrupt priority level
.Fa prio .
The return value of
.Fn vme_intr_establish
may be saved and passed to
.Fn vme_intr_disestablish .
.It Fn vme_intr_disestablish "vc" "cookie"
Disables the interrupt handler when the driver is no longer interested
in interrupts from the device.
.Fa cookie
is the value returned by
.Fn vme_intr_establish .
.It Fn vme_intr_evcnt "vc" "handle"
Increment the interrupt event counter for the interrupt specified by
.Fa handle .
.It Fn vme_dmamap_create "vc" "size" "am" "datasize" "swap" "nsegs" "segsz" "bound" "flags" "map"
Allocates a DMA handle and initializes it according to the parameters
provided.
The VME-specific parameters describe the address-space modifiers
.Fa am ,
datasize
.Fa datasize ,
and endianness
.Fa swap .
The remaining parameters are described in
.Xr bus_dma 9 .
.It Fn vme_dmamap_destroy "vc" "map"
Frees all resources associated with a given DMA handle.
The parameters are described in
.Xr bus_dma 9 .
.It Fn vme_dmamem_alloc "vc" "size" "am" "datasize" "swap" "segs" "nsegs" "rsegs" "flags"
Allocates memory that is
.Do
DMA safe
.Dc for the VME bus managed by
controller
.Fa vc .
The VME-specific parameters describe the
address-space modifiers
.Fa am ,
datasize
.Fa datasize ,
and endianness
.Fa swap .
The remaining parameters are described in
.Xr bus_dma 9 .
.It Fn vme_dmamem_free "vc" "segs" "nsegs"
Frees memory previously allocated by
.Fn vme_dmamem_alloc
for the VME space managed by controller
.Fa vc .
.It Fn vme_space_alloc "tag" "addr" "size" "ams"
Allocate VME space for the bus-space
.Fa tag
at address
.Fa addr
of size
.Fa size
and address-space modifiers
.Fa ams .
.Fn vme_space_alloc
returns EINVAL on invalid inputs.
.It Fn vme_space_free "vc" "addr" "size" "ams"
Deallocate VME space for the bus-space
.Fa tag
at address
.Fa addr
of size
.Fa size
and address-space modifiers
.Fa ams .
.It Fn vme_space_get "vc" "size" "ams" "align" "addr"
Returns EINVAL on invalid inputs.
.El
.Sh AUTOCONFIGURATION
The VME bus is an indirect-connection bus.
During autoconfiguration each driver is required to probe the bus
for the presence of a device.
A VME driver will receive a pointer to a
.Fa struct vme_attach_args
hinting at "locations" (address ranges) on the VME bus where the
device may be located.
The driver should check the number of address
ranges, allocate the address space of these ranges using
.Fn vme_space_alloc ,
and probe the address space for the device using
.Fn vme_probe .
.Pp
During driver attach the driver should also map the address ranges
using
.Fn vme_space_map .
The interrupt locators in
.Fa struct vme_attach_args
are used by
.Fn vme_intr_map
and
.Fn vme_intr_establish .
.Sh DMA SUPPORT
Extensive DMA facilities are provided.
.Sh CODE REFERENCES
The
.Nm
subsystem itself is implemented within the file
.Pa sys/dev/vme/vme.c .
.Sh SEE ALSO
.Xr vme 4 ,
.Xr autoconf 9 ,
.Xr bus_dma 9 ,
.Xr bus_space 9 ,
.Xr driver 9
.Sh HISTORY
The machine-independent VME subsystem appeared in
.Nx 1.5 .
.Sh BUGS
This page is incomplete.