NVIDIA DOCA UPF Application Guide

This document provides a UPF implementation on top of the NVIDIA® BlueField® DPU.

The User Plane Function (UPF) reference application leverages the DPU's hardware capability to handle data traffic between the mobile network and external data networks..

The UPF application is based on the DOCA Flow API used for the programming of the DPU's hardware.

UPF can operate in two modes:

• Bidirectional (Single Port) Mode - In this operational mode, the application is configured to handle both N6 and N3 traffic through a single port, enabling efficient flow management and streamlined resource utilization. The functionality is as follows:

  • Unified Traffic Reception:

    • All incoming traffic (N6 and N3) is received on Port A.

    • The UPF dynamically identifies the traffic type based on metadata, headers, or other distinguishing characteristics to classify it as either N3 or N6.

• • Traffic Processing:

    • N6 Traffic: traffic identified as N6 is processed accordingly, performing actions such as routing to the external data network (EDN), applying quotas, or enforcing policies.

    • N3 Traffic: traffic identified as N3 is processed for interactions between the RAN and the core network, applying relevant handling, such as user-plane function chaining or QoS enforcement.

  • Unified Traffic Forwarding: both N6 and N3 traffic are forwarded back to Port A, ensuring seamless integration with upstream and downstream network elements while maintaining traffic integrity.

This mode simplifies the network topology by using a single ingress/egress port while maintaining precise control and optimized processing for both N6 and N3 traffic flows.

• Unidirectional (Dual Port) Mode - in this operational mode, the application is designed to handle N6 and N3 traffic in a structured and efficient manner, ensuring proper processing and forwarding based on traffic type. The operational flow is defined as follows:

  • N6 Traffic Handling:

    • Reception: All N6 traffic is received on Port A.

    • Processing: The UPF applies appropriate processing to the N6 traffic, including routing, policy enforcement, quota management, or any other relevant actions based on the traffic characteristics and network configuration.

    • Forwarding: After processing, the UPF forwards the N6 traffic to Port B, enabling connectivity to the external data network (EDN).

  • N3 Traffic Handling:

    • Reception: All N3 traffic is received on Port B.

    • Processing: The UPF processes the N3 traffic, applying actions such as QoS enforcement, user-plane policy application, or routing as per the core network's requirements.

    • Forwarding: After processing, the UPF forwards the N3 traffic to Port A, ensuring proper communication with the Radio Access Network (RAN).

This mode ensures efficient and streamlined traffic processing and forwarding for both N6 and N3 interfaces, enabling robust user-plane functionality with clear traffic flow paths.

The UPF application is designed to efficiently handle and manage traffic while incorporating key features for performance, observability, and resource optimization. The detailed operation and capabilities are as follows:

• Rate Meters: configurable rate meters monitor traffic throughput on N3 and N6 interfaces. These meters ensure that traffic conforms to predefined service-level agreements (SLAs) and prevent overload conditions.

• Quota Meters: per-subscriber quota management is enabled, tracking data usage against assigned limits. Notifications or actions (e.g., throttling or redirecting traffic) can be triggered when quotas are exceeded.

• Flow Aging: a flow aging mechanism efficiently tracks active flows and removes inactive ones based on configurable timeouts, ensuring resource efficiency and preventing stale flow accumulation.

• Mimic DPI (Deep Packet Inspection): lightweight DPI capabilities mimic traditional DPI by analyzing packet headers and application metadata to identify and classify flows. This allows basic traffic categorization without the computational overhead of full DPI.

• Debuggability and Telemetry:

  • Real-time debug tools provide visibility into flow-level and packet-level operations.

  • Telemetry includes detailed metrics such as packet counts and dropped packets statistics for both N3 and N6 traffic.

• Shared Resource Management for Flows: N3 and N6 flows share the same underlying resource pool. Dynamic allocation mechanisms optimize resources based on traffic demands, ensuring low-latency processing and high throughput across all interfaces.

These advanced features ensures the UPF is capable of meeting modern network demands with high efficiency, robust observability, and optimal resource management for N3 and N6 flows.

The UPF application client runs on the host and manages offloading conditions on the DPU.

This UPF application architecture leverages DOCA Flow to efficiently manage N3 and N6 traffic by offloading flow processing to the DPU. The architecture is designed to optimize performance, reduce CPU utilization, and maintain dynamic flow management with inactive flow removal.

Key Features

• DOCA Flow Framework:

  • Acts as the foundational API for the application, enabling direct interaction with the DPU.

  • Facilitates high-performance packet processing, flow steering, and offload operations.

• Traffic Management Logic:

  • N3 Traffic:

    • Received from the RAN and processed for interaction with the core network.

    • Managed via DOCA Flow to offload user-plane traffic to the DPU for low-latency forwarding.

  • N6 Traffic:

    • Received from external data networks (EDN) and processed for delivery to the RAN or other destinations.

    • Offloaded to the DPU for efficient handling.

• Flow Management Module:

  • Flow Offloading:

    • New flows are identified by the UPF application and offloaded to the DPU via DOCA Flow APIs.

    • The DPU handles packet forwarding, flow-specific actions (e.g., QoS), and telemetry collection.

  • Flow Aging and Removal:

    • Inactive flows are monitored using timeouts and telemetry feedback.

    • Flows that exceed their inactivity threshold are automatically removed from the DPU, freeing resources.

• Control Plane Integration:

  • Interfaces with the control plane to receive policies, QoS configurations, and subscriber data for N3 and N6 flows.

  • Implements rules dynamically to manage flow-specific behaviors (e.g., rate limiting, quotas).

