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:
11 int vme_register_driver (struct vme_driver *driver);
13 If driver registration is successful this function returns zero, if an error
14 occurred a negative error code will be returned.
16 A pointer to a structure of type ???vme_driver??? must be provided to the
17 registration function. The structure is as follows:
20 struct list_head node;
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;
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
34 The arguments of the probe routine are as follows:
36 probe(struct device *dev, int bus, int slot);
38 The ???.bind_table??? is a pointer to an array of type ???vme_device_id???:
40 struct vme_device_id {
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
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.
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:
56 void vme_unregister_driver (struct vme_driver *driver);
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.
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
74 struct vme_resource * vme_master_request(struct device *dev,
75 vme_address_t aspace, vme_cycle_t cycle, vme_width_t width);
77 struct vme_resource * vme_slave_request(struct device *dev,
78 vme_address_t aspace, vme_cycle_t cycle);
80 TODO: DMA Resource Allocation incomplete. No attribute based selection.
82 struct vme_resource *vme_request_dma(struct device *dev);
84 For slave windows these attributes are split into those of type ???vme_address_t???
85 and ???vme_cycle_t???. Master windows add a further set of attributes ???vme_cycle_t???.
86 These attributes are defined as bitmasks and as such any combination of the
87 attributes can be requested for a single window, the core will assign a window
88 that meets the requirements, returning a pointer of type vme_resource that
89 should be used to identify the allocated resource when it is used. If an
90 unallocated window fitting the requirements can not be found a NULL pointer will
93 Functions are also provided to free window allocations once they are no longer
94 required. These functions should be passed the pointer to the resource provided
95 during resource allocation:
97 void vme_master_free(struct vme_resource *res);
99 void vme_slave_free(struct vme_resource *res);
101 void vme_dma_free(struct vme_resource *res);
107 Master windows provide access from the local processor[s] out onto the VME bus.
108 The number of windows available and the available access modes is dependant on
109 the underlying chipset. A window must be configured before it can be used.
112 Master window configuration
113 ---------------------------
115 Once a master window has been assigned the following functions can be used to
116 configure it and retrieve the current settings:
118 int vme_master_set (struct vme_resource *res, int enabled,
119 unsigned long long base, unsigned long long size,
120 vme_address_t aspace, vme_cycle_t cycle, vme_width_t width);
122 int vme_master_get (struct vme_resource *res, int *enabled,
123 unsigned long long *base, unsigned long long *size,
124 vme_address_t *aspace, vme_cycle_t *cycle, vme_width_t *width);
126 The address spaces, transfer widths and cycle types are the same as described
127 under resource management, however some of the options are mutually exclusive.
128 For example, only one address space may be specified.
130 These functions return 0 on success or an error code should the call fail.
133 Master window broadcast select mask
134 -----------------------------------
136 TODO: Add functions to set and get Broadcast Select mask:
138 int vme_master_bmsk_set (struct vme_resource *res, int mask);
139 int vme_master_bmsk_get (struct vme_resource *res, int *mask);
145 The following functions can be used to read from and write to configured master
146 windows. These functions return the number of bytes copied:
148 ssize_t vme_master_read(struct vme_resource *res, void *buf,
149 size_t count, loff_t offset);
151 ssize_t vme_master_write(struct vme_resource *res, void *buf,
152 size_t count, loff_t offset);
154 In addition to simple reads and writes, a function is provided to do a
155 read-modify-write transaction. This function returns the original value of the
158 unsigned int vme_master_rmw (struct vme_resource *res,
159 unsigned int mask, unsigned int compare, unsigned int swap,
162 This functions by reading the offset, applying the mask. If the bits selected in
163 the mask match with the values of the corresponding bits in the compare field,
164 the value of swap is written the specified offset.
170 Slave windows provide devices on the VME bus access into mapped portions of the
171 local memory. The number of windows available and the access modes that can be
172 used is dependant on the underlying chipset. A window must be configured before
176 Slave window configuration
177 --------------------------
179 Once a slave window has been assigned the following functions can be used to
180 configure it and retrieve the current settings:
182 int vme_slave_set (struct vme_resource *res, int enabled,
183 unsigned long long base, unsigned long long size,
184 dma_addr_t mem, vme_address_t aspace, vme_cycle_t cycle);
186 int vme_slave_get (struct vme_resource *res, int *enabled,
187 unsigned long long *base, unsigned long long *size,
188 dma_addr_t *mem, vme_address_t *aspace, vme_cycle_t *cycle);
190 The address spaces, transfer widths and cycle types are the same as described
191 under resource management, however some of the options are mutually exclusive.
192 For example, only one address space may be specified.
194 These functions return 0 on success or an error code should the call fail.
197 Slave window buffer allocation
198 ------------------------------
200 Functions are provided to allow the user to allocate and free a contiguous
201 buffers which will be accessible by the VME bridge. These functions do not have
202 to be used, other methods can be used to allocate a buffer, though care must be
203 taken to ensure that they are contiguous and accessible by the VME bridge:
205 void * vme_alloc_consistent(struct vme_resource *res, size_t size,
208 void vme_free_consistent(struct vme_resource *res, size_t size,
209 void *virt, dma_addr_t mem);
215 Slave windows map local memory onto the VME bus, the standard methods for
216 accessing memory should be used.
222 The VME DMA transfer provides the ability to run link-list DMA transfers. The
223 API introduces the concept of DMA lists. Each DMA list is a link-list which can
224 be passed to a DMA controller. Multiple lists can be created, extended,
225 executed, reused and destroyed.
231 The following functions are provided to create and destroy DMA lists. Execution
232 of a list will not automatically destroy the list, thus enabling a list to be
233 reused for repetitive tasks:
235 struct vme_dma_list *vme_new_dma_list(struct vme_resource *res);
237 int vme_dma_list_free(struct vme_dma_list *list);
243 An item can be added to a list using the following function ( the source and
244 destination attributes need to be created before calling this function, this is
245 covered under "Transfer Attributes"):
247 int vme_dma_list_add(struct vme_dma_list *list,
248 struct vme_dma_attr *src, struct vme_dma_attr *dest,
255 The attributes for the source and destination are handled separately from adding
256 an item to a list. This is due to the diverse attributes required for each type
257 of source and destination. There are functions to create attributes for PCI, VME
258 and pattern sources and destinations (where appropriate):
262 struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern,
265 PCI source or destination:
267 struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem);
269 VME source or destination:
271 struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base,
272 vme_address_t aspace, vme_cycle_t cycle, vme_width_t width);
274 The following function should be used to free an attribute:
276 void vme_dma_free_attribute(struct vme_dma_attr *attr);
282 The following function queues a list for execution. The function will return
283 once the list has been executed:
285 int vme_dma_list_exec(struct vme_dma_list *list);
291 The VME API provides functions to attach and detach callbacks to specific VME
292 level and status ID combinations and for the generation of VME interrupts with
293 specific VME level and status IDs.
296 Attaching Interrupt Handlers
297 ----------------------------
299 The following functions can be used to attach and free a specific VME level and
300 status ID combination. Any given combination can only be assigned a single
301 callback function. A void pointer parameter is provided, the value of which is
302 passed to the callback function, the use of this pointer is user undefined:
304 int vme_request_irq(struct device *dev, int level, int statid,
305 void (*callback)(int, int, void *), void *priv);
307 void vme_free_irq(struct device *dev, int level, int statid);
309 The callback parameters are as follows. Care must be taken in writing a callback
310 function, callback functions run in interrupt context:
312 void callback(int level, int statid, void *priv);
318 The following function can be used to generate a VME interrupt at a given VME
319 level and VME status ID:
321 int vme_generate_irq(struct device *dev, int level, int statid);
327 The VME API provides the following functionality to configure the location
331 Location Monitor Management
332 ---------------------------
334 The following functions are provided to request the use of a block of location
335 monitors and to free them after they are no longer required:
337 struct vme_resource * vme_lm_request(struct device *dev);
339 void vme_lm_free(struct vme_resource * res);
341 Each block may provide a number of location monitors, monitoring adjacent
342 locations. The following function can be used to determine how many locations
345 int vme_lm_count(struct vme_resource * res);
348 Location Monitor Configuration
349 ------------------------------
351 Once a bank of location monitors has been allocated, the following functions
352 are provided to configure the location and mode of the location monitor:
354 int vme_lm_set(struct vme_resource *res, unsigned long long base,
355 vme_address_t aspace, vme_cycle_t cycle);
357 int vme_lm_get(struct vme_resource *res, unsigned long long *base,
358 vme_address_t *aspace, vme_cycle_t *cycle);
364 The following functions allow a callback to be attached and detached from each
365 location monitor location. Each location monitor can monitor a number of
368 int vme_lm_attach(struct vme_resource *res, int num,
369 void (*callback)(int));
371 int vme_lm_detach(struct vme_resource *res, int num);
373 The callback function is declared as follows.
375 void callback(int num);
381 TODO: The VME API needs functions to access the CR/CSR buffer.
386 This function returns the slot ID of the provided bridge.
388 int vme_slot_get(struct device *dev);