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_request_dma(struct device *dev);
  81
  82 For slave windows these attributes are split into those of type 'vme_address_t'
  83 and 'vme_cycle_t'. Master windows add a further set of attributes 'vme_cycle_t'.
  84 These attributes are defined as bitmasks and as such any combination of the
  85 attributes can be requested for a single window, the core will assign a window
  86 that meets the requirements, returning a pointer of type vme_resource that
  87 should be used to identify the allocated resource when it is used. If an
  88 unallocated window fitting the requirements can not be found a NULL pointer will
  89 be returned.
  90
  91 Functions are also provided to free window allocations once they are no longer
  92 required. These functions should be passed the pointer to the resource provided
  93 during resource allocation:
  94
  95         void vme_master_free(struct vme_resource *res);
  96
  97         void vme_slave_free(struct vme_resource *res);
  98
  99         void vme_dma_free(struct vme_resource *res);
 100
 101
 102 Master windows
 103 ==============
 104
 105 Master windows provide access from the local processor[s] out onto the VME bus.
 106 The number of windows available and the available access modes is dependant on
 107 the underlying chipset. A window must be configured before it can be used.
 108
 109
 110 Master window configuration
 111 ---------------------------
 112
 113 Once a master window has been assigned the following functions can be used to
 114 configure it and retrieve the current settings:
 115
 116         int vme_master_set (struct vme_resource *res, int enabled,
 117                 unsigned long long base, unsigned long long size,
 118                 vme_address_t aspace, vme_cycle_t cycle, vme_width_t width);
 119
 120         int vme_master_get (struct vme_resource *res, int *enabled,
 121                 unsigned long long *base, unsigned long long *size,
 122                 vme_address_t *aspace, vme_cycle_t *cycle, vme_width_t *width);
 123
 124 The address spaces, transfer widths and cycle types are the same as described
 125 under resource management, however some of the options are mutually exclusive.
 126 For example, only one address space may be specified.
 127
 128 These functions return 0 on success or an error code should the call fail.
 129
 130
 131 Master window access
 132 --------------------
 133
 134 The following functions can be used to read from and write to configured master
 135 windows. These functions return the number of bytes copied:
 136
 137         ssize_t vme_master_read(struct vme_resource *res, void *buf,
 138                 size_t count, loff_t offset);
 139
 140         ssize_t vme_master_write(struct vme_resource *res, void *buf,
 141                 size_t count, loff_t offset);
 142
 143 In addition to simple reads and writes, a function is provided to do a
 144 read-modify-write transaction. This function returns the original value of the
 145 VME bus location :
 146
 147         unsigned int vme_master_rmw (struct vme_resource *res,
 148                 unsigned int mask, unsigned int compare, unsigned int swap,
 149                 loff_t offset);
 150
 151 This functions by reading the offset, applying the mask. If the bits selected in
 152 the mask match with the values of the corresponding bits in the compare field,
 153 the value of swap is written the specified offset.
 154
 155
 156 Slave windows
 157 =============
 158
 159 Slave windows provide devices on the VME bus access into mapped portions of the
 160 local memory. The number of windows available and the access modes that can be
 161 used is dependant on the underlying chipset. A window must be configured before
 162 it can be used.
 163
 164
 165 Slave window configuration
 166 --------------------------
 167
 168 Once a slave window has been assigned the following functions can be used to
 169 configure it and retrieve the current settings:
 170
 171         int vme_slave_set (struct vme_resource *res, int enabled,
 172                 unsigned long long base, unsigned long long size,
 173                 dma_addr_t mem, vme_address_t aspace, vme_cycle_t cycle);
 174
 175         int vme_slave_get (struct vme_resource *res, int *enabled,
 176                 unsigned long long *base, unsigned long long *size,
 177                 dma_addr_t *mem, vme_address_t *aspace, vme_cycle_t *cycle);
 178
 179 The address spaces, transfer widths and cycle types are the same as described
 180 under resource management, however some of the options are mutually exclusive.
 181 For example, only one address space may be specified.
 182
 183 These functions return 0 on success or an error code should the call fail.
 184
 185
 186 Slave window buffer allocation
 187 ------------------------------
 188
 189 Functions are provided to allow the user to allocate and free a contiguous
 190 buffers which will be accessible by the VME bridge. These functions do not have
 191 to be used, other methods can be used to allocate a buffer, though care must be
 192 taken to ensure that they are contiguous and accessible by the VME bridge:
 193
 194         void * vme_alloc_consistent(struct vme_resource *res, size_t size,
 195                 dma_addr_t *mem);
 196
 197         void vme_free_consistent(struct vme_resource *res, size_t size,
 198                 void *virt,     dma_addr_t mem);
 199
 200
 201 Slave window access
 202 -------------------
 203
 204 Slave windows map local memory onto the VME bus, the standard methods for
 205 accessing memory should be used.
 206
 207
 208 DMA channels
 209 ============
 210
 211 The VME DMA transfer provides the ability to run link-list DMA transfers. The
 212 API introduces the concept of DMA lists. Each DMA list is a link-list which can
 213 be passed to a DMA controller. Multiple lists can be created, extended,
 214 executed, reused and destroyed.
 215
 216
 217 List Management
 218 ---------------
 219
 220 The following functions are provided to create and destroy DMA lists. Execution
 221 of a list will not automatically destroy the list, thus enabling a list to be
 222 reused for repetitive tasks:
 223
 224         struct vme_dma_list *vme_new_dma_list(struct vme_resource *res);
 225
 226         int vme_dma_list_free(struct vme_dma_list *list);
 227
 228
 229 List Population
 230 ---------------
 231
 232 An item can be added to a list using the following function ( the source and
 233 destination attributes need to be created before calling this function, this is
 234 covered under "Transfer Attributes"):
 235
 236         int vme_dma_list_add(struct vme_dma_list *list,
 237                 struct vme_dma_attr *src, struct vme_dma_attr *dest,
 238                 size_t count);
 239
 240
 241 Transfer Attributes
 242 -------------------
 243
 244 The attributes for the source and destination are handled separately from adding
 245 an item to a list. This is due to the diverse attributes required for each type
 246 of source and destination. There are functions to create attributes for PCI, VME
 247 and pattern sources and destinations (where appropriate):
 248
 249 Pattern source:
 250
 251         struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern,
 252                 vme_pattern_t type);
 253
 254 PCI source or destination:
 255
 256         struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem);
 257
 258 VME source or destination:
 259
 260         struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base,
 261                 vme_address_t aspace, vme_cycle_t cycle, vme_width_t width);
 262
 263 The following function should be used to free an attribute:
 264
 265         void vme_dma_free_attribute(struct vme_dma_attr *attr);
 266
 267
 268 List Execution
 269 --------------
 270
 271 The following function queues a list for execution. The function will return
 272 once the list has been executed:
 273
 274         int vme_dma_list_exec(struct vme_dma_list *list);
 275
 276
 277 Interrupts
 278 ==========
 279
 280 The VME API provides functions to attach and detach callbacks to specific VME
 281 level and status ID combinations and for the generation of VME interrupts with
 282 specific VME level and status IDs.
 283
 284
 285 Attaching Interrupt Handlers
 286 ----------------------------
 287
 288 The following functions can be used to attach and free a specific VME level and
 289 status ID combination. Any given combination can only be assigned a single
 290 callback function. A void pointer parameter is provided, the value of which is
 291 passed to the callback function, the use of this pointer is user undefined:
 292
 293         int vme_request_irq(struct device *dev, int level, int statid,
 294                 void (*callback)(int, int, void *), void *priv);
 295
 296         void vme_free_irq(struct device *dev, int level, int statid);
 297
 298 The callback parameters are as follows. Care must be taken in writing a callback
 299 function, callback functions run in interrupt context:
 300
 301         void callback(int level, int statid, void *priv);
 302
 303
 304 Interrupt Generation
 305 --------------------
 306
 307 The following function can be used to generate a VME interrupt at a given VME
 308 level and VME status ID:
 309
 310         int vme_generate_irq(struct device *dev, int level, int statid);
 311
 312
 313 Location monitors
 314 =================
 315
 316 The VME API provides the following functionality to configure the location
 317 monitor.
 318
 319
 320 Location Monitor Management
 321 ---------------------------
 322
 323 The following functions are provided to request the use of a block of location
 324 monitors and to free them after they are no longer required:
 325
 326         struct vme_resource * vme_lm_request(struct device *dev);
 327
 328         void vme_lm_free(struct vme_resource * res);
 329
 330 Each block may provide a number of location monitors, monitoring adjacent
 331 locations. The following function can be used to determine how many locations
 332 are provided:
 333
 334         int vme_lm_count(struct vme_resource * res);
 335
 336
 337 Location Monitor Configuration
 338 ------------------------------
 339
 340 Once a bank of location monitors has been allocated, the following functions
 341 are provided to configure the location and mode of the location monitor:
 342
 343         int vme_lm_set(struct vme_resource *res, unsigned long long base,
 344                 vme_address_t aspace, vme_cycle_t cycle);
 345
 346         int vme_lm_get(struct vme_resource *res, unsigned long long *base,
 347                 vme_address_t *aspace, vme_cycle_t *cycle);
 348
 349
 350 Location Monitor Use
 351 --------------------
 352
 353 The following functions allow a callback to be attached and detached from each
 354 location monitor location. Each location monitor can monitor a number of
 355 adjacent locations:
 356
 357         int vme_lm_attach(struct vme_resource *res, int num,
 358                 void (*callback)(int));
 359
 360         int vme_lm_detach(struct vme_resource *res, int num);
 361
 362 The callback function is declared as follows.
 363
 364         void callback(int num);
 365
 366
 367 Slot Detection
 368 ==============
 369
 370 This function returns the slot ID of the provided bridge.
 371
 372         int vme_slot_get(struct device *dev);