version: 17.11-rc3
[dpdk.git] / lib / librte_pci / rte_pci.h
1 /*-
2  *   BSD LICENSE
3  *
4  *   Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
5  *   Copyright 2013-2014 6WIND S.A.
6  *   All rights reserved.
7  *
8  *   Redistribution and use in source and binary forms, with or without
9  *   modification, are permitted provided that the following conditions
10  *   are met:
11  *
12  *     * Redistributions of source code must retain the above copyright
13  *       notice, this list of conditions and the following disclaimer.
14  *     * Redistributions in binary form must reproduce the above copyright
15  *       notice, this list of conditions and the following disclaimer in
16  *       the documentation and/or other materials provided with the
17  *       distribution.
18  *     * Neither the name of Intel Corporation nor the names of its
19  *       contributors may be used to endorse or promote products derived
20  *       from this software without specific prior written permission.
21  *
22  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  */
34
35 #ifndef _RTE_PCI_H_
36 #define _RTE_PCI_H_
37
38 /**
39  * @file
40  *
41  * RTE PCI Library
42  */
43
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47
48 #include <stdio.h>
49 #include <stdlib.h>
50 #include <limits.h>
51 #include <errno.h>
52 #include <sys/queue.h>
53 #include <stdint.h>
54 #include <inttypes.h>
55
56 #include <rte_debug.h>
57 #include <rte_interrupts.h>
58
59 /** Formatting string for PCI device identifier: Ex: 0000:00:01.0 */
60 #define PCI_PRI_FMT "%.4" PRIx16 ":%.2" PRIx8 ":%.2" PRIx8 ".%" PRIx8
61 #define PCI_PRI_STR_SIZE sizeof("XXXXXXXX:XX:XX.X")
62
63 /** Short formatting string, without domain, for PCI device: Ex: 00:01.0 */
64 #define PCI_SHORT_PRI_FMT "%.2" PRIx8 ":%.2" PRIx8 ".%" PRIx8
65
66 /** Nb. of values in PCI device identifier format string. */
67 #define PCI_FMT_NVAL 4
68
69 /** Nb. of values in PCI resource format. */
70 #define PCI_RESOURCE_FMT_NVAL 3
71
72 /** Maximum number of PCI resources. */
73 #define PCI_MAX_RESOURCE 6
74
75 /**
76  * A structure describing an ID for a PCI driver. Each driver provides a
77  * table of these IDs for each device that it supports.
78  */
79 struct rte_pci_id {
80         uint32_t class_id;            /**< Class ID or RTE_CLASS_ANY_ID. */
81         uint16_t vendor_id;           /**< Vendor ID or PCI_ANY_ID. */
82         uint16_t device_id;           /**< Device ID or PCI_ANY_ID. */
83         uint16_t subsystem_vendor_id; /**< Subsystem vendor ID or PCI_ANY_ID. */
84         uint16_t subsystem_device_id; /**< Subsystem device ID or PCI_ANY_ID. */
85 };
86
87 /**
88  * A structure describing the location of a PCI device.
89  */
90 struct rte_pci_addr {
91         uint32_t domain;                /**< Device domain */
92         uint8_t bus;                    /**< Device bus */
93         uint8_t devid;                  /**< Device ID */
94         uint8_t function;               /**< Device function. */
95 };
96
97 /** Any PCI device identifier (vendor, device, ...) */
98 #define PCI_ANY_ID (0xffff)
99 #define RTE_CLASS_ANY_ID (0xffffff)
100
101 /**
102  * A structure describing a PCI mapping.
103  */
104 struct pci_map {
105         void *addr;
106         char *path;
107         uint64_t offset;
108         uint64_t size;
109         uint64_t phaddr;
110 };
111
112 struct pci_msix_table {
113         int bar_index;
114         uint32_t offset;
115         uint32_t size;
116 };
117
118 /**
119  * A structure describing a mapped PCI resource.
120  * For multi-process we need to reproduce all PCI mappings in secondary
121  * processes, so save them in a tailq.
122  */
123 struct mapped_pci_resource {
124         TAILQ_ENTRY(mapped_pci_resource) next;
125
126         struct rte_pci_addr pci_addr;
127         char path[PATH_MAX];
128         int nb_maps;
129         struct pci_map maps[PCI_MAX_RESOURCE];
130         struct pci_msix_table msix_table;
131 };
132
133
134 /** mapped pci device list */
135 TAILQ_HEAD(mapped_pci_res_list, mapped_pci_resource);
136
137 /**
138  * @deprecated
139  * Utility function to produce a PCI Bus-Device-Function value
140  * given a string representation. Assumes that the BDF is provided without
141  * a domain prefix (i.e. domain returned is always 0)
142  *
143  * @param input
144  *      The input string to be parsed. Should have the format XX:XX.X
145  * @param dev_addr
146  *      The PCI Bus-Device-Function address to be returned.
147  *      Domain will always be returned as 0
148  * @return
149  *  0 on success, negative on error.
150  */
151 int eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr);
152
153 /**
154  * @deprecated
155  * Utility function to produce a PCI Bus-Device-Function value
156  * given a string representation. Assumes that the BDF is provided including
157  * a domain prefix.
158  *
159  * @param input
160  *      The input string to be parsed. Should have the format XXXX:XX:XX.X
161  * @param dev_addr
162  *      The PCI Bus-Device-Function address to be returned
163  * @return
164  *  0 on success, negative on error.
165  */
166 int eal_parse_pci_DomBDF(const char *input, struct rte_pci_addr *dev_addr);
167
168 /**
169  * Utility function to write a pci device name, this device name can later be
170  * used to retrieve the corresponding rte_pci_addr using eal_parse_pci_*
171  * BDF helpers.
172  *
173  * @param addr
174  *      The PCI Bus-Device-Function address
175  * @param output
176  *      The output buffer string
177  * @param size
178  *      The output buffer size
179  */
180 void rte_pci_device_name(const struct rte_pci_addr *addr,
181                      char *output, size_t size);
182
183 /**
184  * @deprecated
185  * Utility function to compare two PCI device addresses.
186  *
187  * @param addr
188  *      The PCI Bus-Device-Function address to compare
189  * @param addr2
190  *      The PCI Bus-Device-Function address to compare
191  * @return
192  *      0 on equal PCI address.
193  *      Positive on addr is greater than addr2.
194  *      Negative on addr is less than addr2, or error.
195  */
196 int rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
197                              const struct rte_pci_addr *addr2);
198
199 /**
200  * Utility function to compare two PCI device addresses.
201  *
202  * @param addr
203  *      The PCI Bus-Device-Function address to compare
204  * @param addr2
205  *      The PCI Bus-Device-Function address to compare
206  * @return
207  *      0 on equal PCI address.
208  *      Positive on addr is greater than addr2.
209  *      Negative on addr is less than addr2, or error.
210  */
211 int rte_pci_addr_cmp(const struct rte_pci_addr *addr,
212                      const struct rte_pci_addr *addr2);
213
214
215 /**
216  * Utility function to parse a string into a PCI location.
217  *
218  * @param str
219  *      The string to parse
220  * @param addr
221  *      The reference to the structure where the location
222  *      is stored.
223  * @return
224  *      0 on success
225  *      <0 otherwise
226  */
227 int rte_pci_addr_parse(const char *str, struct rte_pci_addr *addr);
228
229 /**
230  * Map a particular resource from a file.
231  *
232  * @param requested_addr
233  *      The starting address for the new mapping range.
234  * @param fd
235  *      The file descriptor.
236  * @param offset
237  *      The offset for the mapping range.
238  * @param size
239  *      The size for the mapping range.
240  * @param additional_flags
241  *      The additional flags for the mapping range.
242  * @return
243  *   - On success, the function returns a pointer to the mapped area.
244  *   - On error, the value MAP_FAILED is returned.
245  */
246 void *pci_map_resource(void *requested_addr, int fd, off_t offset,
247                 size_t size, int additional_flags);
248
249 /**
250  * Unmap a particular resource.
251  *
252  * @param requested_addr
253  *      The address for the unmapping range.
254  * @param size
255  *      The size for the unmapping range.
256  */
257 void pci_unmap_resource(void *requested_addr, size_t size);
258
259 #ifdef __cplusplus
260 }
261 #endif
262
263 #endif /* _RTE_PCI_H_ */