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.

Description

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.

Execution

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.

Best Practices

  • 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

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.

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

Last updated: