NVIDIA 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.

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.

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.

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.

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"

  Tip

  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.