Add the netlink YAML spec and auto-generated UAPI header for a unified
loopback interface covering MAC, PHY, and pluggable module components.

Each loopback point is described by a nested entry attribute
containing:

 - component  where in the path (MAC, PHY, MODULE)
 - name       subsystem label, e.g. "cmis-host" or "cmis-media"
 - id         optional instance selector (e.g. PHY id, port id)
 - depth      ordering index within a component (0 = first/only)
 - supported  bitmask of supported directions
 - direction  LOCAL, REMOTE, or 0 (disabled)

Signed-off-by: Björn Töpel <bjorn@kernel.org>
---
 Documentation/netlink/specs/ethtool.yaml      | 142 ++++++++++++++++++
 .../uapi/linux/ethtool_netlink_generated.h    |  67 +++++++++
 2 files changed, 209 insertions(+)

diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml
index 5dd4d1b5d94b..fe7e644d1b10 100644
--- a/Documentation/netlink/specs/ethtool.yaml
+++ b/Documentation/netlink/specs/ethtool.yaml
@@ -211,6 +211,58 @@ definitions:
         name: discard
         value: 31
 
+  -
+    name: loopback-component
+    type: enum
+    doc: |
+      Loopback component. Identifies where in the network path the
+      loopback is applied.
+    entries:
+      -
+        name: mac
+        doc: |
+          MAC component loopback. Covers loopback points owned by the
+          MAC / network-controller driver, including the MAC block itself,
+          any MAC-side PCS, and SoC SerDes. The name attribute identifies
+          the sublayer using IEEE 802.3 vocabulary (e.g. mac, pcs, mii).
+      -
+        name: phy
+        doc: |
+          Ethernet PHY loopback. Covers loopback points inside the
+          Ethernet PHY managed by phylib, such as the PHY-internal PCS,
+          PMA, or PMD. The name attribute identifies the sublayer using
+          IEEE 802.3 vocabulary (e.g. pcs, pma, pmd, mii). A Base-T SFP
+          module containing an Ethernet PHY driven by Linux should report
+          loopback under this component, not module.
+      -
+        name: module
+        doc: |
+          Pluggable module (e.g. CMIS (Q)SFP) loopback. Covers loopback
+          modes controlled via module firmware or EEPROM registers. When
+          Linux drives an Ethernet PHY inside the module via phylib, use
+          the phy component instead.
+  -
+    name: loopback-direction
+    type: flags
+    doc: |
+      Loopback direction flags. Direction is defined from the
+      component's own viewpoint: local loops traffic originating from
+      the host back to the host, remote loops traffic arriving from
+      the line back toward the line. This convention holds regardless
+      of where the component sits in the system topology. Used as a
+      bitmask in supported, and as a single value in direction.
+    entries:
+      -
+        name: local
+        doc: |
+          Local loopback (IEEE 802.3). Host TX -> looped back -> host
+          RX (traffic originating from host returns to host).
+      -
+        name: remote
+        doc: |
+          Remote loopback (IEEE 802.3). Line RX -> looped back -> line
+          TX (traffic from far end returns to far end).
+
 attribute-sets:
   -
     name: header
@@ -1905,6 +1957,68 @@ attribute-sets:
         name: link
         type: nest
         nested-attributes: mse-snapshot
