lib/librte_eal/common/eal_private.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2014 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
  34 #ifndef _EAL_PRIVATE_H_
  35 #define _EAL_PRIVATE_H_
  36
  37 #include <stdbool.h>
  38 #include <stdint.h>
  39 #include <stdio.h>
  40 #include <rte_pci.h>
  41
  42 /**
  43  * Initialize the memzone subsystem (private to eal).
  44  *
  45  * @return
  46  *   - 0 on success
  47  *   - Negative on error
  48  */
  49 int rte_eal_memzone_init(void);
  50
  51 /**
  52  * Common log initialization function (private to eal).  Determines
  53  * where log data is written when no call to rte_openlog_stream is
  54  * in effect.
  55  *
  56  * @param default_log
  57  *   The default log stream to be used.
  58  * @return
  59  *   - 0 on success
  60  *   - Negative on error
  61  */
  62 void eal_log_set_default(FILE *default_log);
  63
  64 /**
  65  * Fill configuration with number of physical and logical processors
  66  *
  67  * This function is private to EAL.
  68  *
  69  * Parse /proc/cpuinfo to get the number of physical and logical
  70  * processors on the machine.
  71  *
  72  * @return
  73  *   0 on success, negative on error
  74  */
  75 int rte_eal_cpu_init(void);
  76
  77 /**
  78  * Map memory
  79  *
  80  * This function is private to EAL.
  81  *
  82  * Fill configuration structure with these infos, and return 0 on success.
  83  *
  84  * @return
  85  *   0 on success, negative on error
  86  */
  87 int rte_eal_memory_init(void);
  88
  89 /**
  90  * Configure timers
  91  *
  92  * This function is private to EAL.
  93  *
  94  * Mmap memory areas used by HPET (high precision event timer) that will
  95  * provide our time reference, and configure the TSC frequency also for it
  96  * to be used as a reference.
  97  *
  98  * @return
  99  *   0 on success, negative on error
 100  */
 101 int rte_eal_timer_init(void);
 102
 103 /**
 104  * Init the default log stream
 105  *
 106  * This function is private to EAL.
 107  *
 108  * @return
 109  *   0 on success, negative on error
 110  */
 111 int rte_eal_log_init(const char *id, int facility);
 112
 113 struct rte_pci_driver;
 114 struct rte_pci_device;
 115
 116 /**
 117  * Probe the PCI bus
 118  *
 119  * @return
 120  *   - 0 on success.
 121  *   - !0 on error.
 122  */
 123 int
 124 rte_pci_probe(void);
 125
 126 /**
 127  * Scan the content of the PCI bus, and the devices in the devices
 128  * list
 129  *
 130  * @return
 131  *  0 on success, negative on error
 132  */
 133 int rte_pci_scan(void);
 134
 135 /**
 136  * Probe the single PCI device.
 137  *
 138  * Scan the content of the PCI bus, and find the pci device specified by pci
 139  * address, then call the probe() function for registered driver that has a
 140  * matching entry in its id_table for discovered device.
 141  *
 142  * @param addr
 143  *     The PCI Bus-Device-Function address to probe.
 144  * @return
 145  *   - 0 on success.
 146  *   - Negative on error.
 147  */
 148 int rte_pci_probe_one(const struct rte_pci_addr *addr);
 149
 150 /**
 151  * Close the single PCI device.
 152  *
 153  * Scan the content of the PCI bus, and find the pci device specified by pci
 154  * address, then call the remove() function for registered driver that has a
 155  * matching entry in its id_table for discovered device.
 156  *
 157  * @param addr
 158  *     The PCI Bus-Device-Function address to close.
 159  * @return
 160  *   - 0 on success.
 161  *   - Negative on error.
 162  */
 163 int rte_pci_detach(const struct rte_pci_addr *addr);
 164
 165 /**
 166  * Find the name of a PCI device.
 167  */
 168 void pci_name_set(struct rte_pci_device *dev);
 169
 170 /**
 171  * Add a PCI device to the PCI Bus (append to PCI Device list). This function
 172  * also updates the bus references of the PCI Device (and the generic device
 173  * object embedded within.
 174  *
 175  * @param pci_dev
 176  *      PCI device to add
 177  * @return void
 178  */
 179 void rte_pci_add_device(struct rte_pci_device *pci_dev);
 180
 181 /**
 182  * Insert a PCI device in the PCI Bus at a particular location in the device
 183  * list. It also updates the PCI Bus reference of the new devices to be
 184  * inserted.
 185  *
 186  * @param exist_pci_dev
 187  *      Existing PCI device in PCI Bus
 188  * @param new_pci_dev
 189  *      PCI device to be added before exist_pci_dev
 190  * @return void
 191  */
 192 void rte_pci_insert_device(struct rte_pci_device *exist_pci_dev,
 193                 struct rte_pci_device *new_pci_dev);
 194
 195 /**
 196  * Remove a PCI device from the PCI Bus. This sets to NULL the bus references
 197  * in the PCI device object as well as the generic device object.
 198  *
 199  * @param pci_device
 200  *      PCI device to be removed from PCI Bus
 201  * @return void
 202  */
 203 void rte_pci_remove_device(struct rte_pci_device *pci_device);
 204
 205 /**
 206  * Update a pci device object by asking the kernel for the latest information.
 207  *
 208  * This function is private to EAL.
 209  *
 210  * @param addr
 211  *      The PCI Bus-Device-Function address to look for
 212  * @return
 213  *   - 0 on success.
 214  *   - negative on error.
 215  */
 216 int pci_update_device(const struct rte_pci_addr *addr);
 217
 218 /**
 219  * Unbind kernel driver for this device
 220  *
 221  * This function is private to EAL.
 222  *
 223  * @return
 224  *   0 on success, negative on error
 225  */
 226 int pci_unbind_kernel_driver(struct rte_pci_device *dev);
 227
 228 /**
 229  * Map the PCI resource of a PCI device in virtual memory
 230  *
 231  * This function is private to EAL.
 232  *
 233  * @return
 234  *   0 on success, negative on error
 235  */
 236 int pci_uio_map_resource(struct rte_pci_device *dev);
 237
 238 /**
 239  * Unmap the PCI resource of a PCI device
 240  *
 241  * This function is private to EAL.
 242  */
 243 void pci_uio_unmap_resource(struct rte_pci_device *dev);
 244
 245 /**
 246  * Allocate uio resource for PCI device
 247  *
 248  * This function is private to EAL.
 249  *
 250  * @param dev
 251  *   PCI device to allocate uio resource
 252  * @param uio_res
 253  *   Pointer to uio resource.
 254  *   If the function returns 0, the pointer will be filled.
 255  * @return
 256  *   0 on success, negative on error
 257  */
 258 int pci_uio_alloc_resource(struct rte_pci_device *dev,
 259                 struct mapped_pci_resource **uio_res);
 260
 261 /**
 262  * Free uio resource for PCI device
 263  *
 264  * This function is private to EAL.
 265  *
 266  * @param dev
 267  *   PCI device to free uio resource
 268  * @param uio_res
 269  *   Pointer to uio resource.
 270  */
 271 void pci_uio_free_resource(struct rte_pci_device *dev,
 272                 struct mapped_pci_resource *uio_res);
 273
 274 /**
 275  * Map device memory to uio resource
 276  *
 277  * This function is private to EAL.
 278  *
 279  * @param dev
 280  *   PCI device that has memory information.
 281  * @param res_idx
 282  *   Memory resource index of the PCI device.
 283  * @param uio_res
 284  *  uio resource that will keep mapping information.
 285  * @param map_idx
 286  *   Mapping information index of the uio resource.
 287  * @return
 288  *   0 on success, negative on error
 289  */
 290 int pci_uio_map_resource_by_index(struct rte_pci_device *dev, int res_idx,
 291                 struct mapped_pci_resource *uio_res, int map_idx);
 292
 293 /*
 294  * Match the PCI Driver and Device using the ID Table
 295  *
 296  * @param pci_drv
 297  *      PCI driver from which ID table would be extracted
 298  * @param pci_dev
 299  *      PCI device to match against the driver
 300  * @return
 301  *      1 for successful match
 302  *      0 for unsuccessful match
 303  */
 304 int
 305 rte_pci_match(const struct rte_pci_driver *pci_drv,
 306               const struct rte_pci_device *pci_dev);
 307
 308 /**
 309  * Get iommu class of PCI devices on the bus.
 310  * And return their preferred iova mapping mode.
 311  *
 312  * @return
 313  *   - enum rte_iova_mode.
 314  */
 315 enum rte_iova_mode
 316 rte_pci_get_iommu_class(void);
 317
 318 /**
 319  * Init tail queues for non-EAL library structures. This is to allow
 320  * the rings, mempools, etc. lists to be shared among multiple processes
 321  *
 322  * This function is private to EAL
 323  *
 324  * @return
 325  *    0 on success, negative on error
 326  */
 327 int rte_eal_tailqs_init(void);
 328
 329 /**
 330  * Init interrupt handling.
 331  *
 332  * This function is private to EAL.
 333  *
 334  * @return
 335  *  0 on success, negative on error
 336  */
 337 int rte_eal_intr_init(void);
 338
 339 /**
 340  * Init alarm mechanism. This is to allow a callback be called after
 341  * specific time.
 342  *
 343  * This function is private to EAL.
 344  *
 345  * @return
 346  *  0 on success, negative on error
 347  */
 348 int rte_eal_alarm_init(void);
 349
 350 /**
 351  * Function is to check if the kernel module(like, vfio, vfio_iommu_type1,
 352  * etc.) loaded.
 353  *
 354  * @param module_name
 355  *      The module's name which need to be checked
 356  *
 357  * @return
 358  *      -1 means some error happens(NULL pointer or open failure)
 359  *      0  means the module not loaded
 360  *      1  means the module loaded
 361  */
 362 int rte_eal_check_module(const char *module_name);
 363
 364 /**
 365  * Get cpu core_id.
 366  *
 367  * This function is private to the EAL.
 368  */
 369 unsigned eal_cpu_core_id(unsigned lcore_id);
 370
 371 /**
 372  * Check if cpu is present.
 373  *
 374  * This function is private to the EAL.
 375  */
 376 int eal_cpu_detected(unsigned lcore_id);
 377
 378 /**
 379  * Set TSC frequency from precise value or estimation
 380  *
 381  * This function is private to the EAL.
 382  */
 383 void set_tsc_freq(void);
 384
 385 /**
 386  * Get precise TSC frequency from system
 387  *
 388  * This function is private to the EAL.
 389  */
 390 uint64_t get_tsc_freq(void);
 391
 392 /**
 393  * Get TSC frequency if the architecture supports.
 394  *
 395  * This function is private to the EAL.
 396  *
 397  * @return
 398  *   The number of TSC cycles in one second.
 399  *   Returns zero if the architecture support is not available.
 400  */
 401 uint64_t get_tsc_freq_arch(void);
 402
 403 /**
 404  * Prepare physical memory mapping
 405  * i.e. hugepages on Linux and
 406  *      contigmem on BSD.
 407  *
 408  * This function is private to the EAL.
 409  */
 410 int rte_eal_hugepage_init(void);
 411
 412 /**
 413  * Creates memory mapping in secondary process
 414  * i.e. hugepages on Linux and
 415  *      contigmem on BSD.
 416  *
 417  * This function is private to the EAL.
 418  */
 419 int rte_eal_hugepage_attach(void);
 420
 421 /**
 422  * Find a bus capable of identifying a device.
 423  *
 424  * @param str
 425  *   A device identifier (PCI address, virtual PMD name, ...).
 426  *
 427  * @return
 428  *   A valid bus handle if found.
 429  *   NULL if no bus is able to parse this device.
 430  */
 431 struct rte_bus *rte_bus_find_by_device_name(const char *str);
 432
 433 #endif /* _EAL_PRIVATE_H_ */