1 VME Device Driver API 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 the following function: 10 11 int vme_register_driver (struct vme_driver *driver); 12 13If driver registration is successful this function returns zero, if an error 14occurred a negative error code will be returned. 15 16A pointer to a structure of type 'vme_driver' must be provided to the 17registration function. The structure is as follows: 18 19 struct vme_driver { 20 struct list_head node; 21 const char *name; 22 int (*match)(struct vme_dev *); 23 int (*probe)(struct vme_dev *); 24 int (*remove)(struct vme_dev *); 25 void (*shutdown)(void); 26 struct device_driver driver; 27 struct list_head devices; 28 unsigned int ndev; 29 }; 30 31At the minimum, the '.name', '.match' and '.probe' elements of this structure 32should be correctly set. The '.name' element is a pointer to a string holding 33the device driver's name. 34 35The '.match' function allows controlling the number of devices that need to 36be registered. The match function should return 1 if a device should be 37probed and 0 otherwise. This example match function (from vme_user.c) limits 38the number of devices probed to one: 39 40 #define USER_BUS_MAX 1 41 ... 42 static int vme_user_match(struct vme_dev *vdev) 43 { 44 if (vdev->id.num >= USER_BUS_MAX) 45 return 0; 46 return 1; 47 } 48 49The '.probe' element should contain a pointer to the probe routine. The 50probe routine is passed a 'struct vme_dev' pointer as an argument. The 51'struct vme_dev' structure looks like the following: 52 53 struct vme_dev { 54 int num; 55 struct vme_bridge *bridge; 56 struct device dev; 57 struct list_head drv_list; 58 struct list_head bridge_list; 59 }; 60 61Here, the 'num' field refers to the sequential device ID for this specific 62driver. The bridge number (or bus number) can be accessed using 63dev->bridge->num. 64 65A function is also provided to unregister the driver from the VME core and is 66usually called from the device driver's exit routine: 67 68 void vme_unregister_driver (struct vme_driver *driver); 69 70 71Resource management 72=================== 73 74Once a driver has registered with the VME core the provided match routine will 75be called the number of times specified during the registration. If a match 76succeeds, a non-zero value should be returned. A zero return value indicates 77failure. For all successful matches, the probe routine of the corresponding 78driver is called. The probe routine is passed a pointer to the devices 79device structure. This pointer should be saved, it will be required for 80requesting VME resources. 81 82The driver can request ownership of one or more master windows, slave windows 83and/or dma channels. Rather than allowing the device driver to request a 84specific window or DMA channel (which may be used by a different driver) this 85driver allows a resource to be assigned based on the required attributes of the 86driver in question: 87 88 struct vme_resource * vme_master_request(struct vme_dev *dev, 89 u32 aspace, u32 cycle, u32 width); 90 91 struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace, 92 u32 cycle); 93 94 struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route); 95 96For slave windows these attributes are split into the VME address spaces that 97need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'. 98Master windows add a further set of attributes in 'width' specifying the 99required data transfer widths. These attributes are defined as bitmasks and as 100such any combination of the attributes can be requested for a single window, 101the core will assign a window that meets the requirements, returning a pointer 102of type vme_resource that should be used to identify the allocated resource 103when it is used. For DMA controllers, the request function requires the 104potential direction of any transfers to be provided in the route attributes. 105This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can 106support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation. 107If an unallocated window fitting the requirements can not be found a NULL 108pointer will be returned. 109 110Functions are also provided to free window allocations once they are no longer 111required. These functions should be passed the pointer to the resource provided 112during resource allocation: 113 114 void vme_master_free(struct vme_resource *res); 115 116 void vme_slave_free(struct vme_resource *res); 117 118 void vme_dma_free(struct vme_resource *res); 119 120 121Master windows 122============== 123 124Master windows provide access from the local processor[s] out onto the VME bus. 125The number of windows available and the available access modes is dependent on 126the underlying chipset. A window must be configured before it can be used. 127 128 129Master window configuration 130--------------------------- 131 132Once a master window has been assigned the following functions can be used to 133configure it and retrieve the current settings: 134 135 int vme_master_set (struct vme_resource *res, int enabled, 136 unsigned long long base, unsigned long long size, u32 aspace, 137 u32 cycle, u32 width); 138 139 int vme_master_get (struct vme_resource *res, int *enabled, 140 unsigned long long *base, unsigned long long *size, u32 *aspace, 141 u32 *cycle, u32 *width); 142 143The address spaces, transfer widths and cycle types are the same as described 144under resource management, however some of the options are mutually exclusive. 145For example, only one address space may be specified. 146 147These functions return 0 on success or an error code should the call fail. 148 149 150Master window access 151-------------------- 152 153The following functions can be used to read from and write to configured master 154windows. These functions return the number of bytes copied: 155 156 ssize_t vme_master_read(struct vme_resource *res, void *buf, 157 size_t count, loff_t offset); 158 159 ssize_t vme_master_write(struct vme_resource *res, void *buf, 160 size_t count, loff_t offset); 161 162In addition to simple reads and writes, a function is provided to do a 163read-modify-write transaction. This function returns the original value of the 164VME bus location : 165 166 unsigned int vme_master_rmw (struct vme_resource *res, 167 unsigned int mask, unsigned int compare, unsigned int swap, 168 loff_t offset); 169 170This functions by reading the offset, applying the mask. If the bits selected in 171the mask match with the values of the corresponding bits in the compare field, 172the value of swap is written the specified offset. 173 174Parts of a VME window can be mapped into user space memory using the following 175function: 176 177 int vme_master_mmap(struct vme_resource *resource, 178 struct vm_area_struct *vma) 179 180 181Slave windows 182============= 183 184Slave windows provide devices on the VME bus access into mapped portions of the 185local memory. The number of windows available and the access modes that can be 186used is dependent on the underlying chipset. A window must be configured before 187it can be used. 188 189 190Slave window configuration 191-------------------------- 192 193Once a slave window has been assigned the following functions can be used to 194configure it and retrieve the current settings: 195 196 int vme_slave_set (struct vme_resource *res, int enabled, 197 unsigned long long base, unsigned long long size, 198 dma_addr_t mem, u32 aspace, u32 cycle); 199 200 int vme_slave_get (struct vme_resource *res, int *enabled, 201 unsigned long long *base, unsigned long long *size, 202 dma_addr_t *mem, u32 *aspace, u32 *cycle); 203 204The address spaces, transfer widths and cycle types are the same as described 205under resource management, however some of the options are mutually exclusive. 206For example, only one address space may be specified. 207 208These functions return 0 on success or an error code should the call fail. 209 210 211Slave window buffer allocation 212------------------------------ 213 214Functions are provided to allow the user to allocate and free a contiguous 215buffers which will be accessible by the VME bridge. These functions do not have 216to be used, other methods can be used to allocate a buffer, though care must be 217taken to ensure that they are contiguous and accessible by the VME bridge: 218 219 void * vme_alloc_consistent(struct vme_resource *res, size_t size, 220 dma_addr_t *mem); 221 222 void vme_free_consistent(struct vme_resource *res, size_t size, 223 void *virt, dma_addr_t mem); 224 225 226Slave window access 227------------------- 228 229Slave windows map local memory onto the VME bus, the standard methods for 230accessing memory should be used. 231 232 233DMA channels 234============ 235 236The VME DMA transfer provides the ability to run link-list DMA transfers. The 237API introduces the concept of DMA lists. Each DMA list is a link-list which can 238be passed to a DMA controller. Multiple lists can be created, extended, 239executed, reused and destroyed. 240 241 242List Management 243--------------- 244 245The following functions are provided to create and destroy DMA lists. Execution 246of a list will not automatically destroy the list, thus enabling a list to be 247reused for repetitive tasks: 248 249 struct vme_dma_list *vme_new_dma_list(struct vme_resource *res); 250 251 int vme_dma_list_free(struct vme_dma_list *list); 252 253 254List Population 255--------------- 256 257An item can be added to a list using the following function ( the source and 258destination attributes need to be created before calling this function, this is 259covered under "Transfer Attributes"): 260 261 int vme_dma_list_add(struct vme_dma_list *list, 262 struct vme_dma_attr *src, struct vme_dma_attr *dest, 263 size_t count); 264 265NOTE: The detailed attributes of the transfers source and destination 266 are not checked until an entry is added to a DMA list, the request 267 for a DMA channel purely checks the directions in which the 268 controller is expected to transfer data. As a result it is 269 possible for this call to return an error, for example if the 270 source or destination is in an unsupported VME address space. 271 272Transfer Attributes 273------------------- 274 275The attributes for the source and destination are handled separately from adding 276an item to a list. This is due to the diverse attributes required for each type 277of source and destination. There are functions to create attributes for PCI, VME 278and pattern sources and destinations (where appropriate): 279 280Pattern source: 281 282 struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type); 283 284PCI source or destination: 285 286 struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem); 287 288VME source or destination: 289 290 struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base, 291 u32 aspace, u32 cycle, u32 width); 292 293The following function should be used to free an attribute: 294 295 void vme_dma_free_attribute(struct vme_dma_attr *attr); 296 297 298List Execution 299-------------- 300 301The following function queues a list for execution. The function will return 302once the list has been executed: 303 304 int vme_dma_list_exec(struct vme_dma_list *list); 305 306 307Interrupts 308========== 309 310The VME API provides functions to attach and detach callbacks to specific VME 311level and status ID combinations and for the generation of VME interrupts with 312specific VME level and status IDs. 313 314 315Attaching Interrupt Handlers 316---------------------------- 317 318The following functions can be used to attach and free a specific VME level and 319status ID combination. Any given combination can only be assigned a single 320callback function. A void pointer parameter is provided, the value of which is 321passed to the callback function, the use of this pointer is user undefined: 322 323 int vme_irq_request(struct vme_dev *dev, int level, int statid, 324 void (*callback)(int, int, void *), void *priv); 325 326 void vme_irq_free(struct vme_dev *dev, int level, int statid); 327 328The callback parameters are as follows. Care must be taken in writing a callback 329function, callback functions run in interrupt context: 330 331 void callback(int level, int statid, void *priv); 332 333 334Interrupt Generation 335-------------------- 336 337The following function can be used to generate a VME interrupt at a given VME 338level and VME status ID: 339 340 int vme_irq_generate(struct vme_dev *dev, int level, int statid); 341 342 343Location monitors 344================= 345 346The VME API provides the following functionality to configure the location 347monitor. 348 349 350Location Monitor Management 351--------------------------- 352 353The following functions are provided to request the use of a block of location 354monitors and to free them after they are no longer required: 355 356 struct vme_resource * vme_lm_request(struct vme_dev *dev); 357 358 void vme_lm_free(struct vme_resource * res); 359 360Each block may provide a number of location monitors, monitoring adjacent 361locations. The following function can be used to determine how many locations 362are provided: 363 364 int vme_lm_count(struct vme_resource * res); 365 366 367Location Monitor Configuration 368------------------------------ 369 370Once a bank of location monitors has been allocated, the following functions 371are provided to configure the location and mode of the location monitor: 372 373 int vme_lm_set(struct vme_resource *res, unsigned long long base, 374 u32 aspace, u32 cycle); 375 376 int vme_lm_get(struct vme_resource *res, unsigned long long *base, 377 u32 *aspace, u32 *cycle); 378 379 380Location Monitor Use 381-------------------- 382 383The following functions allow a callback to be attached and detached from each 384location monitor location. Each location monitor can monitor a number of 385adjacent locations: 386 387 int vme_lm_attach(struct vme_resource *res, int num, 388 void (*callback)(int)); 389 390 int vme_lm_detach(struct vme_resource *res, int num); 391 392The callback function is declared as follows. 393 394 void callback(int num); 395 396 397Slot Detection 398============== 399 400This function returns the slot ID of the provided bridge. 401 402 int vme_slot_num(struct vme_dev *dev); 403 404 405Bus Detection 406============= 407 408This function returns the bus ID of the provided bridge. 409 410 int vme_bus_num(struct vme_dev *dev); 411 412 413