+  -
+    name: loopback-entry
+    doc: Per-component loopback configuration entry.
+    attr-cnt-name: __ethtool-a-loopback-entry-cnt
+    attributes:
+      -
+        name: unspec
+        type: unused
+        value: 0
+      -
+        name: component
+        type: u32
+        enum: loopback-component
+        doc: Loopback component
+      -
+        name: name
+        type: string
+        doc: |
+          Subsystem-specific name for the loopback point within the
+          component.
+      -
+        name: id
+        type: u32
+        doc: Optional component instance identifier.
+      -
+        name: depth
+        type: u8
+        doc: |
+          Ordering index within a component instance. When a component
+          has multiple loopback points of the same type (e.g. two PCS
+          blocks inside a rate-adaptation PHY), depth distinguishes
+          them. Lower depth values are closer to the host side, higher
+          values are closer to the line/media side. Defaults to 0 when
+          there is only one loopback point per (component, name) tuple.
+      -
+        name: supported
+        type: u8
+        enum: loopback-direction
+        enum-as-flags: true
+        doc: Bitmask of supported loopback directions
+      -
+        name: direction
+        type: u8
+        enum: loopback-direction
+        doc: Current loopback direction, 0 means disabled
+  -
+    name: loopback
+    attr-cnt-name: __ethtool-a-loopback-cnt
+    attributes:
+      -
+        name: unspec
+        type: unused
+        value: 0
+      -
+        name: header
+        type: nest
+        nested-attributes: header
+      -
+        name: entry
+        type: nest
+        multi-attr: true
+        nested-attributes: loopback-entry
 
 operations:
   enum-model: directional
@@ -2859,6 +2973,34 @@ operations:
             - worst-channel
             - link
       dump: *mse-get-op
+    -
+      name: loopback-get
+      doc: Get loopback configuration and capabilities.
+
+      attribute-set: loopback
+
+      do: &loopback-get-op
+        request:
+          attributes:
+            - header
+        reply:
+          attributes: &loopback
+            - header
+            - entry
+      dump: *loopback-get-op
+    -
+      name: loopback-set
+      doc: Set loopback configuration.
+
+      attribute-set: loopback
+
+      do:
+        request:
+          attributes: *loopback
+    -
+      name: loopback-ntf
+      doc: Notification for change in loopback configuration.
+      notify: loopback-get
 
 mcast-groups:
   list:
diff --git a/include/uapi/linux/ethtool_netlink_generated.h b/include/uapi/linux/ethtool_netlink_generated.h
index 8134baf7860f..31f9178f5b62 100644
--- a/include/uapi/linux/ethtool_netlink_generated.h
+++ b/include/uapi/linux/ethtool_netlink_generated.h
@@ -78,6 +78,47 @@ enum ethtool_pse_event {
 	ETHTOOL_PSE_EVENT_SW_PW_CONTROL_ERROR = 64,
 };
 