• Telemetry and Debugging:

  • Real-time telemetry is collected from the DPU for metrics such as packet counts, flow states, and latency.

  • Provides debug tools to trace and analyze flow behavior, ensuring high observability

SMF

The Session Management Function (SMF) is a crucial component of the 5G core network architecture. It is responsible for managing user sessions, including establishing, modifying, and terminating data sessions between user equipment (UE) and the data network.

The UPF application supports static SMF policies provided by a JSON file. An example configuration can be found in the application's directory. The UPF application supports the following fields:

PDR

FAR

URR

QER

This application leverages the following DOCA libraries:

• DOCA Flow - Programming Guide

For additional information about the used DOCA libraries, please refer to the respective programming guides.

• NVIDIA BlueField-3 DPU is required.

• Ubuntu 18.04/20.04/22.04 hosts (x86)

• Open MPI version 4.1.5rc2 or greater (included in DOCA's installation)

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.

The sources of the application can be found under the application's directory: /opt/mellanox/doca/applications/file_compression/.

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:

            

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

Compiling Only the Current Application

1. To directly build only the file compression application: (REPLACE WITH FLAG FOR YOUR APP)

   Copy

   Copied!

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

   Info

   doca_file_compression is created under /tmp/build/file_compression/.

2. 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_file_compression to true

   2. The same compilation commands should be used, as were shown in the previous section:

      Copy

      Copied!

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

      Info

      doca_file_compression is created under /tmp/build/file_compression/.

Troubleshooting

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

Prerequisites

<huge pages and stuff are declared here>

1. The IPsec security gateway application is based on DOCA Flow. Therefore, the user is required to allocate huge pages.

   Copy

   Copied!

               
   
               
   $ echo '1024' | sudo tee -a /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
   $ sudo mkdir /mnt/huge
   $ sudo mount -t hugetlbfs -o pagesize=2M nodev /mnt/huge
           

Application Execution

The file compression application is provided in source form, hence a compilation is required before the application can be executed.

1. Application usage instructions (REPLACE WITH REAL HELP AS PRINTED FROM YOUR APP) :

   Copy

   Copied!

               
   
               
   Usage: doca_file_compression [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:
     -p, --pci-addr                    DOCA Comm Channel device PCI address
     -r, --rep-pci                     DOCA Comm Channel device representor PCI address
     -f, --file                        File to send by the client / File to write by the server
     -t, --timeout                     Application timeout for receiving file content messages, default is 5 sec
           

   For additional information, please refer to the Command Line Flags section below.

   Note

   The above usage printout can be printed to the command line using the -h (or --help) options: (REPLACE WITH REAL PATH OF YOUR APP)

   Copy

   Copied!

               
   
               
   ./doca_file_compression -h
           

2. CLI example for running the application on BlueField: (REPLACE WITH REAL PATH & COMMAND OF YOUR APP)

   Copy

   Copied!

               
   
               
   ./doca_file_compression -p 03:00.0 -r 3b:00.0 -f received.txt
           

   Note

   Both the DOCA Comm Channel device PCI address (03:00.0) and the DOCA Comm Channel device representor PCI address (3b:00.0) should match the addresses of the desired PCI devices.

3. CLI example for running the application on the host: (REPLACE WITH REAL PATH & COMMAND OF YOUR APP)

   Copy

   Copied!

               
   
               
   ./doca_file_compression -p 3b:00.0 -f send.txt
           

   Note

   The DOCA Comm Channel device PCI address (3b:00.0) should match the address of the desired PCI device.

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

   Copy

   Copied!

               
   
               
   ./doca_file_compression --json [json_file]
           

   For example: (REPLACE WITH REAL PATH & COMMAND OF YOUR APP)

   Copy

   Copied!

               
   
               
   ./doca_file_compression --json ./file_compression_params.json
           

   Note

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

Command Line Flags

            

            
"log-level": 60
        

            

            
"sdk-log-level": 40
        

            

            
"file": "/tmp/data.txt"
        

            

            
"pci-addr": 03:00.1 
        

            

            
"rep-pci": b1:00.1 
        

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

Troubleshooting

Please refer to the NVIDIA DOCA Troubleshooting for any issue you may encounter with the installation or execution of the DOCA applications.

1. Parse application argument.

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

      Copy

      Copied!

                  
      
                  
      doca_argp_init();
              

   2. Register file compression application parameters.

      Copy

      Copied!

                  
      
                  
      register_file_compression_params();
              

   3. Parse the arguments.

      Copy

      Copied!

                  
      
                  
      doca_argp_start();
              

      1. Parse app parameters.

2. Set endpoint attributes.

   Copy

   Copied!

               
   
               
   set_endpoint_properties();
           

   1. Set maximum message size of 4080 bytes.

   2. Set maximum number of messages allowed.

3. Create comm channel endpoint.

   Copy

   Copied!

               
   
               
   doca_comm_channel_ep_create();
           

   1. Create endpoint for client/server.

4. Run client/server main logic.

   Copy

   Copied!

               
   
               
   file_compression_client/server();
           

5. Clean up the file compression application.

   Copy

   Copied!

               
   
               
   file_compression_cleanup();
           

   1. Free all application resources.

6. Arg parser destroy.

   Copy

   Copied!

               
   
               
   doca_argp_destroy()
           

• /opt/mellanox/doca/applications/file_compression/

• /opt/mellanox/doca/applications/file_compression/file_compression_params.json