NIC Masks Generator Tool

This document provides guidelines for installing and running the Intel® Gaudi® NIC Masks Generator tool on Intel Gaudi 3 accelerator. The hl-gen-nic-masks tool generates NIC masks for Gaudi 3 servers based on a provided topology and configuration JSON files.

It can also optionally generate an updated ITB (Image Tree Blob) file using a supplied ITB template, embedding the computed NIC masks and recalculating the corresponding hash.

Supported features:

• Validates the input topology and configuration JSON files.

• Computes NIC masks for OAM indices (0-7) based on internal and external links.

• Outputs the generated NIC masks into a JSON file.

• Optionally updates an ITB file with the generated masks and recalculates its hash.

Note

• The tool can run with or without driver loaded.

• It is only possible to run the tool on Hypervisor. Running the tool on a guest VM may cause undefined behavior.

Prerequisites

• Python 3.8 or higher

• No external dependencies (uses only Python standard library modules)

Installation

1. Install the package from `Intel Gaudi vault <https://vault.habana.ai/artifactory/gaudi-odm/1.24.0/gaudi3/`_.

2. Extract the package:

   tar -xvzf gaudi3-gen-nic-masks.tgz
   

3. Run the script:

   1. Basic usage (generates NIC masks only). This generates the generated-nic-masks.json file containing the computed NIC masks:

      python hl-gen-nic-masks.py topology.json config.json
      

   2. With ITB generation. This generates generated-nic-masks.json, and an updated .itb file with embedded NIC masks, ready to be programmed using hl-fw-loader:

      python hl-gen-nic-masks.py --itb template.itb topology.json config.json
      

Options and Usage

Use the -h argument to view all options. The tables below describe all the hl-gen-nic-masks arugments, options and outputs available.

python hl-gen-nic-masks.py [-h] [-v] [-d]
                          [--itb <path-to-itb-template>]
                          <topology-json-path>
                          <config-json-path>

Options

Option	Argument	Description
-h, –help	None	Show help message and exit.
-v, –verbose	None	Enable verbose output for debugging and tracing execution.
-d, –debug	None	Enable debug mode with additional internal details.
–itb	<path>	Path to an ITB template file. When provided, the tool generates an updated ITB file that includes the computed NIC masks and recalculated hash.

Arguments

Argument	Description
topology-json-path	Path to the topology JSON file describing the system layout.
config-json-path	Path to the configuration JSON file defining NIC settings.

Output

Output	Description
generated-nic-masks.json	JSON file containing the computed NIC masks.
Updated ITB file (optional)	Generated only if the –itb option is provided. The .itb file is used to configure the NIC port masks and is applied during firmware loading via hl-fw-loader. Therefore, make sure to unload the driver.

Examples

First Use Case: Enable all Ports on all OAMs

1. Configue the server-config.json file:

   {
      "description": "Gaudi 3 Server Configuration",
      "internal_links": [
      [0, 1, 2, 3, 4, 5, 6, 7]
      ],
      "external_links": [0, 1, 2, 3, 4, 5, 6, 7]
   }
   

   Explanation:

   • A single group in internal_links containing all OAMs enables all internal ports.

   • A single group in external_links enables all external ports for all OAMs.

2. Run the tool:

   cli-prompt> python hl-gen-nic-masks.py server-topology.json server-config.json
   

   • Expected output:

     I: Topology is valid
     I: Configuration is valid
     I: Masks generated and saved to generated-nic-masks.json
     

   • Generated file generated-nic-masks.json:

     {
        "0": "0x00FFFFFF",
        "1": "0x00FFFFFF",
        "2": "0x00FFFFFF",
        "3": "0x00FFFFFF",
        "4": "0x00FFFFFF",
        "5": "0x00FFFFFF",
        "6": "0x00FFFFFF",
        "7": "0x00FFFFFF"
     }
     

   • Explanation:

     • 0x00FFFFFF means ports 0–23 are enabled.

     • Only 24 out of 32 bits are relevant, as each OAM has 24 ports.

To generate an .itb, run the following using template.itb:

cli-prompt> python hl-gen-nic-masks.py --itb template.itb server-topology.json server-config.json

Output:

I: Topology is valid
I: Configuration is valid
I: Masks generated and saved to generated-nic-masks.json
I: ITB template is valid
I: Created ITB file: gaudi3-gen-nic-masks.itb

The generated gaudi3-gen-nic-masks.itb file can be used to program the configuration via:

sudo hl-fw-loader -f gaudi3-gen-nic-masks.itb

Second Use Case: Selective OAM Connectivity

1. Connect and enable external ports:

• OAM0 ↔ OAM1

• OAM2 ↔ OAM3

2. Configure the server-config.json file:

   Explanation:

   • Two separate groups in internal_links:

   • [0, 1] connects OAM0 and OAM1

   • [2, 3] connects OAM2 and OAM3

   • This differs from a single group [0, 1, 2, 3], which would connect all OAMs together.

3. Run the tool:

   cli-prompt> python hl-gen-nic-masks.py --itb template.itb server-topology.json server-config.json
   

   • Expected output:

     I: Topology is valid
     I: Configuration is valid
     I: Masks generated and saved to generated-nic-masks.json
     I: ITB template is valid
     I: Created ITB file: gaudi3-gen-nic-masks.itb
     

   • Generated file (generated-nic-masks.json):

     .. code::
     
        {
           "0": "0x00720003",
           "1": "0x00003B20",
           "2": "0x0000C720",
           "3": "0x00B2000C",
           "4": "0x00000000",
           "5": "0x00000000",
           "6": "0x00000000",
           "7": "0x00000000"
        }
     

   • Explanation:

     • OAM0 (0x00720003): Ports connected to OAM1 + external ports are enabled.

     • OAM1 (0x00003B20): Ports connected to OAM0 + external ports are enabled.

     • OAM2 (0x0000C720): Ports connected to OAM3 + external ports are enabled.

     • OAM3 (0x00B2000C): Ports connected to OAM2 + external ports are enabled.

     • OAM4–OAM7 (0x00000000): All ports are disabled (no internal or external connections).