]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | /*- |
2 | * BSD LICENSE | |
3 | * | |
9f95a23c | 4 | * Copyright 2016 NXP |
11fdf7f2 TL |
5 | * |
6 | * Redistribution and use in source and binary forms, with or without | |
7 | * modification, are permitted provided that the following conditions | |
8 | * are met: | |
9 | * | |
10 | * * Redistributions of source code must retain the above copyright | |
11 | * notice, this list of conditions and the following disclaimer. | |
12 | * * Redistributions in binary form must reproduce the above copyright | |
13 | * notice, this list of conditions and the following disclaimer in | |
14 | * the documentation and/or other materials provided with the | |
15 | * distribution. | |
16 | * * Neither the name of NXP nor the names of its | |
17 | * contributors may be used to endorse or promote products derived | |
18 | * from this software without specific prior written permission. | |
19 | * | |
20 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
21 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
22 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
23 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
24 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
25 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
26 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
27 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
28 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
29 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
30 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
31 | */ | |
32 | ||
33 | #ifndef _RTE_BUS_H_ | |
34 | #define _RTE_BUS_H_ | |
35 | ||
36 | /** | |
37 | * @file | |
38 | * | |
39 | * DPDK device bus interface | |
40 | * | |
41 | * This file exposes API and interfaces for bus abstraction | |
42 | * over the devices and drivers in EAL. | |
43 | */ | |
44 | ||
45 | #ifdef __cplusplus | |
46 | extern "C" { | |
47 | #endif | |
48 | ||
49 | #include <stdio.h> | |
50 | #include <sys/queue.h> | |
51 | ||
52 | #include <rte_log.h> | |
53 | #include <rte_dev.h> | |
54 | ||
55 | /** Double linked list of buses */ | |
56 | TAILQ_HEAD(rte_bus_list, rte_bus); | |
57 | ||
9f95a23c TL |
58 | |
59 | /** | |
60 | * IOVA mapping mode. | |
61 | * | |
62 | * IOVA mapping mode is iommu programming mode of a device. | |
63 | * That device (for example: IOMMU backed DMA device) based | |
64 | * on rte_iova_mode will generate physical or virtual address. | |
65 | * | |
66 | */ | |
67 | enum rte_iova_mode { | |
68 | RTE_IOVA_DC = 0, /* Don't care mode */ | |
69 | RTE_IOVA_PA = (1 << 0), /* DMA using physical address */ | |
70 | RTE_IOVA_VA = (1 << 1) /* DMA using virtual address */ | |
71 | }; | |
72 | ||
11fdf7f2 TL |
73 | /** |
74 | * Bus specific scan for devices attached on the bus. | |
9f95a23c | 75 | * For each bus object, the scan would be responsible for finding devices and |
11fdf7f2 TL |
76 | * adding them to its private device list. |
77 | * | |
78 | * A bus should mandatorily implement this method. | |
79 | * | |
80 | * @return | |
81 | * 0 for successful scan | |
82 | * <0 for unsuccessful scan with error value | |
83 | */ | |
84 | typedef int (*rte_bus_scan_t)(void); | |
85 | ||
86 | /** | |
87 | * Implementation specific probe function which is responsible for linking | |
88 | * devices on that bus with applicable drivers. | |
89 | * | |
90 | * This is called while iterating over each registered bus. | |
91 | * | |
92 | * @return | |
93 | * 0 for successful probe | |
94 | * !0 for any error while probing | |
95 | */ | |
96 | typedef int (*rte_bus_probe_t)(void); | |
97 | ||
9f95a23c TL |
98 | /** |
99 | * Device iterator to find a device on a bus. | |
100 | * | |
101 | * This function returns an rte_device if one of those held by the bus | |
102 | * matches the data passed as parameter. | |
103 | * | |
104 | * If the comparison function returns zero this function should stop iterating | |
105 | * over any more devices. To continue a search the device of a previous search | |
106 | * can be passed via the start parameter. | |
107 | * | |
108 | * @param cmp | |
109 | * Comparison function. | |
110 | * | |
111 | * @param data | |
112 | * Data to compare each device against. | |
113 | * | |
114 | * @param start | |
115 | * starting point for the iteration | |
116 | * | |
117 | * @return | |
118 | * The first device matching the data, NULL if none exists. | |
119 | */ | |
120 | typedef struct rte_device * | |
121 | (*rte_bus_find_device_t)(const struct rte_device *start, rte_dev_cmp_t cmp, | |
122 | const void *data); | |
123 | ||
124 | /** | |
125 | * Implementation specific probe function which is responsible for linking | |
126 | * devices on that bus with applicable drivers. | |
127 | * | |
128 | * @param dev | |
129 | * Device pointer that was returned by a previous call to find_device. | |
130 | * | |
131 | * @return | |
132 | * 0 on success. | |
133 | * !0 on error. | |
134 | */ | |
135 | typedef int (*rte_bus_plug_t)(struct rte_device *dev); | |
136 | ||
137 | /** | |
138 | * Implementation specific remove function which is responsible for unlinking | |
139 | * devices on that bus from assigned driver. | |
140 | * | |
141 | * @param dev | |
142 | * Device pointer that was returned by a previous call to find_device. | |
143 | * | |
144 | * @return | |
145 | * 0 on success. | |
146 | * !0 on error. | |
147 | */ | |
148 | typedef int (*rte_bus_unplug_t)(struct rte_device *dev); | |
149 | ||
150 | /** | |
151 | * Bus specific parsing function. | |
152 | * Validates the syntax used in the textual representation of a device, | |
153 | * If the syntax is valid and ``addr`` is not NULL, writes the bus-specific | |
154 | * device representation to ``addr``. | |
155 | * | |
156 | * @param[in] name | |
157 | * device textual description | |
158 | * | |
159 | * @param[out] addr | |
160 | * device information location address, into which parsed info | |
161 | * should be written. If NULL, nothing should be written, which | |
162 | * is not an error. | |
163 | * | |
164 | * @return | |
165 | * 0 if parsing was successful. | |
166 | * !0 for any error. | |
167 | */ | |
168 | typedef int (*rte_bus_parse_t)(const char *name, void *addr); | |
169 | ||
170 | /** | |
171 | * Device level DMA map function. | |
172 | * After a successful call, the memory segment will be mapped to the | |
173 | * given device. | |
174 | * | |
175 | * @param dev | |
176 | * Device pointer. | |
177 | * @param addr | |
178 | * Virtual address to map. | |
179 | * @param iova | |
180 | * IOVA address to map. | |
181 | * @param len | |
182 | * Length of the memory segment being mapped. | |
183 | * | |
184 | * @return | |
185 | * 0 if mapping was successful. | |
186 | * Negative value and rte_errno is set otherwise. | |
187 | */ | |
188 | typedef int (*rte_dev_dma_map_t)(struct rte_device *dev, void *addr, | |
189 | uint64_t iova, size_t len); | |
190 | ||
191 | /** | |
192 | * Device level DMA unmap function. | |
193 | * After a successful call, the memory segment will no longer be | |
194 | * accessible by the given device. | |
195 | * | |
196 | * @param dev | |
197 | * Device pointer. | |
198 | * @param addr | |
199 | * Virtual address to unmap. | |
200 | * @param iova | |
201 | * IOVA address to unmap. | |
202 | * @param len | |
203 | * Length of the memory segment being mapped. | |
204 | * | |
205 | * @return | |
206 | * 0 if un-mapping was successful. | |
207 | * Negative value and rte_errno is set otherwise. | |
208 | */ | |
209 | typedef int (*rte_dev_dma_unmap_t)(struct rte_device *dev, void *addr, | |
210 | uint64_t iova, size_t len); | |
211 | ||
212 | /** | |
213 | * Implement a specific hot-unplug handler, which is responsible for | |
214 | * handle the failure when device be hot-unplugged. When the event of | |
215 | * hot-unplug be detected, it could call this function to handle | |
216 | * the hot-unplug failure and avoid app crash. | |
217 | * @param dev | |
218 | * Pointer of the device structure. | |
219 | * | |
220 | * @return | |
221 | * 0 on success. | |
222 | * !0 on error. | |
223 | */ | |
224 | typedef int (*rte_bus_hot_unplug_handler_t)(struct rte_device *dev); | |
225 | ||
226 | /** | |
227 | * Implement a specific sigbus handler, which is responsible for handling | |
228 | * the sigbus error which is either original memory error, or specific memory | |
229 | * error that caused of device be hot-unplugged. When sigbus error be captured, | |
230 | * it could call this function to handle sigbus error. | |
231 | * @param failure_addr | |
232 | * Pointer of the fault address of the sigbus error. | |
233 | * | |
234 | * @return | |
235 | * 0 for success handle the sigbus for hot-unplug. | |
236 | * 1 for not process it, because it is a generic sigbus error. | |
237 | * -1 for failed to handle the sigbus for hot-unplug. | |
238 | */ | |
239 | typedef int (*rte_bus_sigbus_handler_t)(const void *failure_addr); | |
240 | ||
241 | /** | |
242 | * Bus scan policies | |
243 | */ | |
244 | enum rte_bus_scan_mode { | |
245 | RTE_BUS_SCAN_UNDEFINED, | |
246 | RTE_BUS_SCAN_WHITELIST, | |
247 | RTE_BUS_SCAN_BLACKLIST, | |
248 | }; | |
249 | ||
250 | /** | |
251 | * A structure used to configure bus operations. | |
252 | */ | |
253 | struct rte_bus_conf { | |
254 | enum rte_bus_scan_mode scan_mode; /**< Scan policy. */ | |
255 | }; | |
256 | ||
257 | ||
258 | /** | |
259 | * Get common iommu class of the all the devices on the bus. The bus may | |
260 | * check that those devices are attached to iommu driver. | |
261 | * If no devices are attached to the bus. The bus may return with don't care | |
262 | * (_DC) value. | |
263 | * Otherwise, The bus will return appropriate _pa or _va iova mode. | |
264 | * | |
265 | * @return | |
266 | * enum rte_iova_mode value. | |
267 | */ | |
268 | typedef enum rte_iova_mode (*rte_bus_get_iommu_class_t)(void); | |
269 | ||
270 | ||
11fdf7f2 TL |
271 | /** |
272 | * A structure describing a generic bus. | |
273 | */ | |
274 | struct rte_bus { | |
275 | TAILQ_ENTRY(rte_bus) next; /**< Next bus object in linked list */ | |
276 | const char *name; /**< Name of the bus */ | |
277 | rte_bus_scan_t scan; /**< Scan for devices attached to bus */ | |
278 | rte_bus_probe_t probe; /**< Probe devices on bus */ | |
9f95a23c TL |
279 | rte_bus_find_device_t find_device; /**< Find a device on the bus */ |
280 | rte_bus_plug_t plug; /**< Probe single device for drivers */ | |
281 | rte_bus_unplug_t unplug; /**< Remove single device from driver */ | |
282 | rte_bus_parse_t parse; /**< Parse a device name */ | |
283 | rte_dev_dma_map_t dma_map; /**< DMA map for device in the bus */ | |
284 | rte_dev_dma_unmap_t dma_unmap; /**< DMA unmap for device in the bus */ | |
285 | struct rte_bus_conf conf; /**< Bus configuration */ | |
286 | rte_bus_get_iommu_class_t get_iommu_class; /**< Get iommu class */ | |
287 | rte_dev_iterate_t dev_iterate; /**< Device iterator. */ | |
288 | rte_bus_hot_unplug_handler_t hot_unplug_handler; | |
289 | /**< handle hot-unplug failure on the bus */ | |
290 | rte_bus_sigbus_handler_t sigbus_handler; | |
291 | /**< handle sigbus error on the bus */ | |
292 | ||
11fdf7f2 TL |
293 | }; |
294 | ||
295 | /** | |
296 | * Register a Bus handler. | |
297 | * | |
298 | * @param bus | |
299 | * A pointer to a rte_bus structure describing the bus | |
300 | * to be registered. | |
301 | */ | |
302 | void rte_bus_register(struct rte_bus *bus); | |
303 | ||
304 | /** | |
305 | * Unregister a Bus handler. | |
306 | * | |
307 | * @param bus | |
308 | * A pointer to a rte_bus structure describing the bus | |
309 | * to be unregistered. | |
310 | */ | |
311 | void rte_bus_unregister(struct rte_bus *bus); | |
312 | ||
313 | /** | |
314 | * Scan all the buses. | |
315 | * | |
316 | * @return | |
317 | * 0 in case of success in scanning all buses | |
318 | * !0 in case of failure to scan | |
319 | */ | |
320 | int rte_bus_scan(void); | |
321 | ||
322 | /** | |
323 | * For each device on the buses, perform a driver 'match' and call the | |
324 | * driver-specific probe for device initialization. | |
325 | * | |
326 | * @return | |
327 | * 0 for successful match/probe | |
328 | * !0 otherwise | |
329 | */ | |
330 | int rte_bus_probe(void); | |
331 | ||
332 | /** | |
333 | * Dump information of all the buses registered with EAL. | |
334 | * | |
335 | * @param f | |
336 | * A valid and open output stream handle | |
9f95a23c TL |
337 | */ |
338 | void rte_bus_dump(FILE *f); | |
339 | ||
340 | /** | |
341 | * Bus comparison function. | |
342 | * | |
343 | * @param bus | |
344 | * Bus under test. | |
345 | * | |
346 | * @param data | |
347 | * Data to compare against. | |
11fdf7f2 TL |
348 | * |
349 | * @return | |
9f95a23c TL |
350 | * 0 if the bus matches the data. |
351 | * !0 if the bus does not match. | |
352 | * <0 if ordering is possible and the bus is lower than the data. | |
353 | * >0 if ordering is possible and the bus is greater than the data. | |
11fdf7f2 | 354 | */ |
9f95a23c TL |
355 | typedef int (*rte_bus_cmp_t)(const struct rte_bus *bus, const void *data); |
356 | ||
357 | /** | |
358 | * Bus iterator to find a particular bus. | |
359 | * | |
360 | * This function compares each registered bus to find one that matches | |
361 | * the data passed as parameter. | |
362 | * | |
363 | * If the comparison function returns zero this function will stop iterating | |
364 | * over any more buses. To continue a search the bus of a previous search can | |
365 | * be passed via the start parameter. | |
366 | * | |
367 | * @param start | |
368 | * Starting point for the iteration. | |
369 | * | |
370 | * @param cmp | |
371 | * Comparison function. | |
372 | * | |
373 | * @param data | |
374 | * Data to pass to comparison function. | |
375 | * | |
376 | * @return | |
377 | * A pointer to a rte_bus structure or NULL in case no bus matches | |
378 | */ | |
379 | struct rte_bus *rte_bus_find(const struct rte_bus *start, rte_bus_cmp_t cmp, | |
380 | const void *data); | |
381 | ||
382 | /** | |
383 | * Find the registered bus for a particular device. | |
384 | */ | |
385 | struct rte_bus *rte_bus_find_by_device(const struct rte_device *dev); | |
386 | ||
387 | /** | |
388 | * Find the registered bus for a given name. | |
389 | */ | |
390 | struct rte_bus *rte_bus_find_by_name(const char *busname); | |
391 | ||
392 | ||
393 | /** | |
394 | * Get the common iommu class of devices bound on to buses available in the | |
395 | * system. The default mode is PA. | |
396 | * | |
397 | * @return | |
398 | * enum rte_iova_mode value. | |
399 | */ | |
400 | enum rte_iova_mode rte_bus_get_iommu_class(void); | |
11fdf7f2 TL |
401 | |
402 | /** | |
403 | * Helper for Bus registration. | |
404 | * The constructor has higher priority than PMD constructors. | |
405 | */ | |
406 | #define RTE_REGISTER_BUS(nm, bus) \ | |
9f95a23c | 407 | RTE_INIT_PRIO(businitfn_ ##nm, BUS) \ |
11fdf7f2 TL |
408 | {\ |
409 | (bus).name = RTE_STR(nm);\ | |
410 | rte_bus_register(&bus); \ | |
411 | } | |
412 | ||
413 | #ifdef __cplusplus | |
414 | } | |
415 | #endif | |
416 | ||
417 | #endif /* _RTE_BUS_H */ |