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