Networking NVIDIA Firmware Tools (MFT) Documentation

nvtoolslogger Utility

Overview

MFT repository (flint, mlxconfig, mlxlink, mtcr, mlxreg, …) contains a shared logging infrastructure called NVIDIA Tools Logger. It is disabled by default and produces no output until it is explicitly turned on.

nvtoolslogger is the command-line tool used to control it. With this tool, you can:

  • Set how verbose the logging is (globally, or per MFT module)

  • Choose where the log goes (screen, file, syslog)

  • Limit how many log files accumulate on disk

  • Inspect the currently active configuration

The tool does not log anything itself — it writes a small JSON configuration file that every MFT tool reads at start-up. Changes take effect on the next run of an MFT tool. Already
running processes are not affected.

File and Directory Locations


Linux / FreeBSD / ESXi

Windows

Configuration file

/var/lib/mft/nvtoolslogger.json

C:\\ProgramData\\mft\\nvtoolslogger.json

Log directory

/var/log/mft/

C:\\ProgramData\\mft\\

Tool

nvtoolslogger

nvtoolslogger.exe

Permissions: The configuration file are found in a system directory, sonvtoolslogger must be run as root (Linux) or from an elevated / Administrator shell (Windows) when writing the default path. Read-only operations such as --show, do not require elevation.

Get Started

Turn logging on, send it to a file, and check the result:

Bash
# 1. Enable everything at INFO level
nvtoolslogger -l info
nvtoolslogger --set-level info

# 2. Send the output to /var/log/mft/
nvtoolslogger -o file
nvtoolslogger --enable-output file

# 3. Verify what is active
nvtoolslogger -s
nvtoolslogger --show

# 4. Run any MFT tool - it now logs
flint -d /dev/mst/mt4123_pciconf0 q

# 5. Look at the log
ls -ltr /var/log/mft/

To turn logging back off completely:

Bash
nvtoolslogger --reset

Concepts

Severity Levels

Logging is threshold-based: a level lets through that level and everything more severe.

Level

Meaning

debug

Everything, including internal flow / register access detail. Most verbose.

info

High-level progress messages.

warning

Recoverable problems.

error

Operation failures.

fatal

Unrecoverable failures only.

off

No logging at all (this is the default).

Example: --set-level warning emits warning, error and fatal, but not info or debug.

Layers (Modules)

Log messages are tagged with the MFT component "layer" that produced them. Each layer can carry its own severity threshold, which is useful when you need deep detail from one component without drowning in output from the rest.

Available layers:

mtcr, mlxreg, mft_core, mlxfwops, npgs, mst_tool, efuse, common, hca_caps , nvfwinject, mlxdpa, mlxtokengenerator, imgen, mlxfwmanager, mlxi2c, mflash, mflash_access , mflash_spi, imgen_mic, cable_access, cable_cdb

The keyword all may be used with --set-module / --clear-module to address every layer at once.

Precedence

per-module override  >  global level

A layer with no explicit override inherits the global level. --show displays which of the two is in effect for every layer ((override) vs (global)).

Output Sinks

A sink is a destination. Any combination may be active at the same time.

Sink

Destination

stdout

Standard output (colored)

stderr

Standard error (colored)

file

Rotating file under the log directory

syslog

syslog on Linux/FreeBSD, Windows Event Log on Windows

If logging is enabled but no sink is configured, MFT falls back to stderr so that messages are never silently lost.

On Windows, the syslog sink writes to the Event Log and requires administrator rights the first time, to register the event source.

Command Reference

nvtoolslogger
    [-l|--set-level LEVEL] [-m|--set-module MODULE:LEVEL] [-M|--clear-module MODULE]
    [-o|--enable-output SINK] [-O|--disable-output SINK] [-n|--set-max-log-files COUNT]
    [-s|--show] [-r|--reset] [-h|--help]

Option

Argument

Description

-l, --set-level

LEVEL

Set the global severity threshold: debug, info, warning, error, fatal, off.

-m, --set-module

MODULE:LEVEL

Set a per-module severity override, e.g. mtcr:debug. May be repeated. all:LEVEL writes an explicit override for every layer.

-M, --clear-module

MODULE

Remove a per-module override, reverting that layer to the global level. all clears every override. May be repeated.

-o, --enable-output

SINK

Enable an output sink: stdout, stderr, file, syslog. May be repeated.

-O, --disable-output

SINK

