Staging: netwave: add TODO file
[linux-2.6.git] / drivers / staging / vme / vme_api.txt
1                         VME Device Driver API
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 the follwoing function:
10
11         int vme_register_driver (struct vme_driver *driver);
12
13 If driver registration is successful this function returns zero, if an error
14 occurred a negative error code will be returned.
15
16 A pointer to a structure of type 'vme_driver' must be provided to the
17 registration function. The structure is as follows:
18
19         struct vme_driver {
20                 struct list_head node;
21                 char *name;
22                 const struct vme_device_id *bind_table;
23                 int (*probe)  (struct device *, int, int);
24                 int (*remove) (struct device *, int, int);
25                 void (*shutdown) (void);
26                 struct device_driver    driver;
27         };
28
29 At the minimum, the '.name', '.probe' and '.bind_table' elements of this
30 structure should be correctly set. The '.name' element is a pointer to a string
31 holding the device driver's name. The '.probe' element should contain a pointer
32 to the probe routine.
33
34 The arguments of the probe routine are as follows:
35
36         probe(struct device *dev, int bus, int slot);
37
38 The '.bind_table' is a pointer to an array of type 'vme_device_id':
39
40         struct vme_device_id {
41                 int bus;
42                 int slot;
43         };
44
45 Each structure in this array should provide a bus and slot number where the core
46 should probe, using the driver's probe routine, for a device on the specified
47 VME bus.
48
49 The VME subsystem supports a single VME driver per 'slot'. There are considered
50 to be 32 slots per bus, one for each slot-ID as defined in the ANSI/VITA 1-1994
51 specification and are analogious to the physical slots on the VME backplane.
52
53 A function is also provided to unregister the driver from the VME core and is
54 usually called from the device driver's exit routine:
55
56         void vme_unregister_driver (struct vme_driver *driver);
57
58
59 Resource management
60 ===================
61
62 Once a driver has registered with the VME core the provided probe routine will
63 be called for each of the bus/slot combination that becomes valid as VME buses
64 are themselves registered.  The probe routine is passed a pointer to the devices
65 device structure. This pointer should be saved, it will be required for
66 requesting VME resources.
67
68 The driver can request ownership of one or more master windows, slave windows
69 and/or dma channels. Rather than allowing the device driver to request a
70 specific window or DMA channel (which may be used by a different driver) this
71 driver allows a resource to be assigned based on the required attributes of the
72 driver in question:
73
74         struct vme_resource * vme_master_request(struct device *dev,
75                 vme_address_t aspace, vme_cycle_t cycle, vme_width_t width);
76
77         struct vme_resource * vme_slave_request(struct device *dev,
78                 vme_address_t aspace, vme_cycle_t cycle);
79
80         struct vme_resource *vme_request_dma(struct device *dev);
81
82 For slave windows these attributes are split into those of type 'vme_address_t'
83 and 'vme_cycle_t'. Master windows add a further set of attributes 'vme_cycle_t'.
84 These attributes are defined as bitmasks and as such any combination of the
85 attributes can be requested for a single window, the core will assign a window
86 that meets the requirements, returning a pointer of type vme_resource that
87 should be used to identify the allocated resource when it is used. If an
88 unallocated window fitting the requirements can not be found a NULL pointer will
89 be returned.
90
91 Functions are also provided to free window allocations once they are no longer
92 required. These functions should be passed the pointer to the resource provided
93 during resource allocation:
94
95         void vme_master_free(struct vme_resource *res);
96
97         void vme_slave_free(struct vme_resource *res);
98
99         void vme_dma_free(struct vme_resource *res);
100
101
102 Master windows
103 ==============
104
105 Master windows provide access from the local processor[s] out onto the VME bus.
106 The number of windows available and the available access modes is dependant on
107 the underlying chipset. A window must be configured before it can be used.
108
109
110 Master window configuration
111 ---------------------------
112
113 Once a master window has been assigned the following functions can be used to
114 configure it and retrieve the current settings:
115
116         int vme_master_set (struct vme_resource *res, int enabled,
117                 unsigned long long base, unsigned long long size,
118                 vme_address_t aspace, vme_cycle_t cycle, vme_width_t width);
119
120         int vme_master_get (struct vme_resource *res, int *enabled,
121                 unsigned long long *base, unsigned long long *size,
122                 vme_address_t *aspace, vme_cycle_t *cycle, vme_width_t *width);
123
124 The address spaces, transfer widths and cycle types are the same as described
125 under resource management, however some of the options are mutually exclusive.
126 For example, only one address space may be specified.
127
128 These functions return 0 on success or an error code should the call fail.
129
130
131 Master window access
132 --------------------
133
134 The following functions can be used to read from and write to configured master
135 windows. These functions return the number of bytes copied:
136
137         ssize_t vme_master_read(struct vme_resource *res, void *buf,
138                 size_t count, loff_t offset);
139
140         ssize_t vme_master_write(struct vme_resource *res, void *buf,
141                 size_t count, loff_t offset);
142
143 In addition to simple reads and writes, a function is provided to do a
144 read-modify-write transaction. This function returns the original value of the
145 VME bus location :
146
147         unsigned int vme_master_rmw (struct vme_resource *res,
148                 unsigned int mask, unsigned int compare, unsigned int swap,
149                 loff_t offset);
150
151 This functions by reading the offset, applying the mask. If the bits selected in
152 the mask match with the values of the corresponding bits in the compare field,
153 the value of swap is written the specified offset.
154
155
156 Slave windows
157 =============
158
159 Slave windows provide devices on the VME bus access into mapped portions of the
160 local memory. The number of windows available and the access modes that can be
161 used is dependant on the underlying chipset. A window must be configured before
162 it can be used.
163
164
165 Slave window configuration
166 --------------------------
167
168 Once a slave window has been assigned the following functions can be used to
169 configure it and retrieve the current settings:
170
171         int vme_slave_set (struct vme_resource *res, int enabled,
172                 unsigned long long base, unsigned long long size,
173                 dma_addr_t mem, vme_address_t aspace, vme_cycle_t cycle);
174
175         int vme_slave_get (struct vme_resource *res, int *enabled,
176                 unsigned long long *base, unsigned long long *size,
177                 dma_addr_t *mem, vme_address_t *aspace, vme_cycle_t *cycle);
178
179 The address spaces, transfer widths and cycle types are the same as described
180 under resource management, however some of the options are mutually exclusive.
181 For example, only one address space may be specified.
182
183 These functions return 0 on success or an error code should the call fail.
184
185
186 Slave window buffer allocation
187 ------------------------------
188
189 Functions are provided to allow the user to allocate and free a contiguous
190 buffers which will be accessible by the VME bridge. These functions do not have
191 to be used, other methods can be used to allocate a buffer, though care must be
192 taken to ensure that they are contiguous and accessible by the VME bridge:
193
194         void * vme_alloc_consistent(struct vme_resource *res, size_t size,
195                 dma_addr_t *mem);
196
197         void vme_free_consistent(struct vme_resource *res, size_t size,
198                 void *virt,     dma_addr_t mem);
199
200
201 Slave window access
202 -------------------
203
204 Slave windows map local memory onto the VME bus, the standard methods for
205 accessing memory should be used.
206
207
208 DMA channels
209 ============
210
211 The VME DMA transfer provides the ability to run link-list DMA transfers. The
212 API introduces the concept of DMA lists. Each DMA list is a link-list which can
213 be passed to a DMA controller. Multiple lists can be created, extended,
214 executed, reused and destroyed.
215
216
217 List Management
218 ---------------
219
220 The following functions are provided to create and destroy DMA lists. Execution
221 of a list will not automatically destroy the list, thus enabling a list to be
222 reused for repetitive tasks:
223
224         struct vme_dma_list *vme_new_dma_list(struct vme_resource *res);
225
226         int vme_dma_list_free(struct vme_dma_list *list);
227
228
229 List Population
230 ---------------
231
232 An item can be added to a list using the following function ( the source and
233 destination attributes need to be created before calling this function, this is
234 covered under "Transfer Attributes"):
235
236         int vme_dma_list_add(struct vme_dma_list *list,
237                 struct vme_dma_attr *src, struct vme_dma_attr *dest,
238                 size_t count);
239
240
241 Transfer Attributes
242 -------------------
243
244 The attributes for the source and destination are handled separately from adding
245 an item to a list. This is due to the diverse attributes required for each type
246 of source and destination. There are functions to create attributes for PCI, VME
247 and pattern sources and destinations (where appropriate):
248
249 Pattern source:
250
251         struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern,
252                 vme_pattern_t type);
253
254 PCI source or destination:
255
256         struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem);
257
258 VME source or destination:
259
260         struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base,
261                 vme_address_t aspace, vme_cycle_t cycle, vme_width_t width);
262
263 The following function should be used to free an attribute:
264
265         void vme_dma_free_attribute(struct vme_dma_attr *attr);
266
267
268 List Execution
269 --------------
270
271 The following function queues a list for execution. The function will return
272 once the list has been executed:
273
274         int vme_dma_list_exec(struct vme_dma_list *list);
275
276
277 Interrupts
278 ==========
279
280 The VME API provides functions to attach and detach callbacks to specific VME
281 level and status ID combinations and for the generation of VME interrupts with
282 specific VME level and status IDs.
283
284
285 Attaching Interrupt Handlers
286 ----------------------------
287
288 The following functions can be used to attach and free a specific VME level and
289 status ID combination. Any given combination can only be assigned a single
290 callback function. A void pointer parameter is provided, the value of which is
291 passed to the callback function, the use of this pointer is user undefined:
292
293         int vme_request_irq(struct device *dev, int level, int statid,
294                 void (*callback)(int, int, void *), void *priv);
295
296         void vme_free_irq(struct device *dev, int level, int statid);
297
298 The callback parameters are as follows. Care must be taken in writing a callback
299 function, callback functions run in interrupt context:
300
301         void callback(int level, int statid, void *priv);
302
303
304 Interrupt Generation
305 --------------------
306
307 The following function can be used to generate a VME interrupt at a given VME
308 level and VME status ID:
309
310         int vme_generate_irq(struct device *dev, int level, int statid);
311
312
313 Location monitors
314 =================
315
316 The VME API provides the following functionality to configure the location
317 monitor.
318
319
320 Location Monitor Management
321 ---------------------------
322
323 The following functions are provided to request the use of a block of location
324 monitors and to free them after they are no longer required:
325
326         struct vme_resource * vme_lm_request(struct device *dev);
327
328         void vme_lm_free(struct vme_resource * res);
329
330 Each block may provide a number of location monitors, monitoring adjacent
331 locations. The following function can be used to determine how many locations
332 are provided:
333
334         int vme_lm_count(struct vme_resource * res);
335
336
337 Location Monitor Configuration
338 ------------------------------
339
340 Once a bank of location monitors has been allocated, the following functions
341 are provided to configure the location and mode of the location monitor:
342
343         int vme_lm_set(struct vme_resource *res, unsigned long long base,
344                 vme_address_t aspace, vme_cycle_t cycle);
345
346         int vme_lm_get(struct vme_resource *res, unsigned long long *base,
347                 vme_address_t *aspace, vme_cycle_t *cycle);
348
349
350 Location Monitor Use
351 --------------------
352
353 The following functions allow a callback to be attached and detached from each
354 location monitor location. Each location monitor can monitor a number of
355 adjacent locations:
356
357         int vme_lm_attach(struct vme_resource *res, int num,
358                 void (*callback)(int));
359
360         int vme_lm_detach(struct vme_resource *res, int num);
361
362 The callback function is declared as follows.
363
364         void callback(int num);
365
366
367 Slot Detection
368 ==============
369
370 This function returns the slot ID of the provided bridge.
371
372         int vme_slot_get(struct device *dev);