hugepages 0.2.10

Inspect and manage Linux hugepages

hugepages

hugepages is a small CLI for inspecting and configuring the Linux hugepage pool. It reports current totals, free, and reserved counts per supported page size, reserves pages via the sysfs interface at /sys/kernel/mm/hugepages/, and mounts the hugetlbfs filesystem (default /dev/hugepages).

Install

pipx install hugepages

Or standalone (single-file, stdlib only, no pip needed):

curl -fsSL https://raw.githubusercontent.com/xnvme/hugepages/main/src/hugepages/hugepages.py \
  -o ~/.local/bin/hugepages && chmod +x ~/.local/bin/hugepages

Shell completion

hugepages --print-completion bash > ~/.local/share/bash-completion/completions/hugepages

Open a new shell (or source the file) and tab-completion is live: hugepages <TAB> lists info setup mount.

Usage

$ hugepages --help
usage: hugepages [-h] [--version] [--verbose] [--print-completion SHELL]
                 {info,setup,mount} ...

Inspect and manage Linux hugepages

positional arguments:
  {info,setup,mount}
    info                Show hugepage status and capabilities
    setup               Configure hugepage pool
    mount               Mount hugetlbfs

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --verbose             Enable verbose logging
  --print-completion SHELL
                        Print shell completion script to stdout and exit

A few common invocations:

hugepages info                                  # current pool state + supported sizes
sudo hugepages setup --count 512                # reserve 512 pages at the smallest supported size
sudo hugepages setup --size 2048 --count 1024   # reserve 1024 x 2 MiB (explicit size)
sudo hugepages mount                            # mount hugetlbfs at /dev/hugepages

1 GiB hugepages are only available if the kernel was booted with default_hugepagesz=1G hugepagesz=1G hugepages=N on the cmdline; the kernel reserves the 1 GiB pool at boot, and hugepages setup cannot enable that size after the fact. hugepages info lists the sizes the running kernel actually supports.

hugepages info sample output (pool not yet reserved):

Hugepage Support:
  Size: 2048kB  Total: 0  Free: 0  Reserved: 0
  Size: 1048576kB  Total: 0  Free: 0  Reserved: 0

Allocation paths

hugepages setup reserves pages in the kernel pool. Programs that allocate via memfd_create(..., MFD_HUGETLB) or mmap(..., MAP_HUGETLB) draw directly from the pool; no filesystem is needed. Modern DPDK and custom xNVMe/uPCIe code take this path.

hugepages mount additionally mounts the hugetlbfs pseudo-filesystem (default /dev/hugepages). Programs that want file-backed hugepages with named-page semantics open and mmap files under the mountpoint. SPDK and classic DPDK with --huge-dir use this path.

Related

• devbind: inspect and control PCI device-driver binding in Linux.
• iommu: inspect and configure the IOMMU in Linux.