1.\" $NetBSD: vme.9,v 1.6 2002/10/14 13:43:36 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.Fd #include \*[Lt]machine/bus.h\*[Gt] 59.Fd #include \*[Lt]dev/vme/vmereg.h\*[Gt] 60.Fd #include \*[Lt]dev/vme/vmevar.h\*[Gt] 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 Fo vme_space_map 193.Fa "vc" "vmeaddr" "len" "am" "datasize" "swap" "tag" "handle" "resc" 194.Fc 195Maps the VME space managed by controller 196.Fa vc 197at address 198.Fa vmeaddr , 199length 200.Fa len , 201with address modifiers 202.Fa am , 203datasize 204.Fa datasize 205and endianness 206.Fa swap 207for a device. 208If the mapping is successful 209.Fa tag 210contains the bus-space tag and 211.Fa handle 212contains the bus-space handle for accessing the VME space mapping. 213.Fa resc 214contains the resources for the mappings. 215.Fn vme_space_map 216returns 0 on success, and nonzero on error. 217.It Fn vme_space_unmap "vc" "resc" 218Unmaps the VME space mapping managed by controller 219.Fa vc 220and resources 221.Fa resc . 222.It Fn vme_intr_map "vc" "level" "vector" "handlep" 223Sets 224.Fa handlep 225to a machine-dependant value which identifies a particular interrupt 226source at level 227.Fa level 228and vector 229.Fa vector 230on the controller 231.Fa vc . 232.Fn vme_intr_map 233returns zero on success, and nonzero on failure. 234.It Fn vme_intr_establish "vc" "handle" "prio" "func" "arg" 235Establishes the interrupt handler 236.Fa handlep . 237When the device interrupts, 238.Fa func() 239will be called with a single argument 240.Fa arg 241and will run at the interrupt priority level 242.Fa prio . 243The return value of 244.Fn vme_intr_establish 245may be saved and passed to 246.Fn vme_intr_disestablish . 247.It Fn vme_intr_disestablish "vc" "cookie" 248Disables the interrupt handler when the driver is no longer interested 249in interrupts from the device. 250.Fa cookie 251is the value returned by 252.Fn vme_intr_establish . 253.It Fn vme_intr_evcnt "vc" "handle" 254Increment the interrupt event counter for the interrupt specified by 255.Fa handle . 256.It Fo vme_dmamap_create 257.Fa "vc" "size" "am" "datasize" "swap" "nsegs" "segsz" "bound" 258.Fa "flags" "map" 259.Fc 260Allocates a DMA handle and initializes it according to the parameters 261provided. 262The VME-specific parameters describe the address-space modifiers 263.Fa am , 264datasize 265.Fa datasize , 266and endianness 267.Fa swap . 268The remaining parameters are described in 269.Xr bus_dma 9 . 270.It Fn vme_dmamap_destroy "vc" "map" 271Frees all resources associated with a given DMA handle. 272The parameters are described in 273.Xr bus_dma 9 . 274.It Fo vme_dmamem_alloc 275.Fa "vc" "size" "am" "datasize" "swap" "segs" "nsegs" "rsegs" "flags" 276.Fc 277Allocates memory that is 278.Do 279DMA safe 280.Dc for the VME bus managed by 281controller 282.Fa vc . 283The VME-specific parameters describe the 284address-space modifiers 285.Fa am , 286datasize 287.Fa datasize , 288and endianness 289.Fa swap . 290The remaining parameters are described in 291.Xr bus_dma 9 . 292.It Fn vme_dmamem_free "vc" "segs" "nsegs" 293Frees memory previously allocated by 294.Fn vme_dmamem_alloc 295for the VME space managed by controller 296.Fa vc . 297.It Fn vme_space_alloc "tag" "addr" "size" "ams" 298Allocate VME space for the bus-space 299.Fa tag 300at address 301.Fa addr 302of size 303.Fa size 304and address-space modifiers 305.Fa ams . 306.Fn vme_space_alloc 307returns EINVAL on invalid inputs. 308.It Fn vme_space_free "vc" "addr" "size" "ams" 309Deallocate VME space for the bus-space 310.Fa tag 311at address 312.Fa addr 313of size 314.Fa size 315and address-space modifiers 316.Fa ams . 317.It Fn vme_space_get "vc" "size" "ams" "align" "addr" 318Returns EINVAL on invalid inputs. 319.El 320.Sh AUTOCONFIGURATION 321The VME bus is an indirect-connection bus. 322During autoconfiguration each driver is required to probe the bus 323for the presence of a device. 324A VME driver will receive a pointer to a 325.Fa struct vme_attach_args 326hinting at "locations" (address ranges) on the VME bus where the 327device may be located. 328The driver should check the number of address 329ranges, allocate the address space of these ranges using 330.Fn vme_space_alloc , 331and probe the address space for the device using 332.Fn vme_probe . 333.Pp 334During driver attach the driver should also map the address ranges 335using 336.Fn vme_space_map . 337The interrupt locators in 338.Fa struct vme_attach_args 339are used by 340.Fn vme_intr_map 341and 342.Fn vme_intr_establish . 343.Sh DMA SUPPORT 344Extensive DMA facilities are provided. 345.Sh CODE REFERENCES 346This section describes places within the 347.Nx 348source tree where actual code implementing or utilising the 349machine-independent 350.Nm 351subsystem can be found. 352All pathnames are relative to 353.Pa /usr/src . 354.Pp 355The 356.Nm 357subsystem itself is implemented within the file 358.Pa sys/dev/vme/vme.c . 359.Sh SEE ALSO 360.Xr vme 4 , 361.Xr autoconf 9 , 362.Xr bus_dma 9 , 363.Xr bus_space 9 , 364.Xr driver 9 365.Sh HISTORY 366The machine-independent VME subsystem appeared in 367.Nx 1.5 . 368.Sh BUGS 369This page is incomplete. 370