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