363 lines
11 KiB
Groff
363 lines
11 KiB
Groff
.\" $NetBSD: vme.9,v 1.3 2001/09/04 03:00:47 wiz 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 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
|
|
.Fd #include <machine/bus.h>
|
|
.Fd #include <dev/vme/vmereg.h>
|
|
.Fd #include <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 Fo vme_space_map
|
|
.Fa "vc" "vmeaddr" "len" "am" "datasize" "swap" "tag" "handle" "resc"
|
|
.Fc
|
|
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-dependant 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 Fo vme_dmamap_create
|
|
.Fa "vc" "size" "am" "datasize" "swap" "nsegs" "segsz" "bound"
|
|
.Fa "flags" "map"
|
|
.Fc
|
|
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 Fo vme_dmamem_alloc
|
|
.Fa "vc" "size" "am" "datasize" "swap" "segs" "nsegs" "rsegs" "flags"
|
|
.Fc
|
|
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
|
|
This section describes places within the
|
|
.Nx
|
|
source tree where actual code implementing or utilising the
|
|
machine-independent
|
|
.Nm
|
|
subsystem can be found. All pathnames are relative to
|
|
.Pa /usr/src .
|
|
.Pp
|
|
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.
|