linux/Documentation/vme_api.txt
<<
>>
Prefs
   1                        VME Device Driver API
   2                        =====================
   3
   4Driver registration
   5===================
   6
   7As with other subsystems within the Linux kernel, VME device drivers register
   8with the VME subsystem, typically called from the devices init routine.  This is
   9achieved via a call to the following function:
  10
  11        int vme_register_driver (struct vme_driver *driver, unsigned int ndevs);
  12
  13If driver registration is successful this function returns zero, if an error
  14occurred a negative error code will be returned.
  15
  16A pointer to a structure of type 'vme_driver' must be provided to the
  17registration function. Along with ndevs, which is the number of devices your
  18driver 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
  32At the minimum, the '.name', '.match' and '.probe' elements of this structure
  33should be correctly set. The '.name' element is a pointer to a string holding
  34the device driver's name.
  35
  36The '.match' function allows control over which VME devices should be registered
  37with the driver. The match function should return 1 if a device should be
  38probed and 0 otherwise. This example match function (from vme_user.c) limits
  39the 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
  50The '.probe' element should contain a pointer to the probe routine. The
  51probe 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
  62Here, the 'num' field refers to the sequential device ID for this specific
  63driver. The bridge number (or bus number) can be accessed using
  64dev->bridge->num.
  65
  66A function is also provided to unregister the driver from the VME core and is
  67usually called from the device driver's exit routine:
  68
  69        void vme_unregister_driver (struct vme_driver *driver);
  70
  71
  72Resource management
  73===================
  74
  75Once a driver has registered with the VME core the provided match routine will
  76be called the number of times specified during the registration. If a match
  77succeeds, a non-zero value should be returned. A zero return value indicates
  78failure. For all successful matches, the probe routine of the corresponding
  79driver is called. The probe routine is passed a pointer to the devices
  80device structure. This pointer should be saved, it will be required for
  81requesting VME resources.
  82
  83The driver can request ownership of one or more master windows, slave windows
  84and/or dma channels. Rather than allowing the device driver to request a
  85specific window or DMA channel (which may be used by a different driver) this
  86driver allows a resource to be assigned based on the required attributes of the
  87driver 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
  97For slave windows these attributes are split into the VME address spaces that
  98need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'.
  99Master windows add a further set of attributes in 'width' specifying the
 100required data transfer widths. These attributes are defined as bitmasks and as
 101such any combination of the attributes can be requested for a single window,
 102the core will assign a window that meets the requirements, returning a pointer
 103of type vme_resource that should be used to identify the allocated resource
 104when it is used. For DMA controllers, the request function requires the
 105potential direction of any transfers to be provided in the route attributes.
 106This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can
 107support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation.
 108If an unallocated window fitting the requirements can not be found a NULL
 109pointer will be returned.
 110
 111Functions are also provided to free window allocations once they are no longer
 112required. These functions should be passed the pointer to the resource provided
 113during 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
 122Master windows
 123==============
 124
 125Master windows provide access from the local processor[s] out onto the VME bus.
 126The number of windows available and the available access modes is dependent on
 127the underlying chipset. A window must be configured before it can be used.
 128
 129
 130Master window configuration
 131---------------------------
 132
 133Once a master window has been assigned the following functions can be used to
 134configure 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
 144The address spaces, transfer widths and cycle types are the same as described
 145under resource management, however some of the options are mutually exclusive.
 146For example, only one address space may be specified.
 147
 148These functions return 0 on success or an error code should the call fail.
 149
 150
 151Master window access
 152--------------------
 153
 154The following functions can be used to read from and write to configured master
 155windows. 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
 163In addition to simple reads and writes, a function is provided to do a
 164read-modify-write transaction. This function returns the original value of the
 165VME 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
 171This functions by reading the offset, applying the mask. If the bits selected in
 172the mask match with the values of the corresponding bits in the compare field,
 173the value of swap is written the specified offset.
 174
 175Parts of a VME window can be mapped into user space memory using the following
 176function:
 177
 178        int vme_master_mmap(struct vme_resource *resource,
 179                struct vm_area_struct *vma)
 180
 181
 182Slave windows
 183=============
 184
 185Slave windows provide devices on the VME bus access into mapped portions of the
 186local memory. The number of windows available and the access modes that can be
 187used is dependent on the underlying chipset. A window must be configured before
 188it can be used.
 189
 190
 191Slave window configuration
 192--------------------------
 193
 194Once a slave window has been assigned the following functions can be used to
 195configure 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
 205The address spaces, transfer widths and cycle types are the same as described
 206under resource management, however some of the options are mutually exclusive.
 207For example, only one address space may be specified.
 208
 209These functions return 0 on success or an error code should the call fail.
 210
 211
 212Slave window buffer allocation
 213------------------------------
 214
 215Functions are provided to allow the user to allocate and free a contiguous
 216buffers which will be accessible by the VME bridge. These functions do not have
 217to be used, other methods can be used to allocate a buffer, though care must be
 218taken 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
 227Slave window access
 228-------------------
 229
 230Slave windows map local memory onto the VME bus, the standard methods for
 231accessing memory should be used.
 232
 233
 234DMA channels
 235============
 236
 237The VME DMA transfer provides the ability to run link-list DMA transfers. The
 238API introduces the concept of DMA lists. Each DMA list is a link-list which can
 239be passed to a DMA controller. Multiple lists can be created, extended,
 240executed, reused and destroyed.
 241
 242
 243List Management
 244---------------
 245
 246The following functions are provided to create and destroy DMA lists. Execution
 247of a list will not automatically destroy the list, thus enabling a list to be
 248reused 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
 255List Population
 256---------------
 257
 258An item can be added to a list using the following function ( the source and
 259destination attributes need to be created before calling this function, this is
 260covered 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
 266NOTE:   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
 273Transfer Attributes
 274-------------------
 275
 276The attributes for the source and destination are handled separately from adding
 277an item to a list. This is due to the diverse attributes required for each type
 278of source and destination. There are functions to create attributes for PCI, VME
 279and pattern sources and destinations (where appropriate):
 280
 281Pattern source:
 282
 283        struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type);
 284
 285PCI source or destination:
 286
 287        struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem);
 288
 289VME 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
 294The following function should be used to free an attribute:
 295
 296        void vme_dma_free_attribute(struct vme_dma_attr *attr);
 297
 298
 299List Execution
 300--------------
 301
 302The following function queues a list for execution. The function will return
 303once the list has been executed:
 304
 305        int vme_dma_list_exec(struct vme_dma_list *list);
 306
 307
 308Interrupts
 309==========
 310
 311The VME API provides functions to attach and detach callbacks to specific VME
 312level and status ID combinations and for the generation of VME interrupts with
 313specific VME level and status IDs.
 314
 315
 316Attaching Interrupt Handlers
 317----------------------------
 318
 319The following functions can be used to attach and free a specific VME level and
 320status ID combination. Any given combination can only be assigned a single
 321callback function. A void pointer parameter is provided, the value of which is
 322passed 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
 329The callback parameters are as follows. Care must be taken in writing a callback
 330function, callback functions run in interrupt context:
 331
 332        void callback(int level, int statid, void *priv);
 333
 334
 335Interrupt Generation
 336--------------------
 337
 338The following function can be used to generate a VME interrupt at a given VME
 339level and VME status ID:
 340
 341        int vme_irq_generate(struct vme_dev *dev, int level, int statid);
 342
 343
 344Location monitors
 345=================
 346
 347The VME API provides the following functionality to configure the location
 348monitor.
 349
 350
 351Location Monitor Management
 352---------------------------
 353
 354The following functions are provided to request the use of a block of location
 355monitors 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
 361Each block may provide a number of location monitors, monitoring adjacent
 362locations. The following function can be used to determine how many locations
 363are provided:
 364
 365        int vme_lm_count(struct vme_resource * res);
 366
 367
 368Location Monitor Configuration
 369------------------------------
 370
 371Once a bank of location monitors has been allocated, the following functions
 372are 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
 381Location Monitor Use
 382--------------------
 383
 384The following functions allow a callback to be attached and detached from each
 385location monitor location. Each location monitor can monitor a number of
 386adjacent 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
 393The callback function is declared as follows.
 394
 395        void callback(void *data);
 396
 397
 398Slot Detection
 399==============
 400
 401This function returns the slot ID of the provided bridge.
 402
 403        int vme_slot_num(struct vme_dev *dev);
 404
 405
 406Bus Detection
 407=============
 408
 409This function returns the bus ID of the provided bridge.
 410
 411        int vme_bus_num(struct vme_dev *dev);
 412
 413
 414