1.\" $NetBSD: vme.9,v 1.10 2003/06/30 19:12:34 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd June 12, 2001 38.Dt VME 9 39.Os 40.Sh NAME 41.Nm VME , 42.Nm vme_probe , 43.Nm vme_space_map , 44.Nm vme_space_unmap , 45.Nm vme_intr_map , 46.Nm vme_intr_establish , 47.Nm vme_intr_disestablish , 48.Nm vme_intr_evcnt , 49.Nm vme_dmamap_create , 50.Nm vme_dmamap_destroy , 51.Nm vme_dmamem_alloc , 52.Nm vme_dmamem_free , 53.Nm vme_space_alloc , 54.Nm vme_space_free , 55.Nm vme_space_get 56.Nd Versa Module Euroboard bus 57.Sh SYNOPSIS 58.In machine/bus.h 59.In dev/vme/vmereg.h 60.In dev/vme/vmevar.h 61.Ft int 62.Fn vme_probe "void *vc" "vme_addr_t vmeaddr" "vme_size_t len" "vme_am_t am" \ 63"vme_datasize_t datasize" \ 64"int (*callback)()" "void *arg" 65.Ft int 66.Fo vme_space_map 67.Fa "void *vc" "vme_addr_t vmeaddr" "vme_size_t len" \ 68"vme_am_t am" "vme_datasize_t datasize" "vme_swap_t swap" \ 69"bus_space_tag_t *tag" "bus_space_handle_t *handle" "vme_mapresc_t *resc" 70.Fc 71.Ft void 72.Fn vme_space_unmap "void *vc" "vme_mapresc_t resc" 73.Ft int 74.Fn vme_intr_map "void *vc" "int level" "int vector" \ 75"vme_intr_handle_t *handlep" 76.Ft void * 77.Fn vme_intr_establish "void *vc" "vme_intr_handle_t handle" "int prio" \ 78"int (*func)(void *)" "void *arg" 79.Ft void 80.Fn vme_intr_disestablish "void *vc" "void *cookie" 81.Ft const struct evcnt * 82.Fn vme_intr_evcnt "void *vc" "vme_intr_handle_t handle" 83.Ft int 84.Fo vme_dmamap_create 85.Fa "void *vc" "vme_size_t size" "vme_am_t am" "vme_datasize_t datasize" 86.Fa "vme_swap_t swap" "int nsegs" "vme_size_t segsz" "vme_addr_t bound" 87.Fa "int flags" "bus_dmamap_t *map" 88.Fc 89.Ft void 90.Fn vme_dmamap_destroy "void *vc" "bus_dmamap_t map" 91.Ft int 92.Fo vme_dmamem_alloc 93.Fa "void *vc" "vme_size_t size" "vme_am_t am" \ 94"vme_datasize_t datasize" "vme_swap_t swap" "bus_dma_segment_t *segs" \ 95"int nsegs" "int *rsegs" "int flags" 96.Fc 97.Ft void 98.Fn vme_dmamem_free "void *vc" "bus_dma_segment_t *segs" "int nsegs" 99.Ft int 100.Fn vme_space_alloc "struct vmebus_softc *tag" "vme_addr_t addr" "vme_size_t size" "vme_am_t ams" 101.Ft void 102.Fn vme_space_free "void *vc" "vme_addr_t addr" "vme_size_t size" \ 103"vme_am_t ams" 104.Ft int 105.Fn vme_space_get "void *vc" "vme_size_t size" "vme_am_t ams" \ 106"u_long align" "vme_addr_t *addr" 107.Sh DESCRIPTION 108The 109.Nm 110bus provides support for VME devices. 111The VME bus is a high-performance backplane bus for use in computer systems. 112It is based on the VMEbus specification initially released by the VMEbus 113International Trade Association (VITA) in August of 1982. 114It has since undergone IEC and IEEE standardisation. 115.Pp 116The VME bus supports 8, 16, and 32-bit transfers over non-multiplexed 11732-bit data and address paths. 118The latest revisions allow 64-bit, multiplexed transfers. 119It supports asynchronous, fully handshaken transfers at speeds 120up to 80 MB/sec. 121It has a master-slave architecture, encouraging multiprocessing and 122supports up to seven interrupt levels. 123.Sh DATA TYPES 124Drivers attached to the 125.Nm 126bus will make use of the following data types: 127.Bl -tag -width compact 128.It Fa vme_chipset_tag_t 129An opaque type identifying the bus controller. 130.It Fa vme_addr_t 131Addresses on the bus. 132.It Fa vme_am_t 133Address modifiers. 134Valid values are VME_AM_A32, VME_AM_A16, VME_AM_A24, VME_AM_USERDEF 135(user/vendor definable), VME_AM_MBO, VME_AM_SUPER, VME_AM_USER, 136VME_AM_DATA, VME_AM_PRG, VME_AM_BLT32 and VME_AM_BLT64. 137.It Fa vme_datasize_t 138The datasize of the address space. 139Valid values are VME_D8, VME_D16, and VME_D32. 140.It Fa vme_mapresc_t 141Generic placeholder for any resources needed for a mapping. 142.It Fa vme_intr_handle_t 143An opaque type describing an interrupt mapping. 144.It Fa vme_swap_t 145Hardware swap capabilities for controlling data endianness. 146Valid values have not been specified yet. 147.It Fa struct vme_range 148A structure used to describe an address range on the VME bus. 149It contains the following members: 150.Bd -literal 151 vme_addr_t offset; 152 vme_size_t size; 153 vme_am_t am; 154.Ed 155.It Fa struct vme_attach_args 156A structure used to inform the driver of the 157device properties. 158It contains the following members: 159.Bd -literal 160 vme_chipset_tag_t va_vct; 161 bus_dma_tag_t va_bdt; 162 int ivector; 163 int ilevel; 164 int numcfranges; 165 struct vme_range r[VME_MAXCFRANGES]; 166.Ed 167.El 168.Sh FUNCTIONS 169.Bl -tag -width compact 170.It Fn vme_probe "vc" "vmeaddr" "len" "am" "datasize" "callback" "arg" 171Probes the VME space managed by controller 172.Fa vc 173at address 174.Fa vmeaddr , 175length 176.Fa len , 177with address modifiers 178.Fa am 179and datasize 180.Fa datasize 181for a device. 182If a VME device is found, the function 183.Fa callback() 184(if it is not NULL) is called to perform device-specific 185identification. 186.Fa callback() 187is called with the argument 188.Fa arg , 189and the bus-space tag and bus-space handle for accessing the VME space 190mapping and should return a nonzero positive integer for a positive 191device match. 192.It Fn vme_space_map "vc" "vmeaddr" "len" "am" "datasize" "swap" "tag" "handle" "resc" 193Maps the VME space managed by controller 194.Fa vc 195at address 196.Fa vmeaddr , 197length 198.Fa len , 199with address modifiers 200.Fa am , 201datasize 202.Fa datasize 203and endianness 204.Fa swap 205for a device. 206If the mapping is successful 207.Fa tag 208contains the bus-space tag and 209.Fa handle 210contains the bus-space handle for accessing the VME space mapping. 211.Fa resc 212contains the resources for the mappings. 213.Fn vme_space_map 214returns 0 on success, and nonzero on error. 215.It Fn vme_space_unmap "vc" "resc" 216Unmaps the VME space mapping managed by controller 217.Fa vc 218and resources 219.Fa resc . 220.It Fn vme_intr_map "vc" "level" "vector" "handlep" 221Sets 222.Fa handlep 223to a machine-dependent value which identifies a particular interrupt 224source at level 225.Fa level 226and vector 227.Fa vector 228on the controller 229.Fa vc . 230.Fn vme_intr_map 231returns zero on success, and nonzero on failure. 232.It Fn vme_intr_establish "vc" "handle" "prio" "func" "arg" 233Establishes the interrupt handler 234.Fa handlep . 235When the device interrupts, 236.Fa func() 237will be called with a single argument 238.Fa arg 239and will run at the interrupt priority level 240.Fa prio . 241The return value of 242.Fn vme_intr_establish 243may be saved and passed to 244.Fn vme_intr_disestablish . 245.It Fn vme_intr_disestablish "vc" "cookie" 246Disables the interrupt handler when the driver is no longer interested 247in interrupts from the device. 248.Fa cookie 249is the value returned by 250.Fn vme_intr_establish . 251.It Fn vme_intr_evcnt "vc" "handle" 252Increment the interrupt event counter for the interrupt specified by 253.Fa handle . 254.It Fn vme_dmamap_create "vc" "size" "am" "datasize" "swap" "nsegs" "segsz" "bound" "flags" "map" 255Allocates a DMA handle and initializes it according to the parameters 256provided. 257The VME-specific parameters describe the address-space modifiers 258.Fa am , 259datasize 260.Fa datasize , 261and endianness 262.Fa swap . 263The remaining parameters are described in 264.Xr bus_dma 9 . 265.It Fn vme_dmamap_destroy "vc" "map" 266Frees all resources associated with a given DMA handle. 267The parameters are described in 268.Xr bus_dma 9 . 269.It Fn vme_dmamem_alloc "vc" "size" "am" "datasize" "swap" "segs" "nsegs" "rsegs" "flags" 270Allocates memory that is 271.Do 272DMA safe 273.Dc for the VME bus managed by 274controller 275.Fa vc . 276The VME-specific parameters describe the 277address-space modifiers 278.Fa am , 279datasize 280.Fa datasize , 281and endianness 282.Fa swap . 283The remaining parameters are described in 284.Xr bus_dma 9 . 285.It Fn vme_dmamem_free "vc" "segs" "nsegs" 286Frees memory previously allocated by 287.Fn vme_dmamem_alloc 288for the VME space managed by controller 289.Fa vc . 290.It Fn vme_space_alloc "tag" "addr" "size" "ams" 291Allocate VME space for the bus-space 292.Fa tag 293at address 294.Fa addr 295of size 296.Fa size 297and address-space modifiers 298.Fa ams . 299.Fn vme_space_alloc 300returns EINVAL on invalid inputs. 301.It Fn vme_space_free "vc" "addr" "size" "ams" 302Deallocate VME space for the bus-space 303.Fa tag 304at address 305.Fa addr 306of size 307.Fa size 308and address-space modifiers 309.Fa ams . 310.It Fn vme_space_get "vc" "size" "ams" "align" "addr" 311Returns EINVAL on invalid inputs. 312.El 313.Sh AUTOCONFIGURATION 314The VME bus is an indirect-connection bus. 315During autoconfiguration each driver is required to probe the bus 316for the presence of a device. 317A VME driver will receive a pointer to a 318.Fa struct vme_attach_args 319hinting at "locations" (address ranges) on the VME bus where the 320device may be located. 321The driver should check the number of address 322ranges, allocate the address space of these ranges using 323.Fn vme_space_alloc , 324and probe the address space for the device using 325.Fn vme_probe . 326.Pp 327During driver attach the driver should also map the address ranges 328using 329.Fn vme_space_map . 330The interrupt locators in 331.Fa struct vme_attach_args 332are used by 333.Fn vme_intr_map 334and 335.Fn vme_intr_establish . 336.Sh DMA SUPPORT 337Extensive DMA facilities are provided. 338.Sh CODE REFERENCES 339This section describes places within the 340.Nx 341source tree where actual code implementing or using the 342machine-independent 343.Nm 344subsystem can be found. 345All pathnames are relative to 346.Pa /usr/src . 347.Pp 348The 349.Nm 350subsystem itself is implemented within the file 351.Pa sys/dev/vme/vme.c . 352.Sh SEE ALSO 353.Xr vme 4 , 354.Xr autoconf 9 , 355.Xr bus_dma 9 , 356.Xr bus_space 9 , 357.Xr driver 9 358.Sh HISTORY 359The machine-independent VME subsystem appeared in 360.Nx 1.5 . 361.Sh BUGS 362This page is incomplete. 363