NVIDIA DOCA doca-hugepages Tool

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.

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.
        

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

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.

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").

  Tip

  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.