drivers/staging/vme/TODO

   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 TODO:   DMA Resource Allocation incomplete. No attribute based selection.
  81
  82         struct vme_resource *vme_request_dma(struct device *dev);
  83
  84 For slave windows these attributes are split into those of type ???vme_address_t???
  85 and ???vme_cycle_t???. Master windows add a further set of attributes ???vme_cycle_t???.
  86 These attributes are defined as bitmasks and as such any combination of the
  87 attributes can be requested for a single window, the core will assign a window
  88 that meets the requirements, returning a pointer of type vme_resource that
  89 should be used to identify the allocated resource when it is used. If an
  90 unallocated window fitting the requirements can not be found a NULL pointer will
  91 be returned.
  92
  93 Functions are also provided to free window allocations once they are no longer
  94 required. These functions should be passed the pointer to the resource provided
  95 during resource allocation:
  96
  97         void vme_master_free(struct vme_resource *res);
  98
  99         void vme_slave_free(struct vme_resource *res);
 100
 101         void vme_dma_free(struct vme_resource *res);
 102
 103
 104 Master windows
 105 ==============
 106
 107 Master windows provide access from the local processor[s] out onto the VME bus.
 108 The number of windows available and the available access modes is dependant on
 109 the underlying chipset. A window must be configured before it can be used.
 110
 111
 112 Master window configuration
 113 ---------------------------
 114
 115 Once a master window has been assigned the following functions can be used to
 116 configure it and retrieve the current settings:
 117
 118         int vme_master_set (struct vme_resource *res, int enabled,
 119                 unsigned long long base, unsigned long long size,
 120                 vme_address_t aspace, vme_cycle_t cycle, vme_width_t width);
 121
 122         int vme_master_get (struct vme_resource *res, int *enabled,
 123                 unsigned long long *base, unsigned long long *size,
 124                 vme_address_t *aspace, vme_cycle_t *cycle, vme_width_t *width);
 125
 126 The address spaces, transfer widths and cycle types are the same as described
 127 under resource management, however some of the options are mutually exclusive.
 128 For example, only one address space may be specified.
 129
 130 These functions return 0 on success or an error code should the call fail.
 131
 132
 133 Master window broadcast select mask
 134 -----------------------------------
 135
 136 TODO:   Add functions to set and get Broadcast Select mask:
 137
 138         int vme_master_bmsk_set (struct vme_resource *res, int mask);
 139         int vme_master_bmsk_get (struct vme_resource *res, int *mask);
 140
 141
 142 Master window access
 143 --------------------
 144
 145 The following functions can be used to read from and write to configured master
 146 windows. These functions return the number of bytes copied:
 147
 148         ssize_t vme_master_read(struct vme_resource *res, void *buf,
 149                 size_t count, loff_t offset);
 150
 151         ssize_t vme_master_write(struct vme_resource *res, void *buf,
 152                 size_t count, loff_t offset);
 153
 154 In addition to simple reads and writes, a function is provided to do a
 155 read-modify-write transaction. This function returns the original value of the
 156 VME bus location :
 157
 158         unsigned int vme_master_rmw (struct vme_resource *res,
 159                 unsigned int mask, unsigned int compare, unsigned int swap,
 160                 loff_t offset);
 161
 162 This functions by reading the offset, applying the mask. If the bits selected in
 163 the mask match with the values of the corresponding bits in the compare field,
 164 the value of swap is written the specified offset.
 165
 166
 167 Slave windows
 168 =============
 169
 170 Slave windows provide devices on the VME bus access into mapped portions of the
 171 local memory. The number of windows available and the access modes that can be
 172 used is dependant on the underlying chipset. A window must be configured before
 173 it can be used.
 174
 175
 176 Slave window configuration
 177 --------------------------
 178
 179 Once a slave window has been assigned the following functions can be used to
 180 configure it and retrieve the current settings:
 181
 182         int vme_slave_set (struct vme_resource *res, int enabled,
 183                 unsigned long long base, unsigned long long size,
 184                 dma_addr_t mem, vme_address_t aspace, vme_cycle_t cycle);
 185
 186         int vme_slave_get (struct vme_resource *res, int *enabled,
 187                 unsigned long long *base, unsigned long long *size,
 188                 dma_addr_t *mem, vme_address_t *aspace, vme_cycle_t *cycle);
 189
 190 The address spaces, transfer widths and cycle types are the same as described
 191 under resource management, however some of the options are mutually exclusive.
 192 For example, only one address space may be specified.
 193
 194 These functions return 0 on success or an error code should the call fail.
 195
 196
 197 Slave window buffer allocation
 198 ------------------------------
 199
 200 Functions are provided to allow the user to allocate and free a contiguous
 201 buffers which will be accessible by the VME bridge. These functions do not have
 202 to be used, other methods can be used to allocate a buffer, though care must be
 203 taken to ensure that they are contiguous and accessible by the VME bridge:
 204
 205         void * vme_alloc_consistent(struct vme_resource *res, size_t size,
 206                 dma_addr_t *mem);
 207
 208         void vme_free_consistent(struct vme_resource *res, size_t size,
 209                 void *virt,     dma_addr_t mem);
 210
 211
 212 Slave window access
 213 -------------------
 214
 215 Slave windows map local memory onto the VME bus, the standard methods for
 216 accessing memory should be used.
 217
 218
 219 DMA channels
 220 ============
 221
 222 The VME DMA transfer provides the ability to run link-list DMA transfers. The
 223 API introduces the concept of DMA lists. Each DMA list is a link-list which can
 224 be passed to a DMA controller. Multiple lists can be created, extended,
 225 executed, reused and destroyed.
 226
 227
 228 List Management
 229 ---------------
 230
 231 The following functions are provided to create and destroy DMA lists. Execution
 232 of a list will not automatically destroy the list, thus enabling a list to be
 233 reused for repetitive tasks:
 234
 235         struct vme_dma_list *vme_new_dma_list(struct vme_resource *res);
 236
 237         int vme_dma_list_free(struct vme_dma_list *list);
 238
 239
 240 List Population
 241 ---------------
 242
 243 An item can be added to a list using the following function ( the source and
 244 destination attributes need to be created before calling this function, this is
 245 covered under "Transfer Attributes"):
 246
 247         int vme_dma_list_add(struct vme_dma_list *list,
 248                 struct vme_dma_attr *src, struct vme_dma_attr *dest,
 249                 size_t count);
 250
 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_request_irq(struct device *dev, int level, int statid,
 305                 void (*callback)(int, int, void *), void *priv);
 306
 307         void vme_free_irq(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_generate_irq(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 TODO:   Provide a mechanism to request use of the location monitor. The location
 335         monitors can be moved and we only want one driver to be able to do that
 336         at a time! We also need to be able to free the location monitor for
 337         others to use.
 338
 339         struct vme_resource * vme_request_lm(struct device *dev);
 340
 341         void vme_free_lm(struct vme_resource * res);
 342
 343
 344 Location Monitor Configuration
 345 ------------------------------
 346
 347 TODO:   Change to struct "vme_resource *res" rather than "struct device *dev".
 348
 349 The following functions are provided to configure the location and mode of the
 350 location monitor:
 351
 352         int vme_lm_set(struct device *dev, unsigned long long base,
 353                 vme_address_t aspace, vme_cycle_t cycle);
 354
 355         int vme_lm_get(struct device *dev, unsigned long long *base,
 356                 vme_address_t *aspace, vme_cycle_t *cycle);
 357
 358
 359 Location Monitor Use
 360 --------------------
 361
 362 TODO:   Change to struct "vme_resource *res" rather than "struct device *dev".
 363
 364 The following functions allow a callback to be attached and detached from each
 365 location monitor location. The API currently supports 4 location monitors,
 366 monitoring 4 adjacent locations:
 367
 368         int vme_lm_attach(struct device *dev, int num,
 369                 void (*callback)(int));
 370
 371         int vme_lm_detach(struct device *dev, int num);
 372
 373 The callback function is declared as follows.
 374
 375         void callback(int num);
 376
 377
 378 CR/CSR
 379 ======
 380
 381 TODO:   The VME API needs functions to access the CR/CSR buffer.
 382
 383 Slot Detection
 384 ==============
 385
 386 This function returns the slot ID of the provided bridge.
 387
 388         int vme_slot_get(struct device *dev);