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