drivers/staging/vme/vme_api.txt

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