vme.rst (10640B)
1VME Device Drivers 2================== 3 4Driver registration 5------------------- 6 7As with other subsystems within the Linux kernel, VME device drivers register 8with the VME subsystem, typically called from the devices init routine. This is 9achieved via a call to :c:func:`vme_register_driver`. 10 11A pointer to a structure of type :c:type:`struct vme_driver <vme_driver>` must 12be provided to the registration function. Along with the maximum number of 13devices your driver is able to support. 14 15At the minimum, the '.name', '.match' and '.probe' elements of 16:c:type:`struct vme_driver <vme_driver>` should be correctly set. The '.name' 17element is a pointer to a string holding the device driver's name. 18 19The '.match' function allows control over which VME devices should be registered 20with the driver. The match function should return 1 if a device should be 21probed and 0 otherwise. This example match function (from vme_user.c) limits 22the number of devices probed to one: 23 24.. code-block:: c 25 26 #define USER_BUS_MAX 1 27 ... 28 static int vme_user_match(struct vme_dev *vdev) 29 { 30 if (vdev->id.num >= USER_BUS_MAX) 31 return 0; 32 return 1; 33 } 34 35The '.probe' element should contain a pointer to the probe routine. The 36probe routine is passed a :c:type:`struct vme_dev <vme_dev>` pointer as an 37argument. 38 39Here, the 'num' field refers to the sequential device ID for this specific 40driver. The bridge number (or bus number) can be accessed using 41dev->bridge->num. 42 43A function is also provided to unregister the driver from the VME core called 44:c:func:`vme_unregister_driver` and should usually be called from the device 45driver's exit routine. 46 47 48Resource management 49------------------- 50 51Once a driver has registered with the VME core the provided match routine will 52be called the number of times specified during the registration. If a match 53succeeds, a non-zero value should be returned. A zero return value indicates 54failure. For all successful matches, the probe routine of the corresponding 55driver is called. The probe routine is passed a pointer to the devices 56device structure. This pointer should be saved, it will be required for 57requesting VME resources. 58 59The driver can request ownership of one or more master windows 60(:c:func:`vme_master_request`), slave windows (:c:func:`vme_slave_request`) 61and/or dma channels (:c:func:`vme_dma_request`). Rather than allowing the device 62driver to request a specific window or DMA channel (which may be used by a 63different driver) the API allows a resource to be assigned based on the required 64attributes of the driver in question. For slave windows these attributes are 65split into the VME address spaces that need to be accessed in 'aspace' and VME 66bus cycle types required in 'cycle'. Master windows add a further set of 67attributes in 'width' specifying the required data transfer widths. These 68attributes are defined as bitmasks and as such any combination of the 69attributes can be requested for a single window, the core will assign a window 70that meets the requirements, returning a pointer of type vme_resource that 71should be used to identify the allocated resource when it is used. For DMA 72controllers, the request function requires the potential direction of any 73transfers to be provided in the route attributes. This is typically VME-to-MEM 74and/or MEM-to-VME, though some hardware can support VME-to-VME and MEM-to-MEM 75transfers as well as test pattern generation. If an unallocated window fitting 76the requirements can not be found a NULL pointer will be returned. 77 78Functions are also provided to free window allocations once they are no longer 79required. These functions (:c:func:`vme_master_free`, :c:func:`vme_slave_free` 80and :c:func:`vme_dma_free`) should be passed the pointer to the resource 81provided during resource allocation. 82 83 84Master windows 85-------------- 86 87Master windows provide access from the local processor[s] out onto the VME bus. 88The number of windows available and the available access modes is dependent on 89the underlying chipset. A window must be configured before it can be used. 90 91 92Master window configuration 93~~~~~~~~~~~~~~~~~~~~~~~~~~~ 94 95Once a master window has been assigned :c:func:`vme_master_set` can be used to 96configure it and :c:func:`vme_master_get` to retrieve the current settings. The 97address spaces, transfer widths and cycle types are the same as described 98under resource management, however some of the options are mutually exclusive. 99For example, only one address space may be specified. 100 101 102Master window access 103~~~~~~~~~~~~~~~~~~~~ 104 105The function :c:func:`vme_master_read` can be used to read from and 106:c:func:`vme_master_write` used to write to configured master windows. 107 108In addition to simple reads and writes, :c:func:`vme_master_rmw` is provided to 109do a read-modify-write transaction. Parts of a VME window can also be mapped 110into user space memory using :c:func:`vme_master_mmap`. 111 112 113Slave windows 114------------- 115 116Slave windows provide devices on the VME bus access into mapped portions of the 117local memory. The number of windows available and the access modes that can be 118used is dependent on the underlying chipset. A window must be configured before 119it can be used. 120 121 122Slave window configuration 123~~~~~~~~~~~~~~~~~~~~~~~~~~ 124 125Once a slave window has been assigned :c:func:`vme_slave_set` can be used to 126configure it and :c:func:`vme_slave_get` to retrieve the current settings. 127 128The address spaces, transfer widths and cycle types are the same as described 129under resource management, however some of the options are mutually exclusive. 130For example, only one address space may be specified. 131 132 133Slave window buffer allocation 134~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 135 136Functions are provided to allow the user to allocate 137(:c:func:`vme_alloc_consistent`) and free (:c:func:`vme_free_consistent`) 138contiguous buffers which will be accessible by the VME bridge. These functions 139do not have to be used, other methods can be used to allocate a buffer, though 140care must be taken to ensure that they are contiguous and accessible by the VME 141bridge. 142 143 144Slave window access 145~~~~~~~~~~~~~~~~~~~ 146 147Slave windows map local memory onto the VME bus, the standard methods for 148accessing memory should be used. 149 150 151DMA channels 152------------ 153 154The VME DMA transfer provides the ability to run link-list DMA transfers. The 155API introduces the concept of DMA lists. Each DMA list is a link-list which can 156be passed to a DMA controller. Multiple lists can be created, extended, 157executed, reused and destroyed. 158 159 160List Management 161~~~~~~~~~~~~~~~ 162 163The function :c:func:`vme_new_dma_list` is provided to create and 164:c:func:`vme_dma_list_free` to destroy DMA lists. Execution of a list will not 165automatically destroy the list, thus enabling a list to be reused for repetitive 166tasks. 167 168 169List Population 170~~~~~~~~~~~~~~~ 171 172An item can be added to a list using :c:func:`vme_dma_list_add` (the source and 173destination attributes need to be created before calling this function, this is 174covered under "Transfer Attributes"). 175 176.. note:: 177 178 The detailed attributes of the transfers source and destination 179 are not checked until an entry is added to a DMA list, the request 180 for a DMA channel purely checks the directions in which the 181 controller is expected to transfer data. As a result it is 182 possible for this call to return an error, for example if the 183 source or destination is in an unsupported VME address space. 184 185Transfer Attributes 186~~~~~~~~~~~~~~~~~~~ 187 188The attributes for the source and destination are handled separately from adding 189an item to a list. This is due to the diverse attributes required for each type 190of source and destination. There are functions to create attributes for PCI, VME 191and pattern sources and destinations (where appropriate): 192 193 - PCI source or destination: :c:func:`vme_dma_pci_attribute` 194 - VME source or destination: :c:func:`vme_dma_vme_attribute` 195 - Pattern source: :c:func:`vme_dma_pattern_attribute` 196 197The function :c:func:`vme_dma_free_attribute` should be used to free an 198attribute. 199 200 201List Execution 202~~~~~~~~~~~~~~ 203 204The function :c:func:`vme_dma_list_exec` queues a list for execution and will 205return once the list has been executed. 206 207 208Interrupts 209---------- 210 211The VME API provides functions to attach and detach callbacks to specific VME 212level and status ID combinations and for the generation of VME interrupts with 213specific VME level and status IDs. 214 215 216Attaching Interrupt Handlers 217~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 218 219The function :c:func:`vme_irq_request` can be used to attach and 220:c:func:`vme_irq_free` to free a specific VME level and status ID combination. 221Any given combination can only be assigned a single callback function. A void 222pointer parameter is provided, the value of which is passed to the callback 223function, the use of this pointer is user undefined. The callback parameters are 224as follows. Care must be taken in writing a callback function, callback 225functions run in interrupt context: 226 227.. code-block:: c 228 229 void callback(int level, int statid, void *priv); 230 231 232Interrupt Generation 233~~~~~~~~~~~~~~~~~~~~ 234 235The function :c:func:`vme_irq_generate` can be used to generate a VME interrupt 236at a given VME level and VME status ID. 237 238 239Location monitors 240----------------- 241 242The VME API provides the following functionality to configure the location 243monitor. 244 245 246Location Monitor Management 247~~~~~~~~~~~~~~~~~~~~~~~~~~~ 248 249The function :c:func:`vme_lm_request` is provided to request the use of a block 250of location monitors and :c:func:`vme_lm_free` to free them after they are no 251longer required. Each block may provide a number of location monitors, 252monitoring adjacent locations. The function :c:func:`vme_lm_count` can be used 253to determine how many locations are provided. 254 255 256Location Monitor Configuration 257~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 258 259Once a bank of location monitors has been allocated, the function 260:c:func:`vme_lm_set` is provided to configure the location and mode of the 261location monitor. The function :c:func:`vme_lm_get` can be used to retrieve 262existing settings. 263 264 265Location Monitor Use 266~~~~~~~~~~~~~~~~~~~~ 267 268The function :c:func:`vme_lm_attach` enables a callback to be attached and 269:c:func:`vme_lm_detach` allows on to be detached from each location monitor 270location. Each location monitor can monitor a number of adjacent locations. The 271callback function is declared as follows. 272 273.. code-block:: c 274 275 void callback(void *data); 276 277 278Slot Detection 279-------------- 280 281The function :c:func:`vme_slot_num` returns the slot ID of the provided bridge. 282 283 284Bus Detection 285------------- 286 287The function :c:func:`vme_bus_num` returns the bus ID of the provided bridge. 288 289 290VME API 291------- 292 293.. kernel-doc:: include/linux/vme.h 294 :internal: 295 296.. kernel-doc:: drivers/vme/vme.c 297 :export: