NVIDIA DOCA DPA L2 Reflector Application Guide

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

Introduction

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.

System Design

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:

system-design-diagram-version-1-modificationdate-1707755629077-api-v2.png

Application Architecture

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

architecture-diagram-version-1-modificationdate-1707755629413-api-v2.png

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

DOCA Libraries and Drivers

This application leverages the following DOCA driver:

FlexIO SDK

Refer to its programming guide for more information.

Dependencies

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

Compiling the Application

Info

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

The installation of DOCA's reference applications contains the sources of the applications, alongside the matching compilation instructions. This allows for compiling the applications "as-is" and provides the ability to modify the sources, then compile a new version of the application.

Tip

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 application's directory: /opt/mellanox/doca/applications/l2_reflector/.

Compiling All Applications

All DOCA applications are defined under a single meson project. So, by default, the compilation includes all of them.

To build all the applications together, run:

Copy
Copied!

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

Info

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

Compiling DPA L2 Reflector Application Only

To directly build only the L2 reflector application:

Copy
Copied!

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

Info

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

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

Edit the following flags in /opt/mellanox/doca/applications/meson_options.txt:
- Set enable_all_applications to false
- Set enable_l2_reflector to true

Run the following compilation commands :

Copy
Copied!

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

Info

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

Troubleshooting

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

Running the Application

Application Execution

The L2 reflector application is provided in source form. Therefore, a compilation is required before the application can be executed.

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

Info

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

Copy
Copied!

            
            ./l2_reflector -h

Info

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

CLI example for running the application on BlueField or host:
Copy

Copied!
```
            
            ./l2_reflector -d mlx5_0
        
```
Note

The used device name (-d flag) must match the identifier of the desired IB device.
Info
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.
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!
```
            
            ./l2_reflector --json ./l2_reflector_params.json
        
```
Note

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

Flag Type	Short Flag	Long Flag/JSON Key	Description	JSON Content
General flags	`h`	`help`	Prints a help synopsis	N/A
	`v`	`version`	Prints program version information	N/A
	`l`	`log-level`	Set the log level for the application: DISABLE=10 CRITICAL=20 ERROR=30 WARNING=40 INFO=50 DEBUG=60 TRACE=70 ( requires compilation with `TRACE` log level support )	Copy Copied! `"log-level": 60`
	N/A	`sdk-log-level`	Sets the log level for the program: DISABLE=10 CRITICAL=20 ERROR=30 WARNING=40 INFO=50 DEBUG=60 TRACE=70	Copy Copied! `"sdk-log-level": 40`
	`j`	`json`	Parse all command flags from an input JSON file	N/A
Program flags	`d`	`device`	Device name	Copy Copied! `"device": mlx5_0`

Info

Refer to DOCA Arg Parser for more information regarding the supported flags and execution modes.

Troubleshooting

Note

DPA L2 reflector works with packets with a specific source MAC address. To check the supported MAC address, refer to /opt/mellanox/doca/applications/l2_reflector/src/host/l2_reflector_core.h.

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

Application Code Flow

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

Parse application argument.

Initialize arg parser resources and register DOCA general parameters.

Copy
Copied!

            
            doca_argp_init();

Register the application's parameters.

Copy
Copied!

            
            register_l2_reflector_params();

Parse the arguments.

Copy
Copied!

            
            doca_argp_start();

Setup the InfiniBand device.

Copy
Copied!

            
            l2_reflector_setup_ibv_device();

Setup the DPA device.

Copy
Copied!

            
            l2_reflector_setup_device();

Allocate the device's resources.

Copy
Copied!

            
            l2_reflector_allocate_device_resources();

R un initialization function on the device.

Copy
Copied!

            
            flexio_process_call();

Create the steering rule.

Copy
Copied!

            
            l2_reflector_create_steering_rule();

Start the event handler on the device.

Copy
Copied!

            
            flexio_event_handler_run();

Main loop.

Copy
Copied!

            
            while (!force_quit)
	sleep(10);

Cleanup the resources.

Copy
Copied!

            
            l2_reflector_destroy();

References

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

On This Page