DOCA SDK Documentation
DOCA SDK Documentation
Breadcrumbs

NVIDIA DOCA doca-hugepages Tool

Introduction

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

All doca-hugepages commands begin with doca-hugepages. The commands are conceptually group 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 based on the current database settings.

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

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

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 based on the current database settings.

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

Manage and display the original system configuration saved by the tool. Upon its initial run, the tool captures a snapshot of the current hugepages configuration and saves it. This snapshot serves as a reference for configuring hugepages. If all configurations set by the tool are deleted, hugepages will revert to this original configuration.

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 use the reload command after updating configurations to ensure changes are applied.

  • Use the --force option with caution when updating configurations to avoid unintended changes.

  • Regularly check the current configuration using the show command to ensure settings are as expected.

Incompatibility with GRUB-Based Hugepages Management

The doca-hugepages tool is not supported on systems where hugepages are managed via a GRUB configuration. The doca-hugepages tool and GRUB-based hugepages management are mutually exclusive. You must choose either to manage hugepages using the doca-hugepages tool or to configure hugepages via GRUB (e.g., by setting hugepages parameters in /etc/default/grub). Using both methods concurrently is not supported and may result in unpredictable behavior or configuration conflicts.

To use the doca-hugepages tool, ensure that all hugepages-related settings are removed from your GRUB configuration. To manage hugepages via GRUB, do not use the doca-hugepages tool.

Integration with Packages

To integrate your custom configuration into an application package, you can define a per-application configuration by adding a configuration file under the directory /etc/mellanox/hugepages.d/.

For example, you can create a configuration file named /etc/mellanox/hugepages.d/APP.json with the following structure:

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

In this example:

  • "2048" specifies the hugepage size in kilobytes.

  • "num" defines the number of hugepages to allocate.

  • "is_active" indicates whether the configuration is active ("active") or inactive ("inactive"). 

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

Last updated: