lib/librte_pci/rte_pci.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2015 Intel Corporation.
   3  * Copyright 2013-2014 6WIND S.A.
   4  */
   5
   6 #ifndef _RTE_PCI_H_
   7 #define _RTE_PCI_H_
   8
   9 /**
  10  * @file
  11  *
  12  * RTE PCI Library
  13  */
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 #include <stdio.h>
  20 #include <stdlib.h>
  21 #include <limits.h>
  22 #include <errno.h>
  23 #include <sys/queue.h>
  24 #include <stdint.h>
  25 #include <inttypes.h>
  26
  27 #include <rte_debug.h>
  28 #include <rte_interrupts.h>
  29
  30 /** Formatting string for PCI device identifier: Ex: 0000:00:01.0 */
  31 #define PCI_PRI_FMT "%.4" PRIx16 ":%.2" PRIx8 ":%.2" PRIx8 ".%" PRIx8
  32 #define PCI_PRI_STR_SIZE sizeof("XXXXXXXX:XX:XX.X")
  33
  34 /** Short formatting string, without domain, for PCI device: Ex: 00:01.0 */
  35 #define PCI_SHORT_PRI_FMT "%.2" PRIx8 ":%.2" PRIx8 ".%" PRIx8
  36
  37 /** Nb. of values in PCI device identifier format string. */
  38 #define PCI_FMT_NVAL 4
  39
  40 /** Nb. of values in PCI resource format. */
  41 #define PCI_RESOURCE_FMT_NVAL 3
  42
  43 /** Maximum number of PCI resources. */
  44 #define PCI_MAX_RESOURCE 6
  45
  46 /**
  47  * A structure describing an ID for a PCI driver. Each driver provides a
  48  * table of these IDs for each device that it supports.
  49  */
  50 struct rte_pci_id {
  51         uint32_t class_id;            /**< Class ID or RTE_CLASS_ANY_ID. */
  52         uint16_t vendor_id;           /**< Vendor ID or PCI_ANY_ID. */
  53         uint16_t device_id;           /**< Device ID or PCI_ANY_ID. */
  54         uint16_t subsystem_vendor_id; /**< Subsystem vendor ID or PCI_ANY_ID. */
  55         uint16_t subsystem_device_id; /**< Subsystem device ID or PCI_ANY_ID. */
  56 };
  57
  58 /**
  59  * A structure describing the location of a PCI device.
  60  */
  61 struct rte_pci_addr {
  62         uint32_t domain;                /**< Device domain */
  63         uint8_t bus;                    /**< Device bus */
  64         uint8_t devid;                  /**< Device ID */
  65         uint8_t function;               /**< Device function. */
  66 };
  67
  68 /** Any PCI device identifier (vendor, device, ...) */
  69 #define PCI_ANY_ID (0xffff)
  70 #define RTE_CLASS_ANY_ID (0xffffff)
  71
  72 /**
  73  * A structure describing a PCI mapping.
  74  */
  75 struct pci_map {
  76         void *addr;
  77         char *path;
  78         uint64_t offset;
  79         uint64_t size;
  80         uint64_t phaddr;
  81 };
  82
  83 struct pci_msix_table {
  84         int bar_index;
  85         uint32_t offset;
  86         uint32_t size;
  87 };
  88
  89 /**
  90  * A structure describing a mapped PCI resource.
  91  * For multi-process we need to reproduce all PCI mappings in secondary
  92  * processes, so save them in a tailq.
  93  */
  94 struct mapped_pci_resource {
  95         TAILQ_ENTRY(mapped_pci_resource) next;
  96
  97         struct rte_pci_addr pci_addr;
  98         char path[PATH_MAX];
  99         int nb_maps;
 100         struct pci_map maps[PCI_MAX_RESOURCE];
 101         struct pci_msix_table msix_table;
 102 };
 103
 104
 105 /** mapped pci device list */
 106 TAILQ_HEAD(mapped_pci_res_list, mapped_pci_resource);
 107
 108 /**
 109  * @deprecated
 110  * Utility function to produce a PCI Bus-Device-Function value
 111  * given a string representation. Assumes that the BDF is provided without
 112  * a domain prefix (i.e. domain returned is always 0)
 113  *
 114  * @param input
 115  *      The input string to be parsed. Should have the format XX:XX.X
 116  * @param dev_addr
 117  *      The PCI Bus-Device-Function address to be returned.
 118  *      Domain will always be returned as 0
 119  * @return
 120  *  0 on success, negative on error.
 121  */
 122 int eal_parse_pci_BDF(const char *input, struct rte_pci_addr *dev_addr);
 123
 124 /**
 125  * @deprecated
 126  * Utility function to produce a PCI Bus-Device-Function value
 127  * given a string representation. Assumes that the BDF is provided including
 128  * a domain prefix.
 129  *
 130  * @param input
 131  *      The input string to be parsed. Should have the format XXXX:XX:XX.X
 132  * @param dev_addr
 133  *      The PCI Bus-Device-Function address to be returned
 134  * @return
 135  *  0 on success, negative on error.
 136  */
 137 int eal_parse_pci_DomBDF(const char *input, struct rte_pci_addr *dev_addr);
 138
 139 /**
 140  * Utility function to write a pci device name, this device name can later be
 141  * used to retrieve the corresponding rte_pci_addr using eal_parse_pci_*
 142  * BDF helpers.
 143  *
 144  * @param addr
 145  *      The PCI Bus-Device-Function address
 146  * @param output
 147  *      The output buffer string
 148  * @param size
 149  *      The output buffer size
 150  */
 151 void rte_pci_device_name(const struct rte_pci_addr *addr,
 152                      char *output, size_t size);
 153
 154 /**
 155  * @deprecated
 156  * Utility function to compare two PCI device addresses.
 157  *
 158  * @param addr
 159  *      The PCI Bus-Device-Function address to compare
 160  * @param addr2
 161  *      The PCI Bus-Device-Function address to compare
 162  * @return
 163  *      0 on equal PCI address.
 164  *      Positive on addr is greater than addr2.
 165  *      Negative on addr is less than addr2, or error.
 166  */
 167 int rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
 168                              const struct rte_pci_addr *addr2);
 169
 170 /**
 171  * Utility function to compare two PCI device addresses.
 172  *
 173  * @param addr
 174  *      The PCI Bus-Device-Function address to compare
 175  * @param addr2
 176  *      The PCI Bus-Device-Function address to compare
 177  * @return
 178  *      0 on equal PCI address.
 179  *      Positive on addr is greater than addr2.
 180  *      Negative on addr is less than addr2, or error.
 181  */
 182 int rte_pci_addr_cmp(const struct rte_pci_addr *addr,
 183                      const struct rte_pci_addr *addr2);
 184
 185
 186 /**
 187  * Utility function to parse a string into a PCI location.
 188  *
 189  * @param str
 190  *      The string to parse
 191  * @param addr
 192  *      The reference to the structure where the location
 193  *      is stored.
 194  * @return
 195  *      0 on success
 196  *      <0 otherwise
 197  */
 198 int rte_pci_addr_parse(const char *str, struct rte_pci_addr *addr);
 199
 200 /**
 201  * Map a particular resource from a file.
 202  *
 203  * @param requested_addr
 204  *      The starting address for the new mapping range.
 205  * @param fd
 206  *      The file descriptor.
 207  * @param offset
 208  *      The offset for the mapping range.
 209  * @param size
 210  *      The size for the mapping range.
 211  * @param additional_flags
 212  *      The additional flags for the mapping range.
 213  * @return
 214  *   - On success, the function returns a pointer to the mapped area.
 215  *   - On error, the value MAP_FAILED is returned.
 216  */
 217 void *pci_map_resource(void *requested_addr, int fd, off_t offset,
 218                 size_t size, int additional_flags);
 219
 220 /**
 221  * Unmap a particular resource.
 222  *
 223  * @param requested_addr
 224  *      The address for the unmapping range.
 225  * @param size
 226  *      The size for the unmapping range.
 227  */
 228 void pci_unmap_resource(void *requested_addr, size_t size);
 229
 230 #ifdef __cplusplus
 231 }
 232 #endif
 233
 234 #endif /* _RTE_PCI_H_ */