Documentation/driver-api/vme.rst

   1 VME Device Drivers
   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 :c:func:`vme_register_driver`.
  10
  11 A pointer to a structure of type :c:type:`struct vme_driver <vme_driver>` must
  12 be provided to the registration function. Along with the maximum number of
  13 devices your driver is able to support.
  14
  15 At the minimum, the '.name', '.match' and '.probe' elements of
  16 :c:type:`struct vme_driver <vme_driver>` should be correctly set. The '.name'
  17 element is a pointer to a string holding the device driver's name.
  18
  19 The '.match' function allows control over which VME devices should be registered
  20 with the driver. The match function should return 1 if a device should be
  21 probed and 0 otherwise. This example match function (from vme_user.c) limits
  22 the number of devices probed to one:
  23
  24 .. code-block:: c
  25
  26         #define USER_BUS_MAX    1
  27         ...
  28         static int vme_user_match(struct vme_dev *vdev)
  29         {
  30                 if (vdev->id.num >= USER_BUS_MAX)
  31                         return 0;
  32                 return 1;
  33         }
  34
  35 The '.probe' element should contain a pointer to the probe routine. The
  36 probe routine is passed a :c:type:`struct vme_dev <vme_dev>` pointer as an
  37 argument.
  38
  39 Here, the 'num' field refers to the sequential device ID for this specific
  40 driver. The bridge number (or bus number) can be accessed using
  41 dev->bridge->num.
  42
  43 A function is also provided to unregister the driver from the VME core called
  44 :c:func:`vme_unregister_driver` and should usually be called from the device
  45 driver's exit routine.
  46
  47
  48 Resource management
  49 -------------------
  50
  51 Once a driver has registered with the VME core the provided match routine will
  52 be called the number of times specified during the registration. If a match
  53 succeeds, a non-zero value should be returned. A zero return value indicates
  54 failure. For all successful matches, the probe routine of the corresponding
  55 driver is called. The probe routine is passed a pointer to the devices
  56 device structure. This pointer should be saved, it will be required for
  57 requesting VME resources.
  58
  59 The driver can request ownership of one or more master windows
  60 (:c:func:`vme_master_request`), slave windows (:c:func:`vme_slave_request`)
  61 and/or dma channels (:c:func:`vme_dma_request`). Rather than allowing the device
  62 driver to request a specific window or DMA channel (which may be used by a
  63 different driver) the API allows a resource to be assigned based on the required
  64 attributes of the driver in question. For slave windows these attributes are
  65 split into the VME address spaces that need to be accessed in 'aspace' and VME
  66 bus cycle types required in 'cycle'. Master windows add a further set of
  67 attributes in 'width' specifying the required data transfer widths. These
  68 attributes are defined as bitmasks and as such any combination of the
  69 attributes can be requested for a single window, the core will assign a window
  70 that meets the requirements, returning a pointer of type vme_resource that
  71 should be used to identify the allocated resource when it is used. For DMA
  72 controllers, the request function requires the potential direction of any
  73 transfers to be provided in the route attributes. This is typically VME-to-MEM
  74 and/or MEM-to-VME, though some hardware can support VME-to-VME and MEM-to-MEM
  75 transfers as well as test pattern generation. If an unallocated window fitting
  76 the requirements can not be found a NULL pointer will be returned.
  77
  78 Functions are also provided to free window allocations once they are no longer
  79 required. These functions (:c:func:`vme_master_free`, :c:func:`vme_slave_free`
  80 and :c:func:`vme_dma_free`) should be passed the pointer to the resource
  81 provided during resource allocation.
  82
  83
  84 Master windows
  85 --------------
  86
  87 Master windows provide access from the local processor[s] out onto the VME bus.
  88 The number of windows available and the available access modes is dependent on
  89 the underlying chipset. A window must be configured before it can be used.
  90
  91
  92 Master window configuration
  93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94
  95 Once a master window has been assigned :c:func:`vme_master_set` can be used to
  96 configure it and :c:func:`vme_master_get` to retrieve the current settings. The
  97 address spaces, transfer widths and cycle types are the same as described
  98 under resource management, however some of the options are mutually exclusive.
  99 For example, only one address space may be specified.
 100
 101
 102 Master window access
 103 ~~~~~~~~~~~~~~~~~~~~
 104
 105 The function :c:func:`vme_master_read` can be used to read from and
 106 :c:func:`vme_master_write` used to write to configured master windows.
 107
 108 In addition to simple reads and writes, :c:func:`vme_master_rmw` is provided to
 109 do a read-modify-write transaction. Parts of a VME window can also be mapped
 110 into user space memory using :c:func:`vme_master_mmap`.
 111
 112
 113 Slave windows
 114 -------------
 115
 116 Slave windows provide devices on the VME bus access into mapped portions of the
 117 local memory. The number of windows available and the access modes that can be
 118 used is dependent on the underlying chipset. A window must be configured before
 119 it can be used.
 120
 121
 122 Slave window configuration
 123 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 124
 125 Once a slave window has been assigned :c:func:`vme_slave_set` can be used to
 126 configure it and :c:func:`vme_slave_get` to retrieve the current settings.
 127
 128 The address spaces, transfer widths and cycle types are the same as described
 129 under resource management, however some of the options are mutually exclusive.
 130 For example, only one address space may be specified.
 131
 132
 133 Slave window buffer allocation
 134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 135
 136 Functions are provided to allow the user to allocate
 137 (:c:func:`vme_alloc_consistent`) and free (:c:func:`vme_free_consistent`)
 138 contiguous buffers which will be accessible by the VME bridge. These functions
 139 do not have to be used, other methods can be used to allocate a buffer, though
 140 care must be taken to ensure that they are contiguous and accessible by the VME
 141 bridge.
 142
 143
 144 Slave window access
 145 ~~~~~~~~~~~~~~~~~~~
 146
 147 Slave windows map local memory onto the VME bus, the standard methods for
 148 accessing memory should be used.
 149
 150
 151 DMA channels
 152 ------------
 153
 154 The VME DMA transfer provides the ability to run link-list DMA transfers. The
 155 API introduces the concept of DMA lists. Each DMA list is a link-list which can
 156 be passed to a DMA controller. Multiple lists can be created, extended,
 157 executed, reused and destroyed.
 158
 159
 160 List Management
 161 ~~~~~~~~~~~~~~~
 162
 163 The function :c:func:`vme_new_dma_list` is provided to create and
 164 :c:func:`vme_dma_list_free` to destroy DMA lists. Execution of a list will not
 165 automatically destroy the list, thus enabling a list to be reused for repetitive
 166 tasks.
 167
 168
 169 List Population
 170 ~~~~~~~~~~~~~~~
 171
 172 An item can be added to a list using :c:func:`vme_dma_list_add` (the source and
 173 destination attributes need to be created before calling this function, this is
 174 covered under "Transfer Attributes").
 175
 176 .. note::
 177
 178         The detailed attributes of the transfers source and destination
 179         are not checked until an entry is added to a DMA list, the request
 180         for a DMA channel purely checks the directions in which the
 181         controller is expected to transfer data. As a result it is
 182         possible for this call to return an error, for example if the
 183         source or destination is in an unsupported VME address space.
 184
 185 Transfer Attributes
 186 ~~~~~~~~~~~~~~~~~~~
 187
 188 The attributes for the source and destination are handled separately from adding
 189 an item to a list. This is due to the diverse attributes required for each type
 190 of source and destination. There are functions to create attributes for PCI, VME
 191 and pattern sources and destinations (where appropriate):
 192
 193  - PCI source or destination: :c:func:`vme_dma_pci_attribute`
 194  - VME source or destination: :c:func:`vme_dma_vme_attribute`
 195  - Pattern source: :c:func:`vme_dma_pattern_attribute`
 196
 197 The function :c:func:`vme_dma_free_attribute` should be used to free an
 198 attribute.
 199
 200
 201 List Execution
 202 ~~~~~~~~~~~~~~
 203
 204 The function :c:func:`vme_dma_list_exec` queues a list for execution and will
 205 return once the list has been executed.
 206
 207
 208 Interrupts
 209 ----------
 210
 211 The VME API provides functions to attach and detach callbacks to specific VME
 212 level and status ID combinations and for the generation of VME interrupts with
 213 specific VME level and status IDs.
 214
 215
 216 Attaching Interrupt Handlers
 217 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 218
 219 The function :c:func:`vme_irq_request` can be used to attach and
 220 :c:func:`vme_irq_free` to free a specific VME level and status ID combination.
 221 Any given combination can only be assigned a single callback function. A void
 222 pointer parameter is provided, the value of which is passed to the callback
 223 function, the use of this pointer is user undefined. The callback parameters are
 224 as follows. Care must be taken in writing a callback function, callback
 225 functions run in interrupt context:
 226
 227 .. code-block:: c
 228
 229         void callback(int level, int statid, void *priv);
 230
 231
 232 Interrupt Generation
 233 ~~~~~~~~~~~~~~~~~~~~
 234
 235 The function :c:func:`vme_irq_generate` can be used to generate a VME interrupt
 236 at a given VME level and VME status ID.
 237
 238
 239 Location monitors
 240 -----------------
 241
 242 The VME API provides the following functionality to configure the location
 243 monitor.
 244
 245
 246 Location Monitor Management
 247 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 248
 249 The function :c:func:`vme_lm_request` is provided to request the use of a block
 250 of location monitors and :c:func:`vme_lm_free` to free them after they are no
 251 longer required. Each block may provide a number of location monitors,
 252 monitoring adjacent locations. The function :c:func:`vme_lm_count` can be used
 253 to determine how many locations are provided.
 254
 255
 256 Location Monitor Configuration
 257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 258
 259 Once a bank of location monitors has been allocated, the function
 260 :c:func:`vme_lm_set` is provided to configure the location and mode of the
 261 location monitor. The function :c:func:`vme_lm_get` can be used to retrieve
 262 existing settings.
 263
 264
 265 Location Monitor Use
 266 ~~~~~~~~~~~~~~~~~~~~
 267
 268 The function :c:func:`vme_lm_attach` enables a callback to be attached and
 269 :c:func:`vme_lm_detach` allows on to be detached from each location monitor
 270 location. Each location monitor can monitor a number of adjacent locations. The
 271 callback function is declared as follows.
 272
 273 .. code-block:: c
 274
 275         void callback(void *data);
 276
 277
 278 Slot Detection
 279 --------------
 280
 281 The function :c:func:`vme_slot_num` returns the slot ID of the provided bridge.
 282
 283
 284 Bus Detection
 285 -------------
 286
 287 The function :c:func:`vme_bus_num` returns the bus ID of the provided bridge.
 288
 289
 290 VME API
 291 -------
 292
 293 .. kernel-doc:: drivers/staging/vme_user/vme.h
 294    :internal:
 295
 296 .. kernel-doc:: drivers/staging/vme_user/vme.c
 297    :export: