1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2010-2018 Intel Corporation
5 #ifndef _EAL_PRIVATE_H_
6 #define _EAL_PRIVATE_H_
11 #include <sys/queue.h>
14 #include <rte_lcore.h>
15 #include <rte_memory.h>
17 #include "eal_internal_cfg.h"
20 * Structure storing internal configuration (per-lcore)
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 */
27 lcore_function_t * volatile f; /**< function to call */
28 void * volatile arg; /**< argument of function */
29 volatile int ret; /**< return value of function */
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 */
37 rte_cpuset_t cpuset; /**< cpu set which the lcore affinity to */
40 extern struct lcore_config lcore_config[RTE_MAX_LCORE];
43 * The global RTE configuration structure.
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. */
53 /** Primary or secondary configuration */
54 enum rte_proc_type_t process_type;
56 /** PA or VA mapping mode */
57 enum rte_iova_mode iova_mode;
60 * Pointer to memory configuration, which may be shared across multiple
63 struct rte_mem_config *mem_config;
67 * Get the global configuration structure.
70 * A pointer to the global configuration structure.
72 struct rte_config *rte_eal_get_configuration(void);
75 * Initialize the memzone subsystem (private to eal).
81 int rte_eal_memzone_init(void);
84 * Fill configuration with number of physical and logical processors
86 * This function is private to EAL.
88 * Parse /proc/cpuinfo to get the number of physical and logical
89 * processors on the machine.
92 * 0 on success, negative on error
94 int rte_eal_cpu_init(void);
99 * This function is private to EAL.
101 * Preallocate virtual memory.
104 * 0 on success, negative on error
106 int rte_eal_memseg_init(void);
111 * This function is private to EAL.
113 * Fill configuration structure with these infos, and return 0 on success.
116 * 0 on success, negative on error
118 int rte_eal_memory_init(void);
123 * This function is private to EAL.
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.
130 * 0 on success, negative on error
132 int rte_eal_timer_init(void);
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
138 * This function is private to EAL
141 * 0 on success, negative on error
143 int rte_eal_tailqs_init(void);
146 * Init interrupt handling.
148 * This function is private to EAL.
151 * 0 on success, negative on error
153 int rte_eal_intr_init(void);
156 * Close the default log stream
158 * This function is private to EAL.
160 void rte_eal_log_cleanup(void);
163 * Init alarm mechanism. This is to allow a callback be called after
166 * This function is private to EAL.
169 * 0 on success, negative on error
171 int rte_eal_alarm_init(void);
174 * Alarm mechanism cleanup.
176 * This function is private to EAL.
179 * 0 on success, negative on error
181 void rte_eal_alarm_cleanup(void);
184 * Function is to check if the kernel module(like, vfio, vfio_iommu_type1,
188 * The module's name which need to be checked
191 * -1 means some error happens(NULL pointer or open failure)
192 * 0 means the module not loaded
193 * 1 means the module loaded
195 int rte_eal_check_module(const char *module_name);
198 * Memory reservation flags.
200 enum eal_mem_reserve_flags {
202 * Reserve hugepages. May be unsupported by some platforms.
204 EAL_RESERVE_HUGEPAGES = 1 << 0,
206 * Force reserving memory at the requested address.
207 * This can be a destructive action depending on the implementation.
209 * @see RTE_MAP_FORCE_ADDRESS for description of possible consequences
210 * (although implementations are not required to use it).
212 EAL_RESERVE_FORCE_ADDRESS = 1 << 1
216 * Get virtual area of specified size from the OS.
218 * This function is private to the EAL.
220 * @param requested_addr
221 * Address where to request address space.
223 * Size of requested area.
225 * Page size on which to align requested virtual area.
227 * EAL_VIRTUAL_AREA_* flags.
228 * @param reserve_flags
229 * Extra flags passed directly to eal_mem_reserve().
232 * Virtual area address if successful.
233 * NULL if unsuccessful.
236 #define EAL_VIRTUAL_AREA_ADDR_IS_HINT (1 << 0)
237 /**< don't fail if cannot get exact requested address. */
238 #define EAL_VIRTUAL_AREA_ALLOW_SHRINK (1 << 1)
239 /**< try getting smaller sized (decrement by page size) virtual areas if cannot
240 * get area of requested size.
242 #define EAL_VIRTUAL_AREA_UNMAP (1 << 2)
243 /**< immediately unmap reserved virtual area. */
245 eal_get_virtual_area(void *requested_addr, size_t *size,
246 size_t page_sz, int flags, int reserve_flags);
249 * Initialize a memory segment list and create its backing storage.
252 * Memory segment list to be filled.
254 * Name for the backing storage.
256 * Size of segment pages in the MSL.
258 * Number of segments.
260 * Socket ID. Must not be SOCKET_ID_ANY.
262 * Mark MSL as pointing to a heap.
264 * 0 on success, (-1) on failure and rte_errno is set.
267 eal_memseg_list_init_named(struct rte_memseg_list *msl, const char *name,
268 uint64_t page_sz, int n_segs, int socket_id, bool heap);
271 * Initialize memory segment list and create its backing storage
272 * with a name corresponding to MSL parameters.
274 * @param type_msl_idx
275 * Index of the MSL among other MSLs of the same socket and page size.
277 * @see eal_memseg_list_init_named for remaining parameters description.
280 eal_memseg_list_init(struct rte_memseg_list *msl, uint64_t page_sz,
281 int n_segs, int socket_id, int type_msl_idx, bool heap);
284 * Reserve VA space for a memory segment list
285 * previously initialized with eal_memseg_list_init().
288 * Initialized memory segment list with page size defined.
289 * @param reserve_flags
290 * Extra memory reservation flags. Can be 0 if unnecessary.
292 * 0 on success, (-1) on failure and rte_errno is set.
295 eal_memseg_list_alloc(struct rte_memseg_list *msl, int reserve_flags);
298 * Populate MSL, each segment is one page long.
301 * Initialized memory segment list with page size defined.
303 * Starting address of list segments.
305 * Number of segments to populate.
308 eal_memseg_list_populate(struct rte_memseg_list *msl, void *addr, int n_segs);
311 * Distribute available memory between MSLs.
314 * 0 on success, (-1) on failure.
317 eal_dynmem_memseg_lists_init(void);
320 * Preallocate hugepages for dynamic allocation.
323 * 0 on success, (-1) on failure.
326 eal_dynmem_hugepage_init(void);
329 * Given the list of hugepage sizes and the number of pages thereof,
330 * calculate the best number of pages of each size to fulfill the request
331 * for RAM on each NUMA node.
334 * Amounts of memory requested for each NUMA node of RTE_MAX_NUMA_NODES.
336 * Information about hugepages of different size.
338 * Receives information about used hugepages of each size.
340 * Number of elements in hp_info and hp_used.
342 * 0 on success, (-1) on failure.
345 eal_dynmem_calc_num_pages_per_socket(
346 uint64_t *memory, struct hugepage_info *hp_info,
347 struct hugepage_info *hp_used, unsigned int num_hp_info);
352 * This function is private to the EAL.
354 unsigned eal_cpu_core_id(unsigned lcore_id);
357 * Check if cpu is present.
359 * This function is private to the EAL.
361 int eal_cpu_detected(unsigned lcore_id);
364 * Set TSC frequency from precise value or estimation
366 * This function is private to the EAL.
368 void set_tsc_freq(void);
371 * Get precise TSC frequency from system
373 * This function is private to the EAL.
375 uint64_t get_tsc_freq(void);
378 * Get TSC frequency if the architecture supports.
380 * This function is private to the EAL.
383 * The number of TSC cycles in one second.
384 * Returns zero if the architecture support is not available.
386 uint64_t get_tsc_freq_arch(void);
389 * Allocate a free lcore to associate to a non-EAL thread.
392 * - the id of a lcore with role ROLE_NON_EAL on success.
393 * - RTE_MAX_LCORE if none was available or initializing was refused (see
394 * rte_lcore_callback_register).
396 unsigned int eal_lcore_non_eal_allocate(void);
399 * Release the lcore used by a non-EAL thread.
400 * Counterpart of eal_lcore_non_eal_allocate().
403 * The lcore with role ROLE_NON_EAL to release.
405 void eal_lcore_non_eal_release(unsigned int lcore_id);
408 * Prepare physical memory mapping
409 * i.e. hugepages on Linux and
412 * This function is private to the EAL.
414 int rte_eal_hugepage_init(void);
417 * Creates memory mapping in secondary process
418 * i.e. hugepages on Linux and
421 * This function is private to the EAL.
423 int rte_eal_hugepage_attach(void);
426 * Detaches all memory mappings from a process.
428 * This function is private to the EAL.
430 int rte_eal_memory_detach(void);
433 * Find a bus capable of identifying a device.
436 * A device identifier (PCI address, virtual PMD name, ...).
439 * A valid bus handle if found.
440 * NULL if no bus is able to parse this device.
442 struct rte_bus *rte_bus_find_by_device_name(const char *str);
445 * Create the unix channel for primary/secondary communication.
451 int rte_mp_channel_init(void);
454 * Primary/secondary communication cleanup.
456 void rte_mp_channel_cleanup(void);
460 * Parse a device string and store its information in an
461 * rte_devargs structure.
463 * A device description is split by layers of abstraction of the device:
464 * bus, class and driver. Each layer will offer a set of properties that
465 * can be applied either to configure or recognize a device.
467 * This function will parse those properties and prepare the rte_devargs
468 * to be given to each layers for processing.
470 * Note: if the "data" field of the devargs points to devstr,
471 * then no dynamic allocation is performed and the rte_devargs
472 * can be safely discarded.
474 * Otherwise ``data`` will hold a workable copy of devstr, that will be
475 * used by layers descriptors within rte_devargs. In this case,
476 * any rte_devargs should be cleaned-up before being freed.
479 * rte_devargs structure to fill.
486 * Negative errno values on error (rte_errno is set).
489 rte_devargs_layers_parse(struct rte_devargs *devargs,
493 * probe a device at local process.
496 * Device arguments including bus, class and driver properties.
498 * new device be probed as output.
500 * 0 on success, negative on error.
502 int local_dev_probe(const char *devargs, struct rte_device **new_dev);
505 * Hotplug remove a given device from a specific bus at local process.
508 * Data structure of the device to remove.
510 * 0 on success, negative on error.
512 int local_dev_remove(struct rte_device *dev);
515 * Iterate over all buses to find the corresponding bus to handle the sigbus
517 * @param failure_addr
518 * Pointer of the fault address of the sigbus error.
521 * 0 success to handle the sigbus.
522 * -1 failed to handle the sigbus
523 * 1 no bus can handler the sigbus
525 int rte_bus_sigbus_handler(const void *failure_addr);
529 * Register the sigbus handler.
532 * - On success, zero.
533 * - On failure, a negative value.
536 dev_sigbus_handler_register(void);
540 * Unregister the sigbus handler.
543 * - On success, zero.
544 * - On failure, a negative value.
547 dev_sigbus_handler_unregister(void);
550 * Get OS-specific EAL mapping base address.
553 eal_get_baseaddr(void);
556 eal_malloc_no_trace(const char *type, size_t size, unsigned int align);
558 void eal_free_no_trace(void *addr);
560 /** Options for eal_file_open(). */
561 enum eal_open_flags {
562 /** Open file for reading. */
563 EAL_OPEN_READONLY = 0x00,
564 /** Open file for reading and writing. */
565 EAL_OPEN_READWRITE = 0x02,
567 * Create the file if it doesn't exist.
568 * New files are only accessible to the owner (0600 equivalent).
570 EAL_OPEN_CREATE = 0x04
574 * Open or create a file.
579 * A combination of eal_open_flags controlling operation and FD behavior.
581 * Open file descriptor on success, (-1) on failure and rte_errno is set.
584 eal_file_open(const char *path, int flags);
586 /** File locking operation. */
588 EAL_FLOCK_SHARED, /**< Acquire a shared lock. */
589 EAL_FLOCK_EXCLUSIVE, /**< Acquire an exclusive lock. */
590 EAL_FLOCK_UNLOCK /**< Release a previously taken lock. */
593 /** Behavior on file locking conflict. */
594 enum eal_flock_mode {
595 EAL_FLOCK_WAIT, /**< Wait until the file gets unlocked to lock it. */
596 EAL_FLOCK_RETURN /**< Return immediately if the file is locked. */
600 * Lock or unlock the file.
602 * On failure @code rte_errno @endcode is set to the error code
603 * specified by POSIX flock(3) description.
606 * Opened file descriptor.
608 * Operation to perform.
610 * Behavior on conflict.
612 * 0 on success, (-1) on failure.
615 eal_file_lock(int fd, enum eal_flock_op op, enum eal_flock_mode mode);
618 * Truncate or extend the file to the specified size.
620 * On failure @code rte_errno @endcode is set to the error code
621 * specified by POSIX ftruncate(3) description.
624 * Opened file descriptor.
628 * 0 on success, (-1) on failure.
631 eal_file_truncate(int fd, ssize_t size);
634 * Reserve a region of virtual memory.
636 * Use eal_mem_free() to free reserved memory.
638 * @param requested_addr
639 * A desired reservation address which must be page-aligned.
640 * The system might not respect it.
641 * NULL means the address will be chosen by the system.
643 * Reservation size. Must be a multiple of system page size.
645 * Reservation options, a combination of eal_mem_reserve_flags.
647 * Starting address of the reserved area on success, NULL on failure.
648 * Callers must not access this memory until remapping it.
651 eal_mem_reserve(void *requested_addr, size_t size, int flags);
654 * Free memory obtained by eal_mem_reserve() and possibly allocated.
656 * If *virt* and *size* describe a part of the reserved region,
657 * only this part of the region is freed (accurately up to the system
658 * page size). If *virt* points to allocated memory, *size* must match
659 * the one specified on allocation. The behavior is undefined
660 * if the memory pointed by *virt* is obtained from another source
664 * A virtual address in a region previously reserved.
666 * Number of bytes to unreserve.
669 eal_mem_free(void *virt, size_t size);
672 * Configure memory region inclusion into dumps.
675 * Starting address of the region.
677 * Size of the region.
679 * True to include memory into dumps, false to exclude.
681 * 0 on success, (-1) on failure and rte_errno is set.
684 eal_mem_set_dump(void *virt, size_t size, bool dump);
687 * Sets the runtime directory of DPDK
690 * The new runtime directory path of DPDK
692 * 0 on success, (-1) on failure.
695 eal_set_runtime_dir(const char *run_dir);
698 * Get the internal configuration structure.
701 * A pointer to the internal configuration structure.
703 struct internal_config *
704 eal_get_internal_configuration(void);
707 * Get the current value of the rte_application_usage pointer
710 * Pointer to the current value of rte_application_usage .
713 eal_get_application_usage_hook(void);
716 * Instruct primary process that a secondary process wants to attach.
718 bool __rte_mp_enable(void);
721 * Init per-lcore info in current thread.
724 * identifier of lcore.
726 * CPU affinity for this thread.
728 void __rte_thread_init(unsigned int lcore_id, rte_cpuset_t *cpuset);
731 * Uninitialize per-lcore info for current thread.
733 void __rte_thread_uninit(void);
736 * asprintf(3) replacement for Windows.
738 #ifdef RTE_EXEC_ENV_WINDOWS
739 __rte_format_printf(2, 3)
740 int eal_asprintf(char **buffer, const char *format, ...);
742 #define asprintf(buffer, format, ...) \
743 eal_asprintf(buffer, format, ##__VA_ARGS__)
746 #endif /* _EAL_PRIVATE_H_ */