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® networking platform (DPU or SuperNIC) software requires following the following step-by-step procedure.
Supported Platforms
Supported BlueField Platforms
The following NVIDIA® BlueField® platforms 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 NVIDIA® ConnectX® NICs supported with DOCA-Host can be found in: NVIDIA DOCA Profiles
Hardware Prerequisites
For BlueField Platform users, this guide assumes that a BlueField device has been installed in a server according to the instructions detailed in your DPU's hardware user guide .
DOCA Packages
See information in the NVIDIA DOCA Release Notes page.
Supported Host OS per DOCA-Host Installation Profile
See information in the NVIDIA DOCA Profiles page.
This guide provides the minimal instructions for setting up DOCA on a standard system.
Make sure to follow the instructions in this section sequentially. Make sure to update DOCA on the host side first before installing the BFB Bundle on the BlueField.
Installation Files
To download the DOCA for host packages from the links in this table, please register to the NVIDIA Developer Program. Otherwise, please use the public repo from DOCA Downloader.
Device |
Component |
OS |
Arch |
Link |
Host |
These files contain the following components suitable for their respective OS version. Note
Please take a look on the NVIDIA DOCA Profiles to know which from the below profiles are supported on your desired OS.
|
Alinux 3.2 |
x86 |
|
Anolis |
aarch64 |
|||
x86 |
||||
BCLinux 21.10 |
aarch64 |
|||
x86 |
||||
BCLinux 21.10 SP2 |
aarch64 |
|||
x86 |
||||
CTyunOS 2.0 |
aarch64 |
|||
x86 |
||||
CTyunOS 23.01 |
aarch64 |
|||
x86 |
||||
Debian 10.13 |
aarch64 |
|||
x86 |
||||
Debian 10.8 |
aarch64 |
|||
x86 |
||||
Debian 10.9 |
x86 |
|||
Debian 11.3 |
aarch64 |
|||
x86 |
||||
Debian 12.1 |
aarch64 |
|||
x86 |
||||
Debian 12.5 |
aarch64 |
|||
x86 |
||||
EulerOS 20 SP11 |
aarch64 |
|||
x86 |
||||
EulerOS 20 SP12 |
aarch64 |
|||
x86 |
||||
Fedora32 |
x86 |
|||
Kylin 1.0 SP2 |
aarch64 |
|||
x86 |
||||
Kylin 1.0 SP3 |
aarch64 |
|||
x86 |
||||
Mariner 2.0 |
x86 |
|||
Oracle Linux 7.9 |
x86 |
|||
Oracle Linux 8.4 |
x86 |
|||
Oracle Linux 8.6 |
x86 |
|||
Oracle Linux 8.7 |
x86 |
|||
Oracle Linux 8.8 |
x86 |
|||
Oracle Linux 9.1 |
x86 |
|||
Oracle Linux 9.2 |
x86 |
|||
openEuler 20.03 SP3 |
aarch64 |
|||
x86 |
||||
openEuler 22.03 |
aarch64 |
|||
x86 |
||||
openEuler 22.03 SP1 |
x86 |
|||
RHEL/CentOS 8.0 |
aarch64 |
|||
x86 |
||||
RHEL/CentOS 8.1 |
aarch64 |
|||
x86 |
||||
RHEL/CentOS 8.2 |
aarch64 |
|||
x86 |
||||
RHEL/CentOS 8.3 |
aarch64 |
|||
x86 |
||||
RHEL/CentOS 8.4 |
aarch64 |
|||
x86 |
||||
RHEL/CentOS 8.5 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 8.6 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 8.7 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 8.8 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 8.9 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 8.10 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 9.0 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 9.1 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 9.2 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 9.3 |
aarch64 |
|||
x86 |
||||
RHEL/Rocky 9.4 |
aarch64 |
|||
x86 |
||||
SLES 15 SP2 |
aarch64 |
|||
x86 |
||||
SLES 15 SP3 |
aarch64 |
|||
x86 |
||||
SLES 15 SP4 |
aarch64 |
|||
x86 |
||||
SLES 15 SP5 |
aarch64 |
|||
x86 |
||||
SLES 15 SP6 |
x86 |
|||
TencentOS 3.3 |
aarch64 |
|||
x86 |
||||
Ubuntu 20.04 |
aarch64 |
|||
x86 |
||||
Ubuntu 22.04 |
aarch64 |
|||
x86 |
||||
Ubuntu 24.04 |
aarch64 |
|||
x86 |
||||
UOS20.1060 |
aarch64 |
|||
x86 |
||||
UOS20.1060A |
aarch64 |
|||
x86 |
||||
XenServer 8.2 |
x86 |
|||
Target BlueField Platform (Arm) |
BlueField Software v 4.8.0 |
Ubuntu 22.04 |
aarch64 |
|
DOCA SDK v2.8.0 |
Ubuntu 22.04 |
aarch64 |
doca-dpu-repo-ubuntu2204-local_1-2.8.0081-1.24.07.0.6.1.bf.4.8.0.13249_arm64.deb |
|
DOCA Runtime v2.8.0 |
Uninstalling Software from Host
If an older DOCA (or MLNX_OFED) software version is installed on your host, make sure to uninstall it before proceeding with the installation of the new version:
Deb-based |
|
RPM-based |
|
Then perform the following steps:
The following procedure is valid for RPM-based OS only.
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 BlueField
Install RShim to manage and flash the BlueField Platform.
OS |
Procedure |
Deb-based |
|
RPM-based |
|
Skip section "Installing Software on Host" to proceed without the DOCA local repo package for host.
Installing Software on Host
Skip this section if you intend to update only the BlueField software (*.bfb
). The RShim driver is sufficient for that purpose.
Make sure to have followed the instructions under "Installing Prerequisites on Host for Target BlueField".
Install DOCA local repo package for host:
InfoThe following table provides instructions for installing the DOCA host repo on your device depending on your OS and desired profile.
OS
Profile
Instructions
Deb-based
doca-all
Download the DOCA host repo 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".
Ensure that the kernel headers installed match the version of the currently running kernel.
InfoIf the build directory exists in under
/lib/modules/$(uname -r)/build
, then the kernel headers are installed.Run apt install for DOCA SDK and DOCA runtime:
host# sudo apt install -y doca-all mlnx-fw-updater
doca-networking
Download the DOCA host repo 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".
Ensure that the kernel headers installed match the version of the currently running kernel.
InfoIf the build directory exists in under
/lib/modules/$(uname -r)/build
, then the kernel headers are installed.Run apt install for DOCA SDK and DOCA runtime:
host# sudo apt install -y doca-networking mlnx-fw-updater
doca-ofed
Download the DOCA host repo from section "Installation Files" for the host.
Unpack the deb repo. Run:
host# sudo dpkg -i <repo_file>
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".
Ensure that the kernel headers installed match the version of the currently running kernel.
InfoIf the build directory exists in under
/lib/modules/$(uname -r)/build
, then the kernel headers are installed.Install
doca-ofed
. Run:host# sudo apt install -y doca-ofed mlnx-fw-updater
RPM-based
doca-all
Download the DOCA host repo 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 and DOCA runtime:
host# sudo yum install -y doca-all mlnx-fw-updater
doca-networking
Download the DOCA host repo 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 and DOCA runtime:
host# sudo yum install -y doca-networking mlnx-fw-updater
doca-ofed
Download the DOCA host repo from section "Installation Files" for the host.
Unpack the RPM repo. Run:
host# sudo 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".
Install
doca-ofed
. Run:host# sudo yum install -y doca-ofed mlnx-fw-updater
Load the drivers:
host# sudo /etc/init.d/openibd restart
Initialize MST. Run:
host# sudo mst restart
DOCA Extra Package
If the kernel version 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/yum install -y doca-extra
Execute the
doca-kernel-support
script which rebuilds and installs the DOCA-Host kernel modules with the running kernel:host# sudo /opt/mellanox/doca/tools/doca-kernel-support
Install user-space packages:
host# sudo apt/yum install -y doca-ofed-userspace
Notedoca-kernel-support
does not support customized or unofficial kernels.(Optional) Retrieve installed packages and their versions as part of DOCA Host installation:
host# doca-info Versions: - DOCA Base MLNX_OFED_LINUX-
24.07
-0.5
.5.0
- MFT4.29
.0
-127
UEFI\ATF versions: - mst_device: mt41692_pciconf0 UEFI Version:4.7
.0
-42
-g13081ae ATF Version:4.7
.0
-25
-g5569834 Firmware (Current): - BlueField-3
32.41
.1000
DOCA: - doca-all2.8
.0
-0.0
.4
- doca-apsh-config2.8
.0079
-1
- doca-bench2.8
.0079
-1
… DOCA Dependencies: … - flexio24.07
.2300
- mlnx-dpdk22.11
.0
-2407.0
.10
OFED: … - rdma-core 2407mlnx52-1.2407055
… - ucx1.17
.0
-1.2407055
…NoteIf BlueField has a BlueField Bundle version older than 2.7.0 installed on it, UEFI\ATF versions appear as N\A. If your version is 2.7.0 or higher and still see N\A, then perform driver restart on the host:
/etc/init.d/openibd restart
Installing Software on BlueField
Users have two options for installing DOCA on BlueField DPU or SuperNIC:
Upgrading the full DOCA image on BlueField (recommended) – this option overwrites the entire boot partition with an Ubuntu 22.04 installation and updates BlueField and NIC firmware.
Upgrading DOCA local repo package on BlueField – this option upgrades DOCA components without overwriting the boot partition. Use this option to preserve configurations or files on BlueField itself.
Upgrading DOCA online repo package on BlueField – this option upgrades DOCA components without overwriting the boot partition. Use this option to preserve configurations or files on BlueField 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 BlueField platforms, skip to section Installing Full DOCA Image on Multiple BlueField Platforms.
Option 1 – No Pre-defined Password
To change the default Ubuntu password during the BFB bundle installation, proceed to Option 2.
BFB installation is executed as follows:
host# sudo bfb-install --rshim rshim<N> --bfb <image_path.bfb>
Where rshim<N>
is rshim0
if you only have one Bluefield. 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 BFB bundle 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# echo ubuntu_PASSWORD=
'$1$3B0RIrfX$TlHry93NFUJzg3Nya00rE1'
> bf.cfgWhen running the installation command, use the
--config
flag to provide the file containing the password:host# sudo bfb-install --rshim rshim<N> --bfb <image_path.bfb> --config bf.cfg
NoteOptionally, to upgrade the BlueField integrated BMC firmware using BFB bundle, please provide the current BMC root credentials in a
bf.cfg
file, as shown in the following:BMC_PASSWORD=
"<root password>"
BMC_USER="root"
BMC_REBOOT="yes"
Unless previously changed, the default BMC root password is
0penBmc
.NoteIf
--config
is not used, then upon first login to the BlueField device, users will be prompted to update the default 'ubuntu' password.The following is an example of Ubuntu-22.04 BFB bundle installation (Release version may vary in the future).
host# sudo bfb-install --rshim rshim0 --bfb bf-bundle-
2.7
.0_24.04_ubuntu-22
.04_prod.bfb --config bf.cfg Pushing bfb1
.41GiB0
:02
:02
[11
.7MiB/s] [ <=> ] Collecting BlueField booting status. Press Ctrl+C to stop INFO[PSC]: PSC BL1 START INFO[BL2]: start INFO[BL2]: boot mode (rshim) INFO[BL2]: VDDQ:1120
mV INFO[BL2]: DDR POST passed INFO[BL2]: UEFI loaded INFO[BL31]: start INFO[BL31]: lifecycle GA Secured INFO[BL31]: VDD:850
mV INFO[BL31]: runtime INFO[BL31]: MB ping success INFO[UEFI]: eMMC init INFO[UEFI]: eMMC probed INFO[UEFI]: UPVS valid INFO[UEFI]: PMI: updates started INFO[UEFI]: PMI: total updates:1
INFO[UEFI]: PMI: updates completed, status0
INFO[UEFI]: PCIeenum
start INFO[UEFI]: PCIeenum
end INFO[UEFI]: UEFI Secure Boot INFO[UEFI]: PK configured INFO[UEFI]: Redfish enabled INFO[UEFI]: exit Boot Service INFO[MISC]: Found bf.cfg INFO[MISC]: Ubuntu installation started INFO[MISC]: Installing OS image INFO[MISC]: Changing thedefault
passwordfor
user ubuntu INFO[MISC]: Ubuntu installation completed INFO[MISC]: Updating NIC firmware... INFO[MISC]: NIC firmware update done INFO[MISC]: Installation finishedTo verify the BlueField has completed booting up, allow additional 90 seconds then perform the following:
host# sudo cat /dev/rshim<N>/misc ... INFO[MISC]: Linux up INFO[MISC]: DPU is ready
Installing Full DOCA Image on Multiple BlueField Platforms
On a host with multiple BlueField devices, the BFB image can be installed on all of them using the multi-bfb-install
script.
host# ./multi-bfb-install --bfb <image_path.bfb> --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 8.0 and 8.2 – the script installs the
bridge-utils
package to use thebrctl
command, creates thetm-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 BlueField and configures a new IP, 192.168.100.x, as described earlier.
Installing DOCA Local Repo Package on BlueField
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 BlueField, make sure the out-of-band interface (mgmt
) is connected to the internet.
Download the DOCA SDK and DOCA Runtime 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 and DOCA SDK:dpu# sudo apt install doca-runtime doca-sdk
Upgrading Firmware
This operation is only required if the user skipped NIC firmware update during BFB bundle installation using the parameter WITH_NIC_FW_UPDATE=no
in the bf.cfg
file.
This section explains how to update the NIC firmware on a DOCA installed BlueField OS.
If multiple BlueFields are installed, the following steps must be performed on all of them after BFB installation.
An up-to-date NIC firmware image is provided in BlueField BFB bundle and copied to the BlueField filesystem during BFB installation.
To upgrade firmware in the BlueField Arm OS:
SSH to your BlueField Arm OS by any means available.
The following instructions enable to login to the BlueField Arm OS from the host OS over the RShim virtual interface,
tmfifo_net<N>
and do not require LAN connectivity with the BlueField OOB network port.NoteThis operation can be performed over the host's
tmfifo_net0
IPv4, 192.168.100.1 (preconfigured) with BlueField Arm OS at 192.168.100.2 (default).If multiple BlueField DPUs were updated using the
multi-bfb-install
script, as explained above, then each target BlueField OS IPv4 address changes in its last octate according to the underlaying RShim interface number: 192.168.100.3 for rshim1, 192.168.100.4 for rshim2, etc.The default credentials for Ubuntu are as follows:
Username
Password
ubuntu
ubuntu
For example, to log into BlueField Arm OS over IPv6:
host]# systemctl restart rshim
// Wait 10 seconds
host]# ssh -6
fe80::21a:caff:feff:ff01%tmfifo_net<N> Password: <configured-password>Upgrade firmware in BlueField. 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 perform a BlueField system reboot.
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 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 BlueField networking platforms (DPUs or SuperNICs) without the need for a full installation.
This process 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 BlueField BMC firmware
After completion of BlueField upgrade:
If NIC firmware was not updated, perform BlueField Arm reset (software reset/reboot BlueField )
If NIC firmware was updated, perform firmware reset (
mlxfwreset
) or perform a graceful shutdown and power cycle
OS |
Action |
Instructions |
Ubuntu/ Debian |
Remove |
|
Install the the GPG key |
|
|
Export the desired distribution |
Export
|
|
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 NIC firmware |
The following commands update the firmware package and flash the firmware to the NIC:
|
|
Remove old metapackages |
|
|
Install new metapackages |
|
|
Upgrade system |
|
|
Apply the new changes, NIC firmware, and UEFI/ATF |
For the upgrade to take effect, perform BlueField system reboot. Note
This step triggers immediate reboot of the BlueField Arm cores.
|
|
CentOS/RHEL/ Anolis/Rocky |
Remove |
|
Export the desired distribution |
Export
|
|
Add DOCA online repository |
A file is created under |
|
Update index |
|
|
Upgrade UEFI/ATF firmware |
Run:
Then i nitiate the upgrade for UEFI/ATF firmware:
|
|
Upgrade BlueField NIC firmware |
The following commands update the firmware package and flash the firmware to the NIC:
|
|
Remove old metapackages |
|
|
Install new metapackages |
Note
Before installing the metapackages, please remove strongSwan and libreSwan packages to avoid any conflicts:
|
|
Upgrade system |
|
|
Apply the new changes, NIC firmware, and UEFI/ATF |
For the upgrade to take effect, perform BlueField system reboot. Note
This step triggers immediate reboot of the BlueField Arm cores.
|
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.
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 BlueField (default BlueField 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
NoteThe 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 and the GPU operate separately
BlueField-X mode – the GPU is exposed to BlueField 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 your BlueField Platform's device ID, refer to section "Determining BlueField 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 your BlueField Platform's device ID, refer to section "Determining BlueField Device ID".
Power cycle is required for configuration to take effect. For 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.
NoteSelect the Linux distribution and version relevant for your environment.
NoteThis 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
NoteIf the
vectorAdd
sample works as expected, it should output "Test Passed
".NoteIf 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 BlueField
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 BlueField: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.