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 <limits.h>
  21 #include <sys/queue.h>
  22 #include <inttypes.h>
  23
  24 /** Formatting string for PCI device identifier: Ex: 0000:00:01.0 */
  25 #define PCI_PRI_FMT "%.4" PRIx16 ":%.2" PRIx8 ":%.2" PRIx8 ".%" PRIx8
  26 #define PCI_PRI_STR_SIZE sizeof("XXXXXXXX:XX:XX.X")
  27
  28 /** Short formatting string, without domain, for PCI device: Ex: 00:01.0 */
  29 #define PCI_SHORT_PRI_FMT "%.2" PRIx8 ":%.2" PRIx8 ".%" PRIx8
  30
  31 /** Nb. of values in PCI device identifier format string. */
  32 #define PCI_FMT_NVAL 4
  33
  34 /** Nb. of values in PCI resource format. */
  35 #define PCI_RESOURCE_FMT_NVAL 3
  36
  37 /** Maximum number of PCI resources. */
  38 #define PCI_MAX_RESOURCE 6
  39
  40 /**
  41  * A structure describing an ID for a PCI driver. Each driver provides a
  42  * table of these IDs for each device that it supports.
  43  */
  44 struct rte_pci_id {
  45         uint32_t class_id;            /**< Class ID or RTE_CLASS_ANY_ID. */
  46         uint16_t vendor_id;           /**< Vendor ID or PCI_ANY_ID. */
  47         uint16_t device_id;           /**< Device ID or PCI_ANY_ID. */
  48         uint16_t subsystem_vendor_id; /**< Subsystem vendor ID or PCI_ANY_ID. */
  49         uint16_t subsystem_device_id; /**< Subsystem device ID or PCI_ANY_ID. */
  50 };
  51
  52 /**
  53  * A structure describing the location of a PCI device.
  54  */
  55 struct rte_pci_addr {
  56         uint32_t domain;                /**< Device domain */
  57         uint8_t bus;                    /**< Device bus */
  58         uint8_t devid;                  /**< Device ID */
  59         uint8_t function;               /**< Device function. */
  60 };
  61
  62 /** Any PCI device identifier (vendor, device, ...) */
  63 #define PCI_ANY_ID (0xffff)
  64 #define RTE_CLASS_ANY_ID (0xffffff)
  65
  66 /**
  67  * A structure describing a PCI mapping.
  68  */
  69 struct pci_map {
  70         void *addr;
  71         char *path;
  72         uint64_t offset;
  73         uint64_t size;
  74         uint64_t phaddr;
  75 };
  76
  77 struct pci_msix_table {
  78         int bar_index;
  79         uint32_t offset;
  80         uint32_t size;
  81 };
  82
  83 /**
  84  * A structure describing a mapped PCI resource.
  85  * For multi-process we need to reproduce all PCI mappings in secondary
  86  * processes, so save them in a tailq.
  87  */
  88 struct mapped_pci_resource {
  89         TAILQ_ENTRY(mapped_pci_resource) next;
  90
  91         struct rte_pci_addr pci_addr;
  92         char path[PATH_MAX];
  93         int nb_maps;
  94         struct pci_map maps[PCI_MAX_RESOURCE];
  95         struct pci_msix_table msix_table;
  96 };
  97
  98
  99 /** mapped pci device list */
 100 TAILQ_HEAD(mapped_pci_res_list, mapped_pci_resource);
 101
 102 /**
 103  * Utility function to write a pci device name, this device name can later be
 104  * used to retrieve the corresponding rte_pci_addr using eal_parse_pci_*
 105  * BDF helpers.
 106  *
 107  * @param addr
 108  *      The PCI Bus-Device-Function address
 109  * @param output
 110  *      The output buffer string
 111  * @param size
 112  *      The output buffer size
 113  */
 114 void rte_pci_device_name(const struct rte_pci_addr *addr,
 115                      char *output, size_t size);
 116
 117 /**
 118  * Utility function to compare two PCI device addresses.
 119  *
 120  * @param addr
 121  *      The PCI Bus-Device-Function address to compare
 122  * @param addr2
 123  *      The PCI Bus-Device-Function address to compare
 124  * @return
 125  *      0 on equal PCI address.
 126  *      Positive on addr is greater than addr2.
 127  *      Negative on addr is less than addr2, or error.
 128  */
 129 int rte_pci_addr_cmp(const struct rte_pci_addr *addr,
 130                      const struct rte_pci_addr *addr2);
 131
 132
 133 /**
 134  * Utility function to parse a string into a PCI location.
 135  *
 136  * @param str
 137  *      The string to parse
 138  * @param addr
 139  *      The reference to the structure where the location
 140  *      is stored.
 141  * @return
 142  *      0 on success
 143  *      <0 otherwise
 144  */
 145 int rte_pci_addr_parse(const char *str, struct rte_pci_addr *addr);
 146
 147 /**
 148  * Map a particular resource from a file.
 149  *
 150  * @param requested_addr
 151  *      The starting address for the new mapping range.
 152  * @param fd
 153  *      The file descriptor.
 154  * @param offset
 155  *      The offset for the mapping range.
 156  * @param size
 157  *      The size for the mapping range.
 158  * @param additional_flags
 159  *      The additional flags for the mapping range.
 160  * @return
 161  *   - On success, the function returns a pointer to the mapped area.
 162  *   - On error, the value MAP_FAILED is returned.
 163  */
 164 void *pci_map_resource(void *requested_addr, int fd, off_t offset,
 165                 size_t size, int additional_flags);
 166
 167 /**
 168  * Unmap a particular resource.
 169  *
 170  * @param requested_addr
 171  *      The address for the unmapping range.
 172  * @param size
 173  *      The size for the unmapping range.
 174  */
 175 void pci_unmap_resource(void *requested_addr, size_t size);
 176
 177 #ifdef __cplusplus
 178 }
 179 #endif
 180
 181 #endif /* _RTE_PCI_H_ */