1.\" $NetBSD: vme.9,v 1.1 2001/07/01 04:11:14 gmcgarry 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 <machine/bus.h> 59.Fd #include <dev/vme/vmereg.h> 60.Fd #include <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. The VME bus is a 111high-performance backplane bus for use in computer systems. It is 112based on the VMEbus specification initially released by the VMEbus 113International Trade Association (VITA) in August of 1982. It has 114since 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. The latest revisions allow 64-bit, 118multiplexed transfers. It supports asynchronous, fully handshaken 119transfers at speeds up to 80 MB/sec. It has a master-slave 120architecture, encouraging multiprocessing and supports up to seven 121interrupt levels. 122.Sh DATA TYPES 123Drivers attached to the 124.Nm 125bus will make use of the following data types: 126.Bl -tag -width compact 127.It Fa vme_chipset_tag_t 128An opaque type identifying the bus controller. 129.It Fa vme_addr_t 130Addresses on the bus. 131.It Fa vme_am_t 132Address modifiers. Valid values are VME_AM_A32, VME_AM_A16, 133VME_AM_A24, VME_AM_USERDEF (user/vendor definable), VME_AM_MBO, 134VME_AM_SUPER, VME_AM_USER, VME_AM_DATA, VME_AM_PRG, VME_AM_BLT32 and 135VME_AM_BLT64. 136.It Fa vme_datasize_t 137The datasize of the address space. Valid values are 138VME_D8, VME_D16, and VME_D32. 139.It Fa vme_mapresc_t 140Generic placeholder for any resources needed for a mapping. 141.It Fa vme_intr_handle_t 142An opaque type describing an interrupt mapping. 143.It Fa vme_swap_t 144Hardware swap capabilities for controlling data endianness. Valid 145values have not been specified yet. 146.It Fa struct vme_range 147A structure used to describe an address range on the VME bus. It 148contains the following members: 149.Bd -literal 150 vme_addr_t offset; 151 vme_size_t size; 152 vme_am_t am; 153.Ed 154.It Fa struct vme_attach_args 155A structure used to inform the driver of the 156device properties. It contains the following members: 157.Bd -literal 158 vme_chipset_tag_t va_vct; 159 bus_dma_tag_t va_bdt; 160 int ivector; 161 int ilevel; 162 int numcfranges; 163 struct vme_range r[VME_MAXCFRANGES]; 164.Ed 165.El 166.Sh FUNCTIONS 167.Bl -tag -width compact 168.It Fn vme_probe "vc" "vmeaddr" "len" "am" "datasize" "callback" "arg" 169Probes the VME space managed by controller 170.Fa vc 171at address 172.Fa vmeaddr , 173length 174.Fa len , 175with address modifiers 176.Fa am 177and datasize 178.Fa datasize 179for a device. If a VME device is found, the function 180.Fa callback() 181(if it is not NULL) is called to perform device-specific 182identification. 183.Fa callback() 184is called with the argument 185.Fa arg , 186and the bus-space tag and bus-space handle for accessing the VME space 187mapping and should return a nonzero positive integer for a positive 188device match. 189.It Fo vme_space_map 190.Fa "vc" "vmeaddr" "len" "am" "datasize" "swap" "tag" "handle" "resc" 191.Fc 192Maps the VME space managed by controller 193.Fa vc 194at address 195.Fa vmeaddr , 196length 197.Fa len , 198with address modifiers 199.Fa am , 200datasize 201.Fa datasize 202and endianness 203.Fa swap 204for a device. If the mapping is successful 205.Fa tag 206contains the bus-space tag and 207.Fa handle 208contains the bus-space handle for accessing the VME space mapping. 209.Fa resc 210contains the resources for the mappings. 211.Fn vme_space_map 212returns 0 on success, and nonzero on error. 213.It Fn vme_space_unmap "vc" "resc" 214Unmaps the VME space mapping managed by controller 215.Fa vc 216and resources 217.Fa resc . 218.It Fn vme_intr_map "vc" "level" "vector" "handlep" 219Sets 220.Fa handlep 221to a machine-dependant value which identifies a particular interrupt 222source at level 223.Fa level 224and vector 225.Fa vector 226on the controller 227.Fa vc . 228.Fn vme_intr_map 229returns zero on success, and nonzero on failure. 230.It Fn vme_intr_establish "vc" "handle" "prio" "func" "arg" 231Establishes the interrupt handler 232.Fa handlep . 233When the device interrupts, 234.Fa func() 235will be called with a single argument 236.Fa arg 237and will run at the interrupt priority level 238.Fa prio . 239The return value of 240.Fn vme_intr_establish 241may be saved and passed to 242.Fn vme_intr_disestablish . 243.It Fn vme_intr_disestablish "vc" "cookie" 244Disables the interrupt handler when the driver is no longer interested 245in interrupts from the device. 246.Fa cookie 247is the value returned by 248.Fn vme_intr_establish . 249.It Fn vme_intr_evcnt "vc" "handle" 250Increment the interrupt event counter for the interrupt specified by 251.Fa handle . 252.It Fo vme_dmamap_create 253.Fa "vc" "size" "am" "datasize" "swap" "nsegs" "segsz" "bound" 254.Fa "flags" "map" 255.Fc 256Allocates a DMA handle and initializes it according to the parameters 257provided. The VME-specific parameters describe the 258address-space modifiers 259.Fa am , 260datasize 261.Fa datasize , 262and endianness 263.Fa swap . 264The remaining parameters are described in 265.Xr bus_dma 9 . 266.It Fn vme_dmamap_destroy "vc" "map" 267Frees all resources associated with a given DMA handle. The parameters 268are described in 269.Xr bus_dma 9 . 270.It Fo vme_dmamem_alloc 271.Fa "vc" "size" "am" "datasize" "swap" "segs" "nsegs" "rsegs" "flags" 272.Fc 273Allocates memory that is 274.Do 275DMA safe 276.Dc for the VME bus managed by 277controller 278.Fa vc . 279The VME-specific parameters describe the 280address-space modifiers 281.Fa am , 282datasize 283.Fa datasize , 284and endianness 285.Fa swap . 286The remaining parameters are described in 287.Xr bus_dma 9 . 288.It Fn vme_dmamem_free "vc" "segs" "nsegs" 289Frees memory previously allocated by 290.Fn vme_dmamem_alloc 291for the VME space managed by controller 292.Fa vc . 293.It Fn vme_space_alloc "tag" "addr" "size" "ams" 294Allocate VME space for the bus-space 295.Fa tag 296at address 297.Fa addr 298of size 299.Fa size 300and address-space modifiers 301.Fa ams. 302.Fn vme_space_alloc 303returns EINVAL on invalid inputs. 304.It Fn vme_space_free "vc" "addr" "size" "ams" 305Deallocate VME space for the bus-space 306.Fa tag 307at address 308.Fa addr 309of size 310.Fa size 311and address-space modifiers 312.Fa ams. 313.It Fn vme_space_get "vc" "size" "ams" "align" "addr" 314Returns EINVAL on invalid inputs. 315.El 316.Sh AUTOCONFIGURATION 317The VME bus is an indirect-connection bus. During autoconfiguration 318each driver is required to probe the bus for the presence of a 319device. A VME driver will receive a pointer to a 320.Fa struct vme_attach_args 321hinting at "locations" (address ranges) on the VME bus where the 322device may be located. The driver should check the number of address 323ranges, allocate the address space of these ranges using 324.Fn vme_space_alloc , 325and probe the address space for the device using 326.Fn vme_probe . 327.Pp 328During driver attach the driver should also map the address ranges 329using 330.Fn vme_space_map . 331The interrupt locators in 332.Fa struct vme_attach_args 333are used by 334.Fn vme_intr_map 335and 336.Fn vme_intr_establish . 337.Sh DMA SUPPORT 338Extensive DMA facilities are provided. 339.Sh CODE REFERENCES 340This section describes places within the 341.Nx 342source tree where actual code implementing or utilising the 343machine-independent 344.Nm 345subsystem can be found. All 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