blob: ffe6e22a2ccd992169b654b8de7b4c3041140112 [file] [log] [blame]
Martyn Welchbf39f9a2009-08-28 11:28:56 +01001 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
Lucas De Marchi25985ed2011-03-30 22:57:33 -03009achieved via a call to the following function:
Martyn Welchbf39f9a2009-08-28 11:28:56 +010010
11 int vme_register_driver (struct vme_driver *driver);
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. The structure is as follows:
18
19 struct vme_driver {
20 struct list_head node;
Manohar Vanga5d6abf32011-09-26 11:27:16 +020021 const char *name;
22 int (*match)(struct vme_dev *);
23 int (*probe)(struct vme_dev *);
24 int (*remove)(struct vme_dev *);
25 void (*shutdown)(void);
26 struct device_driver driver;
27 struct list_head devices;
28 unsigned int ndev;
Martyn Welchbf39f9a2009-08-28 11:28:56 +010029 };
30
Manohar Vanga5d6abf32011-09-26 11:27:16 +020031At the minimum, the '.name', '.match' and '.probe' elements of this structure
32should be correctly set. The '.name' element is a pointer to a string holding
33the device driver's name.
Martyn Welchbf39f9a2009-08-28 11:28:56 +010034
Manohar Vanga5d6abf32011-09-26 11:27:16 +020035The '.match' function allows controlling the number of devices that need to
36be registered. The match function should return 1 if a device should be
37probed and 0 otherwise. This example match function (from vme_user.c) limits
38the number of devices probed to one:
Martyn Welchbf39f9a2009-08-28 11:28:56 +010039
Manohar Vanga5d6abf32011-09-26 11:27:16 +020040 #define USER_BUS_MAX 1
41 ...
42 static int vme_user_match(struct vme_dev *vdev)
43 {
44 if (vdev->id.num >= USER_BUS_MAX)
45 return 0;
46 return 1;
47 }
Manohar Vanga8f966dc2011-09-26 11:27:15 +020048
Manohar Vanga5d6abf32011-09-26 11:27:16 +020049The '.probe' element should contain a pointer to the probe routine. The
50probe routine is passed a 'struct vme_dev' pointer as an argument. The
51'struct vme_dev' structure looks like the following:
Manohar Vanga8f966dc2011-09-26 11:27:15 +020052
53 struct vme_dev {
Manohar Vangaa916a392011-09-26 11:27:17 +020054 int num;
Manohar Vanga8f966dc2011-09-26 11:27:15 +020055 struct vme_bridge *bridge;
56 struct device dev;
Manohar Vangaa916a392011-09-26 11:27:17 +020057 struct list_head drv_list;
58 struct list_head bridge_list;
Manohar Vanga8f966dc2011-09-26 11:27:15 +020059 };
60
Manohar Vangaa916a392011-09-26 11:27:17 +020061Here, the 'num' field refers to the sequential device ID for this specific
62driver. The bridge number (or bus number) can be accessed using
63dev->bridge->num.
Martyn Welchbf39f9a2009-08-28 11:28:56 +010064
65A function is also provided to unregister the driver from the VME core and is
66usually called from the device driver's exit routine:
67
68 void vme_unregister_driver (struct vme_driver *driver);
69
70
71Resource management
72===================
73
Manohar Vangaa916a392011-09-26 11:27:17 +020074Once a driver has registered with the VME core the provided match routine will
75be called the number of times specified during the registration. If a match
76succeeds, a non-zero value should be returned. A zero return value indicates
77failure. For all successful matches, the probe routine of the corresponding
78driver is called. The probe routine is passed a pointer to the devices
Martyn Welchbf39f9a2009-08-28 11:28:56 +010079device structure. This pointer should be saved, it will be required for
80requesting VME resources.
81
82The driver can request ownership of one or more master windows, slave windows
83and/or dma channels. Rather than allowing the device driver to request a
84specific window or DMA channel (which may be used by a different driver) this
85driver allows a resource to be assigned based on the required attributes of the
86driver in question:
87
Manohar Vanga8f966dc2011-09-26 11:27:15 +020088 struct vme_resource * vme_master_request(struct vme_dev *dev,
Martyn Welch6af04b02011-12-01 17:06:29 +000089 u32 aspace, u32 cycle, u32 width);
Martyn Welchbf39f9a2009-08-28 11:28:56 +010090
Martyn Welch6af04b02011-12-01 17:06:29 +000091 struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace,
92 u32 cycle);
Martyn Welchbf39f9a2009-08-28 11:28:56 +010093
Martyn Welch6af04b02011-12-01 17:06:29 +000094 struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route);
Martyn Welchbf39f9a2009-08-28 11:28:56 +010095
Martyn Welch6af04b02011-12-01 17:06:29 +000096For slave windows these attributes are split into the VME address spaces that
97need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'.
98Master windows add a further set of attributes in 'width' specifying the
99required data transfer widths. These attributes are defined as bitmasks and as
100such any combination of the attributes can be requested for a single window,
101the core will assign a window that meets the requirements, returning a pointer
102of type vme_resource that should be used to identify the allocated resource
103when it is used. For DMA controllers, the request function requires the
104potential direction of any transfers to be provided in the route attributes.
105This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can
106support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation.
107If an unallocated window fitting the requirements can not be found a NULL
108pointer will be returned.
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100109
110Functions are also provided to free window allocations once they are no longer
111required. These functions should be passed the pointer to the resource provided
112during resource allocation:
113
114 void vme_master_free(struct vme_resource *res);
115
116 void vme_slave_free(struct vme_resource *res);
117
118 void vme_dma_free(struct vme_resource *res);
119
120
121Master windows
122==============
123
124Master windows provide access from the local processor[s] out onto the VME bus.
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300125The number of windows available and the available access modes is dependent on
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100126the underlying chipset. A window must be configured before it can be used.
127
128
129Master window configuration
130---------------------------
131
132Once a master window has been assigned the following functions can be used to
133configure it and retrieve the current settings:
134
135 int vme_master_set (struct vme_resource *res, int enabled,
Martyn Welch6af04b02011-12-01 17:06:29 +0000136 unsigned long long base, unsigned long long size, u32 aspace,
137 u32 cycle, u32 width);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100138
139 int vme_master_get (struct vme_resource *res, int *enabled,
Martyn Welch6af04b02011-12-01 17:06:29 +0000140 unsigned long long *base, unsigned long long *size, u32 *aspace,
141 u32 *cycle, u32 *width);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100142
143The address spaces, transfer widths and cycle types are the same as described
144under resource management, however some of the options are mutually exclusive.
145For example, only one address space may be specified.
146
147These functions return 0 on success or an error code should the call fail.
148
149
150Master window access
151--------------------
152
153The following functions can be used to read from and write to configured master
154windows. These functions return the number of bytes copied:
155
156 ssize_t vme_master_read(struct vme_resource *res, void *buf,
157 size_t count, loff_t offset);
158
159 ssize_t vme_master_write(struct vme_resource *res, void *buf,
160 size_t count, loff_t offset);
161
162In addition to simple reads and writes, a function is provided to do a
163read-modify-write transaction. This function returns the original value of the
164VME bus location :
165
166 unsigned int vme_master_rmw (struct vme_resource *res,
167 unsigned int mask, unsigned int compare, unsigned int swap,
168 loff_t offset);
169
170This functions by reading the offset, applying the mask. If the bits selected in
171the mask match with the values of the corresponding bits in the compare field,
172the value of swap is written the specified offset.
173
174
175Slave windows
176=============
177
178Slave windows provide devices on the VME bus access into mapped portions of the
179local memory. The number of windows available and the access modes that can be
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300180used is dependent on the underlying chipset. A window must be configured before
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100181it can be used.
182
183
184Slave window configuration
185--------------------------
186
187Once a slave window has been assigned the following functions can be used to
188configure it and retrieve the current settings:
189
190 int vme_slave_set (struct vme_resource *res, int enabled,
191 unsigned long long base, unsigned long long size,
Martyn Welch6af04b02011-12-01 17:06:29 +0000192 dma_addr_t mem, u32 aspace, u32 cycle);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100193
194 int vme_slave_get (struct vme_resource *res, int *enabled,
195 unsigned long long *base, unsigned long long *size,
Martyn Welch6af04b02011-12-01 17:06:29 +0000196 dma_addr_t *mem, u32 *aspace, u32 *cycle);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100197
198The address spaces, transfer widths and cycle types are the same as described
199under resource management, however some of the options are mutually exclusive.
200For example, only one address space may be specified.
201
202These functions return 0 on success or an error code should the call fail.
203
204
205Slave window buffer allocation
206------------------------------
207
208Functions are provided to allow the user to allocate and free a contiguous
209buffers which will be accessible by the VME bridge. These functions do not have
210to be used, other methods can be used to allocate a buffer, though care must be
211taken to ensure that they are contiguous and accessible by the VME bridge:
212
213 void * vme_alloc_consistent(struct vme_resource *res, size_t size,
214 dma_addr_t *mem);
215
216 void vme_free_consistent(struct vme_resource *res, size_t size,
217 void *virt, dma_addr_t mem);
218
219
220Slave window access
221-------------------
222
223Slave windows map local memory onto the VME bus, the standard methods for
224accessing memory should be used.
225
226
227DMA channels
228============
229
230The VME DMA transfer provides the ability to run link-list DMA transfers. The
231API introduces the concept of DMA lists. Each DMA list is a link-list which can
232be passed to a DMA controller. Multiple lists can be created, extended,
233executed, reused and destroyed.
234
235
236List Management
237---------------
238
239The following functions are provided to create and destroy DMA lists. Execution
240of a list will not automatically destroy the list, thus enabling a list to be
241reused for repetitive tasks:
242
243 struct vme_dma_list *vme_new_dma_list(struct vme_resource *res);
244
245 int vme_dma_list_free(struct vme_dma_list *list);
246
247
248List Population
249---------------
250
251An item can be added to a list using the following function ( the source and
252destination attributes need to be created before calling this function, this is
253covered under "Transfer Attributes"):
254
255 int vme_dma_list_add(struct vme_dma_list *list,
256 struct vme_dma_attr *src, struct vme_dma_attr *dest,
257 size_t count);
258
Martyn Welch4f723df2010-02-18 15:12:58 +0000259NOTE: The detailed attributes of the transfers source and destination
260 are not checked until an entry is added to a DMA list, the request
261 for a DMA channel purely checks the directions in which the
262 controller is expected to transfer data. As a result it is
263 possible for this call to return an error, for example if the
264 source or destination is in an unsupported VME address space.
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100265
266Transfer Attributes
267-------------------
268
269The attributes for the source and destination are handled separately from adding
270an item to a list. This is due to the diverse attributes required for each type
271of source and destination. There are functions to create attributes for PCI, VME
272and pattern sources and destinations (where appropriate):
273
274Pattern source:
275
Martyn Welch6af04b02011-12-01 17:06:29 +0000276 struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100277
278PCI source or destination:
279
280 struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem);
281
282VME source or destination:
283
284 struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base,
Martyn Welch6af04b02011-12-01 17:06:29 +0000285 u32 aspace, u32 cycle, u32 width);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100286
287The following function should be used to free an attribute:
288
289 void vme_dma_free_attribute(struct vme_dma_attr *attr);
290
291
292List Execution
293--------------
294
295The following function queues a list for execution. The function will return
296once the list has been executed:
297
298 int vme_dma_list_exec(struct vme_dma_list *list);
299
300
301Interrupts
302==========
303
304The VME API provides functions to attach and detach callbacks to specific VME
305level and status ID combinations and for the generation of VME interrupts with
306specific VME level and status IDs.
307
308
309Attaching Interrupt Handlers
310----------------------------
311
312The following functions can be used to attach and free a specific VME level and
313status ID combination. Any given combination can only be assigned a single
314callback function. A void pointer parameter is provided, the value of which is
315passed to the callback function, the use of this pointer is user undefined:
316
Manohar Vanga8f966dc2011-09-26 11:27:15 +0200317 int vme_irq_request(struct vme_dev *dev, int level, int statid,
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100318 void (*callback)(int, int, void *), void *priv);
319
Manohar Vanga8f966dc2011-09-26 11:27:15 +0200320 void vme_irq_free(struct vme_dev *dev, int level, int statid);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100321
322The callback parameters are as follows. Care must be taken in writing a callback
323function, callback functions run in interrupt context:
324
325 void callback(int level, int statid, void *priv);
326
327
328Interrupt Generation
329--------------------
330
331The following function can be used to generate a VME interrupt at a given VME
332level and VME status ID:
333
Manohar Vanga8f966dc2011-09-26 11:27:15 +0200334 int vme_irq_generate(struct vme_dev *dev, int level, int statid);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100335
336
337Location monitors
338=================
339
340The VME API provides the following functionality to configure the location
341monitor.
342
343
344Location Monitor Management
345---------------------------
346
347The following functions are provided to request the use of a block of location
348monitors and to free them after they are no longer required:
349
Manohar Vanga8f966dc2011-09-26 11:27:15 +0200350 struct vme_resource * vme_lm_request(struct vme_dev *dev);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100351
352 void vme_lm_free(struct vme_resource * res);
353
354Each block may provide a number of location monitors, monitoring adjacent
355locations. The following function can be used to determine how many locations
356are provided:
357
358 int vme_lm_count(struct vme_resource * res);
359
360
361Location Monitor Configuration
362------------------------------
363
364Once a bank of location monitors has been allocated, the following functions
365are provided to configure the location and mode of the location monitor:
366
367 int vme_lm_set(struct vme_resource *res, unsigned long long base,
Martyn Welch6af04b02011-12-01 17:06:29 +0000368 u32 aspace, u32 cycle);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100369
370 int vme_lm_get(struct vme_resource *res, unsigned long long *base,
Martyn Welch6af04b02011-12-01 17:06:29 +0000371 u32 *aspace, u32 *cycle);
Martyn Welchbf39f9a2009-08-28 11:28:56 +0100372
373
374Location Monitor Use
375--------------------
376
377The following functions allow a callback to be attached and detached from each
378location monitor location. Each location monitor can monitor a number of
379adjacent locations:
380
381 int vme_lm_attach(struct vme_resource *res, int num,
382 void (*callback)(int));
383
384 int vme_lm_detach(struct vme_resource *res, int num);
385
386The callback function is declared as follows.
387
388 void callback(int num);
389
390
391Slot Detection
392==============
393
394This function returns the slot ID of the provided bridge.
395
Martyn Welchd7729f02013-11-08 11:58:35 +0000396 int vme_slot_num(struct vme_dev *dev);
Martyn Welch978f47d2013-11-08 11:58:34 +0000397
398
399Bus Detection
400=============
401
402This function returns the bus ID of the provided bridge.
403
404 int vme_bus_num(struct vme_dev *dev);
405
406