Common CLI Usage
Mango SDK provides Command-Line Interface (CLI) tools for SDK users to easily control and manage MB-DPU devices. Each CLI tool supports tab-completion to automatically complete bash commands.
This page covers the commands that are common to every MangoBoost solution.
Solution-specific subcommands such as mango-ctl rdma or mango-ctl nvmf are described in each solution's manual.
Device Control
mango-ctl CLI tool is used to configure MangoBoost solutions.
~$ mango-ctl dev -h
Control MangoBoost DPU devices
Usage: mango-ctl dev [OPTIONS] [SUBCOMMAND]
Options:
-h,--help Print this help message and exit
Subcommands:
list List the available devices
show Show the details of devices
rescan Rescan the PCIe devices
remove Remove the PCIe device
enable Enable the MangoBoost project
disable Disable the MangoBoost project
sriov Enable SR-IOV for the PCIe device
reset Perform PCIe hot reset on the device
You can list all the MangoBoost PCIe devices using the mango-ctl dev command.
Each device is identified by a unique BDF (Bus, Device, Function).
The following example shows a Mango BoostX™ RoCE AI device (0a:00.0) on the machine.
~$ mango-ctl dev list
0000:0a:00.0
~$ sudo mango-ctl dev show
PCI FPGA Devices
0000:0a:00.0
Vendor ID: 1f52
Device ID: 1008
Revision ID: 0
Description: Mango BoostX - RoCE AI
BAR[0]: 0x91100000 [size=0x40000]
BAR[2]: 0x90c00000 [size=0x400000]
BAR[4]: 0x91000000 [size=0x100000]
NUMA Node: 0
PCIe MSI-X: 16
PCIe Link: Speed 16GT/s (ok), Width x8 (ok)
Kernel module:
Resetting a Device
mango-ctl dev reset performs a PCIe hot reset on the card that owns the given device.
It prints the PCIe bridges and the devices affected by the reset and asks for confirmation.
Add -y to skip the confirmation prompt, and --golden to boot the card from its golden image after the reset.
~$ sudo mango-ctl dev reset 0000:0a:00.0
Bridges to reset:
0000:00:03.1
Devices to remove:
0000:0a:00.0 Mango BoostX - RoCE AI
Proceed? [y/N] y
Removing devices...
Performing Secondary Bus Reset...
Rescanning...
Done. (The SoC side service will take few seconds to restart.)
~$ mango-ctl dev list
0000:0a:00.0
A hot reset removes every device of the card and reloads the drivers. Stop the workloads using the card before resetting it.
Card Management
mango-ctl mgmt CLI tool is used to manage the card itself: sensors, firmware images, EEPROM, and the
in-band management network to the SoC.
Most of the subcommands take the BDF of the SMI (System Management Interface) PF, which appears as
Mango Management PF (SMI) in the mango-ctl dev show output.
~$ mango-ctl mgmt -h
Device management commands
Usage: mango-ctl mgmt [OPTIONS] [SUBCOMMAND]
Options:
-h,--help Print this help message and exit
Subcommands:
flash Flash configuration memory
sensor View device sensor information
boot-source Show boot source: primary or golden
smc-debug-level Set the SMC debug verbosity
beacon Blink the locate LED of SMI devices
eeprom EEPROM access commands
smbus Show or set the SMC SMBus address (EEPROM 0x08)
replace-rootfs Replace eMMC rootfs
net Manage mango-mgmt network interfaces
enable-emmc Provision eMMC partitions on the SoC
mango-ctl mgmt list-smi prints only the BDFs of the SMI PFs on the machine.
~$ mango-ctl mgmt list-smi
0000:02:00.1
Sensor Monitoring
mango-ctl mgmt sensor reads the sensors of the card.
By default it prints the temperature sensors: Board for the board, Ethernet for the QSFP-DD transceiver,
and FPGA for the FPGA chip.
~$ mango-ctl mgmt sensor 0000:02:00.1
Device: 0000:02:00.1
Label | Value
---------+---------
Board | 40.000 C
Ethernet | 49.000 C
FPGA | 72.000 C
Add -v to show every field of each sensor: the status, the maximum and average values, the warning,
critical, and fatal limits, and the sensor name in the kernel hwmon interface.
~$ mango-ctl mgmt sensor 0000:02:00.1 -v
Device: 0000:02:00.1
Label | Value | Status | Max | Average | Limits (Warn, Crit, Fatal) | Name
---------+----------+--------+----------+----------+----------------------------+------
Board | 40.000 C | valid | 61.000 C | 43.500 C | 85.000, 95.000, 105.000 | temp1
Ethernet | 49.000 C | valid | 55.000 C | 48.200 C | 70.000, 75.000, 80.000 | temp2
FPGA | 72.000 C | valid | 81.000 C | 70.400 C | 95.000, 100.000, 105.000 | temp3
Use -e to add only some of these fields: name, max, average, limits, and status, separated by spaces.
~$ mango-ctl mgmt sensor 0000:02:00.1 -e max limits
Device: 0000:02:00.1
Label | Value | Max | Limits (Warn, Crit, Fatal)
---------+----------+----------+---------------------------
Board | 39.000 C | 47.000 C | N/A
Ethernet | 50.000 C | 52.000 C | 65.000, 70.000, 85.000
FPGA | 57.000 C | 66.000 C | 85.000, 100.000, 105.000
Use -t to select another sensor type: temp (temperature), in (voltage), curr (current), power, sfp (transceiver link status), or all.
sfp shows the link status of each port: Connect when the link is up, Disconnect when it is down, and No cable when the cage is empty.
~$ mango-ctl mgmt sensor 0000:02:00.1 -t sfp
Device: 0000:02:00.1
SFP Link Status:
Cage | Record | Link | Link Status | Link Speed
-----+------------+------+-------------+-----------
0 | SFP0_Link0 | 0 | Connect | 200G
0 | SFP0_Link1 | 1 | Disconnect | -
-f json prints the same fields as a JSON array, and -o writes the output to a file instead of the terminal.
~$ mango-ctl mgmt sensor 0000:02:00.1 -t power -f json
[
{
"label": "Total_Power",
"value": 38.0
}
]
~$ mango-ctl mgmt sensor 0000:02:00.1 -t all -v -f json -o sensors.json
Boot Source and Firmware Update
The card holds a primary image and a golden fallback image in its configuration memory.
mango-ctl mgmt boot-source shows which one the card booted from.
~$ mango-ctl mgmt boot-source 0000:02:00.1
Boot Source : primary
mango-ctl mgmt flash writes a firmware image into a partition of the configuration memory.
The partition is boot by default, golden selects the fallback image, and a FIT image is detected
automatically and written to the fit partition.
The boot and golden partitions take a PDI image such as BOOT.BIN, and the fit partition takes a FIT image such as image.ub; an image that does not match the partition is refused before anything is written.
Add --reset to perform a PCIe hot reset right after flashing.
--progress-format json prints the progress as one JSON object per line for scripts: a start record, a progress record for each percent, and a result record with the error code.
The following example flashes the boot partition and hot resets the card so that it boots the new image. The progress bar shows the bytes written, the write rate, and the estimated remaining time.
~$ sudo mango-ctl mgmt flash 0000:02:00.1 firmware.pdi boot --reset
Flashing configuration memory...
Image Path : firmware.pdi (58720256 Bytes)
Device BDF : 0000:02:00.1
Boot Device: primary
Partition : boot
[==================================================] 100% [02m:48s] 56.0 MB / 56.0 MB | 341.3 KB/s | ETA: 0.0m
Device flashing completed.
Performing PCIe hot reset...
Removing devices...
Performing Secondary Bus Reset...
Rescanning...
PCIe hot reset completed.
Without --reset, the command reminds you that the card still runs the old image.
~$ sudo mango-ctl mgmt flash 0000:02:00.1 firmware.pdi golden
Flashing configuration memory...
Image Path : firmware.pdi (58720256 Bytes)
Device BDF : 0000:02:00.1
Boot Device: primary
Partition : golden
[==================================================] 100% [02m:47s] 56.0 MB / 56.0 MB | 343.1 KB/s | ETA: 0.0m
Device flashing completed.
Cold reboot the machine to load the new image.
Flashing does not activate the new image by itself.
The card keeps running the current image until it is reset or the machine is power-cycled.
Keep a known-good image in the golden partition so the card can fall back to it with mango-ctl dev reset --golden.
Card Beacon
mango-ctl mgmt beacon blinks the link LEDs of the card green so that you can find the card in a rack.
The beacon turns off by itself after the timeout, which is 30 seconds by default.
Use -t to set the timeout from 1 to 600 seconds, and off to turn the beacon off before the timeout.
~$ sudo mango-ctl mgmt beacon on 0000:02:00.1
~$ sudo mango-ctl mgmt beacon on 0000:02:00.1 -t 600
~$ sudo mango-ctl mgmt beacon off 0000:02:00.1
Give several BDFs to blink several cards at once, or omit the BDF to blink every card on the machine. When the beacon turns off, the LEDs go back to their usual indication.
EEPROM Access
mango-ctl mgmt eeprom reads and writes the card EEPROM that stores the board identity.
mango-ctl mgmt eeprom read takes the byte offset and the number of bytes to read, and dumps them as hex
with 16 bytes per line.
Add -o to save the raw bytes to a file instead.
~$ mango-ctl mgmt eeprom read 0000:02:00.1 0 32
Reading 32 bytes from 0000:02:00.1 at offset 0x00
00: 01 23 45 67 89 ab cd ef 01 23 45 67 89 ab cd ef
10: 01 23 45 67 89 ab cd ef 01 23 45 67 89 ab cd ef
~$ mango-ctl mgmt eeprom read 0000:02:00.1 0 256 -o eeprom.bin
Reading 256 bytes from 0000:02:00.1 at offset 0x00
Data written to output file.
Management Network
The Management PF provides an in-band network interface between the host and the DPU SoC.
mango-ctl mgmt net lists these interfaces and configures their IP addresses.
~$ mango-ctl mgmt net list
mango_mgmt0
~$ mango-ctl mgmt net show
In-band Management Devices
mango_mgmt0
Host BDF: 0000:02:00.2
Host IP: 192.168.10.1
Soc IP: 192.168.10.2
mango-ctl mgmt net config assigns the host-side and SoC-side IP addresses of an interface.
When --host-ip, --soc-ip, and --subnet are omitted, the defaults 192.168.10.1, 192.168.10.2, and 24
are used.
Use a different subnet for each card when the machine has several cards.
The command brings up the host interface, pushes the SoC address to the card, and verifies the link with a ping before returning.
~$ sudo mango-ctl mgmt net config mango_mgmt0 --host-ip 192.168.10.1 --soc-ip 192.168.10.2 --subnet 24
mango_mgmt0: ping verified (192.168.10.1 -> 192.168.10.2)
~$ sudo mango-ctl mgmt net config mango_mgmt1 --host-ip 192.168.20.1 --soc-ip 192.168.20.2 --subnet 24
mango_mgmt1: ping verified (192.168.20.1 -> 192.168.20.2)
~$ mango-ctl mgmt net show
In-band Management Devices
mango_mgmt0
Host BDF: 0000:02:00.2
Host IP: 192.168.10.1
Soc IP: 192.168.10.2
mango_mgmt1
Host BDF: 0000:82:00.2
Host IP: 192.168.20.1
Soc IP: 192.168.20.2
eMMC and Root Filesystem
On a card whose SoC has an eMMC, mango-ctl mgmt enable-emmc and mango-ctl mgmt replace-rootfs prepare the eMMC and install a root filesystem on it.
They reach the SoC over the management network, so configure it with mango-ctl mgmt net config and set up SSH key login from the host to the SoC as root.
Both take the management interface name (for example, mango_mgmt0) or the BDF as the target.
mango-ctl mgmt enable-emmc creates three ext4 partitions on the eMMC: two of 25 GiB and one with the remaining space.
If the eMMC already has this layout, it is left unchanged.
Otherwise the command asks for confirmation before partitioning, and -y skips the prompt.
~$ sudo mango-ctl mgmt enable-emmc mango_mgmt0
mango-ctl mgmt replace-rootfs copies a root filesystem image such as rootfs.tar.gz to the SoC and writes it to the eMMC prepared by enable-emmc.
The SoC uses the new root filesystem after it restarts.
Add -r to perform a PCIe hot reset after the replacement, in the same way as mango-ctl dev reset.
~$ sudo mango-ctl mgmt replace-rootfs mango_mgmt0 rootfs.tar.gz -r
enable-emmc repartitions and formats the eMMC, so any data on the eMMC is lost.
It refuses to run while the SoC is running from a root filesystem on the eMMC.
JSON Output
mango-ctl has no JSON option common to every command.
The following commands print their result as JSON with the option shown, and the other commands print text only.
| Command | Option | Output |
|---|---|---|
mango-ctl dev, mango-ctl dev list, mango-ctl dev show | --json | The devices and their details. |
mango-ctl mgmt sensor | -f json | The sensor readings as a JSON array. |
mango-ctl mgmt boot-source | -f json | The boot source. |
mango-ctl mgmt flash | --progress-format json | The progress of flashing, one JSON object per line. |
mango-ctl mgmt net list, mango-ctl mgmt net show | --json | The in-band management interfaces. |
Card Monitoring
mango-smi CLI tool is used to monitor the status of MangoBoost DPU devices.
It groups the Core PFs of each card by serial number and shows the card-level sensor readings including power
and temperature.
Running mango-smi without a subcommand is the same as mango-smi show.
~$ mango-smi -h
MangoBoost System Mangement Interface (SMI)
Usage: mango-smi [OPTIONS] [SUBCOMMAND]
Options:
-h,--help Print this help message and exit
-V,--Version Show the CLI version
Subcommands:
list List MangoBoost devices
show Show MangoBoost devices
soc Control MangoBoost SoC
~$ sudo mango-smi
+---------------------------------------------------------------------------+
| MANGO-SMI 0.8.2 Kernel Driver 1.0.0-260716 |
|===========================================================================|
| Product | Device | Sensor (Avg / Max) |
+------------------------+------------------------+-------------------------+
| Mango BoostX - RoCE AI | 0000:01:00.0 (port 0) | Total Power (38W / 39W) |
| Serial: XXXXXXXXXXXX | 0000:02:00.0 (port 1) | FPGA Temp (44C / 44C) |
+------------------------+------------------------+-------------------------+
mango-smi list prints only the device names.
~$ mango-smi list
0000:01:00.0
0000:02:00.0
Link Diagnostics
mango-link CLI tool is used to inspect and control the QSFP transceivers plugged into the cages of a card.
A cage is a QSFP slot on the card bracket that holds one transceiver module or cable, and one or more Ethernet ports run through it.
The module commands handle the transceivers, the dev commands report the link state of the ports, and the port commands read each port's counters and error rates.
~$ mango-link -h
MangoBoost Link Diagnostics
Usage: mango-link [OPTIONS] [SUBCOMMAND]
Options:
-h,--help Print this help message and exit
-V,--Version Show the CLI version
-j,--json Output JSON
-v,--verbose Verbose output (watch: every line in full)
Subcommands:
dev The card itself; no verb is dev list
module The QSFP module in each cage; no verb is module list
No noun is dev show all. Example: mango-link dev show all -s ddm -j
Notation: <device>[/<cage>] - <page>:<offset>[+<len>] - KEY=VALUE[@<lanes>] - @<file>
Exit codes: 0 ok, 1 failed, 2 usage, 3 transient, 4 absent, 5 confirm, 6 rejected, 7 permission, 8 stale
<device> is the BDF of the SMI PF, and all selects every card.
The module commands also take <device>/<cage> or all/<cage> to select a cage.
list, show, and watch select every card when the target is omitted, and mango-link without arguments runs mango-link dev show all.
The SMC on the card publishes the transceiver information to the host. It reads the identity, thresholds, and controls when the transceiver is inserted, and reads the flags and monitor values again every second. Reading the published information does not require root privileges, while reading the transceiver directly or changing it does.
Port Status
mango-link dev list lists the cards with their device state and the number of cages.
PORTS shows where the port numbers come from, and hw_port means that the driver provides them.
~$ mango-link dev list
DEVICE STATE PORTS CAGES
0000:02:00.1 READY hw_port 1
mango-link dev show reports the link state of each port and the cage that the port runs through.
State is up when the link is up, down when a transceiver is detected but the link is down, and no cable when the cage is empty.
Speed shows the speed of a port that is up.
Fields that the firmware does not report yet are shown as N/A.
~$ mango-link dev show 0000:02:00.1
Device 0000:02:00.1 (ports: hw_port)
Port 0 (0000:02:00.0, cage 0)
State : up
Speed : 200G
LinkTraining : N/A (not supported by firmware yet)
Port 1 (0000:01:00.0, cage 0)
State : down
Speed : -
LinkTraining : N/A (not supported by firmware yet)
-s selects the sections to print, separated by commas: link (default), or the transceiver sections module, ddm, and controls described below.
-p selects one port for link, and -c selects one cage for the transceiver sections.
mango-link port list prints one line per port: the state, the speed, the FEC mode, and the cage.
A port that is down shows the cause, for example no_module, no_signal, fec_unaligned, hi_ber, local_fault, or remote_fault, and mango-link port show adds the sublayer that reported it (module, pmd, fec, pcs, or mac).
~$ mango-link port list
DEVICE PORT STATE SPEED FEC CAGE
0000:38:00.1 0 up 200G rs544 0
0000:38:00.1 1 up 200G rs544 0
0000:8b:00.1 0 down (no_module) - - 0
0000:8b:00.1 1 down (no_module) - - 0
mango-link port show prints the port in sections, selected with -s: link, fec, pcs, serdes, events, eye, and counters.
--netdev compares the counters with ethtool -S of the network interface of the port.
--live (serdes section) reads from the card whether the receiver of each lane has finished initializing, and requires root privileges. It does not measure the signal or the alignment.
mango-link port clear saves the current counters as the baseline of the user.
mango-link port show then counts from the baseline and computes the error rates over the interval.
The counters on the card are not changed.
The error rates, the counters, and the rates in mango-link port watch come from counters that the mango-mgmt driver collects once the card brings up the MAC of the port; nothing needs to be turned on.
The age in the mango-link port show header shows that the collection is running: it stays at about one second, and keeps growing if the collection stops.
The following example checks the link quality: it starts an interval, waits, and then reads the rates.
~$ mango-link port clear 0000:38:00.1
~$ mango-link port show 0000:38:00.1/0 -s link,fec
Device 0000:38:00.1
Port 0 (0000:38:00.0, cage 0) since clear 2026-11-09 21:36:12 (12.5 s), valid / age 597 ms
State : up
Speed : 200G configured 200G / supported 200G
Lanes : 4
Medium : -
Pause : off configured off / supported off rx
Admin : up
Link modes : 200G_CR4 200G_SR4 200G_DR4 200G_FR4 200G_LR4
Module : present ready
MAC : dcmac
FEC : rs544 configured rs544 / supported rs544
codeword errors 0 /cw
corrected 5.92e-08 /cw
pre-FEC BER -
Lane Symbol err/cw Bit err/cw
0-3 - -
mango-link port watch prints one line per port at each interval (1 s by default) with the state, the speed, and the RX and TX rates in Gbps and packets per second.
It also marks state changes and short link drops.
Press Ctrl-C to stop the command.
Transceiver Information
mango-link module list prints one line per cage.
STATE is the state of the cage: empty, initializing, ready, or failed.
EPOCH increases when a transceiver is plugged in or reset, or when the cage recovers from failed.
FLAGS lists the sticky flags described below and other cage conditions such as lowpower.
~$ mango-link module list
DEVICE CAGE STATE TYPE SPEC VENDOR PART NUMBER SERIAL TEMP LINKS EPOCH FLAGS
0000:02:00.1 0 ready QSFP+ (CMIS) CMIS 4.0 VENDOR QSFP-200G-SR4 XXXXXXXXXX 50.74 C 0,1 65542 sticky: rx_los@1-4 rx_cdr_lol@1-4 tx_cdr_lol@1-4 temp_high_warn vcc_low_warn rx_power_low_alarm@1-4 rx_power_low_warn@1-4 tx_bias_low_alarm@1-4 tx_bias_low_warn@1-4 dp_state_changed@1-8 rx_output_status_changed@1-4 module_state_changed
mango-link module show prints three sections for each cage.
- Module: the identity of the transceiver, such as the type, the management standard, the vendor, the part number, and the media. The management standard is SFF-8636 for earlier QSFP transceivers, or CMIS (Common Management Interface Specification) for QSFP-DD and newer transceivers. A CMIS transceiver also reports its module state, firmware versions, and the applications it supports, such as
200GBASE-SR4. - DDM: the digital diagnostic monitoring values: the temperature, the supply voltage, and the receive power, transmit power, and transmit bias current of each lane, with the thresholds that the transceiver advertises.
- Controls: the current value of each control that
mango-link module setcan change. For a CMIS transceiver, theData pathline shows the state of each host lane; in the example below, lanes 1 to 4 are activated for application 1 and lanes 5 to 8 are deactivated.
~$ mango-link module show 0000:02:00.1/0
Device 0000:02:00.1
Module (cage 0, links 0,1) epoch 65542 / sample 1052 / poll 1000 ms / control_gen 0
State : ready module state ready
Identifier : QSFP+ (CMIS) (0x1E) CMIS 4.0 / paged / 1 bank
Vendor : VENDOR OUI 00:00:00
Part Number : QSFP-200G-SR4 Rev 00
Serial Number : XXXXXXXXXX Date 2025-01-01
Media : 850 nm VCSEL / OM4 100 m / OM3 70 m Connector MPO 1x12
Power Class : 3 (max 5.00 W) case temp [0 .. 70] C
Firmware : active 1.0 / inactive 0.0 hardware 0.0
Pages : lower 00h 01h 02h 10h 11h checksums ok
Applications : 1 200GAUI-4 C2M / 200GBASE-SR4 host 4 lanes / media 4 lanes
: 2 100GAUI-2 C2M / 100GBASE-SR2 host 2 lanes / media 2 lanes
: 3 IB EDR / 200GBASE-SR4 host 4 lanes / media 4 lanes
: 4 IB EDR / 100GBASE-SR2 host 2 lanes / media 2 lanes
DDM (cage 0) thresholds: module-advertised
Current High alarm High warn Low warn Low alarm
Temperature 50.74 C 80.00 73.00 -3.00 -10.00
Voltage 3.293 V 3.630 3.465 3.135 2.970
Lane Rx Power Tx Power Tx Bias
1 0.82 dBm 1.97 dBm 7.93 mA
2 0.68 dBm 1.67 dBm 7.64 mA
3 0.36 dBm 1.81 dBm 7.71 mA
4 0.32 dBm 1.71 dBm 7.72 mA
Thresholds : Rx Power [-9.40 .. 7.00] dBm / Tx Power [-9.50 .. 7.00] dBm / Tx Bias [1.00 .. 15.00] mA
Flags : -
Sticky : rx_los@1-4 rx_cdr_lol@1-4 tx_cdr_lol@1-4 temp_high_warn vcc_low_warn rx_power_low_alarm@1-4 rx_power_low_warn@1-4 tx_bias_low_alarm@1-4 tx_bias_low_warn@1-4 dp_state_changed@1-8 rx_output_status_changed@1-4 module_state_changed flag_seq 13
Legend : ++ high alarm / + high warning / - low warning / -- low alarm
Controls (cage 0) control_gen 0
Data path : activated@1-4 deactivated@5-8 config_undefined x8 / DPInitPending none
tx_disable : off
rx_out_disable : off
squelch_tx : auto
polarity_tx : normal
polarity_rx : normal
dp_deinit : off
appsel : AppSel 1 / DPID 0
explicit_control: off
tx_adaptive_eq : on
cdr_tx : on
cdr_rx : on
tx_eq : 0
rx_emph : 2
rx_post_emph : 0
rx_amp : 3
Low power : policy highpower request 0 / allow hw 1
In the header line, sample increases each time the SMC reads the flags and monitor values, poll is the interval of those reads, and control_gen counts the set and write requests accepted since the insertion.
A mark next to a DDM value shows that the value is at or beyond a threshold, as described in the Legend line.
Flags lists the flags reported at the last read, and Sticky keeps every flag reported since the insertion, the last reset, or the last mango-link module ack, with the lanes after @.
In the example above, every lane receives an optical signal and no flag is raised now, while Sticky still lists the flags reported earlier.
-s selects the sections to print, separated by commas: module, ddm, controls, or all (default).
Transceiver Memory
The memory of a transceiver is divided into 128-byte pages: the lower page (bytes 0 to 127) and the upper pages such as 00h (bytes 128 to 255).
mango-link module dump prints the published pages as a hex dump, or only the page given by name.
~$ mango-link module dump 0000:02:00.1/0 lower
Device 0000:02:00.1
Page lower / cage 0 / published (sample 1052) / 128 B
0: 1e 40 04 07 01 00 00 00 00 00 00 00 00 00 32 be |.@............2.|
16: 80 a1 00 00 00 00 00 00 00 00 60 00 00 00 00 00 |..........`.....|
32: 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 |................|
48: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
64: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
80: 00 00 00 00 00 01 0f 0e 44 01 0d 0c 22 05 31 0e |........D...".1.|
96: 44 01 31 0c 22 05 ff 00 00 00 00 00 00 00 00 00 |D.1."...........|
112: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
--sticky prints the sticky copy of the flag bytes, and --advertised also prints the pages that the transceiver provides beyond the published ones.
mango-link module read reads a window of up to 128 bytes, given as a field name or <page>:<offset>[+<len>], and names the fields in it.
--live reads the transceiver instead of the published copy, except for the latched flag bytes.
--advertised, --live, and a page or window that is not published read the transceiver directly and require root privileges.
~$ mango-link module read 0000:02:00.1/0 VendorName
Device 0000:02:00.1
cage 0 / page 00h / bytes 129-144 / published (sample 1052)
129: 56 45 4e 44 4f 52 20 20 20 20 20 20 20 20 20 20 |VENDOR | VendorName (00h:129+16, RO)
~$ mango-link module read 0000:02:00.1/0 lower:14+2
Device 0000:02:00.1
cage 0 / page lower / bytes 14-15 / published (sample 1052)
14: 32 be |2.| TempMonValue (lower:14+2, RO)
~$ sudo mango-link module read 0000:02:00.1/0 00h:129+16 --live
Device 0000:02:00.1
cage 0 / page 00h / bytes 129-144 / wire
129: 56 45 4e 44 4f 52 20 20 20 20 20 20 20 20 20 20 |VENDOR | VendorName (00h:129+16, RO)
mango-link module fields prints the field table of each standard and does not require a card.
ACCESS is the access type defined by the standard: RO, WO, RW, or - for reserved and vendor-specific bytes.
~$ mango-link module fields lower --spec cmis | head -n 8
CMIS
BYTE BIT LANES NAME ACCESS
0 7-0 - Identifier RO
1 7-0 - CmisRevision RO
2 7 - MemoryModel RO
2 6 - SteppedConfigOnly RO
2 3-2 - MciMaxSpeed RO
Transceiver Monitoring
mango-link module watch prints the full status of each cage, and then a line whenever the state, epoch, flags, temperature, or supply voltage of a cage changes or a cage reports an error.
--interval sets the read interval (for example, 500ms, 2s, or 1m; the default is the shortest poll of the selected cages), --count stops after the given number of reads, and -v prints every read in full.
Press Ctrl-C to stop the command.
In the following example, only the temperature and the supply voltage change after the first line.
~$ mango-link module watch 0000:02:00.1/0 --count 3 --interval 1s
10:00:00.459 0000:02:00.1 cage0 ready epoch 65542 sample 1052 50.74 C 3.293 V flags - sticky rx_los@1-4 rx_cdr_lol@1-4 tx_cdr_lol@1-4 temp_high_warn vcc_low_warn rx_power_low_alarm@1-4 rx_power_low_warn@1-4 tx_bias_low_alarm@1-4 tx_bias_low_warn@1-4 dp_state_changed@1-8 rx_output_status_changed@1-4 module_state_changed
10:00:01.466 0000:02:00.1 cage0 ready epoch 65542 sample 1053 50.59 C 3.292 V
10:00:02.473 0000:02:00.1 cage0 ready epoch 65542 sample 1054 50.68 C 3.293 V
Transceiver Control
mango-link module set, write, ack, and power change one cage of one card and require root privileges.
They ask for confirmation before the change, and -y skips it.
Without -y, they make no change when they are not run from an interactive terminal.
The examples in this section were taken with an SFF-8636 transceiver.
When a cage carries more than one port, a change to the transceiver can interrupt the other ports.
In that case, set, write, and power are refused (exit code 6) while any port of the cage is up or its state cannot be read, or when the card does not report which ports the cage carries.
Add --force-shared only when the interruption is acceptable.
Setting Controls
mango-link module set changes the controls by name in the form KEY=VALUE[@<lanes>].
Without @<lanes>, the value applies to every lane.
--dry-run prints the bytes to be written without writing them, and does not require root privileges.
The following example turns off the transmitter of lane 1 and turns it on again.
~$ mango-link module set 0000:02:00.1/0 tx_disable=on@1 --dry-run
0000:02:00.1 cage 0 / QSFP28 VENDOR QSFP-200G-SR4 / epoch 65538 / control_gen 0
tx_disable lower:86+1 00 -> 01 (immediate)
dry run: nothing written
~$ sudo mango-link module set 0000:02:00.1/0 tx_disable=on@1 -y
0000:02:00.1 cage 0 / QSFP28 VENDOR QSFP-200G-SR4 / epoch 65538 / control_gen 0
tx_disable lower:86+1 00 -> 01 (immediate, control_gen 0 -> 1)
written
~$ mango-link module show 0000:02:00.1/0 -s controls
Device 0000:02:00.1
Controls (cage 0) control_gen 1
tx_disable : on@1 off@2-4
rx_out_disable: off
squelch_tx : auto
cdr_tx : off
cdr_rx : off
rx_rate : 3
tx_rate : 3
tx_eq : 0
rx_emph : 0
rx_amp : 0
Low power : policy highpower request 0 / allow hw 1
~$ sudo mango-link -j module set 0000:02:00.1/0 tx_disable=off -y
{
"schema_version": 1,
"device_id": "0000:02:00.1",
"cage": 0,
"spec": "sff8636",
"dry_run": false,
"apply": null,
"ops": [
{
"key": "tx_disable",
"page": "lower",
"bank": 0,
"offset": 86,
"length": 1,
"before": "01",
"after": "00",
"control_gen": {
"before": 1,
"after": 2
},
"effect": "immediate"
}
],
"control_gen": {
"before": 1,
"after": 2
}
}
The keys depend on the management standard and are listed by mango-link module fields -j.
The SFF-8636 keys below take effect as soon as they are written.
| Key | Value | Description |
|---|---|---|
tx_disable | on, off | Turns off the transmitter of the lanes. |
rx_out_disable | on, off | Turns off the receiver outputs of the lanes toward the card. |
squelch_tx | auto, off, force | Sets the transmitter squelch: automatic, disabled, or forced. |
cdr_tx, cdr_rx | on, off | Turns the transmit or receive clock and data recovery (CDR) on or off. |
rx_rate, tx_rate | code | Sets the rate select code of the lanes. |
tx_eq, rx_emph, rx_amp | code | Sets the transmit input equalization, the receive output emphasis, or the receive output amplitude. |
tx_eq and rx_emph are limited to the maximum that the transceiver advertises, and rx_amp to the codes that it advertises; other values are refused before writing.
Writing Raw Bytes
mango-link module write writes raw bytes to <page>:<offset> for diagnostics.
It prints the bytes before and after the write, and verifies them with the bytes that the card reads back from the transceiver.
Bytes that the host may not change, such as the identity pages, are refused.
~$ sudo mango-link module write 0000:02:00.1/0 lower:86 01 -y
0000:02:00.1 cage 0 / QSFP28 VENDOR QSFP-200G-SR4 / epoch 65538 / control_gen 2
lower:86 00 -> 01 TxDisable
written / control_gen 2 -> 3 / readback matches
~$ sudo mango-link -j module write 0000:02:00.1/0 lower:86 00 -y
{
"schema_version": 1,
"device_id": "0000:02:00.1",
"cage": 0,
"page": "lower",
"bank": 0,
"offset": 86,
"length": 1,
"before": "01",
"after": "00",
"control_gen": {
"before": 3,
"after": 4
},
"verified": true,
"dry_run": false
}
~$ mango-link module write 0000:02:00.1/0 00h:148 41 --dry-run
mango-link: slot for page 00h is not writable
Power Policy
mango-link module power sets the power policy of a transceiver to lowpower or highpower.
The power policy is kept until the transceiver is removed or the card restarts.
~$ sudo mango-link module power 0000:02:00.1/0 lowpower -y
0000:02:00.1 cage 0 / QSFP28 VENDOR QSFP-200G-SR4 / epoch 65538 / control_gen 4 / links 0,1
lowpower / epoch 65538 -> 65538 / state ready at 1000 ms
~$ sudo mango-link -j module power 0000:02:00.1/0 highpower -y
{
"schema_version": 1,
"device_id": "0000:02:00.1",
"cage": 0,
"policy": "highpower",
"module_epoch": {
"before": 65538,
"after": 65538
},
"state": "ready",
"power": "highpower",
"elapsed_ms": 1000,
"result": "success"
}
Clearing Sticky Flags
mango-link module ack clears the sticky flags that the cage shows.
A flag whose cause remains, such as rx_los without an optical signal, is raised again at the next read.
~$ sudo mango-link module ack 0000:02:00.1/0 -y
0000:02:00.1 cage 0 / QSFP28 VENDOR QSFP-200G-SR4 / epoch 65538 / control_gen 4 / flag_seq 11 / sticky: lower rx_los@1-4 tx_los@1-4 rx_cdr_lol@1-4 tx_cdr_lol@1-4 rx_power_low_alarm@1-4 rx_power_low_warn@1-4 tx_power_low_alarm@1-4 tx_power_low_warn@1-4 tx_bias_low_warn@1-4 init_complete
cleared / flag_seq 11 (no new flags since the read)
Resetting a Transceiver
mango-link module power with reset resets the transceiver.
The reset is handled like removing and inserting the transceiver: the epoch increases and control_gen starts again from 0, while the power policy is kept.
~$ sudo mango-link -j module power 0000:02:00.1/0 reset -y
{
"schema_version": 1,
"device_id": "0000:02:00.1",
"cage": 0,
"policy": "reset",
"module_epoch": {
"before": 65538,
"after": 65540
},
"state": "ready",
"power": "highpower",
"elapsed_ms": 6002,
"result": "success"
}
JSON Output and Exit Codes
Add -j to any mango-link command to print the result as JSON.
The commands that read cards print one document of the form {"schema_version": 1, "devices": [...]}, mango-link port watch -j prints one object per port, and mango-link module watch -j one object per cage, on each read.
Errors are printed to the standard error, and with -j also as an error object in the document.
~$ mango-link -j dev show 0000:02:00.1
{
"schema_version": 1,
"devices": [
{
"device_id": "0000:02:00.1",
"port_source": "hw_port",
"ports": [
{
"port": 0,
"pf": "0000:02:00.0",
"cage": 0,
"state": "up",
"speed": "200G",
"link_training": null
},
{
"port": 1,
"pf": "0000:01:00.0",
"cage": 0,
"state": "down",
"speed": null,
"link_training": null
}
]
}
]
}
The exit code of mango-link shows the result of the command.
| Exit code | Name | Description |
|---|---|---|
| 0 | ok | The command succeeded. |
| 1 | failed | The command failed, or the result of a change is unknown. Read the state again before retrying. |
| 2 | usage | The command or its options are invalid. Nothing was sent to the card. |
| 3 | transient | The cage or the card is in a temporary state, such as an empty or initializing cage. Retry later. |
| 4 | absent | The device, cage, port, page, or field does not exist, or the operation is not supported. |
| 5 | confirm | The change was not confirmed. |
| 6 | rejected | The request was refused by the card, the transceiver, the shared-cage check, or the readback check. |
| 7 | permission | Root privileges are required, or the published cage information cannot be read. |
| 8 | stale | The transceiver was reinserted, reset, or written by another host during the command. Read the state again before retrying. |