docs/gettingstarted/users/configuring/hugepages.rst

   1 .. _hugepages:
   2
   3 Huge Pages
   4 ----------
   5
   6 VPP requires *'hugepages'* to run. VPP will overwrite existing hugepage settings
   7 when VPP is installed. By default, VPP sets the number of hugepages on a system
   8 to 1024 2M hugepages (1G hugepages are no longer supported). This is the number
   9 of hugepages on the system, not just used by VPP.
  10
  11 When VPP is installed, the following file is copied to the system and used to apply the
  12 hugepage settings on VPP installation and system reboot:
  13
  14 .. code-block:: console
  15
  16     $ cat /etc/sysctl.d/80-vpp.conf
  17     # Number of 2MB hugepages desired
  18     vm.nr_hugepages=1024
  19
  20     # Must be greater than or equal to (2 * vm.nr_hugepages).
  21     vm.max_map_count=3096
  22
  23     # All groups allowed to access hugepages
  24     vm.hugetlb_shm_group=0
  25
  26     # Shared Memory Max must be greator or equal to the total size of hugepages.
  27     # For 2MB pages, TotalHugepageSize = vm.nr_hugepages * 2 * 1024 * 1024
  28     # If the existing kernel.shmmax setting  (cat /sys/proc/kernel/shmmax)
  29     # is greater than the calculated TotalHugepageSize then set this parameter
  30     # to current shmmax value.
  31     kernel.shmmax=2147483648
  32
  33 Depending on how the system is being used, this file can be updated to adjust
  34 the number of hugepages reserved on a system. Below are some examples of
  35 possible values.
  36
  37 For a small VM with minimal workload:
  38
  39 .. code-block:: console
  40
  41     vm.nr_hugepages=512
  42     vm.max_map_count=2048
  43     kernel.shmmax=1073741824
  44
  45 For a large system running multiple VMs, each needing its own set of hugepages:
  46
  47 .. code-block:: console
  48
  49     vm.nr_hugepages=32768
  50     vm.max_map_count=66560
  51     kernel.shmmax=68719476736
  52
  53
  54 .. note::
  55
  56     If VPP is being run in a Virtual Machine (VM), the VM must have hugepage
  57     backing. When VPP is installed, it will attempt to overwrite existing
  58     hugepage setting. If the VM does not have hugepage backing, this will fail,
  59     but this may go unnoticed. When the VM is rebooted, on system startup,
  60     *'vm.nr_hugepages'* will be reapplied, will fail, and the VM will abort kernel
  61     boot, locking up the VM. To avoid this scenario, ensure the VM has enough
  62     hugepage backing.