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