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