DOCA SDK Documentation
DOCA SDK Documentation
Breadcrumbs

DOCA doca-hugepages Tool

This guide provides an overview of the doca-hugepages tool, including its purpose, usage instructions, command syntax, and integration guidelines for managing hugepage allocations in NVIDIA DOCA environments.

Introduction

The doca-hugepages tool manages hugepages configurations for various applications. It enables users to configure, reload, remove, and display hugepages settings efficiently. The tool is located at /usr/sbin/doca-hugepages.

All doca-hugepages commands begin with doca-hugepages and fall into the following categories:

  • config – Adds or updates an application's configuration in the database. This command does not apply changes immediately; use the reload command to allocate hugepages based on the updated configuration.

  • reload – Reloads the hugepages configuration for all applications according to the current database.

  • remove – Removes an application's configuration from the database.

  • show – Displays the current hugepages configuration for all applications.

  • original-config – Manages and displays the original system configuration saved by the tool.

Execution

config

Adds or updates an application's configuration in the database.

doca-hugepages config [-h] --app APP --size SIZE --num NUM [--force]

doca-hugepages config Flags:
	--force (optional)		Forces updating the configuration without prompting.
	--app					Name of the application.
	--size					Hugepage size in kB.
	--num 					Number of hugepages to allocate.

For example:

doca-hugepages config --app myApp --size 2048 --num 10

reload

Reloads the hugepages configuration for all applications.

doca-hugepages reload

remove

Removes an application's configuration from the database.

doca-hugepages remove <app>

doca-hugepages remove Flags:
	--all: 		Removes all configurations for the app without prompting.

show

Displays the current hugepages configuration for all applications.

doca-hugepages show

original-config

Manages the original system configuration captured by the tool on its first run. This snapshot serves as a reference for restoring or comparing configurations.

doca-hugepages original-config {update,show}

doca-hugepages original-config Flags:
	show:		Display the original system configuration.
	update: 	Override the original system configuration.

Important Notes

  • Always run doca-hugepages reload after updating configurations to apply changes.

  • Use --force with caution to avoid unintended updates.

  • Periodically use show to verify the active configuration.

Incompatibility with GRUB-Based Hugepages Management

The doca-hugepages tool is not supported on systems where hugepages are configured through GRUB (e.g., via /etc/default/grub). These two methods are mutually exclusive. Attempting to use both may result in unpredictable behavior or configuration conflicts.

To use doca-hugepages, ensure that all hugepages-related GRUB parameters are removed. Conversely, when using GRUB-based configuration, do not invoke doca-hugepages.

Integration with Packages

Custom per-application hugepages configurations can be integrated into packages by placing a configuration file in the /etc/mellanox/hugepages.d/ directory.

Example:

/etc/mellanox/hugepages.d/APP.json

{
  "2048": {
    "num": 1024,
    "is_active": "inactive"
  }
}

In this example:

  • "2048" – Hugepage size in kilobytes

  • "num" – Number of hugepages to allocate 

  • "is_active" – Marks the configuration as "active" or "inactive" 

    NVIDIA recommends setting "is_active": "inactive" and using the doca-hugepages tool to activate the configuration during driver load or system boot. This workflow is supported only on Ubuntu 22.04 systems running on BlueField platforms.

Last updated: