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  * Allocate a free lcore to associate to a non-EAL thread.
 401  *
 402  * @return
 403  *   - the id of a lcore with role ROLE_NON_EAL on success.
 404  *   - RTE_MAX_LCORE if none was available.
 405  */
 406 unsigned int eal_lcore_non_eal_allocate(void);
 407
 408 /**
 409  * Release the lcore used by a non-EAL thread.
 410  * Counterpart of eal_lcore_non_eal_allocate().
 411  *
 412  * @param lcore_id
 413  *   The lcore with role ROLE_NON_EAL to release.
 414  */
 415 void eal_lcore_non_eal_release(unsigned int lcore_id);
 416
 417 /**
 418  * Prepare physical memory mapping
 419  * i.e. hugepages on Linux and
 420  *      contigmem on BSD.
 421  *
 422  * This function is private to the EAL.
 423  */
 424 int rte_eal_hugepage_init(void);
 425
 426 /**
 427  * Creates memory mapping in secondary process
 428  * i.e. hugepages on Linux and
 429  *      contigmem on BSD.
 430  *
 431  * This function is private to the EAL.
 432  */
 433 int rte_eal_hugepage_attach(void);
 434
 435 /**
 436  * Find a bus capable of identifying a device.
 437  *
 438  * @param str
 439  *   A device identifier (PCI address, virtual PMD name, ...).
 440  *
 441  * @return
 442  *   A valid bus handle if found.
 443  *   NULL if no bus is able to parse this device.
 444  */
 445 struct rte_bus *rte_bus_find_by_device_name(const char *str);
 446
 447 /**
 448  * Create the unix channel for primary/secondary communication.
 449  *
 450  * @return
 451  *   0 on success;
 452  *   (<0) on failure.
 453  */
 454 int rte_mp_channel_init(void);
 455
 456 /**
 457  * Primary/secondary communication cleanup.
 458  */
 459 void rte_mp_channel_cleanup(void);
 460
 461 /**
 462  * @internal
 463  * Parse a device string and store its information in an
 464  * rte_devargs structure.
 465  *
 466  * A device description is split by layers of abstraction of the device:
 467  * bus, class and driver. Each layer will offer a set of properties that
 468  * can be applied either to configure or recognize a device.
 469  *
 470  * This function will parse those properties and prepare the rte_devargs
 471  * to be given to each layers for processing.
 472  *
 473  * Note: if the "data" field of the devargs points to devstr,
 474  * then no dynamic allocation is performed and the rte_devargs
 475  * can be safely discarded.
 476  *
 477  * Otherwise ``data`` will hold a workable copy of devstr, that will be
 478  * used by layers descriptors within rte_devargs. In this case,
 479  * any rte_devargs should be cleaned-up before being freed.
 480  *
 481  * @param da
 482  *   rte_devargs structure to fill.
 483  *
 484  * @param devstr
 485  *   Device string.
 486  *
 487  * @return
 488  *   0 on success.
 489  *   Negative errno values on error (rte_errno is set).
 490  */
 491 int
 492 rte_devargs_layers_parse(struct rte_devargs *devargs,
 493                          const char *devstr);
 494
 495 /*
 496  * probe a device at local process.
 497  *
 498  * @param devargs
 499  *   Device arguments including bus, class and driver properties.
 500  * @param new_dev
 501  *   new device be probed as output.
 502  * @return
 503  *   0 on success, negative on error.
 504  */
 505 int local_dev_probe(const char *devargs, struct rte_device **new_dev);
 506
 507 /**
 508  * Hotplug remove a given device from a specific bus at local process.
 509  *
 510  * @param dev
 511  *   Data structure of the device to remove.
 512  * @return
 513  *   0 on success, negative on error.
 514  */
 515 int local_dev_remove(struct rte_device *dev);
 516
 517 /**
 518  * Iterate over all buses to find the corresponding bus to handle the sigbus
 519  * error.
 520  * @param failure_addr
 521  *      Pointer of the fault address of the sigbus error.
 522  *
 523  * @return
 524  *       0 success to handle the sigbus.
 525  *      -1 failed to handle the sigbus
 526  *       1 no bus can handler the sigbus
 527  */
 528 int rte_bus_sigbus_handler(const void *failure_addr);
 529
 530 /**
 531  * @internal
 532  * Register the sigbus handler.
 533  *
 534  * @return
 535  *   - On success, zero.
 536  *   - On failure, a negative value.
 537  */
 538 int
 539 dev_sigbus_handler_register(void);
 540
 541 /**
 542  * @internal
 543  * Unregister the sigbus handler.
 544  *
 545  * @return
 546  *   - On success, zero.
 547  *   - On failure, a negative value.
 548  */
 549 int
 550 dev_sigbus_handler_unregister(void);
 551
 552 /**
 553  * Get OS-specific EAL mapping base address.
 554  */
 555 uint64_t
 556 eal_get_baseaddr(void);
 557
 558 void *
 559 eal_malloc_no_trace(const char *type, size_t size, unsigned int align);
 560
 561 void eal_free_no_trace(void *addr);
 562
 563 /** Options for eal_file_open(). */
 564 enum eal_open_flags {
 565         /** Open file for reading. */
 566         EAL_OPEN_READONLY = 0x00,
 567         /** Open file for reading and writing. */
 568         EAL_OPEN_READWRITE = 0x02,
 569         /**
 570          * Create the file if it doesn't exist.
 571          * New files are only accessible to the owner (0600 equivalent).
 572          */
 573         EAL_OPEN_CREATE = 0x04
 574 };
 575
 576 /**
 577  * Open or create a file.
 578  *
 579  * @param path
 580  *  Path to the file.
 581  * @param flags
 582  *  A combination of eal_open_flags controlling operation and FD behavior.
 583  * @return
 584  *  Open file descriptor on success, (-1) on failure and rte_errno is set.
 585  */
 586 int
 587 eal_file_open(const char *path, int flags);
 588
 589 /** File locking operation. */
 590 enum eal_flock_op {
 591         EAL_FLOCK_SHARED,    /**< Acquire a shared lock. */
 592         EAL_FLOCK_EXCLUSIVE, /**< Acquire an exclusive lock. */
 593         EAL_FLOCK_UNLOCK     /**< Release a previously taken lock. */
 594 };
 595
 596 /** Behavior on file locking conflict. */
 597 enum eal_flock_mode {
 598         EAL_FLOCK_WAIT,  /**< Wait until the file gets unlocked to lock it. */
 599         EAL_FLOCK_RETURN /**< Return immediately if the file is locked. */
 600 };
 601
 602 /**
 603  * Lock or unlock the file.
 604  *
 605  * On failure @code rte_errno @endcode is set to the error code
 606  * specified by POSIX flock(3) description.
 607  *
 608  * @param fd
 609  *  Opened file descriptor.
 610  * @param op
 611  *  Operation to perform.
 612  * @param mode
 613  *  Behavior on conflict.
 614  * @return
 615  *  0 on success, (-1) on failure.
 616  */
 617 int
 618 eal_file_lock(int fd, enum eal_flock_op op, enum eal_flock_mode mode);
 619
 620 /**
 621  * Truncate or extend the file to the specified size.
 622  *
 623  * On failure @code rte_errno @endcode is set to the error code
 624  * specified by POSIX ftruncate(3) description.
 625  *
 626  * @param fd
 627  *  Opened file descriptor.
 628  * @param size
 629  *  Desired file size.
 630  * @return
 631  *  0 on success, (-1) on failure.
 632  */
 633 int
 634 eal_file_truncate(int fd, ssize_t size);
 635
 636 /**
 637  * Reserve a region of virtual memory.
 638  *
 639  * Use eal_mem_free() to free reserved memory.
 640  *
 641  * @param requested_addr
 642  *  A desired reservation address which must be page-aligned.
 643  *  The system might not respect it.
 644  *  NULL means the address will be chosen by the system.
 645  * @param size
 646  *  Reservation size. Must be a multiple of system page size.
 647  * @param flags
 648  *  Reservation options, a combination of eal_mem_reserve_flags.
 649  * @returns
 650  *  Starting address of the reserved area on success, NULL on failure.
 651  *  Callers must not access this memory until remapping it.
 652  */
 653 void *
 654 eal_mem_reserve(void *requested_addr, size_t size, int flags);
 655
 656 /**
 657  * Free memory obtained by eal_mem_reserve() and possibly allocated.
 658  *
 659  * If *virt* and *size* describe a part of the reserved region,
 660  * only this part of the region is freed (accurately up to the system
 661  * page size). If *virt* points to allocated memory, *size* must match
 662  * the one specified on allocation. The behavior is undefined
 663  * if the memory pointed by *virt* is obtained from another source
 664  * than listed above.
 665  *
 666  * @param virt
 667  *  A virtual address in a region previously reserved.
 668  * @param size
 669  *  Number of bytes to unreserve.
 670  */
 671 void
 672 eal_mem_free(void *virt, size_t size);
 673
 674 /**
 675  * Configure memory region inclusion into dumps.
 676  *
 677  * @param virt
 678  *  Starting address of the region.
 679  * @param size
 680  *  Size of the region.
 681  * @param dump
 682  *  True to include memory into dumps, false to exclude.
 683  * @return
 684  *  0 on success, (-1) on failure and rte_errno is set.
 685  */
 686 int
 687 eal_mem_set_dump(void *virt, size_t size, bool dump);
 688
 689 /**
 690  * Sets the runtime directory of DPDK
 691  *
 692  * @param run_dir
 693  *   The new runtime directory path of DPDK
 694  * @param size
 695  *   The size of the new runtime directory path in bytes.
 696  * @return
 697  *   0 on success, (-1) on failure.
 698  */
 699 int
 700 eal_set_runtime_dir(char *run_dir, size_t size);
 701
 702 /**
 703  * Get the internal configuration structure.
 704  *
 705  * @return
 706  *   A pointer to the internal configuration structure.
 707  */
 708 struct internal_config *
 709 eal_get_internal_configuration(void);
 710
 711 /**
 712  * Get the current value of the rte_application_usage pointer
 713  *
 714  * @return
 715  *   Pointer to the current value of rte_application_usage .
 716  */
 717 rte_usage_hook_t
 718 eal_get_application_usage_hook(void);
 719
 720 /**
 721  * Mark primary process as not supporting multi-process.
 722  */
 723 bool __rte_mp_disable(void);
 724
 725 /**
 726  * Instruct primary process that a secondary process wants to attach.
 727  */
 728 bool __rte_mp_enable(void);
 729
 730 /**
 731  * Init per-lcore info in current thread.
 732  *
 733  * @param lcore_id
 734  *   identifier of lcore.
 735  * @param cpuset
 736  *   CPU affinity for this thread.
 737  */
 738 void __rte_thread_init(unsigned int lcore_id, rte_cpuset_t *cpuset);
 739
 740 /**
 741  * Uninitialize per-lcore info for current thread.
 742  */
 743 void __rte_thread_uninit(void);
 744
 745 #endif /* _EAL_PRIVATE_H_ */