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