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.

The doca-hugepages tool supports the following configuration commands:

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

1. config Command

Usage:

            

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

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

Options

• --force (optional) - Forces updating the configuration without prompting.

• --app - Name of the application.

• --size - Hugepage size in kB.

• --num - Number of hugepages to allocate.

Example

            

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

2. reload Command

Usage:

            

            
doca-hugepages reload
        

Purpose: Reloads the hugepages configuration for all applications based on the current database settings.

Example:

            

            
doca-hugepages reload
        

3. remove Command

Usage :

            

            
doca-hugepages remove <app>
        

Purpose: Removes an application's configuration from the database.

Options:

• --all: Removes all configurations for the app without prompting.

Example:

            

            
doca-hugepages remove myApp
        

4. show Command

Usage:

            

            
doca-hugepages show
        

Purpose: Displays the current hugepages configuration for all applications.

Example:

            

            
doca-hugepages show
        

5. original-config

Usage:

            

            
doca-hugepages original-config {update,show}
        

Purpose: Manage and display the original system configuration saved by the tool. Upon its first run, the tool captures a snapshot of the current system Hugepages configuration and saves it. This configuration is used as a reference when configuring hugepages. If all configurations set by the tool are deleted, this original configuration will be reapplied.

Example:

            

            
doca-hugepages original-config show
        

Options:

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

As of the latest update, the doca-hugepages tool is not supported on systems where hugepages are managed via GRUB configuration.

Details

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

Recommendation

• If you wish to use the doca-hugepages tool, ensure that all hugepages-related settings are removed from your GRUB configuration.

• If you prefer 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 rely 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.