NVIDIA DOCA DPA L2 Reflector Application Guide

This document provides a DPA L2 reflector implementation on top of the NVIDIA® BlueField®-3 DPU.

The BlueField-3 DPU supports high-speed Data Path Accelerator (DPA) . Data path accelerator allows for accelerated packet processing and manipulation.

DOCA l ayer-2 reflector uses the DPA engine to intercept network traffic and swap the source and destination MAC addresses of each packet.

The application accepts traffic from a specific port given as an argument and leverages DPA capabilities for accelerated processing.

The following figure provides a high-level view of the components of the application:

DOCA L2 reflector runs on top of FlexIO SDK to configure the DPA engine.

The FlexIO application consist of two parts:

• Host side – responsible for allocating resources and loading them to the DPA

• Device side – core processing logic of the application which swaps the MACs on the DPA

For more information, refer to "Programming FlexIO SDK".

This application leverages the following DOCA driver:

• FlexIO SDK

Refer to its programming guide for more information.

NVIDIA® BlueField®-3 DPU and above is required.

Installation

Please refer to the NVIDIA DOCA Installation Guide for Linux for details on how to install BlueField-related software.

Application Execution

The L2 reflector application is provided in both source and binary forms. The binary is located under /opt/mellanox/doca/applications/l2_reflector/bin/l2_reflector.

1. Application usage instructions:

   Copy

   Copied!

               
   
               
   Usage: l2_reflector [DOCA Flags] [Program Flags]
    
   DOCA Flags:
     -h, --help                        Print a help synopsis
     -v, --version                     Print program version information
     -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
     --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
     -j, --json <path>                 Parse all command flags from an input json file
    
   Program Flags:
     -d, --device <device name>        Device name
           

   Note

   This usage printout can be printed to the command line using the -h (or --help) options:

   Copy

   Copied!

               
   
               
   /opt/mellanox/doca/applications/l2_reflector/bin/l2_reflector -h
           

   Note

   For additional information, refer to section "Command Line Flags".

2. CLI example for running the application on BlueField or host:

   Copy

   Copied!

               
   
               
   /opt/mellanox/doca/applications/l2_reflector/bin/l2_reflector -d mlx5_0
           

   Warning

   The used device name (-d flag) must match the identifier of the desired IB device.

   Note

   To run the application on the second port, verify that it has a partition. Run:

   Copy

   Copied!

               
   
               
   dpaeumgmt partition info -d mlx5_1
           

   If DPA EU partition creation is required, refer to NVIDIA DOCA DPA Execution Unit Management Tool.

3. The application also supports a JSON-based deployment mode, in which all command-line arguments are provided through a JSON file:

   Copy

   Copied!

               
   
               
   l2_reflector --json [json_file]
           

   For example:

   Copy

   Copied!

               
   
               
   cd /opt/mellanox/doca/applications/l2_reflector/bin
   ./l2_reflector --json ./l2_reflector_params.json
           

   Warning

   Before execution, ensure that the used JSON file contains the correct configuration parameters, and especially the desired PCIe addresses required for the deployment.

Command Line Flags

            

            
"log-level": 60
        

            

            
"sdk-log-level": 40
        

            

            
"device": mlx5_0 
        

Troubleshooting

Please refer to the NVIDIA DOCA Troubleshooting Guide for any issue encountered with the installation or execution of the DOCA applications.

In addition to providing the application in binary form, the installation also includes all of the application sources and compilation instructions so as to allow modifying the sources and recompiling the application. For more information about the applications, as well as development and compilation tips, refer to the DOCA Applications page.

The sources of the application can be found under the /opt/mellanox/doca/applications/l2_reflector/src directory.

Recompiling All Applications

The applications are all defined under a single meson project, so the default compilation recompiles all the DOCA applications.

To build all the applications together, run:

            

            
cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build
        

Recompiling DPA L2 Reflector Application Only

To directly build only the L2 reflector application:

            

            
cd /opt/mellanox/doca/applications/
meson /tmp/build -Denable_all_applications=false -Denable_l2_reflector=true
ninja -C /tmp/build
        

Alternatively, one can set the desired flags in the meson_options.txt file instead of providing them in the compilation command line:

1. Edit the following flags in /opt/mellanox/doca/applications/meson_options.txt:

   • Set enable_all_applications to false

   • Set enable_l2_reflector to true

2. Run the following compilation commands :

   Copy

   Copied!

               
   
               
   cd /opt/mellanox/doca/applications/
   meson /tmp/build 
   ninja -C /tmp/build
           

   Note

   l2_reflector is created under /tmp/build/l2_reflector/src/host.

Troubleshooting

Refer to the NVIDIA DOCA Troubleshooting Guide for any issue you may encounter with the compilation of the DOCA applications.

This section lists the application's configuration flow which includes different FlexIO functions and wrappers.

1. Parse application argument.

   1. Initialize arg parser resources and register DOCA general parameters.

      Copy

      Copied!

                  
      
                  
      doca_argp_init();
              

   2. Register the application's parameters.

      Copy

      Copied!

                  
      
                  
      register_l2_reflector_params();
              

   3. Parse the arguments.

      Copy

      Copied!

                  
      
                  
      doca_argp_start();
              

2. Setup the InfiniBand device.

   Copy

   Copied!

               
   
               
   l2_reflector_setup_ibv_device();
           

3. Setup the DPA device.

   Copy

   Copied!

               
   
               
   l2_reflector_setup_device();
           

4. Allocate the device's resources.

   Copy

   Copied!

               
   
               
   l2_reflector_allocate_device_resources();
           

5. R un initialization function on the device.

   Copy

   Copied!

               
   
               
   flexio_process_call();
           

6. Create the steering rule.

   Copy

   Copied!

               
   
               
   l2_reflector_create_steering_rule();
           

7. Start the event handler on the device.

   Copy

   Copied!

               
   
               
   flexio_event_handler_run();
           

8. Main loop.

   Copy

   Copied!

               
   
               
   while (!force_quit)
   	sleep(10);
           

9. Cleanup the resources.

   Copy

   Copied!

               
   
               
   l2_reflector_destroy();
           

• /opt/mellanox/doca/applications/l2_reflector/src

• /opt/mellanox/doca/applications/l2_reflector/bin/l2_reflector_params.json