vme.rst 10 KB

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