June 12, 2001 VME 9

### NAME

VME, vme_probe, vme_space_map, vme_space_unmap, vme_intr_map, vme_intr_establish, vme_intr_disestablish, vme_intr_evcnt, vme_dmamap_create, vme_dmamap_destroy, vme_dmamem_alloc, vme_dmamem_free, vme_space_alloc, vme_space_free, vme_space_get - Versa Module Euroboard bus

### SYNOPSIS

```int` vme_probe(```void *vc``, vme_addr_t vmeaddr``, vme_size_t len``, vme_am_t am``, vme_datasize_t datasize``, int (*callback)()``, void *arg`)
```int` vme_space_map(`` ```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` )
```void` vme_space_unmap(```void *vc``, vme_mapresc_t resc`)
```int` vme_intr_map(```void *vc``, int level``, int vector``, vme_intr_handle_t *handlep`)
```void``*` vme_intr_establish(```void *vc``, vme_intr_handle_t handle``, int prio``, int (*func)(void *)``, void *arg`)
```void` vme_intr_disestablish(```void *vc``, void *cookie`)
```const` `struct` `evcnt``*` vme_intr_evcnt(```void *vc``, vme_intr_handle_t handle`)
```int` vme_dmamap_create(`` ```void *vc` `vme_size_t size` `vme_am_t am` `vme_datasize_t datasize` ```vme_swap_t swap` `int nsegs` `vme_size_t segsz` `vme_addr_t bound` ```int flags` `bus_dmamap_t *map` )
```void` vme_dmamap_destroy(```void *vc``, bus_dmamap_t map`)
```int` vme_dmamem_alloc(`` ```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` )
```void` vme_dmamem_free(```void *vc``, bus_dma_segment_t *segs``, int nsegs`)
```int` vme_space_alloc(```struct vmebus_softc *tag``, vme_addr_t addr``, vme_size_t size``, vme_am_t ams`)
```void` vme_space_free(```void *vc``, vme_addr_t addr``, vme_size_t size``, vme_am_t ams`)
```int` vme_space_get(```void *vc``, vme_size_t size``, vme_am_t ams``, u_long align``, vme_addr_t *addr`)

### DESCRIPTION

The VME 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.

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.

### DATA TYPES

Drivers attached to the VME bus will make use of the following data types:

```vme_chipset_tag_t`
  An opaque type identifying the bus controller.

```vme_addr_t`
  Addresses on the bus.

```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.

```vme_datasize_t`
  The datasize of the address space. Valid values are VME_D8, VME_D16, and VME_D32.

```vme_mapresc_t`
  Generic placeholder for any resources needed for a mapping.

```vme_intr_handle_t`
  An opaque type describing an interrupt mapping.

```vme_swap_t`
  Hardware swap capabilities for controlling data endianness. Valid values have not been specified yet.

```struct` `vme_range`
  A structure used to describe an address range on the VME bus. It contains the following members: `

              vme_addr_t offset;
              vme_size_t size;
              vme_am_t am;

  `

```struct` `vme_attach_args`
  A structure used to inform the driver of the device properties. It contains the following members: `

              vme_chipset_tag_t va_vct;
              bus_dma_tag_t va_bdt;
              int ivector;
              int ilevel;
              int numcfranges;
              struct vme_range r[VME_MAXCFRANGES];

  `

### FUNCTIONS

vme_probe(```vc``, vmeaddr``, len``, am``, datasize``, callback``, arg`)
  Probes the VME space managed by controller ```vc` at address ```vmeaddr`, length ```len`, with address modifiers ```am` and datasize ```datasize` for a device. If a VME device is found, the function ```callback()` (if it is not NULL) is called to perform device-specific identification. ```callback()` is called with the argument ```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.

vme_space_map(```vc``, vmeaddr``, len``, am``, datasize``, swap``, tag``, handle``, resc`)
  Maps the VME space managed by controller ```vc` at address ```vmeaddr`, length ```len`, with address modifiers ```am`, datasize ```datasize` and endianness ```swap` for a device. If the mapping is successful ```tag` contains the bus-space tag and ```handle` contains the bus-space handle for accessing the VME space mapping. ```resc` contains the resources for the mappings. vme_space_map(``) returns 0 on success, and nonzero on error.

vme_space_unmap(```vc``, resc`)
  Unmaps the VME space mapping managed by controller ```vc` and resources ```resc`.

vme_intr_map(```vc``, level``, vector``, handlep`)
  Sets ```handlep` to a machine-dependent value which identifies a particular interrupt source at level ```level` and vector ```vector` on the controller ```vc`. vme_intr_map(``) returns zero on success, and nonzero on failure.

vme_intr_establish(```vc``, handle``, prio``, func``, arg`)
  Establishes the interrupt handler ```handlep`. When the device interrupts, ```func()` will be called with a single argument ```arg` and will run at the interrupt priority level ```prio`. The return value of vme_intr_establish(``) may be saved and passed to vme_intr_disestablish(``).

vme_intr_disestablish(```vc``, cookie`)
  Disables the interrupt handler when the driver is no longer interested in interrupts from the device. ```cookie` is the value returned by vme_intr_establish(``).

vme_intr_evcnt(```vc``, handle`)
  Increment the interrupt event counter for the interrupt specified by ```handle`.

vme_dmamap_create(```vc``, size``, am``, datasize``, swap``, nsegs``, segsz``, bound``, flags``, map`)
  Allocates a DMA handle and initializes it according to the parameters provided. The VME-specific parameters describe the address-space modifiers ```am`, datasize ```datasize`, and endianness ```swap`. The remaining parameters are described in bus_dma(9).

vme_dmamap_destroy(```vc``, map`)
  Frees all resources associated with a given DMA handle. The parameters are described in bus_dma(9).

vme_dmamem_alloc(```vc``, size``, am``, datasize``, swap``, segs``, nsegs``, rsegs``, flags`)
  Allocates memory that is ``DMA safefor the VME bus managed by '' controller ```vc`. The VME-specific parameters describe the address-space modifiers ```am`, datasize ```datasize`, and endianness ```swap`. The remaining parameters are described in bus_dma(9).

vme_dmamem_free(```vc``, segs``, nsegs`)
  Frees memory previously allocated by vme_dmamem_alloc(``) for the VME space managed by controller ```vc`.

vme_space_alloc(```tag``, addr``, size``, ams`)
  Allocate VME space for the bus-space ```tag` at address ```addr` of size ```size` and address-space modifiers ```ams`. vme_space_alloc(``) returns EINVAL on invalid inputs.

vme_space_free(```vc``, addr``, size``, ams`)
  Deallocate VME space for the bus-space ```tag` at address ```addr` of size ```size` and address-space modifiers ```ams`.

vme_space_get(```vc``, size``, ams``, align``, addr`)
  Returns EINVAL on invalid inputs.

### 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 ```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 vme_space_alloc(``), and probe the address space for the device using vme_probe(``).

During driver attach the driver should also map the address ranges using vme_space_map(``). The interrupt locators in ```struct` `vme_attach_args` are used by vme_intr_map(``) and vme_intr_establish(``).

### DMA SUPPORT

Extensive DMA facilities are provided.

### CODE REFERENCES

This section describes places within the NetBSD source tree where actual code implementing or using the machine-independent VME subsystem can be found. All pathnames are relative to ```/usr/src`.

The VME subsystem itself is implemented within the file ```sys/dev/vme/vme.c`.

### SEE ALSO

vme(4), autoconf(9), bus_dma(9), bus_space(9), driver(9)

### HISTORY

The machine-independent VME subsystem appeared in NetBSD1.5.

### BUGS

This page is incomplete.