Metadata-Version: 2.4
Name: hugepages
Version: 0.2.10
Summary: Inspect and manage Linux hugepages
Author-email: "Simon A. F. Lund" <os@safl.dk>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/xnvme/hugepages
Project-URL: Repository, https://github.com/xnvme/hugepages
Project-URL: Issues, https://github.com/xnvme/hugepages/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Operating System
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

![hugepages: inspect and manage Linux hugepages](https://raw.githubusercontent.com/xnvme/hugepages/main/assets/banner.svg)

# hugepages

[![PyPI](https://img.shields.io/pypi/v/hugepages.svg)](https://pypi.org/project/hugepages/)
[![Python](https://img.shields.io/pypi/pyversions/hugepages.svg)](https://pypi.org/project/hugepages/)
[![Test](https://github.com/xnvme/hugepages/actions/workflows/test.yml/badge.svg)](https://github.com/xnvme/hugepages/actions/workflows/test.yml)

`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`](https://github.com/xnvme/devbind): inspect and control PCI device-driver binding in Linux.
- [`iommu`](https://github.com/safl/iommu): inspect and configure the IOMMU in Linux.
