lib/librte_eal/common/include/rte_memory.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2014 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_MEMORY_H_
   6 #define _RTE_MEMORY_H_
   7
   8 /**
   9  * @file
  10  *
  11  * Memory-related RTE API.
  12  */
  13
  14 #include <stdint.h>
  15 #include <stddef.h>
  16 #include <stdio.h>
  17
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 #include <rte_common.h>
  23 #include <rte_compat.h>
  24 #include <rte_config.h>
  25 #include <rte_fbarray.h>
  26
  27 __extension__
  28 enum rte_page_sizes {
  29         RTE_PGSIZE_4K    = 1ULL << 12,
  30         RTE_PGSIZE_64K   = 1ULL << 16,
  31         RTE_PGSIZE_256K  = 1ULL << 18,
  32         RTE_PGSIZE_2M    = 1ULL << 21,
  33         RTE_PGSIZE_16M   = 1ULL << 24,
  34         RTE_PGSIZE_256M  = 1ULL << 28,
  35         RTE_PGSIZE_512M  = 1ULL << 29,
  36         RTE_PGSIZE_1G    = 1ULL << 30,
  37         RTE_PGSIZE_4G    = 1ULL << 32,
  38         RTE_PGSIZE_16G   = 1ULL << 34,
  39 };
  40
  41 #define SOCKET_ID_ANY -1                    /**< Any NUMA socket. */
  42 #define RTE_CACHE_LINE_MASK (RTE_CACHE_LINE_SIZE-1) /**< Cache line mask. */
  43
  44 #define RTE_CACHE_LINE_ROUNDUP(size) \
  45         (RTE_CACHE_LINE_SIZE * ((size + RTE_CACHE_LINE_SIZE - 1) / RTE_CACHE_LINE_SIZE))
  46 /**< Return the first cache-aligned value greater or equal to size. */
  47
  48 /**< Cache line size in terms of log2 */
  49 #if RTE_CACHE_LINE_SIZE == 64
  50 #define RTE_CACHE_LINE_SIZE_LOG2 6
  51 #elif RTE_CACHE_LINE_SIZE == 128
  52 #define RTE_CACHE_LINE_SIZE_LOG2 7
  53 #else
  54 #error "Unsupported cache line size"
  55 #endif
  56
  57 #define RTE_CACHE_LINE_MIN_SIZE 64      /**< Minimum Cache line size. */
  58
  59 /**
  60  * Force alignment to cache line.
  61  */
  62 #define __rte_cache_aligned __rte_aligned(RTE_CACHE_LINE_SIZE)
  63
  64 /**
  65  * Force minimum cache line alignment.
  66  */
  67 #define __rte_cache_min_aligned __rte_aligned(RTE_CACHE_LINE_MIN_SIZE)
  68
  69 typedef uint64_t phys_addr_t; /**< Physical address. */
  70 #define RTE_BAD_PHYS_ADDR ((phys_addr_t)-1)
  71 /**
  72  * IO virtual address type.
  73  * When the physical addressing mode (IOVA as PA) is in use,
  74  * the translation from an IO virtual address (IOVA) to a physical address
  75  * is a direct mapping, i.e. the same value.
  76  * Otherwise, in virtual mode (IOVA as VA), an IOMMU may do the translation.
  77  */
  78 typedef uint64_t rte_iova_t;
  79 #define RTE_BAD_IOVA ((rte_iova_t)-1)
  80
  81 /**
  82  * Physical memory segment descriptor.
  83  */
  84 #define RTE_MEMSEG_FLAG_DO_NOT_FREE (1 << 0)
  85 /**< Prevent this segment from being freed back to the OS. */
  86 struct rte_memseg {
  87         RTE_STD_C11
  88         union {
  89                 phys_addr_t phys_addr;  /**< deprecated - Start physical address. */
  90                 rte_iova_t iova;        /**< Start IO address. */
  91         };
  92         RTE_STD_C11
  93         union {
  94                 void *addr;         /**< Start virtual address. */
  95                 uint64_t addr_64;   /**< Makes sure addr is always 64 bits */
  96         };
  97         size_t len;               /**< Length of the segment. */
  98         uint64_t hugepage_sz;       /**< The pagesize of underlying memory */
  99         int32_t socket_id;          /**< NUMA socket ID. */
 100         uint32_t nchannel;          /**< Number of channels. */
 101         uint32_t nrank;             /**< Number of ranks. */
 102         uint32_t flags;             /**< Memseg-specific flags */
 103 } __rte_packed;
 104
 105 /**
 106  * memseg list is a special case as we need to store a bunch of other data
 107  * together with the array itself.
 108  */
 109 struct rte_memseg_list {
 110         RTE_STD_C11
 111         union {
 112                 void *base_va;
 113                 /**< Base virtual address for this memseg list. */
 114                 uint64_t addr_64;
 115                 /**< Makes sure addr is always 64-bits */
 116         };
 117         uint64_t page_sz; /**< Page size for all memsegs in this list. */
 118         int socket_id; /**< Socket ID for all memsegs in this list. */
 119         volatile uint32_t version; /**< version number for multiprocess sync. */
 120         size_t len; /**< Length of memory area covered by this memseg list. */
 121         unsigned int external; /**< 1 if this list points to external memory */
 122         struct rte_fbarray memseg_arr;
 123 };
 124
 125 /**
 126  * Lock page in physical memory and prevent from swapping.
 127  *
 128  * @param virt
 129  *   The virtual address.
 130  * @return
 131  *   0 on success, negative on error.
 132  */
 133 int rte_mem_lock_page(const void *virt);
 134
 135 /**
 136  * Get physical address of any mapped virtual address in the current process.
 137  * It is found by browsing the /proc/self/pagemap special file.
 138  * The page must be locked.
 139  *
 140  * @param virt
 141  *   The virtual address.
 142  * @return
 143  *   The physical address or RTE_BAD_IOVA on error.
 144  */
 145 phys_addr_t rte_mem_virt2phy(const void *virt);
 146
 147 /**
 148  * Get IO virtual address of any mapped virtual address in the current process.
 149  *
 150  * @param virt
 151  *   The virtual address.
 152  * @return
 153  *   The IO address or RTE_BAD_IOVA on error.
 154  */
 155 rte_iova_t rte_mem_virt2iova(const void *virt);
 156
 157 /**
 158  * Get virtual memory address corresponding to iova address.
 159  *
 160  * @note This function read-locks the memory hotplug subsystem, and thus cannot
 161  *       be used within memory-related callback functions.
 162  *
 163  * @param iova
 164  *   The iova address.
 165  * @return
 166  *   Virtual address corresponding to iova address (or NULL if address does not
 167  *   exist within DPDK memory map).
 168  */
 169 __rte_experimental
 170 void *
 171 rte_mem_iova2virt(rte_iova_t iova);
 172
 173 /**
 174  * Get memseg to which a particular virtual address belongs.
 175  *
 176  * @param virt
 177  *   The virtual address.
 178  * @param msl
 179  *   The memseg list in which to look up based on ``virt`` address
 180  *   (can be NULL).
 181  * @return
 182  *   Memseg pointer on success, or NULL on error.
 183  */
 184 __rte_experimental
 185 struct rte_memseg *
 186 rte_mem_virt2memseg(const void *virt, const struct rte_memseg_list *msl);
 187
 188 /**
 189  * Get memseg list corresponding to virtual memory address.
 190  *
 191  * @param virt
 192  *   The virtual address.
 193  * @return
 194  *   Memseg list to which this virtual address belongs to.
 195  */
 196 __rte_experimental
 197 struct rte_memseg_list *
 198 rte_mem_virt2memseg_list(const void *virt);
 199
 200 /**
 201  * Memseg walk function prototype.
 202  *
 203  * Returning 0 will continue walk
 204  * Returning 1 will stop the walk
 205  * Returning -1 will stop the walk and report error
 206  */
 207 typedef int (*rte_memseg_walk_t)(const struct rte_memseg_list *msl,
 208                 const struct rte_memseg *ms, void *arg);
 209
 210 /**
 211  * Memseg contig walk function prototype. This will trigger a callback on every
 212  * VA-contiguous area starting at memseg ``ms``, so total valid VA space at each
 213  * callback call will be [``ms->addr``, ``ms->addr + len``).
 214  *
 215  * Returning 0 will continue walk
 216  * Returning 1 will stop the walk
 217  * Returning -1 will stop the walk and report error
 218  */
 219 typedef int (*rte_memseg_contig_walk_t)(const struct rte_memseg_list *msl,
 220                 const struct rte_memseg *ms, size_t len, void *arg);
 221
 222 /**
 223  * Memseg list walk function prototype. This will trigger a callback on every
 224  * allocated memseg list.
 225  *
 226  * Returning 0 will continue walk
 227  * Returning 1 will stop the walk
 228  * Returning -1 will stop the walk and report error
 229  */
 230 typedef int (*rte_memseg_list_walk_t)(const struct rte_memseg_list *msl,
 231                 void *arg);
 232
 233 /**
 234  * Walk list of all memsegs.
 235  *
 236  * @note This function read-locks the memory hotplug subsystem, and thus cannot
 237  *       be used within memory-related callback functions.
 238  *
 239  * @note This function will also walk through externally allocated segments. It
 240  *       is up to the user to decide whether to skip through these segments.
 241  *
 242  * @param func
 243  *   Iterator function
 244  * @param arg
 245  *   Argument passed to iterator
 246  * @return
 247  *   0 if walked over the entire list
 248  *   1 if stopped by the user
 249  *   -1 if user function reported error
 250  */
 251 __rte_experimental
 252 int
 253 rte_memseg_walk(rte_memseg_walk_t func, void *arg);
 254
 255 /**
 256  * Walk each VA-contiguous area.
 257  *
 258  * @note This function read-locks the memory hotplug subsystem, and thus cannot
 259  *       be used within memory-related callback functions.
 260  *
 261  * @note This function will also walk through externally allocated segments. It
 262  *       is up to the user to decide whether to skip through these segments.
 263  *
 264  * @param func
 265  *   Iterator function
 266  * @param arg
 267  *   Argument passed to iterator
 268  * @return
 269  *   0 if walked over the entire list
 270  *   1 if stopped by the user
 271  *   -1 if user function reported error
 272  */
 273 __rte_experimental
 274 int
 275 rte_memseg_contig_walk(rte_memseg_contig_walk_t func, void *arg);
 276
 277 /**
 278  * Walk each allocated memseg list.
 279  *
 280  * @note This function read-locks the memory hotplug subsystem, and thus cannot
 281  *       be used within memory-related callback functions.
 282  *
 283  * @note This function will also walk through externally allocated segments. It
 284  *       is up to the user to decide whether to skip through these segments.
 285  *
 286  * @param func
 287  *   Iterator function
 288  * @param arg
 289  *   Argument passed to iterator
 290  * @return
 291  *   0 if walked over the entire list
 292  *   1 if stopped by the user
 293  *   -1 if user function reported error
 294  */
 295 __rte_experimental
 296 int
 297 rte_memseg_list_walk(rte_memseg_list_walk_t func, void *arg);
 298
 299 /**
 300  * Walk list of all memsegs without performing any locking.
 301  *
 302  * @note This function does not perform any locking, and is only safe to call
 303  *       from within memory-related callback functions.
 304  *
 305  * @param func
 306  *   Iterator function
 307  * @param arg
 308  *   Argument passed to iterator
 309  * @return
 310  *   0 if walked over the entire list
 311  *   1 if stopped by the user
 312  *   -1 if user function reported error
 313  */
 314 __rte_experimental
 315 int
 316 rte_memseg_walk_thread_unsafe(rte_memseg_walk_t func, void *arg);
 317
 318 /**
 319  * Walk each VA-contiguous area without performing any locking.
 320  *
 321  * @note This function does not perform any locking, and is only safe to call
 322  *       from within memory-related callback functions.
 323  *
 324  * @param func
 325  *   Iterator function
 326  * @param arg
 327  *   Argument passed to iterator
 328  * @return
 329  *   0 if walked over the entire list
 330  *   1 if stopped by the user
 331  *   -1 if user function reported error
 332  */
 333 __rte_experimental
 334 int
 335 rte_memseg_contig_walk_thread_unsafe(rte_memseg_contig_walk_t func, void *arg);
 336
 337 /**
 338  * Walk each allocated memseg list without performing any locking.
 339  *
 340  * @note This function does not perform any locking, and is only safe to call
 341  *       from within memory-related callback functions.
 342  *
 343  * @param func
 344  *   Iterator function
 345  * @param arg
 346  *   Argument passed to iterator
 347  * @return
 348  *   0 if walked over the entire list
 349  *   1 if stopped by the user
 350  *   -1 if user function reported error
 351  */
 352 __rte_experimental
 353 int
 354 rte_memseg_list_walk_thread_unsafe(rte_memseg_list_walk_t func, void *arg);
 355
 356 /**
 357  * Return file descriptor associated with a particular memseg (if available).
 358  *
 359  * @note This function read-locks the memory hotplug subsystem, and thus cannot
 360  *       be used within memory-related callback functions.
 361  *
 362  * @note This returns an internal file descriptor. Performing any operations on
 363  *       this file descriptor is inherently dangerous, so it should be treated
 364  *       as read-only for all intents and purposes.
 365  *
 366  * @param ms
 367  *   A pointer to memseg for which to get file descriptor.
 368  *
 369  * @return
 370  *   Valid file descriptor in case of success.
 371  *   -1 in case of error, with ``rte_errno`` set to the following values:
 372  *     - EINVAL  - ``ms`` pointer was NULL or did not point to a valid memseg
 373  *     - ENODEV  - ``ms`` fd is not available
 374  *     - ENOENT  - ``ms`` is an unused segment
 375  *     - ENOTSUP - segment fd's are not supported
 376  */
 377 __rte_experimental
 378 int
 379 rte_memseg_get_fd(const struct rte_memseg *ms);
 380
 381 /**
 382  * Return file descriptor associated with a particular memseg (if available).
 383  *
 384  * @note This function does not perform any locking, and is only safe to call
 385  *       from within memory-related callback functions.
 386  *
 387  * @note This returns an internal file descriptor. Performing any operations on
 388  *       this file descriptor is inherently dangerous, so it should be treated
 389  *       as read-only for all intents and purposes.
 390  *
 391  * @param ms
 392  *   A pointer to memseg for which to get file descriptor.
 393  *
 394  * @return
 395  *   Valid file descriptor in case of success.
 396  *   -1 in case of error, with ``rte_errno`` set to the following values:
 397  *     - EINVAL  - ``ms`` pointer was NULL or did not point to a valid memseg
 398  *     - ENODEV  - ``ms`` fd is not available
 399  *     - ENOENT  - ``ms`` is an unused segment
 400  *     - ENOTSUP - segment fd's are not supported
 401  */
 402 __rte_experimental
 403 int
 404 rte_memseg_get_fd_thread_unsafe(const struct rte_memseg *ms);
 405
 406 /**
 407  * Get offset into segment file descriptor associated with a particular memseg
 408  * (if available).
 409  *
 410  * @note This function read-locks the memory hotplug subsystem, and thus cannot
 411  *       be used within memory-related callback functions.
 412  *
 413  * @param ms
 414  *   A pointer to memseg for which to get file descriptor.
 415  * @param offset
 416  *   A pointer to offset value where the result will be stored.
 417  *
 418  * @return
 419  *   Valid file descriptor in case of success.
 420  *   -1 in case of error, with ``rte_errno`` set to the following values:
 421  *     - EINVAL  - ``ms`` pointer was NULL or did not point to a valid memseg
 422  *     - EINVAL  - ``offset`` pointer was NULL
 423  *     - ENODEV  - ``ms`` fd is not available
 424  *     - ENOENT  - ``ms`` is an unused segment
 425  *     - ENOTSUP - segment fd's are not supported
 426  */
 427 __rte_experimental
 428 int
 429 rte_memseg_get_fd_offset(const struct rte_memseg *ms, size_t *offset);
 430
 431 /**
 432  * Get offset into segment file descriptor associated with a particular memseg
 433  * (if available).
 434  *
 435  * @note This function does not perform any locking, and is only safe to call
 436  *       from within memory-related callback functions.
 437  *
 438  * @param ms
 439  *   A pointer to memseg for which to get file descriptor.
 440  * @param offset
 441  *   A pointer to offset value where the result will be stored.
 442  *
 443  * @return
 444  *   Valid file descriptor in case of success.
 445  *   -1 in case of error, with ``rte_errno`` set to the following values:
 446  *     - EINVAL  - ``ms`` pointer was NULL or did not point to a valid memseg
 447  *     - EINVAL  - ``offset`` pointer was NULL
 448  *     - ENODEV  - ``ms`` fd is not available
 449  *     - ENOENT  - ``ms`` is an unused segment
 450  *     - ENOTSUP - segment fd's are not supported
 451  */
 452 __rte_experimental
 453 int
 454 rte_memseg_get_fd_offset_thread_unsafe(const struct rte_memseg *ms,
 455                 size_t *offset);
 456
 457 /**
 458  * @warning
 459  * @b EXPERIMENTAL: this API may change without prior notice
 460  *
 461  * Register external memory chunk with DPDK.
 462  *
 463  * @note Using this API is mutually exclusive with ``rte_malloc`` family of
 464  *   API's.
 465  *
 466  * @note This API will not perform any DMA mapping. It is expected that user
 467  *   will do that themselves.
 468  *
 469  * @note Before accessing this memory in other processes, it needs to be
 470  *   attached in each of those processes by calling ``rte_extmem_attach`` in
 471  *   each other process.
 472  *
 473  * @param va_addr
 474  *   Start of virtual area to register. Must be aligned by ``page_sz``.
 475  * @param len
 476  *   Length of virtual area to register. Must be aligned by ``page_sz``.
 477  * @param iova_addrs
 478  *   Array of page IOVA addresses corresponding to each page in this memory
 479  *   area. Can be NULL, in which case page IOVA addresses will be set to
 480  *   RTE_BAD_IOVA.
 481  * @param n_pages
 482  *   Number of elements in the iova_addrs array. Ignored if  ``iova_addrs``
 483  *   is NULL.
 484  * @param page_sz
 485  *   Page size of the underlying memory
 486  *
 487  * @return
 488  *   - 0 on success
 489  *   - -1 in case of error, with rte_errno set to one of the following:
 490  *     EINVAL - one of the parameters was invalid
 491  *     EEXIST - memory chunk is already registered
 492  *     ENOSPC - no more space in internal config to store a new memory chunk
 493  */
 494 __rte_experimental
 495 int
 496 rte_extmem_register(void *va_addr, size_t len, rte_iova_t iova_addrs[],
 497                 unsigned int n_pages, size_t page_sz);
 498
 499 /**
 500  * @warning
 501  * @b EXPERIMENTAL: this API may change without prior notice
 502  *
 503  * Unregister external memory chunk with DPDK.
 504  *
 505  * @note Using this API is mutually exclusive with ``rte_malloc`` family of
 506  *   API's.
 507  *
 508  * @note This API will not perform any DMA unmapping. It is expected that user
 509  *   will do that themselves.
 510  *
 511  * @note Before calling this function, all other processes must call
 512  *   ``rte_extmem_detach`` to detach from the memory area.
 513  *
 514  * @param va_addr
 515  *   Start of virtual area to unregister
 516  * @param len
 517  *   Length of virtual area to unregister
 518  *
 519  * @return
 520  *   - 0 on success
 521  *   - -1 in case of error, with rte_errno set to one of the following:
 522  *     EINVAL - one of the parameters was invalid
 523  *     ENOENT - memory chunk was not found
 524  */
 525 __rte_experimental
 526 int
 527 rte_extmem_unregister(void *va_addr, size_t len);
 528
 529 /**
 530  * @warning
 531  * @b EXPERIMENTAL: this API may change without prior notice
 532  *
 533  * Attach to external memory chunk registered in another process.
 534  *
 535  * @note Using this API is mutually exclusive with ``rte_malloc`` family of
 536  *   API's.
 537  *
 538  * @note This API will not perform any DMA mapping. It is expected that user
 539  *   will do that themselves.
 540  *
 541  * @param va_addr
 542  *   Start of virtual area to register
 543  * @param len
 544  *   Length of virtual area to register
 545  *
 546  * @return
 547  *   - 0 on success
 548  *   - -1 in case of error, with rte_errno set to one of the following:
 549  *     EINVAL - one of the parameters was invalid
 550  *     ENOENT - memory chunk was not found
 551  */
 552 __rte_experimental
 553 int
 554 rte_extmem_attach(void *va_addr, size_t len);
 555
 556 /**
 557  * @warning
 558  * @b EXPERIMENTAL: this API may change without prior notice
 559  *
 560  * Detach from external memory chunk registered in another process.
 561  *
 562  * @note Using this API is mutually exclusive with ``rte_malloc`` family of
 563  *   API's.
 564  *
 565  * @note This API will not perform any DMA unmapping. It is expected that user
 566  *   will do that themselves.
 567  *
 568  * @param va_addr
 569  *   Start of virtual area to unregister
 570  * @param len
 571  *   Length of virtual area to unregister
 572  *
 573  * @return
 574  *   - 0 on success
 575  *   - -1 in case of error, with rte_errno set to one of the following:
 576  *     EINVAL - one of the parameters was invalid
 577  *     ENOENT - memory chunk was not found
 578  */
 579 __rte_experimental
 580 int
 581 rte_extmem_detach(void *va_addr, size_t len);
 582
 583 /**
 584  * Dump the physical memory layout to a file.
 585  *
 586  * @note This function read-locks the memory hotplug subsystem, and thus cannot
 587  *       be used within memory-related callback functions.
 588  *
 589  * @param f
 590  *   A pointer to a file for output
 591  */
 592 void rte_dump_physmem_layout(FILE *f);
 593
 594 /**
 595  * Get the total amount of available physical memory.
 596  *
 597  * @note This function read-locks the memory hotplug subsystem, and thus cannot
 598  *       be used within memory-related callback functions.
 599  *
 600  * @return
 601  *    The total amount of available physical memory in bytes.
 602  */
 603 uint64_t rte_eal_get_physmem_size(void);
 604
 605 /**
 606  * Get the number of memory channels.
 607  *
 608  * @return
 609  *   The number of memory channels on the system. The value is 0 if unknown
 610  *   or not the same on all devices.
 611  */
 612 unsigned rte_memory_get_nchannel(void);
 613
 614 /**
 615  * Get the number of memory ranks.
 616  *
 617  * @return
 618  *   The number of memory ranks on the system. The value is 0 if unknown or
 619  *   not the same on all devices.
 620  */
 621 unsigned rte_memory_get_nrank(void);
 622
 623 /**
 624  * @warning
 625  * @b EXPERIMENTAL: this API may change without prior notice
 626  *
 627  * Check if all currently allocated memory segments are compliant with
 628  * supplied DMA address width.
 629  *
 630  *  @param maskbits
 631  *    Address width to check against.
 632  */
 633 __rte_experimental
 634 int rte_mem_check_dma_mask(uint8_t maskbits);
 635
 636 /**
 637  * @warning
 638  * @b EXPERIMENTAL: this API may change without prior notice
 639  *
 640  * Check if all currently allocated memory segments are compliant with
 641  * supplied DMA address width. This function will use
 642  * rte_memseg_walk_thread_unsafe instead of rte_memseg_walk implying
 643  * memory_hotplug_lock will not be acquired avoiding deadlock during
 644  * memory initialization.
 645  *
 646  * This function is just for EAL core memory internal use. Drivers should
 647  * use the previous rte_mem_check_dma_mask.
 648  *
 649  *  @param maskbits
 650  *    Address width to check against.
 651  */
 652 __rte_experimental
 653 int rte_mem_check_dma_mask_thread_unsafe(uint8_t maskbits);
 654
 655 /**
 656  * @warning
 657  * @b EXPERIMENTAL: this API may change without prior notice
 658  *
 659  *  Set dma mask to use once memory initialization is done. Previous functions
 660  *  rte_mem_check_dma_mask and rte_mem_check_dma_mask_thread_unsafe can not be
 661  *  used safely until memory has been initialized.
 662  */
 663 __rte_experimental
 664 void rte_mem_set_dma_mask(uint8_t maskbits);
 665
 666 /**
 667  * Drivers based on uio will not load unless physical
 668  * addresses are obtainable. It is only possible to get
 669  * physical addresses when running as a privileged user.
 670  *
 671  * @return
 672  *   1 if the system is able to obtain physical addresses.
 673  *   0 if using DMA addresses through an IOMMU.
 674  */
 675 int rte_eal_using_phys_addrs(void);
 676
 677
 678 /**
 679  * Enum indicating which kind of memory event has happened. Used by callbacks to
 680  * distinguish between memory allocations and deallocations.
 681  */
 682 enum rte_mem_event {
 683         RTE_MEM_EVENT_ALLOC = 0, /**< Allocation event. */
 684         RTE_MEM_EVENT_FREE,      /**< Deallocation event. */
 685 };
 686 #define RTE_MEM_EVENT_CALLBACK_NAME_LEN 64
 687 /**< maximum length of callback name */
 688
 689 /**
 690  * Function typedef used to register callbacks for memory events.
 691  */
 692 typedef void (*rte_mem_event_callback_t)(enum rte_mem_event event_type,
 693                 const void *addr, size_t len, void *arg);
 694
 695 /**
 696  * Function used to register callbacks for memory events.
 697  *
 698  * @note callbacks will happen while memory hotplug subsystem is write-locked,
 699  *       therefore some functions (e.g. `rte_memseg_walk()`) will cause a
 700  *       deadlock when called from within such callbacks.
 701  *
 702  * @note mem event callbacks not being supported is an expected error condition,
 703  *       so user code needs to handle this situation. In these cases, return
 704  *       value will be -1, and rte_errno will be set to ENOTSUP.
 705  *
 706  * @param name
 707  *   Name associated with specified callback to be added to the list.
 708  *
 709  * @param clb
 710  *   Callback function pointer.
 711  *
 712  * @param arg
 713  *   Argument to pass to the callback.
 714  *
 715  * @return
 716  *   0 on successful callback register
 717  *   -1 on unsuccessful callback register, with rte_errno value indicating
 718  *   reason for failure.
 719  */
 720 __rte_experimental
 721 int
 722 rte_mem_event_callback_register(const char *name, rte_mem_event_callback_t clb,
 723                 void *arg);
 724
 725 /**
 726  * Function used to unregister callbacks for memory events.
 727  *
 728  * @param name
 729  *   Name associated with specified callback to be removed from the list.
 730  *
 731  * @param arg
 732  *   Argument to look for among callbacks with specified callback name.
 733  *
 734  * @return
 735  *   0 on successful callback unregister
 736  *   -1 on unsuccessful callback unregister, with rte_errno value indicating
 737  *   reason for failure.
 738  */
 739 __rte_experimental
 740 int
 741 rte_mem_event_callback_unregister(const char *name, void *arg);
 742
 743
 744 #define RTE_MEM_ALLOC_VALIDATOR_NAME_LEN 64
 745 /**< maximum length of alloc validator name */
 746 /**
 747  * Function typedef used to register memory allocation validation callbacks.
 748  *
 749  * Returning 0 will allow allocation attempt to continue. Returning -1 will
 750  * prevent allocation from succeeding.
 751  */
 752 typedef int (*rte_mem_alloc_validator_t)(int socket_id,
 753                 size_t cur_limit, size_t new_len);
 754
 755 /**
 756  * @brief Register validator callback for memory allocations.
 757  *
 758  * Callbacks registered by this function will be called right before memory
 759  * allocator is about to trigger allocation of more pages from the system if
 760  * said allocation will bring total memory usage above specified limit on
 761  * specified socket. User will be able to cancel pending allocation if callback
 762  * returns -1.
 763  *
 764  * @note callbacks will happen while memory hotplug subsystem is write-locked,
 765  *       therefore some functions (e.g. `rte_memseg_walk()`) will cause a
 766  *       deadlock when called from within such callbacks.
 767  *
 768  * @note validator callbacks not being supported is an expected error condition,
 769  *       so user code needs to handle this situation. In these cases, return
 770  *       value will be -1, and rte_errno will be set to ENOTSUP.
 771  *
 772  * @param name
 773  *   Name associated with specified callback to be added to the list.
 774  *
 775  * @param clb
 776  *   Callback function pointer.
 777  *
 778  * @param socket_id
 779  *   Socket ID on which to watch for allocations.
 780  *
 781  * @param limit
 782  *   Limit above which to trigger callbacks.
 783  *
 784  * @return
 785  *   0 on successful callback register
 786  *   -1 on unsuccessful callback register, with rte_errno value indicating
 787  *   reason for failure.
 788  */
 789 __rte_experimental
 790 int
 791 rte_mem_alloc_validator_register(const char *name,
 792                 rte_mem_alloc_validator_t clb, int socket_id, size_t limit);
 793
 794 /**
 795  * @brief Unregister validator callback for memory allocations.
 796  *
 797  * @param name
 798  *   Name associated with specified callback to be removed from the list.
 799  *
 800  * @param socket_id
 801  *   Socket ID on which to watch for allocations.
 802  *
 803  * @return
 804  *   0 on successful callback unregister
 805  *   -1 on unsuccessful callback unregister, with rte_errno value indicating
 806  *   reason for failure.
 807  */
 808 __rte_experimental
 809 int
 810 rte_mem_alloc_validator_unregister(const char *name, int socket_id);
 811
 812 #ifdef __cplusplus
 813 }
 814 #endif
 815
 816 #endif /* _RTE_MEMORY_H_ */