NVBandwidth Plugin#

The NVBandwidth plugin is a single-node transfer-path diagnostic that validates memory-copy operations and measures bandwidth and latency.

Availability and prerequisites#

The canonical test name is nvbandwidth. It runs on selected physical GPUs on one host. This diagnostic runs on a subset of NVIDIA GPU products by default. See the diagnostic configuration file associated with your installation for supported products.

Behavior#

DCGM runs the single-node portion of NVBandwidth on the selected physical GPUs; multi-node test cases are outside the plugin workload. Unless the testcases parameter limits the workload, the suite exercises:

Copies between host memory and one or all selected GPUs, including unidirectional and bidirectional patterns.
Copies between selected GPUs, including pairwise, bidirectional, one-to-all, and all-to-one patterns.
Copy-engine and streaming-multiprocessor (SM) implementations of the transfer patterns.
Host-device and device-to-device latency tests, plus copies within a device.

NVBandwidth runs the cases applicable to the paths available among the selected GPUs. A test family that requires an unavailable peer path can be waived. For memory-copy tests, NVBandwidth verifies that the copied data matches the source data. Execution and data-verification failures are reported as diagnostic errors.

Note

The plugin does not validate the measured bandwidth or latency of a transfer path. It reports the observed values without comparing them with expected, minimum, or topology-specific thresholds. These values characterize the test run rather than determine whether its performance is acceptable.

For details about the individual test cases, see the NVBandwidth repository.

Parameters#

The following table lists the global parameters for this plugin:

Parameter	Type	Default	Description
testcases	string		The list of specific testcases to run, separated by `,`, e.g.: `0,1,2`.
is_allowed	Bool	False	Specifies whether or not this test is allowed to run.

Examples#

Run the test with default parameters:

$ dcgmi diag -r nvbandwidth

Run the test, specifying only testcase 1

$ dcgmi diag -r nvbandwidth -p nvbandwidth.testcases=1

Run the test, specifying multiple testcases

$ dcgmi diag -r nvbandwidth -p nvbandwidth.testcases=1,2,3

Run the level 3 test, indicating the nvbandwidth test should be allowed to run:

$ dcgmi diag -r 3 -p nvbandwidth.is_allowed=true

Results and failure conditions#

NVBandwidth results#
Condition	Result or code	Interpretation
Every requested NVBandwidth testcase completes without an error status.	Pass	No testcase reported an error. DCGM does not apply a general minimum-bandwidth threshold to this plugin, and an externally waived or unavailable testcase does not itself make the plugin fail. Review the testcase messages to confirm which paths actually ran.
NVBandwidth reports an error for a testcase or reports an overall execution error.	`DCGM_FR_INTERNAL`; fail	Inspect the NVBandwidth message and diagnostic log for the affected path and underlying error.
The NVBandwidth output is absent or cannot be interpreted.	`DCGM_FR_INTERNAL`; fail	The external workload did not return a usable result. This is not a measured bandwidth failure.
The required executable cannot be found or launched.	`DCGM_FR_INTERNAL`; fail	Verify the installation and retain the diagnostic log.
DCGM cannot retrieve memory-copy utilization before the run.	`DCGM_FR_CANNOT_GET_FIELD_TAG`; fail	The plugin cannot determine whether a competing copy workload is active.
Memory-copy utilization remains above 10% for the 20-second idle wait.	`DCGM_FR_FIELD_THRESHOLD_TS`; test proceeds	Residual activity can distort the measured bandwidth. The condition is reported, but it does not by itself prevent NVBandwidth from running.
Memory-copy utilization is unavailable as a blank field value.	Test proceeds	The plugin treats the GPU as idle; interpret the result with that limitation.
The plugin is disabled.	`DCGM_FR_TEST_DISABLED`; skip	The external workload was not run and no copy-path result was produced.