NVIDIA DOCA Installation Guide for Linux
This guide details the necessary steps to set up NVIDIA DOCA in your Linux environment.
Installation of the NVIDIA® BlueField® DPU software requires following the following step-by-step procedure.
Supported Platforms
Supported BlueField DPUs
The following NVIDIA® BlueField® DPUs are supported with DOCA:
NVIDIA SKU |
Legacy OPN |
PSID |
Description |
900-9D3B6-00CV-AA0 |
N/A |
MT_0000000884 |
BlueField-3 B3220 P-Series FHHL DPU; 200GbE (default mode) / NDR200 IB; Dual-port QSFP112; PCIe Gen5.0 x16 with x16 PCIe extension option; 16 Arm cores; 32GB on-board DDR; integrated BMC; Crypto Enabled |
900-9D3B6-00SV-AA0 |
N/A |
MT_0000000965 |
BlueField-3 B3220 P-Series FHHL DPU; 200GbE (default mode) / NDR200 IB; Dual-port QSFP112; PCIe Gen5.0 x16 with x16 PCIe extension option; 16 Arm cores; 32GB on-board DDR; integrated BMC; Crypto Disabled |
900-9D3B6-00CC-AA0 |
N/A |
MT_0000001024 |
BlueField-3 B3210 P-Series FHHL DPU; 100GbE (default mode) / HDR100 IB; Dual-port QSFP112; PCIe Gen5.0 x16 with x16 PCIe extension option; 16 Arm cores; 32GB on-board DDR; integrated BMC; Crypto Enabled |
900-9D3B6-00SC-AA0 |
N/A |
MT_0000001025 |
BlueField-3 B3210 P-Series FHHL DPU; 100GbE (default mode) / HDR100 IB; Dual-port QSFP112; PCIe Gen5.0 x16 with x16 PCIe extension option; 16 Arm cores; 32GB on-board DDR; integrated BMC; Crypto Disabled |
900-9D219-0086-ST1 |
MBF2M516A-CECOT |
MT_0000000375 |
BlueField-2 E-Series DPU 100GbE Dual-Port QSFP56; PCIe Gen4 x16; Crypto and Secure Boot Enabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D219-0086-ST0 |
MBF2M516A-EECOT |
MT_0000000376 |
BlueField-2 E-Series DPU 100GbE/EDR/HDR100 VPI Dual-Port QSFP56; PCIe Gen4 x16; Crypto and Secure Boot Enabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D219-0056-ST1 |
MBF2M516A-EENOT |
MT_0000000377 |
BlueField-2 E-Series DPU 100GbE/EDR/HDR100 VPI Dual-Port QSFP56; PCIe Gen4 x16; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D206-0053-SQ0 |
MBF2H332A-AENOT |
MT_0000000539 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; PCIe Gen4 x8; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; HHHL |
900-9D206-0063-ST2 |
MBF2H332A-AEEOT |
MT_0000000540 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; PCIe Gen4 x8; Crypto Enabled; 16GB on-board DDR; 1GbE OOB management; HHHL |
900-9D206-0083-ST3 |
MBF2H332A-AECOT |
MT_0000000541 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; PCIe Gen4 x8; Crypto and Secure Boot Enabled; 16GB on-board DDR; 1GbE OOB management; HHHL |
900-9D206-0083-ST1 |
MBF2H322A-AECOT |
MT_0000000542 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; PCIe Gen4 x8; Crypto and Secure Boot Enabled; 8GB on-board DDR; 1GbE OOB management; HHHL |
900-9D206-0063-ST1 |
MBF2H322A-AEEOT |
MT_0000000543 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; PCIe Gen4 x8; Crypto Enabled; 8GB on-board DDR; 1GbE OOB management; HHHL |
900-9D219-0066-ST0 |
MBF2M516A-EEEOT |
MT_0000000559 |
BlueField-2 E-Series DPU 100GbE/EDR/HDR100 VPI Dual-Port QSFP56; PCIe Gen4 x16; Crypto Enabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D219-0056-SN1 |
MBF2M516A-CENOT |
MT_0000000560 |
BlueField-2 E-Series DPU 100GbE Dual-Port QSFP56; PCIe Gen4 x16; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D219-0066-ST2 |
MBF2M516A-CEEOT |
MT_0000000561 |
BlueField-2 E-Series DPU 100GbE Dual-Port QSFP56; PCIe Gen4 x16; Crypto Enabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D219-0006-ST0 |
MBF2H516A-CEEOT |
MT_0000000702 |
BlueField-2 DPU 100GbE Dual-Port QSFP56; PCIe Gen4 x16; Crypto; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D219-0056-ST2 |
MBF2H516A-CENOT |
MT_0000000703 |
BlueField-2 DPU 100GbE Dual-Port QSFP56; PCIe Gen4 x16; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D219-0066-ST3 |
MBF2H516A-EEEOT |
MT_0000000704 |
BlueField-2 DPU 100GbE/EDR/HDR100 VPI Dual-Port QSFP56; PCIe Gen4 x16; Crypto Enabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D219-0056-SQ0 |
MBF2H516A-EENOT |
MT_0000000705 |
BlueField-2 DPU 100GbE/EDR/HDR100 VPI Dual-Port QSFP56; PCIe Gen4 x16; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D250-0038-ST1 |
MBF2M345A-HESOT |
MT_0000000715 |
BlueField-2 E-Series DPU; 200GbE/HDR single-port QSFP56; PCIe Gen4 x16; Secure Boot Enabled; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; HHHL |
900-9D250-0048-ST1 |
MBF2M345A-HECOT |
MT_0000000716 |
BlueField-2 E-Series DPU; 200GbE/HDR single-port QSFP56; PCIe Gen4 x16; Secure Boot Enabled; Crypto Enabled; 16GB on-board DDR; 1GbE OOB management; HHHL |
900-9D218-0073-ST1 |
MBF2H512C-AESOT |
MT_0000000723 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; integrated BMC; PCIe Gen4 x8; Secure Boot Enabled; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D218-0083-ST2 |
MBF2H512C-AECOT |
MT_0000000724 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; integrated BMC; PCIe Gen4 x8; Secure Boot Enabled; Crypto Enabled; 16GB on-board DDR; 1GbE OOB management; FHHL |
900-9D208-0086-ST4 |
MBF2M516C-EECOT |
MT_0000000728 |
BlueField-2 E-Series DPU 100GbE/EDR/HDR100 VPI Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled; Crypto Enabled; 16GB on-board DDR; 1GbE OOB management; Tall Bracket; FHHL |
900-9D208-0086-SQ0 |
MBF2H516C-CECOT |
MT_0000000729 |
BlueField-2 P-Series DPU 100GbE Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled; Crypto Enabled; 16GB on-board DDR; 1GbE OOB management; Tall Bracket; FHHL |
900-9D208-0076-ST5 |
MBF2M516C-CESOT |
MT_0000000731 |
BlueField-2 E-Series DPU 100GbE Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; Tall Bracket; FHHL |
900-9D208-0076-ST6 |
MBF2M516C-EESOT |
MT_0000000732 |
BlueField-2 E-Series DPU 100GbE/EDR/HDR100 VPI Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; Tall Bracket; FHHL |
900-9D208-0086-ST3 |
MBF2M516C-CECOT |
MT_0000000733 |
BlueField-2 E-Series DPU 100GbE Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled; Crypto Enabled; 16GB on-board DDR; 1GbE OOB management; Tall Bracket; FHHL |
900-9D208-0076-ST2 |
MBF2H516C-EESOT |
MT_0000000737 |
BlueField-2 P-Series DPU 100GbE/EDR/HDR100 VPI Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; Tall Bracket; FHHL |
900-9D208-0076-ST1 |
MBF2H516C-CESOT |
MT_0000000738 |
BlueField-2 P-Series DPU 100GbE Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management; Tall Bracket; FHHL |
900-9D218-0083-ST4 |
MBF2H532C-AECOT |
MT_0000000765 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; integrated BMC; PCIe Gen4 x8; Secure Boot Enabled; Crypto Enabled; 32GB on-board DDR; 1GbE OOB management; FHHL |
900-9D218-0073-ST0 |
MBF2H532C-AESOT |
MT_0000000766 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; integrated BMC; PCIe Gen4 x8; Secure Boot Enabled; Crypto Disabled; 32GB on-board DDR; 1GbE OOB management; FHHL |
900-9D208-0076-ST3 |
MBF2H536C-CESOT |
MT_0000000767 |
BlueField-2 P-Series DPU 100GbE Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled; Crypto Disabled; 32GB on-board DDR; 1GbE OOB management; FHHL |
900-9D208-0086-ST2 |
MBF2H536C-CECOT |
MT_0000000768 |
BlueField-2 P-Series DPU 100GbE Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled; Crypto Enabled; 32GB on-board DDR; 1GbE OOB management; FHHL |
900-9D218-0073-ST4 |
MBF2H512C-AEUOT |
MT_0000000972 |
BlueField-2 P-Series DPU 25GbE Dual-Port SFP56; integrated BMC; PCIe Gen4 x8; Secure Boot Enabled with UEFI disabled; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management |
900-9D208-0076-STA |
MBF2H516C-CEUOT |
MT_0000000973 |
BlueField-2 P-Series DPU 100GbE Dual-Port QSFP56; integrated BMC; PCIe Gen4 x16; Secure Boot Enabled with UEFI disabled; Crypto Disabled; 16GB on-board DDR; 1GbE OOB management |
900-9D208-0076-STB |
MBF2H536C-CEUOT |
MT_0000001008 |
BlueField-2 P-Series DPU 100GbE Dual-Port QSFP56, integrated BMC, PCIe Gen4 x16, Secure Boot Enabled with UEFI Disabled, Crypto Disabled, 32GB on-board DDR, 1GbE OOB management, Tall Bracket, FHHL |
P1004/699210040230 |
N/A |
NVD0000000015 |
BlueField-2 A30X, P1004 SKU 205, Generic, GA100, 24GB HBM2e, PCIe passive Dual Slot 230W GEN4, DPU Crypto ON W/ Bkt, 1 Dongle, Black, HF, VCPD |
P4028/699140280000 |
N/A |
NVD0000000020 |
ZAM / NAS |
Supported ConnectX NICs
The following NVIDIA® ConnectX® NICs are supported with DOCA on the host:
Hardware Prerequisites
This quick start guide assumes that an NVIDIA® BlueField® DPU has been installed in a server according to the instructions detailed in your DPU's hardware user guide .
DOCA Packages
Device |
Component |
Version |
Description |
Host |
DOCA SDK |
2.5.1 |
Software development kit package for developing host software |
DOCA Runtime |
2.5.1 |
Runtime libraries required to run DOCA-based software applications on host |
|
DOCA Tools |
2.5.1 |
Tools for developers and administrators on host |
|
DOCA Extra |
2.5.1 |
Contains helper scripts (doca-info, doca-kernel-support) |
|
DOCA OFED |
2.5.1 |
Software stack which operates across all NVIDIA network adapter solutions |
|
Arm emulated (QEMU) development container |
4.5.1 |
Linux-based BlueField Arm emulated container for developers |
|
Target BlueField DPU (Arm) |
BlueField BSP |
4.5.1 |
BlueField image and firmware |
DOCA SDK |
2.5.1 |
Software development kit packages for developing Arm software |
|
DOCA Runtime |
2.5.1 |
Runtime libraries required to run DOCA-based software applications on Arm |
|
DOCA Tools |
2.5.1 |
Tools for developers and administrators for Arm target |
Supported Operating System Distributions
Supported Operating System Distributions - January 31, 2024 and later
Supported Operating System Distributions - December 12, 2023 and later
Supported Operating System Distributions - February 29, 2024 and later
This guide provides the minimal instructions for setting up DOCA on a standard system.
Installation Files
Uninstalling Software from Host
If an older DOCA software version is installed on your host, make sure to uninstall it before proceeding with the installation of the new version:
Ubuntu/Debian |
|
CentOS/RHEL/Rocky |
|
Then perform the following steps:
Download NVIDIA's RPM-GPG-KEY-Mellanox-SHA256 key:
# wget http://www.mellanox.com/downloads/ofed/RPM-GPG-KEY-Mellanox-SHA256 --2018-01-25 13:52:30-- http://www.mellanox.com/downloads/ofed/RPM-GPG-KEY-Mellanox-SHA256 Resolving www.mellanox.com... 72.3.194.0 Connecting to www.mellanox.com|72.3.194.0|:80... connected. HTTP request sent, awaiting response... 200 OK Length: 1354 (1.3K) [text/plain] Saving to: ?RPM-GPG-KEY-Mellanox-SHA256? 100%[=================================================>] 1,354 --.-K/s in 0s 2018-01-25 13:52:30 (247 MB/s) - ?RPM-GPG-KEY-Mellanox-SHA256? saved [1354/1354]
Install the key:
# sudo rpm --import RPM-GPG-KEY-Mellanox-SHA256 warning: rpmts_HdrFromFdno: Header V3 DSA/SHA1 Signature, key ID 6224c050: NOKEY Retrieving key from file:///repos/MLNX_OFED//RPM-GPG-KEY-Mellanox Importing GPG key 0x6224C050: Userid: "Mellanox Technologies (Mellanox Technologies - Signing Key v2) " From : /repos/MLNX_OFED//RPM-GPG-KEY-Mellanox-SHA256 Is this ok [y/N]:
Verify that the key was successfully imported:
# rpm -q gpg-pubkey --qf '%{NAME}-%{VERSION}-%{RELEASE}\t%{SUMMARY}\n' | grep Mellanox gpg-pubkey-a9e4b643-520791ba gpg(Mellanox Technologies )
Installing Prerequisites on Host for Target DPU
Install doca-tools to manage and flash the BlueField DPU.
OS |
Procedure |
Ubuntu/Debian |
|
CentOS/RHEL 7.x |
|
CentOS/RHEL 8.x or Rocky 8.6 |
|
Skip section "Installing Software on Host" to proceed without the DOCA local repo package for host.
Determining DPU Device ID
It is is important to learn your DPU's device-id for performing some of the software installations or upgrades in this guide.
To determine the device ID of the DPUs on your setup, run:
host# mst start
host# mst status -v
Example output:
MST modules:
------------
MST PCI module is not loaded
MST PCI configuration module loaded
PCI devices:
------------
DEVICE_TYPE MST PCI RDMA NET NUMA
BlueField2(rev:1
) /dev/mst/mt41686_pciconf0.1
3b:00.1
mlx5_1 net-ens1f1 0
BlueField2(rev:1
) /dev/mst/mt41686_pciconf0 3b:00.0
mlx5_0 net-ens1f0 0
BlueField3(rev:1
) /dev/mst/mt41692_pciconf0.1
e2:00.1
mlx5_1 net-ens7f1np1 4
BlueField3(rev:1
) /dev/mst/mt41692_pciconf0 e2:00.0
mlx5_0 net-ens7f0np0 4
The device IDs for the BlueField-2 and BlueField-3 DPUs in this example are /dev/mst/mt41686_pciconf0 and /dev/mst/mt41692_pciconf0 respectively.
Installing Software on Host
Skip this section if you intend to update only the BlueField software (*.bfb).
- Follow the instructions under "Installing Prerequisites on Host for Target DPU".
Install DOCA local repo package for host:
NoteThe following table provides instructions for installing the DOCA host repo on your device depending on your OS and desired profile.
OS
Profile
Device
Instructions
Ubuntu/
Debiandoca-all
BlueField
Download the DOCA SDK and DOCA Runtime packages from section "Installation Files" for the host.
Unpack the deb repo. Run:
host# dpkg -i <repo_file>
Perform apt update. Run:
host# apt-get update
If the kernel version on your host is not supported (not shown under "Supported Operating System Distributions"), refer to section "DOCA Extra Package".
Run apt install for DOCA SDK, DOCA runtime, DOCA tools:
host# sudo apt install -y doca-runtime doca-sdk doca-tools
doca-cx
ConnectX
Download the DOCA SDK and DOCA Runtime packages from section "Installation Files" for the host.
Unpack the deb repo. Run:
host# dpkg -i <repo_file>
Perform apt update. Run:
host# apt-get update
If the kernel version on your host is not supported (not shown under "Supported Operating System Distributions"), refer to section "DOCA Extra Package".
Run apt install for DOCA SDK, DOCA runtime, DOCA tools:
host# sudo apt install -y doca-cx-runtime doca-cx-sdk doca-cx-tools
doca-ofed
All
Download the DOCA SDK and DOCA Runtime packages from section "Installation Files" for the host.
Unpack the deb repo. Run:
host# sudo dpkg -i doca-host-repo-ubuntu<version>_amd64.deb
Perform apt update. Run:
host# sudo apt-get update
If the kernel version on your host is not supported (not shown under "Supported Operating System Distributions"), refer to section "DOCA Extra Package".
Install doca-ofed. Run:
host# sudo apt install -y doca-ofed
CentOS/RHEL/
Alinux/Rocky/Oracle Linuxdoca-all
BlueField
WarningRHEL users need a valid subscription to install packages. See "HowTo Open RedHat Account".
Install the following software dependencies. Run:
For RH 8.x, run:
host# yum -y install https:
//dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
For Alinux 3.x (Alibaba Cloud Linux), run:
host# yum -y install https:
//dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
For Rocky 8.x, run:
host# sudo dnf makecache host# sudo dnf install epel-release host# sudo dnf install -y yum-utils host# sudo dnf config-manager --enable PowerTools host# sudo dnf clean dbcache
For CentOS 8.x, run:
host# sudo dnf install epel-release host# sudo dnf config-manager --set-enabled PowerTools
For CentOS 7.x, run:
host# sudo yum install -y https:
//dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
host# sudo yum-config-manager --add-repo http://mirror.centos.org/centos/7/os/x86_64
host# sudo rpm --import
http://mirror.centos.org/centos/7/os/x86_64/RPM-GPG-KEY-CentOS-7
host# sudo yum-config-manager --add-repo http://mirror.centos.org/centos/7/extras/x86_64
host# sudo yum-config-manager --save --setopt=mirror.centos.org_centos_7_os_x86_64.exclude='pciutils* libnl3*'
host# yum makecache
Download the DOCA SDK and DOCA Runtime packages from section "Installation Files" for the host .
Unpack the rpm repo. Run:
host# rpm -Uvh <repo_file>.rpm
Perform yum update. Run:
host# sudo yum makecache
If the kernel version on your host is not supported (not shown under "Supported Operating System Distributions"), refer to section "DOCA Extra Package".
Run yum install for DOCA SDK, DOCA runtime, DOCA tools:
host# sudo yum install -y doca-runtime doca-sdk doca-tools
doca-cx
ConnectX
Install the following software dependencies. Run:
For RH 8.x, run:
host# yum -y install https:
//dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
For Alinux 3.x (Alibaba Cloud Linux), run:
host# yum -y install https:
//dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
For Rocky 8.x, run:
host# sudo dnf makecache host# sudo dnf install epel-release host# sudo dnf install -y yum-utils host# sudo dnf config-manager --enable PowerTools host# sudo dnf clean dbcache
For CentOS 8.x, run:
host# sudo dnf install epel-release host# sudo dnf config-manager --set-enabled PowerTools
For CentOS 7.x, run:
host# sudo yum install -y https:
//dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
host# sudo yum-config-manager --add-repo http://mirror.centos.org/centos/7/os/x86_64
host# sudo rpm --import
http://mirror.centos.org/centos/7/os/x86_64/RPM-GPG-KEY-CentOS-7
host# sudo yum-config-manager --add-repo http://mirror.centos.org/centos/7/extras/x86_64
host# sudo yum-config-manager --save --setopt=mirror.centos.org_centos_7_os_x86_64.exclude='pciutils* libnl3*'
host# yum makecacheFor Oracle Linux 8.7, run:
host# yum config-manager --set-enabled ol8_codeready_builder
Download the DOCA SDK and DOCA Runtime packages from section "Installation Files" for the host .
Unpack the rpm repo. Run:
host# rpm -Uvh <repo_file>.rpm
Perform yum update. Run:
host# sudo yum makecache
If the kernel version on your host is not supported (not shown under "Supported Operating System Distributions"), refer to section "DOCA Extra Package".
Run yum install for DOCA SDK, DOCA runtime, DOCA tools:
host# sudo yum install -y doca-cx-runtime doca-cx-sdk doca-cx-tools
doca-ofed
All
Download the DOCA SDK and DOCA Runtime packages from section "Installation Files" for the host.
Unpack the RPM repo. Run:
host# sudo rpm -Uvh doca-host-repo-rhel<version>.x86_64.rpm
Install doca-extra. Run:
host# sudo yum/dnf install -y doca-extra
If the kernel version on your host is not supported (not shown under "Supported Operating System Distributions"), refer to section "DOCA Extra Package".
Install doca-ofed. Run:
host# sudo yum install -y doca-ofed
Initialize MST. Run:
host# sudo mst start
Reset the nvconfig parameters to their default values:
host# sudo mlxconfig -d <device-id> -y reset Reset configuration
for
device <device-id>? (y/n) [n] : y Applying... Done! -I- Please reboot machine to loadnew
configurations.WarningTo learn the DPU's device ID, refer to section "Determining DPU Device ID".
Skip this step if your BlueField DPU is Ethernet only. Please refer to Supported Platforms to learn your DPU type.
If you have a VPI DPU, the default link type of the ports will be configured to IB. To verify your link type, run:
host# sudo mst start host# sudo mlxconfig -d <device-id> -e q | grep -i link_type Configurations: Default Current Next Boot * LINK_TYPE_P1 IB(
1
) ETH(2
) IB(1
) * LINK_TYPE_P2 IB(1
) ETH(2
) IB(1
)WarningIf your DPU is Ethernet capable only, then the sudo mlxconfig -d <device> command will not provide an output.
If the current link type is set to IB, run the following command to change it to Ethernet:
host# sudo mlxconfig -d <device-id> s LINK_TYPE_P1=
2
LINK_TYPE_P2=2
Verify that RShim is active.
host# sudo systemctl status rshim
This command is expected to display active (running). If RShim service does not launch automatically, run:
host# sudo systemctl enable rshim host# sudo systemctl start rshim
Assign a dynamic IP to tmfifo_net0 interface (RShim host interface).
WarningSkip this step if you are installing the DOCA image on multiple DPUs.
host# ifconfig tmfifo_net0
192.168
.100.1
netmask255.255
.255.252
up
DOCA Extra Package
If the kernel version on on your host is not supported (not shown under "Supported Operating System Distributions"), two options are available:
- Switch to a compatible kernel.
Install doca-extra package:
Run:
host# sudo apt install -y doca-tools doca-extra
Execute the doca-kernel-support script which downloads the appropriate missing packages from your kernel to support DOCA:
host# sudo /opt/mellanox/doca/tools/doca-kernel-support
Warningdoca-kernel-support does not support customized or unofficial kernels.
Installing Software on DPU
Users have two options for installing DOCA on the DPU:
- Upgrading the full DOCA image on the DPU (recommended) – this option overwrites the entire boot partition
- Upgrading DOCA local repo package on the DPU – this option upgrades DOCA components without overwriting the boot partition. Use this option to preserve configurations or files on the DPU itself.
Installing Full DOCA Image on DPU via Host
This step overwrites the entire boot partition.
This installation sets up the OVS bridge.
If you are installing DOCA on multiple DPUs, skip to section Installing Full DOCA Image on Multiple DPUs.
Option 1 – No Pre-defined Password
To set the password in advance, proceed to Option 2.
BFB installation is executed as follows:
host# sudo bfb-install --rshim <rshimN> --bfb <image_path.bfb>
Where rshimN is rshim0 if you only have one DPU. You may run the following command to verify:
host# ls -la /dev/ | grep rshim
Option 2 – Set Pre-defined Password
Ubuntu users can provide a unique password that will be applied at the end of the BlueField software image installation. This password needs to be defined in a bf.cfg configuration file.
To set the password for the "ubuntu" user:
Create password hash. Run:
host# openssl passwd -
1
Password: Verifying - Password: $1
$3B0RIrfX$TlHry93NFUJzg3Nya00rE1Add the password hash in quotes to the bf.cfg file:
host# sudo vim bf.cfg ubuntu_PASSWORD=
'$1$3B0RIrfX$TlHry93NFUJzg3Nya00rE1'
When running the installation command, use the --config flag to provide the file containing the password:
host# sudo bfb-install --rshim <rshimN> --bfb <image_path.bfb> --config bf.cfg
WarningIf --config is not used, then upon first login to the BlueField device, users will be asked to update their password.
The following is an example of Ubuntu installation assuming the pv Linux tool has been installed (to view the installation progress).
host# sudo bfb-install --rshim rshim0 --bfb DOCA_<version>-aarch64.bfb --config bf.cfg Pushing bfb
1
.08GiB0
:00
:57
[19
.5MiB/s] [ <=> ] Collecting BlueField booting status. Press Ctrl+C to stop… INFO[BL2]: start INFO[BL2]: DDR POST passed INFO[BL2]: UEFI loaded INFO[BL31]: start INFO[BL31]: runtime INFO[UEFI]: eMMC init INFO[UEFI]: eMMC probed INFO[UEFI]: PCIeenum
start INFO[UEFI]: PCIeenum
end INFO[MISC]: Ubuntu installation started INFO[MISC]: Installation finished INFO[MISC]: Rebooting...
Installing Full DOCA Image on Multiple DPUs
On a host with multiple DPUs, the BFB image can be installed on all of them using the multi-bfb-install script.
host# ./multi-bfb-install --bfb <bfb-file> --password <password>
This script detects the number of RShim devices and configures them statically.
- For Ubuntu – the script creates a configuration file /etc/netplan/20-tmfifo.yaml
- For CentOS/RH 7.6 – the script creates a configuration file /etc/sysconfig/network-scripts/ifcfg-br_tmfifo
- For CentOS/RH 8.0 and 8.2 – the script installs the bridge-utils package to use the brctl command, creates the tm-br bridge, and connects all RShim interfaces to it
After the installation is complete, the configuration of the bridge and each RShim interface can be observed using ifconfig. The expected result is to see the IP on the tm-br bridge configured to 192.168.100.1 with subnet 255.255.255.0.
To log into BlueField with rshim0, run:
ssh ubuntu@192
.168.100.2
For each RShim after that, add 1 to the fourth octet of the IP address (e.g., ubuntu@192.168.100.3 for rshim1, ubuntu@192.168.100.4 for rshim2, etc).
The script burns a new MAC address to each DPU and configures a new IP, 192.168.100.x, as described earlier.
Installing DOCA Local Repo Package on DPU
If you have already installed BlueField image, be aware that the DOCA SDK, Runtime, and Tools are already contained in the BFB, and this installation is not mandatory. If you have not installed the BlueField image and wish to update DOCA Local Repo package, proceed with the following procedure.
Before installing DOCA on the target DPU, make sure the out-of-band interface (mgmt) is connected to the internet.
- Download the DOCA SDK, DOCA Runtime, and DOCA Tools package from section Installation Files.
Copy deb repo package into BlueField. Run:
host# sudo scp -r doca-repo-aarch64-ubuntu2204-local_<version>_arm64.deb ubuntu
@192
.168.100.2
:/tmp/Unpack the deb repo. Run:
dpu# sudo dpkg -i doca-dpu-repo-ubuntu2204-local_<version>_arm64.deb
Run apt update.
dpu# sudo apt-get update
Run apt install for DOCA Runtime, DOCA Tools, and DOCA SDK:
dpu# sudo apt install doca-runtime dpu# sudo apt install doca-tools dpu# sudo apt install doca-sdk
Upgrading Firmware
If multiple DPUs are installed, the following steps must be performed on all of them after BFB installation.
To upgrade firmware:
SSH to your BlueField device via 192.168.100.2 (preconfigured).
WarningIf multiple DPUs are installed, the tmfifo IP interface does not have to be 192.168.100.2. The last octate changes and depends on the RShim number.
The default credentials for Ubuntu are as follows:
Username
Password
ubuntu
ubuntu or a unique password that you set in bf.cfg
For example:
host# ssh ubuntu
@192
.168.100.2
Password: <configured-password>Upgrade firmware in BlueField DPU. Run:
dpu# sudo /opt/mellanox/mlnx-fw-updater/mlnx_fw_updater.pl --force-fw-update
Example output:
Device #
1
: ---------- Device Type: BlueField-2
[...] Versions: Current Available FW <Old_FW> <New_FW>For the firmware upgrade to take effect:
Run the following command on the BlueField DPU and host:
dpu# sudo mst start
Otherwise, trigger reset by running the following:
dpu# sudo mlxfwreset -d /dev/mst/mt41686_pciconf0 --sync 1 -y reset
If the mlxfwreset command fails, perform a graceful reboot and host power cycle.
WarningThe entire DPU will experience reset.
Post-installation Procedure
Restart the driver. Run:
host# sudo /etc/init.d/openibd restart Unloading HCA driver: [ OK ] Loading HCA driver and Access Layer: [ OK ]
Configure the physical function (PF) interfaces.
host# sudo ifconfig <
interface
-1
> <network-1
/mask> up host# sudo ifconfig <interface
-2
> <network-2
/mask> upFor example:
host# sudo ifconfig p2p1
192.168
.200.32
/24
up host# sudo ifconfig p2p2192.168
.201.32
/24
upPings between the source and destination should now be operational.
This dpu-upgrade procedure enables upgrading DOCA components using standard Linux tools (e.g., apt update and yum update). This process utilizes native package manager repositories to upgrade DPUs without the need for a full installation, and has the following benefits :
Only updates components that include modifications
Configurable – user can select specific components (e.g., UEFI-ATF, NIC-FW)
Includes upgrade of:
DOCA drivers and libraries
DOCA reference applications
BSP (UEFI/ATF) upgrade while maintaining the configuration
NIC firmware upgrade while maintaining the configuration
Does not:
Impact user binaries
Upgrade non-Ubuntu OS kernels
Upgrade DPU BMC firmware
After completion of DPU upgrade:
If NIC firmware was not updated, perform DPU Arm reset (software reset / reboot DPU)
If NIC firmware was updated, perform firmware reset (mlxfwreset) or perform a graceful shutdown and power cycle
OS |
Action |
Instructions |
Ubuntu/ Debian |
Remove mlxbf-bootimages package |
|
Install the the GPG key |
|
|
Export the desired distribution |
Export DOCA_REPO with the relevant URL. The following is an example for Ubuntu 22.04:
|
|
Add GPG key to APT trusted keyring |
|
|
Add DOCA online repository |
|
|
Update index |
|
|
Upgrade UEFI/ATF firmware |
Run:
Then i nitiate upgrade for UEFI/ATF firmware:
|
|
Upgrade BlueField DPU NIC firmware |
Run:
Warning
This immediately starts NIC firmware upgrade.
To prevent automatic upgrade, run:
|
|
Upgrade system |
|
|
Apply the new changes, NIC firmware, and UEFI/ATF |
Warning
If mlxfwreset is not supported, graceful shutdown and host power cycle are required for the NIC firmware upgrade to take effect. |
|
CentOS/RHEL/ Anolis/Rocky |
Remove mlxbf-bootimages, librerswan, and openvswitch-ipsec packages |
|
Export the desired distribution |
Export DOCA_REPO with the relevant URL. The following is an example for Rocky Linux 8.6:
|
|
Add DOCA online repository |
A file is created under /etc/yum.repos.d/doca.repo . |
|
Update index |
|
|
Upgrade UEFI/ATF firmware |
Run:
Then i nitiate the upgrade for UEFI/ATF firmware:
|
|
Upgrade BlueField DPU NIC firmware |
The following command updates the firmware package and automatically attempts to flash the firmware to the NIC:
Warning
To prevent automatic flashing of the firmware to the NIC, run the following first:
Note
This step can be used as a standalone firmware update. In any case, it is performed as part of the upgrade flow.
Note
Flashing the firmware to the NIC can be performed manually by running the following command, after the firmware package had been updated:
|
|
Upgrade system |
|
|
Apply the new changes, NIC firmware, and UEFI/ATF |
Warning
If mlxfwreset is not supported, a graceful shutdown and host power cycle are required for the NIC firmware upgrade to take effect. |
Users wishing to build their own customized BlueField OS image can use the BFB build environment. Please refer to the bfb-build project in this GitHub webpage for more information.
For a customized BlueField OS image to boot on the UEFI secure-boot-enabled DPU (default DPU secure boot setting), the OS must be either signed with an existing key in the UEFI DB (e.g., the Microsoft key), or UEFI secure boot must be disabled. Please refer to the "Secure Boot" page under NVIDIA BlueField DPU Platform Operating System Documentation for more details.
For full instructions about setting up a development environment, refer to the NVIDIA DOCA Developer Guide.
Installing CUDA on NVIDIA Converged Accelerator
NVIDIA® CUDA® is a parallel computing platform and programming model developed by NVIDIA for general computing GPUs.
This section details the necessary steps to set up CUDA on your environment. This section assumes that a BFB image has already been installed on your environment.
To install CUDA on your converged accelerator:
Download and install the latest NVIDIA Data Center GPU driver.
Download and install CUDA
WarningThe CUDA version tested to work with DOCA SDK is 11.8.0.
Downloading CUDA includes the latest NVIDIA Data Center GPU driver and CUDA toolkit. For more information about CUDA and driver compatibility, refer to the NVIDIA CUDA Toolkit Release Notes.
Configuring Operation Mode
There are two modes that the NVIDIA Converged Accelerator may operate in:
Standard mode (default) – the BlueField DPU and the GPU operate separately
BlueField-X mode – the GPU is exposed to the DPU and is no longer visible on the host
To verify which mode the system is operating in, run:
host# sudo mst start
host# sudo mlxconfig -d <device-id> q PCI_DOWNSTREAM_PORT_OWNER[4
]
To learn the DPU's device ID, refer to section "Determining DPU Device ID".
Standard mode output:
Device #
1
: […] Configurations: Next Boot PCI_DOWNSTREAM_PORT_OWNER[4
] DEVICE_DEFAULT(0
)
BlueField-X mode output:
Device #
1
: […] Configurations: Next Boot PCI_DOWNSTREAM_PORT_OWNER[4
] EMBEDDED_CPU(15
)
To configure BlueField-X mode, run:
host# mlxconfig -d <device-id> s PCI_DOWNSTREAM_PORT_OWNER[4
]=0xF
To configure standard mode, run:
host# mlxconfig -d <device-id> s PCI_DOWNSTREAM_PORT_OWNER[4
]=0x0
To learn the DPU's device ID, refer to section "Determining DPU Device ID".
Graceful reboot and power cycle are required for configuration to take effect. To power cycle the host run:
host# ipmitool power cycle
Downloading and Installing CUDA Toolkit and Driver
This section details the necessary steps to set up CUDA on your environment. It assumes that a BFB image has already been installed on your environment.
Install CUDA by visiting the CUDA Toolkit Downloads webpage.
WarningSelect the Linux distribution and version relevant for your environment.
WarningThis section shows the native compilation option either on x86 or aarch64 hosts.
Test that the driver installation completed successfully. Run:
dpu# nvidia-smi Tue Apr
5
13
:37
:59
2022
+-----------------------------------------------------------------------------+ | NVIDIA-SMI510.47
.03
Driver Version:510.47
.03
CUDA Version:11.8
| |-------------------------------+----------------------+----------------------+ | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. | | | | MIG M. | |===============================+======================+======================| |0
NVIDIA BF A10 Off |00000000
:06
:00.0
Off |0
| |0
% 43C P0 N/A / 225W | 0MiB / 23028MiB |0
% Default | | | | N/A | +-------------------------------+----------------------+----------------------+ +-----------------------------------------------------------------------------+ | Processes: | | GPU GI CI PID Type Process name GPU Memory | | ID ID Usage | |=============================================================================| | No running processes found | +-----------------------------------------------------------------------------+Verify that the installation completed successfully.
Download CUDA samples repo. Run:
dpu# git clone https:
//github.com/NVIDIA/cuda-samples.git
Build and run vectorAdd CUDA sample. Run:
dpu# cd cuda-samples/Samples/0_Introduction/vectorAdd dpu# make dpu# ./vectorAdd
WarningIf the vectorAdd sample works as expected, it should output "Test Passed".
WarningIf it seems that the GPU is slow or stuck, stop execution and run:
dpu# sudo setpci -v -d ::
0302
800
.L=201
# CPL_VC0 =32
GPUDirect RDMA
For information on GPUDirect RMDA and more, refer to DOCA GPUNetIO documentation.
Installing Rivermax on DPU
NVIDIA Rivermax offers a unique IP-based solution for any media and data streaming use case.
This section provides the steps to install Rivermax assuming that a BFB image has already been installed on your environment.
Downloading Rivermax Driver
Navigate to the NVIDIA Rivermax SDK product page.
Register to be able to download the driver package using the JOIN button at the top of the page.
D ownload the appropriate driver package according to your BFB under the "Linux" subsection. For example, for Ubuntu 22.04 BFB, download rivermax_ubuntu2204_<version>.tar.gz.
Installing Rivermax Driver
Copy the .tgz file to the DPU:
host# sudo scp -r rivermax_ubuntu2204_<version>.tar.gz ubuntu@192.168.100.2:/tmp/
Extract the Rivermax file:
dpu# sudo tar xzf rivermax_ubuntu2204_<version>.tar.gz
Install the Rivermax driver package:
dpu# cd <rivermax-version>/Ubuntu.22.04/deb-dist/aarch64/ dpu# sudo dpkg -i rivermax_<version>.deb
Installing Rivermax Libraries from DOCA
Rivermax libraries are compatibles with DOCA components and can be found inside the doca-dpu-repo.
Unpack the doca-dpu-repo:
dpu# sudo dpkg -i doca-dpu-repo-ubuntu2204-local_<version>_arm64.deb
Run apt update:
dpu# sudo apt-get update
Install the Rivermax libraries:
dpu# sudo apt install doca-rmax-libs dpu# sudo apt install libdoca-rmax-libs-dev
For additional details and guidelines, please visit the NVIDIA Rivermax SDK product page.
For questions, comments, and feedback, please contact us at DOCA-Feedback@exchange.nvidia.com.