pci: inherit common driver in PCI driver
[dpdk.git] / lib / librte_eal / common / include / rte_pci.h
1 /*-
2  *   BSD LICENSE
3  *
4  *   Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
5  *   All rights reserved.
6  *
7  *   Redistribution and use in source and binary forms, with or without
8  *   modification, are permitted provided that the following conditions
9  *   are met:
10  *
11  *     * Redistributions of source code must retain the above copyright
12  *       notice, this list of conditions and the following disclaimer.
13  *     * Redistributions in binary form must reproduce the above copyright
14  *       notice, this list of conditions and the following disclaimer in
15  *       the documentation and/or other materials provided with the
16  *       distribution.
17  *     * Neither the name of Intel Corporation nor the names of its
18  *       contributors may be used to endorse or promote products derived
19  *       from this software without specific prior written permission.
20  *
21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32  */
33 /*   BSD LICENSE
34  *
35  *   Copyright 2013-2014 6WIND S.A.
36  *
37  *   Redistribution and use in source and binary forms, with or without
38  *   modification, are permitted provided that the following conditions
39  *   are met:
40  *
41  *     * Redistributions of source code must retain the above copyright
42  *       notice, this list of conditions and the following disclaimer.
43  *     * Redistributions in binary form must reproduce the above copyright
44  *       notice, this list of conditions and the following disclaimer in
45  *       the documentation and/or other materials provided with the
46  *       distribution.
47  *     * Neither the name of 6WIND S.A. nor the names of its
48  *       contributors may be used to endorse or promote products derived
49  *       from this software without specific prior written permission.
50  *
51  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
52  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
53  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
54  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
55  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
56  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
57  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
58  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
59  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
60  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
61  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
62  */
63
64 #ifndef _RTE_PCI_H_
65 #define _RTE_PCI_H_
66
67 /**
68  * @file
69  *
70  * RTE PCI Interface
71  */
72
73 #ifdef __cplusplus
74 extern "C" {
75 #endif
76
77 #include <stdio.h>
78 #include <stdlib.h>
79 #include <limits.h>
80 #include <errno.h>
81 #include <sys/queue.h>
82 #include <stdint.h>
83 #include <inttypes.h>
84
85 #include <rte_debug.h>
86 #include <rte_interrupts.h>
87 #include <rte_dev.h>
88
89 TAILQ_HEAD(pci_device_list, rte_pci_device); /**< PCI devices in D-linked Q. */
90 TAILQ_HEAD(pci_driver_list, rte_pci_driver); /**< PCI drivers in D-linked Q. */
91
92 extern struct pci_driver_list pci_driver_list; /**< Global list of PCI drivers. */
93 extern struct pci_device_list pci_device_list; /**< Global list of PCI devices. */
94
95 /** Pathname of PCI devices directory. */
96 const char *pci_get_sysfs_path(void);
97
98 /** Formatting string for PCI device identifier: Ex: 0000:00:01.0 */
99 #define PCI_PRI_FMT "%.4" PRIx16 ":%.2" PRIx8 ":%.2" PRIx8 ".%" PRIx8
100 #define PCI_PRI_STR_SIZE sizeof("XXXX:XX:XX.X")
101
102 /** Short formatting string, without domain, for PCI device: Ex: 00:01.0 */
103 #define PCI_SHORT_PRI_FMT "%.2" PRIx8 ":%.2" PRIx8 ".%" PRIx8
104
105 /** Nb. of values in PCI device identifier format string. */
106 #define PCI_FMT_NVAL 4
107
108 /** Nb. of values in PCI resource format. */
109 #define PCI_RESOURCE_FMT_NVAL 3
110
111 /** Maximum number of PCI resources. */
112 #define PCI_MAX_RESOURCE 6
113
114 /**
115  * A structure describing an ID for a PCI driver. Each driver provides a
116  * table of these IDs for each device that it supports.
117  */
118 struct rte_pci_id {
119         uint32_t class_id;            /**< Class ID (class, subclass, pi) or RTE_CLASS_ANY_ID. */
120         uint16_t vendor_id;           /**< Vendor ID or PCI_ANY_ID. */
121         uint16_t device_id;           /**< Device ID or PCI_ANY_ID. */
122         uint16_t subsystem_vendor_id; /**< Subsystem vendor ID or PCI_ANY_ID. */
123         uint16_t subsystem_device_id; /**< Subsystem device ID or PCI_ANY_ID. */
124 };
125
126 /**
127  * A structure describing the location of a PCI device.
128  */
129 struct rte_pci_addr {
130         uint16_t domain;                /**< Device domain */
131         uint8_t bus;                    /**< Device bus */
132         uint8_t devid;                  /**< Device ID */
133         uint8_t function;               /**< Device function. */
134 };
135
136 struct rte_devargs;
137
138 enum rte_kernel_driver {
139         RTE_KDRV_UNKNOWN = 0,
140         RTE_KDRV_IGB_UIO,
141         RTE_KDRV_VFIO,
142         RTE_KDRV_UIO_GENERIC,
143         RTE_KDRV_NIC_UIO,
144         RTE_KDRV_NONE,
145 };
146
147 /**
148  * A structure describing a PCI device.
149  */
150 struct rte_pci_device {
151         TAILQ_ENTRY(rte_pci_device) next;       /**< Next probed PCI device. */
152         struct rte_pci_addr addr;               /**< PCI location. */
153         struct rte_pci_id id;                   /**< PCI ID. */
154         struct rte_mem_resource mem_resource[PCI_MAX_RESOURCE];
155                                                 /**< PCI Memory Resource */
156         struct rte_intr_handle intr_handle;     /**< Interrupt handle */
157         struct rte_pci_driver *driver;          /**< Associated driver */
158         uint16_t max_vfs;                       /**< sriov enable if not zero */
159         int numa_node;                          /**< NUMA node connection */
160         struct rte_devargs *devargs;            /**< Device user arguments */
161         enum rte_kernel_driver kdrv;            /**< Kernel driver passthrough */
162 };
163
164 /** Any PCI device identifier (vendor, device, ...) */
165 #define PCI_ANY_ID (0xffff)
166 #define RTE_CLASS_ANY_ID (0xffffff)
167
168 #ifdef __cplusplus
169 /** C++ macro used to help building up tables of device IDs */
170 #define RTE_PCI_DEVICE(vend, dev) \
171         RTE_CLASS_ANY_ID,         \
172         (vend),                   \
173         (dev),                    \
174         PCI_ANY_ID,               \
175         PCI_ANY_ID
176 #else
177 /** Macro used to help building up tables of device IDs */
178 #define RTE_PCI_DEVICE(vend, dev)          \
179         .class_id = RTE_CLASS_ANY_ID,      \
180         .vendor_id = (vend),               \
181         .device_id = (dev),                \
182         .subsystem_vendor_id = PCI_ANY_ID, \
183         .subsystem_device_id = PCI_ANY_ID
184 #endif
185
186 struct rte_pci_driver;
187
188 /**
189  * Initialisation function for the driver called during PCI probing.
190  */
191 typedef int (pci_probe_t)(struct rte_pci_driver *, struct rte_pci_device *);
192
193 /**
194  * Uninitialisation function for the driver called during hotplugging.
195  */
196 typedef int (pci_remove_t)(struct rte_pci_device *);
197
198 /**
199  * A structure describing a PCI driver.
200  */
201 struct rte_pci_driver {
202         TAILQ_ENTRY(rte_pci_driver) next;       /**< Next in list. */
203         struct rte_driver driver;               /**< Inherit core driver. */
204         pci_probe_t *probe;                     /**< Device Probe function. */
205         pci_remove_t *remove;                   /**< Device Remove function. */
206         const struct rte_pci_id *id_table;      /**< ID table, NULL terminated. */
207         uint32_t drv_flags;                     /**< Flags contolling handling of device. */
208 };
209
210 /** Device needs PCI BAR mapping (done with either IGB_UIO or VFIO) */
211 #define RTE_PCI_DRV_NEED_MAPPING 0x0001
212 /** Device needs to be unbound even if no module is provided */
213 #define RTE_PCI_DRV_FORCE_UNBIND 0x0004
214 /** Device driver supports link state interrupt */
215 #define RTE_PCI_DRV_INTR_LSC    0x0008
216 /** Device driver supports detaching capability */
217 #define RTE_PCI_DRV_DETACHABLE  0x0010
218
219 /**
220  * A structure describing a PCI mapping.
221  */
222 struct pci_map {
223         void *addr;
224         char *path;
225         uint64_t offset;
226         uint64_t size;
227         uint64_t phaddr;
228 };
229
230 /**
231  * A structure describing a mapped PCI resource.
232  * For multi-process we need to reproduce all PCI mappings in secondary
233  * processes, so save them in a tailq.
234  */
235 struct mapped_pci_resource {
236         TAILQ_ENTRY(mapped_pci_resource) next;
237
238         struct rte_pci_addr pci_addr;
239         char path[PATH_MAX];
240         int nb_maps;
241         struct pci_map maps[PCI_MAX_RESOURCE];
242 };
243
244 /** mapped pci device list */
245 TAILQ_HEAD(mapped_pci_res_list, mapped_pci_resource);
246
247 /**< Internal use only - Macro used by pci addr parsing functions **/
248 #define GET_PCIADDR_FIELD(in, fd, lim, dlm)                   \
249 do {                                                               \
250         unsigned long val;                                      \
251         char *end;                                              \
252         errno = 0;                                              \
253         val = strtoul((in), &end, 16);                          \
254         if (errno != 0 || end[0] != (dlm) || val > (lim))       \
255                 return -EINVAL;                                 \
256         (fd) = (typeof (fd))val;                                \
257         (in) = end + 1;                                         \
258 } while(0)
259
260 /**
261  * Utility function to produce a PCI Bus-Device-Function value
262  * given a string representation. Assumes that the BDF is provided without
263  * a domain prefix (i.e. domain returned is always 0)
264  *
265  * @param input
266  *      The input string to be parsed. Should have the format XX:XX.X
267  * @param dev_addr
268  *      The PCI Bus-Device-Function address to be returned. Domain will always be
269  *      returned as 0
270  * @return
271  *  0 on success, negative on error.
272  */
273 static inline int
274 eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr)
275 {
276         dev_addr->domain = 0;
277         GET_PCIADDR_FIELD(input, dev_addr->bus, UINT8_MAX, ':');
278         GET_PCIADDR_FIELD(input, dev_addr->devid, UINT8_MAX, '.');
279         GET_PCIADDR_FIELD(input, dev_addr->function, UINT8_MAX, 0);
280         return 0;
281 }
282
283 /**
284  * Utility function to produce a PCI Bus-Device-Function value
285  * given a string representation. Assumes that the BDF is provided including
286  * a domain prefix.
287  *
288  * @param input
289  *      The input string to be parsed. Should have the format XXXX:XX:XX.X
290  * @param dev_addr
291  *      The PCI Bus-Device-Function address to be returned
292  * @return
293  *  0 on success, negative on error.
294  */
295 static inline int
296 eal_parse_pci_DomBDF(const char *input, struct rte_pci_addr *dev_addr)
297 {
298         GET_PCIADDR_FIELD(input, dev_addr->domain, UINT16_MAX, ':');
299         GET_PCIADDR_FIELD(input, dev_addr->bus, UINT8_MAX, ':');
300         GET_PCIADDR_FIELD(input, dev_addr->devid, UINT8_MAX, '.');
301         GET_PCIADDR_FIELD(input, dev_addr->function, UINT8_MAX, 0);
302         return 0;
303 }
304 #undef GET_PCIADDR_FIELD
305
306 /**
307  * Utility function to write a pci device name, this device name can later be
308  * used to retrieve the corresponding rte_pci_addr using eal_parse_pci_*
309  * BDF helpers.
310  *
311  * @param addr
312  *      The PCI Bus-Device-Function address
313  * @param output
314  *      The output buffer string
315  * @param size
316  *      The output buffer size
317  */
318 static inline void
319 rte_eal_pci_device_name(const struct rte_pci_addr *addr,
320                     char *output, size_t size)
321 {
322         RTE_VERIFY(size >= PCI_PRI_STR_SIZE);
323         RTE_VERIFY(snprintf(output, size, PCI_PRI_FMT,
324                             addr->domain, addr->bus,
325                             addr->devid, addr->function) >= 0);
326 }
327
328 /* Compare two PCI device addresses. */
329 /**
330  * Utility function to compare two PCI device addresses.
331  *
332  * @param addr
333  *      The PCI Bus-Device-Function address to compare
334  * @param addr2
335  *      The PCI Bus-Device-Function address to compare
336  * @return
337  *      0 on equal PCI address.
338  *      Positive on addr is greater than addr2.
339  *      Negative on addr is less than addr2, or error.
340  */
341 static inline int
342 rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
343                          const struct rte_pci_addr *addr2)
344 {
345         uint64_t dev_addr, dev_addr2;
346
347         if ((addr == NULL) || (addr2 == NULL))
348                 return -1;
349
350         dev_addr = (addr->domain << 24) | (addr->bus << 16) |
351                                 (addr->devid << 8) | addr->function;
352         dev_addr2 = (addr2->domain << 24) | (addr2->bus << 16) |
353                                 (addr2->devid << 8) | addr2->function;
354
355         if (dev_addr > dev_addr2)
356                 return 1;
357         else if (dev_addr < dev_addr2)
358                 return -1;
359         else
360                 return 0;
361 }
362
363 /**
364  * Scan the content of the PCI bus, and the devices in the devices
365  * list
366  *
367  * @return
368  *  0 on success, negative on error
369  */
370 int rte_eal_pci_scan(void);
371
372 /**
373  * Probe the PCI bus for registered drivers.
374  *
375  * Scan the content of the PCI bus, and call the probe() function for
376  * all registered drivers that have a matching entry in its id_table
377  * for discovered devices.
378  *
379  * @return
380  *   - 0 on success.
381  *   - Negative on error.
382  */
383 int rte_eal_pci_probe(void);
384
385 /**
386  * Map the PCI device resources in user space virtual memory address
387  *
388  * Note that driver should not call this function when flag
389  * RTE_PCI_DRV_NEED_MAPPING is set, as EAL will do that for
390  * you when it's on.
391  *
392  * @param dev
393  *   A pointer to a rte_pci_device structure describing the device
394  *   to use
395  *
396  * @return
397  *   0 on success, negative on error and positive if no driver
398  *   is found for the device.
399  */
400 int rte_eal_pci_map_device(struct rte_pci_device *dev);
401
402 /**
403  * Unmap this device
404  *
405  * @param dev
406  *   A pointer to a rte_pci_device structure describing the device
407  *   to use
408  */
409 void rte_eal_pci_unmap_device(struct rte_pci_device *dev);
410
411 /**
412  * @internal
413  * Map a particular resource from a file.
414  *
415  * @param requested_addr
416  *      The starting address for the new mapping range.
417  * @param fd
418  *      The file descriptor.
419  * @param offset
420  *      The offset for the mapping range.
421  * @param size
422  *      The size for the mapping range.
423  * @param additional_flags
424  *      The additional flags for the mapping range.
425  * @return
426  *   - On success, the function returns a pointer to the mapped area.
427  *   - On error, the value MAP_FAILED is returned.
428  */
429 void *pci_map_resource(void *requested_addr, int fd, off_t offset,
430                 size_t size, int additional_flags);
431
432 /**
433  * @internal
434  * Unmap a particular resource.
435  *
436  * @param requested_addr
437  *      The address for the unmapping range.
438  * @param size
439  *      The size for the unmapping range.
440  */
441 void pci_unmap_resource(void *requested_addr, size_t size);
442
443 /**
444  * Probe the single PCI device.
445  *
446  * Scan the content of the PCI bus, and find the pci device specified by pci
447  * address, then call the probe() function for registered driver that has a
448  * matching entry in its id_table for discovered device.
449  *
450  * @param addr
451  *      The PCI Bus-Device-Function address to probe.
452  * @return
453  *   - 0 on success.
454  *   - Negative on error.
455  */
456 int rte_eal_pci_probe_one(const struct rte_pci_addr *addr);
457
458 /**
459  * Close the single PCI device.
460  *
461  * Scan the content of the PCI bus, and find the pci device specified by pci
462  * address, then call the remove() function for registered driver that has a
463  * matching entry in its id_table for discovered device.
464  *
465  * @param addr
466  *      The PCI Bus-Device-Function address to close.
467  * @return
468  *   - 0 on success.
469  *   - Negative on error.
470  */
471 int rte_eal_pci_detach(const struct rte_pci_addr *addr);
472
473 /**
474  * Dump the content of the PCI bus.
475  *
476  * @param f
477  *   A pointer to a file for output
478  */
479 void rte_eal_pci_dump(FILE *f);
480
481 /**
482  * Register a PCI driver.
483  *
484  * @param driver
485  *   A pointer to a rte_pci_driver structure describing the driver
486  *   to be registered.
487  */
488 void rte_eal_pci_register(struct rte_pci_driver *driver);
489
490 /** Helper for PCI device registration from driver (eth, crypto) instance */
491 #define DRIVER_REGISTER_PCI(nm, pci_drv) \
492 RTE_INIT(pciinitfn_ ##nm); \
493 static void pciinitfn_ ##nm(void) \
494 {\
495         (pci_drv).driver.name = RTE_STR(nm);\
496         rte_eal_pci_register(&pci_drv); \
497 } \
498 DRIVER_EXPORT_NAME(nm, __COUNTER__)
499
500 /**
501  * Unregister a PCI driver.
502  *
503  * @param driver
504  *   A pointer to a rte_pci_driver structure describing the driver
505  *   to be unregistered.
506  */
507 void rte_eal_pci_unregister(struct rte_pci_driver *driver);
508
509 /**
510  * Read PCI config space.
511  *
512  * @param device
513  *   A pointer to a rte_pci_device structure describing the device
514  *   to use
515  * @param buf
516  *   A data buffer where the bytes should be read into
517  * @param len
518  *   The length of the data buffer.
519  * @param offset
520  *   The offset into PCI config space
521  */
522 int rte_eal_pci_read_config(const struct rte_pci_device *device,
523                             void *buf, size_t len, off_t offset);
524
525 /**
526  * Write PCI config space.
527  *
528  * @param device
529  *   A pointer to a rte_pci_device structure describing the device
530  *   to use
531  * @param buf
532  *   A data buffer containing the bytes should be written
533  * @param len
534  *   The length of the data buffer.
535  * @param offset
536  *   The offset into PCI config space
537  */
538 int rte_eal_pci_write_config(const struct rte_pci_device *device,
539                              const void *buf, size_t len, off_t offset);
540
541 /**
542  * A structure used to access io resources for a pci device.
543  * rte_pci_ioport is arch, os, driver specific, and should not be used outside
544  * of pci ioport api.
545  */
546 struct rte_pci_ioport {
547         struct rte_pci_device *dev;
548         uint64_t base;
549         uint64_t len; /* only filled for memory mapped ports */
550 };
551
552 /**
553  * Initialize a rte_pci_ioport object for a pci device io resource.
554  *
555  * This object is then used to gain access to those io resources (see below).
556  *
557  * @param dev
558  *   A pointer to a rte_pci_device structure describing the device
559  *   to use.
560  * @param bar
561  *   Index of the io pci resource we want to access.
562  * @param p
563  *   The rte_pci_ioport object to be initialized.
564  * @return
565  *  0 on success, negative on error.
566  */
567 int rte_eal_pci_ioport_map(struct rte_pci_device *dev, int bar,
568                            struct rte_pci_ioport *p);
569
570 /**
571  * Release any resources used in a rte_pci_ioport object.
572  *
573  * @param p
574  *   The rte_pci_ioport object to be uninitialized.
575  * @return
576  *  0 on success, negative on error.
577  */
578 int rte_eal_pci_ioport_unmap(struct rte_pci_ioport *p);
579
580 /**
581  * Read from a io pci resource.
582  *
583  * @param p
584  *   The rte_pci_ioport object from which we want to read.
585  * @param data
586  *   A data buffer where the bytes should be read into
587  * @param len
588  *   The length of the data buffer.
589  * @param offset
590  *   The offset into the pci io resource.
591  */
592 void rte_eal_pci_ioport_read(struct rte_pci_ioport *p,
593                              void *data, size_t len, off_t offset);
594
595 /**
596  * Write to a io pci resource.
597  *
598  * @param p
599  *   The rte_pci_ioport object to which we want to write.
600  * @param data
601  *   A data buffer where the bytes should be read into
602  * @param len
603  *   The length of the data buffer.
604  * @param offset
605  *   The offset into the pci io resource.
606  */
607 void rte_eal_pci_ioport_write(struct rte_pci_ioport *p,
608                               const void *data, size_t len, off_t offset);
609
610 #ifdef __cplusplus
611 }
612 #endif
613
614 #endif /* _RTE_PCI_H_ */