lib/librte_eal/common/eal_private.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2018 Intel Corporation
   3  */
   4
   5 #ifndef _EAL_PRIVATE_H_
   6 #define _EAL_PRIVATE_H_
   7
   8 #include <stdbool.h>
   9 #include <stdint.h>
  10 #include <stdio.h>
  11
  12 #include <rte_dev.h>
  13 #include <rte_lcore.h>
  14 #include <rte_memory.h>
  15
  16 #include "eal_internal_cfg.h"
  17
  18 /**
  19  * Structure storing internal configuration (per-lcore)
  20  */
  21 struct lcore_config {
  22         pthread_t thread_id;       /**< pthread identifier */
  23         int pipe_master2slave[2];  /**< communication pipe with master */
  24         int pipe_slave2master[2];  /**< communication pipe with master */
  25
  26         lcore_function_t * volatile f; /**< function to call */
  27         void * volatile arg;       /**< argument of function */
  28         volatile int ret;          /**< return value of function */
  29
  30         volatile enum rte_lcore_state_t state; /**< lcore state */
  31         unsigned int socket_id;    /**< physical socket id for this lcore */
  32         unsigned int core_id;      /**< core number on socket for this lcore */
  33         int core_index;            /**< relative index, starting from 0 */
  34         uint8_t core_role;         /**< role of core eg: OFF, RTE, SERVICE */
  35
  36         rte_cpuset_t cpuset;       /**< cpu set which the lcore affinity to */
  37 };
  38
  39 extern struct lcore_config lcore_config[RTE_MAX_LCORE];
  40
  41 /**
  42  * The global RTE configuration structure.
  43  */
  44 struct rte_config {
  45         uint32_t master_lcore;       /**< Id of the master lcore */
  46         uint32_t lcore_count;        /**< Number of available logical cores. */
  47         uint32_t numa_node_count;    /**< Number of detected NUMA nodes. */
  48         uint32_t numa_nodes[RTE_MAX_NUMA_NODES]; /**< List of detected NUMA nodes. */
  49         uint32_t service_lcore_count;/**< Number of available service cores. */
  50         enum rte_lcore_role_t lcore_role[RTE_MAX_LCORE]; /**< State of cores. */
  51
  52         /** Primary or secondary configuration */
  53         enum rte_proc_type_t process_type;
  54
  55         /** PA or VA mapping mode */
  56         enum rte_iova_mode iova_mode;
  57
  58         /**
  59          * Pointer to memory configuration, which may be shared across multiple
  60          * DPDK instances
  61          */
  62         struct rte_mem_config *mem_config;
  63 } __rte_packed;
  64
  65 /**
  66  * Get the global configuration structure.
  67  *
  68  * @return
  69  *   A pointer to the global configuration structure.
  70  */
  71 struct rte_config *rte_eal_get_configuration(void);
  72
  73 /**
  74  * Initialize the memzone subsystem (private to eal).
  75  *
  76  * @return
  77  *   - 0 on success
  78  *   - Negative on error
  79  */
  80 int rte_eal_memzone_init(void);
  81
  82 /**
  83  * Common log initialization function (private to eal).  Determines
  84  * where log data is written when no call to rte_openlog_stream is
  85  * in effect.
  86  *
  87  * @param default_log
  88  *   The default log stream to be used.
  89  * @return
  90  *   - 0 on success
  91  *   - Negative on error
  92  */
  93 void eal_log_set_default(FILE *default_log);
  94
  95 /**
  96  * Fill configuration with number of physical and logical processors
  97  *
  98  * This function is private to EAL.
  99  *
 100  * Parse /proc/cpuinfo to get the number of physical and logical
 101  * processors on the machine.
 102  *
 103  * @return
 104  *   0 on success, negative on error
 105  */
 106 int rte_eal_cpu_init(void);
 107
 108 /**
 109  * Create memseg lists
 110  *
 111  * This function is private to EAL.
 112  *
 113  * Preallocate virtual memory.
 114  *
 115  * @return
 116  *   0 on success, negative on error
 117  */
 118 int rte_eal_memseg_init(void);
 119
 120 /**
 121  * Map memory
 122  *
 123  * This function is private to EAL.
 124  *
 125  * Fill configuration structure with these infos, and return 0 on success.
 126  *
 127  * @return
 128  *   0 on success, negative on error
 129  */
 130 int rte_eal_memory_init(void);
 131
 132 /**
 133  * Configure timers
 134  *
 135  * This function is private to EAL.
 136  *
 137  * Mmap memory areas used by HPET (high precision event timer) that will
 138  * provide our time reference, and configure the TSC frequency also for it
 139  * to be used as a reference.
 140  *
 141  * @return
 142  *   0 on success, negative on error
 143  */
 144 int rte_eal_timer_init(void);
 145
 146 /**
 147  * Init the default log stream
 148  *
 149  * This function is private to EAL.
 150  *
 151  * @return
 152  *   0 on success, negative on error
 153  */
 154 int rte_eal_log_init(const char *id, int facility);
 155
 156 /**
 157  * Save the log regexp for later
 158  */
 159 int rte_log_save_regexp(const char *type, int priority);
 160 int rte_log_save_pattern(const char *pattern, int priority);
 161
 162 /**
 163  * Init tail queues for non-EAL library structures. This is to allow
 164  * the rings, mempools, etc. lists to be shared among multiple processes
 165  *
 166  * This function is private to EAL
 167  *
 168  * @return
 169  *    0 on success, negative on error
 170  */
 171 int rte_eal_tailqs_init(void);
 172
 173 /**
 174  * Init interrupt handling.
 175  *
 176  * This function is private to EAL.
 177  *
 178  * @return
 179  *  0 on success, negative on error
 180  */
 181 int rte_eal_intr_init(void);
 182
 183 /**
 184  * Init alarm mechanism. This is to allow a callback be called after
 185  * specific time.
 186  *
 187  * This function is private to EAL.
 188  *
 189  * @return
 190  *  0 on success, negative on error
 191  */
 192 int rte_eal_alarm_init(void);
 193
 194 /**
 195  * Function is to check if the kernel module(like, vfio, vfio_iommu_type1,
 196  * etc.) loaded.
 197  *
 198  * @param module_name
 199  *      The module's name which need to be checked
 200  *
 201  * @return
 202  *      -1 means some error happens(NULL pointer or open failure)
 203  *      0  means the module not loaded
 204  *      1  means the module loaded
 205  */
 206 int rte_eal_check_module(const char *module_name);
 207
 208 /**
 209  * Memory reservation flags.
 210  */
 211 enum eal_mem_reserve_flags {
 212         /**
 213          * Reserve hugepages. May be unsupported by some platforms.
 214          */
 215         EAL_RESERVE_HUGEPAGES = 1 << 0,
 216         /**
 217          * Force reserving memory at the requested address.
 218          * This can be a destructive action depending on the implementation.
 219          *
 220          * @see RTE_MAP_FORCE_ADDRESS for description of possible consequences
 221          *      (although implementations are not required to use it).
 222          */
 223         EAL_RESERVE_FORCE_ADDRESS = 1 << 1
 224 };
 225
 226 /**
 227  * Get virtual area of specified size from the OS.
 228  *
 229  * This function is private to the EAL.
 230  *
 231  * @param requested_addr
 232  *   Address where to request address space.
 233  * @param size
 234  *   Size of requested area.
 235  * @param page_sz
 236  *   Page size on which to align requested virtual area.
 237  * @param flags
 238  *   EAL_VIRTUAL_AREA_* flags.
 239  * @param reserve_flags
 240  *   Extra flags passed directly to eal_mem_reserve().
 241  *
 242  * @return
 243  *   Virtual area address if successful.
 244  *   NULL if unsuccessful.
 245  */
 246
 247 #define EAL_VIRTUAL_AREA_ADDR_IS_HINT (1 << 0)
 248 /**< don't fail if cannot get exact requested address. */
 249 #define EAL_VIRTUAL_AREA_ALLOW_SHRINK (1 << 1)
 250 /**< try getting smaller sized (decrement by page size) virtual areas if cannot
 251  * get area of requested size.
 252  */
 253 #define EAL_VIRTUAL_AREA_UNMAP (1 << 2)
 254 /**< immediately unmap reserved virtual area. */
 255 void *
 256 eal_get_virtual_area(void *requested_addr, size_t *size,
 257                 size_t page_sz, int flags, int reserve_flags);
 258
 259 /**
 260  * Initialize a memory segment list and create its backing storage.
 261  *
 262  * @param msl
 263  *  Memory segment list to be filled.
 264  * @param name
 265  *  Name for the backing storage.
 266  * @param page_sz
 267  *  Size of segment pages in the MSL.
 268  * @param n_segs
 269  *  Number of segments.
 270  * @param socket_id
 271  *  Socket ID. Must not be SOCKET_ID_ANY.
 272  * @param heap
 273  *  Mark MSL as pointing to a heap.
 274  * @return
 275  *  0 on success, (-1) on failure and rte_errno is set.
 276  */
 277 int
 278 eal_memseg_list_init_named(struct rte_memseg_list *msl, const char *name,
 279         uint64_t page_sz, int n_segs, int socket_id, bool heap);
 280
 281 /**
 282  * Initialize memory segment list and create its backing storage
 283  * with a name corresponding to MSL parameters.
 284  *
 285  * @param type_msl_idx
 286  *  Index of the MSL among other MSLs of the same socket and page size.
 287  *
 288  * @see eal_memseg_list_init_named for remaining parameters description.
 289  */
 290 int
 291 eal_memseg_list_init(struct rte_memseg_list *msl, uint64_t page_sz,
 292         int n_segs, int socket_id, int type_msl_idx, bool heap);
 293
 294 /**
 295  * Reserve VA space for a memory segment list
 296  * previously initialized with eal_memseg_list_init().
 297  *
 298  * @param msl
 299  *  Initialized memory segment list with page size defined.
 300  * @param reserve_flags
 301  *  Extra memory reservation flags. Can be 0 if unnecessary.
 302  * @return
 303  *  0 on success, (-1) on failure and rte_errno is set.
 304  */
 305 int
 306 eal_memseg_list_alloc(struct rte_memseg_list *msl, int reserve_flags);
 307
 308 /**
 309  * Populate MSL, each segment is one page long.
 310  *
 311  * @param msl
 312  *  Initialized memory segment list with page size defined.
 313  * @param addr
 314  *  Starting address of list segments.
 315  * @param n_segs
 316  *  Number of segments to populate.
 317  */
 318 void
 319 eal_memseg_list_populate(struct rte_memseg_list *msl, void *addr, int n_segs);
 320
 321 /**
 322  * Distribute available memory between MSLs.
 323  *
 324  * @return
 325  *  0 on success, (-1) on failure.
 326  */
 327 int
 328 eal_dynmem_memseg_lists_init(void);
 329
 330 /**
 331  * Preallocate hugepages for dynamic allocation.
 332  *
 333  * @return
 334  *  0 on success, (-1) on failure.
 335  */
 336 int
 337 eal_dynmem_hugepage_init(void);
 338
 339 /**
 340  * Given the list of hugepage sizes and the number of pages thereof,
 341  * calculate the best number of pages of each size to fulfill the request
 342  * for RAM on each NUMA node.
 343  *
 344  * @param memory
 345  *  Amounts of memory requested for each NUMA node of RTE_MAX_NUMA_NODES.
 346  * @param hp_info
 347  *  Information about hugepages of different size.
 348  * @param hp_used
 349  *  Receives information about used hugepages of each size.
 350  * @param num_hp_info
 351  *  Number of elements in hp_info and hp_used.
 352  * @return
 353  *  0 on success, (-1) on failure.
 354  */
 355 int
 356 eal_dynmem_calc_num_pages_per_socket(
 357                 uint64_t *memory, struct hugepage_info *hp_info,
 358                 struct hugepage_info *hp_used, unsigned int num_hp_info);
 359
 360 /**
 361  * Get cpu core_id.
 362  *
 363  * This function is private to the EAL.
 364  */
 365 unsigned eal_cpu_core_id(unsigned lcore_id);
 366
 367 /**
 368  * Check if cpu is present.
 369  *
 370  * This function is private to the EAL.
 371  */
 372 int eal_cpu_detected(unsigned lcore_id);
 373
 374 /**
 375  * Set TSC frequency from precise value or estimation
 376  *
 377  * This function is private to the EAL.
 378  */
 379 void set_tsc_freq(void);
 380
 381 /**
 382  * Get precise TSC frequency from system
 383  *
 384  * This function is private to the EAL.
 385  */
 386 uint64_t get_tsc_freq(void);
 387
 388 /**
 389  * Get TSC frequency if the architecture supports.
 390  *
 391  * This function is private to the EAL.
 392  *
 393  * @return
 394  *   The number of TSC cycles in one second.
 395  *   Returns zero if the architecture support is not available.
 396  */
 397 uint64_t get_tsc_freq_arch(void);
 398
 399 /**
 400  * Prepare physical memory mapping
 401  * i.e. hugepages on Linux and
 402  *      contigmem on BSD.
 403  *
 404  * This function is private to the EAL.
 405  */
 406 int rte_eal_hugepage_init(void);
 407
 408 /**
 409  * Creates memory mapping in secondary process
 410  * i.e. hugepages on Linux and
 411  *      contigmem on BSD.
 412  *
 413  * This function is private to the EAL.
 414  */
 415 int rte_eal_hugepage_attach(void);
 416
 417 /**
 418  * Find a bus capable of identifying a device.
 419  *
 420  * @param str
 421  *   A device identifier (PCI address, virtual PMD name, ...).
 422  *
 423  * @return
 424  *   A valid bus handle if found.
 425  *   NULL if no bus is able to parse this device.
 426  */
 427 struct rte_bus *rte_bus_find_by_device_name(const char *str);
 428
 429 /**
 430  * Create the unix channel for primary/secondary communication.
 431  *
 432  * @return
 433  *   0 on success;
 434  *   (<0) on failure.
 435  */
 436 int rte_mp_channel_init(void);
 437
 438 /**
 439  * Primary/secondary communication cleanup.
 440  */
 441 void rte_mp_channel_cleanup(void);
 442
 443 /**
 444  * @internal
 445  * Parse a device string and store its information in an
 446  * rte_devargs structure.
 447  *
 448  * A device description is split by layers of abstraction of the device:
 449  * bus, class and driver. Each layer will offer a set of properties that
 450  * can be applied either to configure or recognize a device.
 451  *
 452  * This function will parse those properties and prepare the rte_devargs
 453  * to be given to each layers for processing.
 454  *
 455  * Note: if the "data" field of the devargs points to devstr,
 456  * then no dynamic allocation is performed and the rte_devargs
 457  * can be safely discarded.
 458  *
 459  * Otherwise ``data`` will hold a workable copy of devstr, that will be
 460  * used by layers descriptors within rte_devargs. In this case,
 461  * any rte_devargs should be cleaned-up before being freed.
 462  *
 463  * @param da
 464  *   rte_devargs structure to fill.
 465  *
 466  * @param devstr
 467  *   Device string.
 468  *
 469  * @return
 470  *   0 on success.
 471  *   Negative errno values on error (rte_errno is set).
 472  */
 473 int
 474 rte_devargs_layers_parse(struct rte_devargs *devargs,
 475                          const char *devstr);
 476
 477 /*
 478  * probe a device at local process.
 479  *
 480  * @param devargs
 481  *   Device arguments including bus, class and driver properties.
 482  * @param new_dev
 483  *   new device be probed as output.
 484  * @return
 485  *   0 on success, negative on error.
 486  */
 487 int local_dev_probe(const char *devargs, struct rte_device **new_dev);
 488
 489 /**
 490  * Hotplug remove a given device from a specific bus at local process.
 491  *
 492  * @param dev
 493  *   Data structure of the device to remove.
 494  * @return
 495  *   0 on success, negative on error.
 496  */
 497 int local_dev_remove(struct rte_device *dev);
 498
 499 /**
 500  * Iterate over all buses to find the corresponding bus to handle the sigbus
 501  * error.
 502  * @param failure_addr
 503  *      Pointer of the fault address of the sigbus error.
 504  *
 505  * @return
 506  *       0 success to handle the sigbus.
 507  *      -1 failed to handle the sigbus
 508  *       1 no bus can handler the sigbus
 509  */
 510 int rte_bus_sigbus_handler(const void *failure_addr);
 511
 512 /**
 513  * @internal
 514  * Register the sigbus handler.
 515  *
 516  * @return
 517  *   - On success, zero.
 518  *   - On failure, a negative value.
 519  */
 520 int
 521 dev_sigbus_handler_register(void);
 522
 523 /**
 524  * @internal
 525  * Unregister the sigbus handler.
 526  *
 527  * @return
 528  *   - On success, zero.
 529  *   - On failure, a negative value.
 530  */
 531 int
 532 dev_sigbus_handler_unregister(void);
 533
 534 /**
 535  * Get OS-specific EAL mapping base address.
 536  */
 537 uint64_t
 538 eal_get_baseaddr(void);
 539
 540 void *
 541 eal_malloc_no_trace(const char *type, size_t size, unsigned int align);
 542
 543 void eal_free_no_trace(void *addr);
 544
 545 /** Options for eal_file_open(). */
 546 enum eal_open_flags {
 547         /** Open file for reading. */
 548         EAL_OPEN_READONLY = 0x00,
 549         /** Open file for reading and writing. */
 550         EAL_OPEN_READWRITE = 0x02,
 551         /**
 552          * Create the file if it doesn't exist.
 553          * New files are only accessible to the owner (0600 equivalent).
 554          */
 555         EAL_OPEN_CREATE = 0x04
 556 };
 557
 558 /**
 559  * Open or create a file.
 560  *
 561  * @param path
 562  *  Path to the file.
 563  * @param flags
 564  *  A combination of eal_open_flags controlling operation and FD behavior.
 565  * @return
 566  *  Open file descriptor on success, (-1) on failure and rte_errno is set.
 567  */
 568 int
 569 eal_file_open(const char *path, int flags);
 570
 571 /** File locking operation. */
 572 enum eal_flock_op {
 573         EAL_FLOCK_SHARED,    /**< Acquire a shared lock. */
 574         EAL_FLOCK_EXCLUSIVE, /**< Acquire an exclusive lock. */
 575         EAL_FLOCK_UNLOCK     /**< Release a previously taken lock. */
 576 };
 577
 578 /** Behavior on file locking conflict. */
 579 enum eal_flock_mode {
 580         EAL_FLOCK_WAIT,  /**< Wait until the file gets unlocked to lock it. */
 581         EAL_FLOCK_RETURN /**< Return immediately if the file is locked. */
 582 };
 583
 584 /**
 585  * Lock or unlock the file.
 586  *
 587  * On failure @code rte_errno @endcode is set to the error code
 588  * specified by POSIX flock(3) description.
 589  *
 590  * @param fd
 591  *  Opened file descriptor.
 592  * @param op
 593  *  Operation to perform.
 594  * @param mode
 595  *  Behavior on conflict.
 596  * @return
 597  *  0 on success, (-1) on failure.
 598  */
 599 int
 600 eal_file_lock(int fd, enum eal_flock_op op, enum eal_flock_mode mode);
 601
 602 /**
 603  * Truncate or extend the file to the specified size.
 604  *
 605  * On failure @code rte_errno @endcode is set to the error code
 606  * specified by POSIX ftruncate(3) description.
 607  *
 608  * @param fd
 609  *  Opened file descriptor.
 610  * @param size
 611  *  Desired file size.
 612  * @return
 613  *  0 on success, (-1) on failure.
 614  */
 615 int
 616 eal_file_truncate(int fd, ssize_t size);
 617
 618 /**
 619  * Reserve a region of virtual memory.
 620  *
 621  * Use eal_mem_free() to free reserved memory.
 622  *
 623  * @param requested_addr
 624  *  A desired reservation address which must be page-aligned.
 625  *  The system might not respect it.
 626  *  NULL means the address will be chosen by the system.
 627  * @param size
 628  *  Reservation size. Must be a multiple of system page size.
 629  * @param flags
 630  *  Reservation options, a combination of eal_mem_reserve_flags.
 631  * @returns
 632  *  Starting address of the reserved area on success, NULL on failure.
 633  *  Callers must not access this memory until remapping it.
 634  */
 635 void *
 636 eal_mem_reserve(void *requested_addr, size_t size, int flags);
 637
 638 /**
 639  * Free memory obtained by eal_mem_reserve() and possibly allocated.
 640  *
 641  * If *virt* and *size* describe a part of the reserved region,
 642  * only this part of the region is freed (accurately up to the system
 643  * page size). If *virt* points to allocated memory, *size* must match
 644  * the one specified on allocation. The behavior is undefined
 645  * if the memory pointed by *virt* is obtained from another source
 646  * than listed above.
 647  *
 648  * @param virt
 649  *  A virtual address in a region previously reserved.
 650  * @param size
 651  *  Number of bytes to unreserve.
 652  */
 653 void
 654 eal_mem_free(void *virt, size_t size);
 655
 656 /**
 657  * Configure memory region inclusion into dumps.
 658  *
 659  * @param virt
 660  *  Starting address of the region.
 661  * @param size
 662  *  Size of the region.
 663  * @param dump
 664  *  True to include memory into dumps, false to exclude.
 665  * @return
 666  *  0 on success, (-1) on failure and rte_errno is set.
 667  */
 668 int
 669 eal_mem_set_dump(void *virt, size_t size, bool dump);
 670
 671 #endif /* _EAL_PRIVATE_H_ */