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