[PATCH net-next v10 5/5] net: dsa: mxl862xx: document devlink flash and info support
From: Daniel Golle <daniel@makrotopia.org>
Date: 2026-08-09 17:09:24
Also in:
linux-doc, lkml
Subsystem:
documentation, networking [general], the rest · Maintainers:
Jonathan Corbet, "David S. Miller", Eric Dumazet, Jakub Kicinski, Paolo Abeni, Linus Torvalds
Describe the devlink info versions and the flash update behaviour,
including the MCUboot rescue mode recovery, in a dedicated file under
Documentation/networking/devlink/ and link it from the index. Add the
new file to the driver's MAINTAINERS entry.
Signed-off-by: Daniel Golle <daniel@makrotopia.org>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
---
v10: document that a switch power cycled on its own needs the driver
unbound and rebound before a failed recovery is re-examined
v9: no changes, picked up Andrew's v5 Reviewed-by
v8:
- asic.id and asic.rev are omitted whenever the part number reads
zero, not only in MCUboot rescue mode (found by Sashiko AI review)
- drop the claim that "0.0.0" marks a switch that never ran firmware;
rescue mode always reports it (found by Sashiko AI review)
- document devlink dev flash as the signal that says whether a
recovery is still running, including the -EIO it returns once the
recovery has failed (found by Sashiko AI review)
v7: no changes
v6: no changes
v5: new patch, splitting the devlink documentation out of the flash
update and rescue mode recovery patches so each keeps to code
(Jakub Kicinski asked for the documentation)
Documentation/networking/devlink/index.rst | 1 +
Documentation/networking/devlink/mxl862xx.rst | 74 +++++++++++++++++++
MAINTAINERS | 1 +
3 files changed, 76 insertions(+)
create mode 100644 Documentation/networking/devlink/mxl862xx.rst
diff --git a/Documentation/networking/devlink/index.rst b/Documentation/networking/devlink/index.rst
index 4745148fecf4..058999d0dc56 100644
--- a/Documentation/networking/devlink/index.rst
+++ b/Documentation/networking/devlink/index.rst@@ -94,6 +94,7 @@ parameters, info versions, and other features it supports. mlx5 mlxsw mv88e6xxx + mxl862xx netdevsim nfp octeontx2
diff --git a/Documentation/networking/devlink/mxl862xx.rst b/Documentation/networking/devlink/mxl862xx.rst
new file mode 100644
index 000000000000..5b24d8cb57bc
--- /dev/null
+++ b/Documentation/networking/devlink/mxl862xx.rst@@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +mxl862xx devlink support +======================== + +This document describes the devlink features implemented by the +``mxl862xx`` device driver. + +Info versions +============= + +The ``mxl862xx`` driver reports the following versions + +.. list-table:: devlink info versions implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Example + - Description + * - ``asic.id`` + - fixed + - 8628 + - The chip part number read from the CHIP ID registers. Omitted + when the part number reads as zero, which happens for a switch + sitting in MCUboot rescue mode (the registers need a running + firmware), for an unfused part, and after a failed flash. + * - ``asic.rev`` + - fixed + - 0 + - The chip version read from the same register word, so it is + omitted whenever ``asic.id`` is. + * - ``fw`` + - running, stored + - 1.0.70 + - Version of the firmware running on the switch, reported as both + running and stored since the switch boots it from its own flash. + It is omitted while no firmware version is known: after a failed + flash, and in MCUboot rescue mode while an interrupted download + is still being recovered in the background. Once the loader is + ready to accept a new image the version appears as "0.0.0", + which no released firmware reports, so version-comparing tools + offer any available release as an upgrade. Use ``devlink dev + flash`` to tell a recovering switch from a ready one, see below; + a missing version on its own does not say why. + +Flash update +============ + +The ``mxl862xx`` driver implements support for ``devlink dev flash``. +The signed firmware image is transferred to the switch over the same +MDIO bus which is also used to manage the switch, then verified and +installed by the MCUboot bootloader running on the switch. All ports +of the switch are closed for the duration of the update and the driver +reprobes the switch after it has rebooted into the new firmware. A +complete flash and reprobe cycle takes about one minute. + +A switch stuck in MCUboot rescue mode, e.g. after an interrupted +update, is registered without user ports. If the previous download was +interrupted mid-transfer the loader is wedged; the driver drains it +back to a clean ready state in the background, one byte at a time, +which takes tens of minutes for a large image and is reported through +the kernel log as it progresses. During that recovery ``devlink dev +flash`` returns ``-EBUSY`` with an extack message saying so, and +``devlink dev info`` reports no firmware version. Once the loader is +ready the firmware version appears and flashing a firmware image +through the regular update flow recovers the switch. + +If the recovery fails, the loader needs a power cycle: ``devlink dev +flash`` then returns ``-EIO`` and says so in its extack message. The +driver only re-examines the switch when it binds, so on a board where +the switch can be power cycled on its own, unbind and rebind the driver +afterwards to have the recovered switch recognised.
diff --git a/MAINTAINERS b/MAINTAINERS
index 03bfb79fca2a..8d9b1ea3faad 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS@@ -16107,6 +16107,7 @@ M: Daniel Golle <daniel@makrotopia.org> L: netdev@vger.kernel.org S: Maintained F: Documentation/devicetree/bindings/net/dsa/maxlinear,mxl862xx.yaml +F: Documentation/networking/devlink/mxl862xx.rst F: drivers/net/dsa/mxl862xx/ F: net/dsa/tag_mxl862xx.c
--
2.55.0