+/**
+ * enum ethtool_loopback_component - Loopback component. Identifies where in
+ *   the network path the loopback is applied.
+ * @ETHTOOL_LOOPBACK_COMPONENT_MAC: MAC component loopback. Covers loopback
+ *   points owned by the MAC / network-controller driver, including the MAC
+ *   block itself, any MAC-side PCS, and SoC SerDes. The name attribute
+ *   identifies the sublayer using IEEE 802.3 vocabulary (e.g. mac, pcs, mii).
+ * @ETHTOOL_LOOPBACK_COMPONENT_PHY: Ethernet PHY loopback. Covers loopback
+ *   points inside the Ethernet PHY managed by phylib, such as the PHY-internal
+ *   PCS, PMA, or PMD. The name attribute identifies the sublayer using IEEE
+ *   802.3 vocabulary (e.g. pcs, pma, pmd, mii). A Base-T SFP module containing
+ *   an Ethernet PHY driven by Linux should report loopback under this
+ *   component, not module.
+ * @ETHTOOL_LOOPBACK_COMPONENT_MODULE: Pluggable module (e.g. CMIS (Q)SFP)
+ *   loopback. Covers loopback modes controlled via module firmware or EEPROM
+ *   registers. When Linux drives an Ethernet PHY inside the module via phylib,
+ *   use the phy component instead.
+ */
+enum ethtool_loopback_component {
+	ETHTOOL_LOOPBACK_COMPONENT_MAC,
+	ETHTOOL_LOOPBACK_COMPONENT_PHY,
+	ETHTOOL_LOOPBACK_COMPONENT_MODULE,
+};
+
+/**
+ * enum ethtool_loopback_direction - Loopback direction flags. Direction is
+ *   defined from the component's own viewpoint: local loops traffic
+ *   originating from the host back to the host, remote loops traffic arriving
+ *   from the line back toward the line. This convention holds regardless of
+ *   where the component sits in the system topology. Used as a bitmask in
+ *   supported, and as a single value in direction.
+ * @ETHTOOL_LOOPBACK_DIRECTION_LOCAL: Local loopback (IEEE 802.3). Host TX ->
+ *   looped back -> host RX (traffic originating from host returns to host).
+ * @ETHTOOL_LOOPBACK_DIRECTION_REMOTE: Remote loopback (IEEE 802.3). Line RX ->
+ *   looped back -> line TX (traffic from far end returns to far end).
+ */
+enum ethtool_loopback_direction {
+	ETHTOOL_LOOPBACK_DIRECTION_LOCAL = 1,
+	ETHTOOL_LOOPBACK_DIRECTION_REMOTE = 2,
+};
+
 enum {
 	ETHTOOL_A_HEADER_UNSPEC,
 	ETHTOOL_A_HEADER_DEV_INDEX,
@@ -840,6 +881,28 @@ enum {
 	ETHTOOL_A_MSE_MAX = (__ETHTOOL_A_MSE_CNT - 1)
 };
 
+enum {
+	ETHTOOL_A_LOOPBACK_ENTRY_UNSPEC,
+	ETHTOOL_A_LOOPBACK_ENTRY_COMPONENT,
+	ETHTOOL_A_LOOPBACK_ENTRY_NAME,
+	ETHTOOL_A_LOOPBACK_ENTRY_ID,
+	ETHTOOL_A_LOOPBACK_ENTRY_DEPTH,
+	ETHTOOL_A_LOOPBACK_ENTRY_SUPPORTED,
+	ETHTOOL_A_LOOPBACK_ENTRY_DIRECTION,
+
+	__ETHTOOL_A_LOOPBACK_ENTRY_CNT,
+	ETHTOOL_A_LOOPBACK_ENTRY_MAX = (__ETHTOOL_A_LOOPBACK_ENTRY_CNT - 1)
+};
+
+enum {
+	ETHTOOL_A_LOOPBACK_UNSPEC,
+	ETHTOOL_A_LOOPBACK_HEADER,
+	ETHTOOL_A_LOOPBACK_ENTRY,
+
+	__ETHTOOL_A_LOOPBACK_CNT,
+	ETHTOOL_A_LOOPBACK_MAX = (__ETHTOOL_A_LOOPBACK_CNT - 1)
+};
+
 enum {
 	ETHTOOL_MSG_USER_NONE = 0,
 	ETHTOOL_MSG_STRSET_GET = 1,
@@ -893,6 +956,8 @@ enum {
 	ETHTOOL_MSG_RSS_CREATE_ACT,
 	ETHTOOL_MSG_RSS_DELETE_ACT,
 	ETHTOOL_MSG_MSE_GET,
+	ETHTOOL_MSG_LOOPBACK_GET,
+	ETHTOOL_MSG_LOOPBACK_SET,
 
 	__ETHTOOL_MSG_USER_CNT,
 	ETHTOOL_MSG_USER_MAX = (__ETHTOOL_MSG_USER_CNT - 1)
@@ -954,6 +1019,8 @@ enum {
 	ETHTOOL_MSG_RSS_CREATE_NTF,
 	ETHTOOL_MSG_RSS_DELETE_NTF,
 	ETHTOOL_MSG_MSE_GET_REPLY,
+	ETHTOOL_MSG_LOOPBACK_GET_REPLY,
+	ETHTOOL_MSG_LOOPBACK_NTF,
 
 	__ETHTOOL_MSG_KERNEL_CNT,
 	ETHTOOL_MSG_KERNEL_MAX = (__ETHTOOL_MSG_KERNEL_CNT - 1)
-- 
2.53.0

On Wed, 25 Mar 2026 15:50:10 +0100 Björn Töpel wrote:
> +      -
> +        name: depth
> +        type: u8
> +        doc: |
> +          Ordering index within a component instance. When a component
> +          has multiple loopback points of the same type (e.g. two PCS
> +          blocks inside a rate-adaptation PHY), depth distinguishes
> +          them. Lower depth values are closer to the host side, higher
> +          values are closer to the line/media side. Defaults to 0 when
> +          there is only one loopback point per (component, name) tuple.
> +      -
> +        name: supported
> +        type: u8
> +        enum: loopback-direction
> +        enum-as-flags: true
> +        doc: Bitmask of supported loopback directions
> +      -
> +        name: direction
> +        type: u8
> +        enum: loopback-direction
> +        doc: Current loopback direction, 0 means disabled

u32, Netlink attrs are padded to 4B anyway

On 26/03/2026 23:23, Jakub Kicinski wrote:
> On Wed, 25 Mar 2026 15:50:10 +0100 Björn Töpel wrote:
>> +      -
>> +        name: depth
>> +        type: u8
>> +        doc: |
>> +          Ordering index within a component instance. When a component
>> +          has multiple loopback points of the same type (e.g. two PCS
>> +          blocks inside a rate-adaptation PHY), depth distinguishes
>> +          them. Lower depth values are closer to the host side, higher
>> +          values are closer to the line/media side. Defaults to 0 when
>> +          there is only one loopback point per (component, name) tuple.
>> +      -
>> +        name: supported
>> +        type: u8
>> +        enum: loopback-direction
>> +        enum-as-flags: true
>> +        doc: Bitmask of supported loopback directions
>> +      -
>> +        name: direction
>> +        type: u8
>> +        enum: loopback-direction
>> +        doc: Current loopback direction, 0 means disabled
> 
> u32, Netlink attrs are padded to 4B anyway

That's my bad, I was the one suggesting u8 :( I didn't have the padding
thing in mind at that time :/

Maxime

On Wed, 25 Mar 2026 15:50:10 +0100 Björn Töpel wrote:
> +      -
> +        name: unspec
> +        type: unused
> +        value: 0

I don't think we need to add unspec attrs for new sets ?

Hi Björn,

On 25/03/2026 15:50, Björn Töpel wrote:
> Add the netlink YAML spec and auto-generated UAPI header for a unified
> loopback interface covering MAC, PHY, and pluggable module components.
> 
> Each loopback point is described by a nested entry attribute

Is the nest actually needed ? if everything is under the nest, you might
as well just drop it and return all the attributes directly ?

Maxime

> containing:
> 
>  - component  where in the path (MAC, PHY, MODULE)
>  - name       subsystem label, e.g. "cmis-host" or "cmis-media"
>  - id         optional instance selector (e.g. PHY id, port id)
>  - depth      ordering index within a component (0 = first/only)
>  - supported  bitmask of supported directions
>  - direction  LOCAL, REMOTE, or 0 (disabled)
> 
> Signed-off-by: Björn Töpel <bjorn@kernel.org>
>

Maxime

Maxime!

On Thu, 26 Mar 2026 at 09:10, Maxime Chevallier
<maxime.chevallier@bootlin.com> wrote:
>
> Hi Björn,
>
> On 25/03/2026 15:50, Björn Töpel wrote:
> > Add the netlink YAML spec and auto-generated UAPI header for a unified
> > loopback interface covering MAC, PHY, and pluggable module components.
> >
> > Each loopback point is described by a nested entry attribute
>
> Is the nest actually needed ? if everything is under the nest, you might
> as well just drop it and return all the attributes directly ?

Hmm, you're right! This is a leftover pre the dumpit change. GET/SET
never needs nesting. I'll fix that for the next round!

Thanks!
Björn