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  * @deprecated
 170  * Utility function to write a pci device name, this device name can later be
 171  * used to retrieve the corresponding rte_pci_addr using eal_parse_pci_*
 172  * BDF helpers.
 173  *
 174  * @param addr
 175  *      The PCI Bus-Device-Function address
 176  * @param output
 177  *      The output buffer string
 178  * @param size
 179  *      The output buffer size
 180  */
 181 void rte_pci_device_name(const struct rte_pci_addr *addr,
 182                          char *output, size_t size);
 183
 184 /**
 185  * Utility function to write a pci device name, this device name can later be
 186  * used to retrieve the corresponding rte_pci_addr using eal_parse_pci_*
 187  * BDF helpers.
 188  *
 189  * @param addr
 190  *      The PCI Bus-Device-Function address
 191  * @param output
 192  *      The output buffer string
 193  * @param size
 194  *      The output buffer size
 195  */
 196 void pci_device_name(const struct rte_pci_addr *addr,
 197                      char *output, size_t size);
 198
 199 /**
 200  * @deprecated
 201  * Utility function to compare two PCI device addresses.
 202  *
 203  * @param addr
 204  *      The PCI Bus-Device-Function address to compare
 205  * @param addr2
 206  *      The PCI Bus-Device-Function address to compare
 207  * @return
 208  *      0 on equal PCI address.
 209  *      Positive on addr is greater than addr2.
 210  *      Negative on addr is less than addr2, or error.
 211  */
 212 int rte_eal_compare_pci_addr(const struct rte_pci_addr *addr,
 213                              const struct rte_pci_addr *addr2);
 214
 215 /**
 216  * Utility function to compare two PCI device addresses.
 217  *
 218  * @param addr
 219  *      The PCI Bus-Device-Function address to compare
 220  * @param addr2
 221  *      The PCI Bus-Device-Function address to compare
 222  * @return
 223  *      0 on equal PCI address.
 224  *      Positive on addr is greater than addr2.
 225  *      Negative on addr is less than addr2, or error.
 226  */
 227 int pci_addr_cmp(const struct rte_pci_addr *addr,
 228                  const struct rte_pci_addr *addr2);
 229
 230
 231 /**
 232  * Utility function to parse a string into a PCI location.
 233  *
 234  * @param str
 235  *      The string to parse
 236  * @param addr
 237  *      The reference to the structure where the location
 238  *      is stored.
 239  * @return
 240  *      0 on success
 241  *      <0 otherwise
 242  */
 243 int pci_addr_parse(const char *str, struct rte_pci_addr *addr);
 244
 245 /**
 246  * Map a particular resource from a file.
 247  *
 248  * @param requested_addr
 249  *      The starting address for the new mapping range.
 250  * @param fd
 251  *      The file descriptor.
 252  * @param offset
 253  *      The offset for the mapping range.
 254  * @param size
 255  *      The size for the mapping range.
 256  * @param additional_flags
 257  *      The additional flags for the mapping range.
 258  * @return
 259  *   - On success, the function returns a pointer to the mapped area.
 260  *   - On error, the value MAP_FAILED is returned.
 261  */
 262 void *pci_map_resource(void *requested_addr, int fd, off_t offset,
 263                 size_t size, int additional_flags);
 264
 265 /**
 266  * Unmap a particular resource.
 267  *
 268  * @param requested_addr
 269  *      The address for the unmapping range.
 270  * @param size
 271  *      The size for the unmapping range.
 272  */
 273 void pci_unmap_resource(void *requested_addr, size_t size);
 274
 275 #ifdef __cplusplus
 276 }
 277 #endif
 278
 279 #endif /* _RTE_PCI_H_ */