doc/guides/prog_guide/mempool_lib.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2014 Intel Corporation.
   3
   4 .. _Mempool_Library:
   5
   6 Mempool Library
   7 ===============
   8
   9 A memory pool is an allocator of a fixed-sized object.
  10 In the DPDK, it is identified by name and uses a mempool handler to store free objects.
  11 The default mempool handler is ring based.
  12 It provides some other optional services such as a per-core object cache and
  13 an alignment helper to ensure that objects are padded to spread them equally on all DRAM or DDR3 channels.
  14
  15 This library is used by the :ref:`Mbuf Library <Mbuf_Library>`.
  16
  17 Cookies
  18 -------
  19
  20 In debug mode, cookies are added at the beginning and end of allocated blocks.
  21 The allocated objects then contain overwrite protection fields to help debugging buffer overflows.
  22
  23 Stats
  24 -----
  25
  26 In debug mode, statistics about get from/put in the pool are stored in the mempool structure.
  27 Statistics are per-lcore to avoid concurrent access to statistics counters.
  28
  29 Memory Alignment Constraints on x86 architecture
  30 ------------------------------------------------
  31
  32 Depending on hardware memory configuration on X86 architecture, performance can be greatly improved by adding a specific padding between objects.
  33 The objective is to ensure that the beginning of each object starts on a different channel and rank in memory so that all channels are equally loaded.
  34
  35 This is particularly true for packet buffers when doing L3 forwarding or flow classification.
  36 Only the first 64 bytes are accessed, so performance can be increased by spreading the start addresses of objects among the different channels.
  37
  38 The number of ranks on any DIMM is the number of independent sets of DRAMs that can be accessed for the full data bit-width of the DIMM.
  39 The ranks cannot be accessed simultaneously since they share the same data path.
  40 The physical layout of the DRAM chips on the DIMM itself does not necessarily relate to the number of ranks.
  41
  42 When running an application, the EAL command line options provide the ability to add the number of memory channels and ranks.
  43
  44 .. note::
  45
  46     The command line must always have the number of memory channels specified for the processor.
  47
  48 Examples of alignment for different DIMM architectures are shown in
  49 :numref:`figure_memory-management` and :numref:`figure_memory-management2`.
  50
  51 .. _figure_memory-management:
  52
  53 .. figure:: img/memory-management.*
  54
  55    Two Channels and Quad-ranked DIMM Example
  56
  57
  58 In this case, the assumption is that a packet is 16 blocks of 64 bytes, which is not true.
  59
  60 The Intel® 5520 chipset has three channels, so in most cases,
  61 no padding is required between objects (except for objects whose size are n x 3 x 64 bytes blocks).
  62
  63 .. _figure_memory-management2:
  64
  65 .. figure:: img/memory-management2.*
  66
  67    Three Channels and Two Dual-ranked DIMM Example
  68
  69
  70 When creating a new pool, the user can specify to use this feature or not.
  71
  72 .. _mempool_local_cache:
  73
  74 Local Cache
  75 -----------
  76
  77 In terms of CPU usage, the cost of multiple cores accessing a memory pool's ring of free buffers may be high
  78 since each access requires a compare-and-set (CAS) operation.
  79 To avoid having too many access requests to the memory pool's ring,
  80 the memory pool allocator can maintain a per-core cache and do bulk requests to the memory pool's ring,
  81 via the cache with many fewer locks on the actual memory pool structure.
  82 In this way, each core has full access to its own cache (with locks) of free objects and
  83 only when the cache fills does the core need to shuffle some of the free objects back to the pools ring or
  84 obtain more objects when the cache is empty.
  85
  86 While this may mean a number of buffers may sit idle on some core's cache,
  87 the speed at which a core can access its own cache for a specific memory pool without locks provides performance gains.
  88
  89 The cache is composed of a small, per-core table of pointers and its length (used as a stack).
  90 This internal cache can be enabled or disabled at creation of the pool.
  91
  92 The maximum size of the cache is static and is defined at compilation time (RTE_MEMPOOL_CACHE_MAX_SIZE).
  93
  94 :numref:`figure_mempool` shows a cache in operation.
  95
  96 .. _figure_mempool:
  97
  98 .. figure:: img/mempool.*
  99
 100    A mempool in Memory with its Associated Ring
 101
 102 Alternatively to the internal default per-lcore local cache, an application can create and manage external caches through the ``rte_mempool_cache_create()``, ``rte_mempool_cache_free()`` and ``rte_mempool_cache_flush()`` calls.
 103 These user-owned caches can be explicitly passed to ``rte_mempool_generic_put()`` and ``rte_mempool_generic_get()``.
 104 The ``rte_mempool_default_cache()`` call returns the default internal cache if any.
 105 In contrast to the default caches, user-owned caches can be used by unregistered non-EAL threads too.
 106
 107 .. _Mempool_Handlers:
 108
 109 Mempool Handlers
 110 ------------------------
 111
 112 This allows external memory subsystems, such as external hardware memory
 113 management systems and software based memory allocators, to be used with DPDK.
 114
 115 There are two aspects to a mempool handler.
 116
 117 * Adding the code for your new mempool operations (ops). This is achieved by
 118   adding a new mempool ops code, and using the ``MEMPOOL_REGISTER_OPS`` macro.
 119
 120 * Using the new API to call ``rte_mempool_create_empty()`` and
 121   ``rte_mempool_set_ops_byname()`` to create a new mempool and specifying which
 122   ops to use.
 123
 124 Several different mempool handlers may be used in the same application. A new
 125 mempool can be created by using the ``rte_mempool_create_empty()`` function,
 126 then using ``rte_mempool_set_ops_byname()`` to point the mempool to the
 127 relevant mempool handler callback (ops) structure.
 128
 129 Legacy applications may continue to use the old ``rte_mempool_create()`` API
 130 call, which uses a ring based mempool handler by default. These applications
 131 will need to be modified to use a new mempool handler.
 132
 133 For applications that use ``rte_pktmbuf_create()``, there is a config setting
 134 (``RTE_MBUF_DEFAULT_MEMPOOL_OPS``) that allows the application to make use of
 135 an alternative mempool handler.
 136
 137   .. note::
 138
 139     When running a DPDK application with shared libraries, mempool handler
 140     shared objects specified with the '-d' EAL command-line parameter are
 141     dynamically loaded. When running a multi-process application with shared
 142     libraries, the -d arguments for mempool handlers *must be specified in the
 143     same order for all processes* to ensure correct operation.
 144
 145
 146 Use Cases
 147 ---------
 148
 149 All allocations that require a high level of performance should use a pool-based memory allocator.
 150 Below are some examples:
 151
 152 *   :ref:`Mbuf Library <Mbuf_Library>`
 153
 154 *   :ref:`Environment Abstraction Layer <Environment_Abstraction_Layer>` , for logging service
 155
 156 *   Any application that needs to allocate fixed-sized objects in the data plane and that will be continuously utilized by the system.