Disable an output sink. May be repeated.

-n, --set-max-log-files

COUNT

Maximum number of *.log files kept in the log directory (default 100, must be positive).

Maximum value is 1000.

-s, --show

—

Print the active configuration and the resolved level of every layer.

-r, --reset

—

Restore the default configuration (global level off, no overrides, no sinks).

-h, --help

—

Print usage and exit.

Both --option value and --option=value forms are accepted, as are the short forms
(-l info).

Common Tasks

Watch the log live on the terminal while running a tool:

Bash
nvtoolslogger --set-level debug --enable-output stdout
mlxlink -d /dev/mst/mt4123_pciconf0

Investigate a device-access problem (infrastructure layer):

Bash
nvtoolslogger --set-module mtcr:debug --set-module reg_access:debug --enable-output file

Turn a single layer back to the global level:

Bash
nvtoolslogger --clear-module mtcr

Quiet down without losing the configuration (keeps overrides and sinks, stops most output):

Bash
nvtoolslogger --set-level error

Stop writing to disk, keep the rest:

Bash
nvtoolslogger --disable-output file

Inspecting the Configuration

$ nvtoolslogger --show
NVIDIA Tools Logger Configuration
========================

Global severity level: info
Max log directory files: 100

Active sinks:
  - file
  - stdout

Per-module severity overrides:
  mtcr: debug

Resolved layer settings:
  mtcr: debug (override)
  reg_access: info (global)
  flint: info (global)
  mlxconfig: info (global)
  mlxlink: info (global)
  mlxreg: info (global)
  mft_core: info (global)
  mlxfwops: info (global)
  npgs: info (global)
  mst_tool: info (global)
  efuse: info (global)
  common: info (global)
  hca_caps: info (global)

The Resolved layer settings section is the authoritative answer to "what will actually be logged": it shows the effective level per layer and whether it came from an override or from the global level.

Reading the Log Output

Log File Naming

Each MFT process writes its own file in the log directory:

/var/log/mft/<tool-name>_<pid>.log

for example /var/log/mft/flint_20416.log.

Line Format

[2026-07-30 13:41:07.482] [debug] [mtcr] [mtcr_ul.c:412 mread4] read 0xf0014 = 0x00000001
 |                          |        |     |                     |
 timestamp                  severity layer source location        message

Session Banner

Whenever logging is enabled, each MFT process writes a three-line banner at the top of its output, so every log is self-describing:

[2026-07-30 13:41:07.480] [logger] PID: 20416
[2026-07-30 13:41:07.480] [logger] Command line: flint -d /dev/mst/mt4123_pciconf0 q
[2026-07-30 13:41:07.481] [logger] MFT version: ...

Always include this banner when attaching a log to a bug report.

Log Rotation and Clean-up

A single process log rotates at 10 MB, keeping up to 5 rotated files.

At start-up, the file sink prunes the log directory so at most --set-max-log-files (default 100) *.log files remain; the oldest are deleted first.

Nothing is deleted automatically while logging is disabled or when the file sink is off.

Configuration File Format

nvtoolslogger is the supported way to edit the configuration, but the file is plain JSON and readable for inspection or for deployment via configuration management:

JSON
{
	"global_level" : "info",
	"max_log_dir_files" : 100,
	"modules" :
	{
		"mtcr" : "debug"
	},
	"sinks" :
	[
		"file",
		"stdout"
	],
	"version" : 1
}

Key

Meaning

version

Configuration schema version (currently 1).

global_level

Global severity threshold.

max_log_dir_files

Log-directory file cap.

modules

Per-layer overrides.

sinks

Enabled output destinations.

The file is written atomically (temporary file + rename), so a tool reading it concurrently never sees a partially written configuration. Unknown module names are skipped with a warning; unknown or malformed values fall back to defaults.

Appendix for Developers

Adding log calls inside MFT sources goes through the shared logger API rather thanprintf/cout:

  • C++: nvtoolslogger/NvToolsLogger.h — NvToolsLogger::debug(Layer::FLINT, "..."), plus thelogf() printf-style variant

  • C: nvtoolslogger/nvtoolslogger_c.h — mft_log() / mft_log_fmt()

  • Python: nvtoolslogger_api.py — Logger.debug(Layer.MTCR, "...")

New layers are added to layers.h (both the C enum and the C++ table); they then appear automatically in nvtoolslogger --help, --show, and the validation messages.

Last updated: