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