[PATCH 1/3] dt-bindings: dsa: microchip: add KSZ low-loss cable errata properties

[PATCH 1/3] dt-bindings: dsa: microchip: add KSZ low-loss cable errata properties

[Fidelio Lawson]

Microchip KSZ87xx switches are affected by the "Module 3: Equalizer fix
for short cables" erratum described in DS80000687C.
The embedded PHY receivers are tuned for long, high-loss cables,
which may cause signal distortion when operated with short or low-loss
cabling such as CAT5e or CAT6. In these cases,
the PHY may fail to establish a link due to internal over-amplification.

Two workarounds are provided by Microchip, each configuring a different
indirect register value to adjust the PHY equalizer settings.

This patch introduces two new device tree properties to enable and
select the appropriate workaround:

  - microchip,low-loss-errata-enable: boolean enabling the feature
  - microchip,low-loss-errata: selects workaround 1 or 2 (default: 1)

These properties allow board designers to opt into the errata fix
according to the targeted cable characteristics of their platform.

Signed-off-by: Fidelio Lawson <fidelio.lawson@exotec.com>
---
 .../devicetree/bindings/net/dsa/microchip,ksz.yaml     | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
index 8d4a3a9a33fc..ddfbc36aace6 100644
--- a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
+++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml
@@ -85,6 +85,24 @@ properties:
     enum: [2000, 4000, 8000, 12000, 16000, 20000, 24000, 28000]
     default: 8000
 
+  microchip,low-loss-errata-enable:
+    description:
+      The receiver of the embedded PHYs is tuned by default to support long cable length applications. This was developed
+      using low quality, high loss cables. Because of this, the equalizer in the PHY may amplify high amplitude receiver signals
+      to the point that the signal is distorted internally, preventing a link from being established.
+      A more balanced receiver setting has been found that still functions at the long cable lengths and also supports
+      low loss applications.
+      If present, enables the selected errata workaround. If absent, the
+      workaround is disabled regardless of microchip,cat56-errata value.
+    type: boolean
+
+  microchip,low-loss-errata:
+    description:
+      Selects Microchip KSZ87xx CAT5e/CAT6 short-cable errata workaround.
+      1 = Workaround 1, 2 = Workaround 2. If omitted, workaround 1 is applied.
+    enum: [1, 2]
+    default: 1
+
   interrupts:
     maxItems: 1
 

-- 
2.53.0

Re: [PATCH 1/3] dt-bindings: dsa: microchip: add KSZ low-loss cable errata properties

[Rob Herring (Arm)]

On Thu, 26 Mar 2026 10:10:21 +0100, Fidelio Lawson wrote:
> Microchip KSZ87xx switches are affected by the "Module 3: Equalizer fix
> for short cables" erratum described in DS80000687C.
> The embedded PHY receivers are tuned for long, high-loss cables,
> which may cause signal distortion when operated with short or low-loss
> cabling such as CAT5e or CAT6. In these cases,
> the PHY may fail to establish a link due to internal over-amplification.
> 
> Two workarounds are provided by Microchip, each configuring a different
> indirect register value to adjust the PHY equalizer settings.
> 
> This patch introduces two new device tree properties to enable and
> select the appropriate workaround:
> 
>   - microchip,low-loss-errata-enable: boolean enabling the feature
>   - microchip,low-loss-errata: selects workaround 1 or 2 (default: 1)
> 
> These properties allow board designers to opt into the errata fix
> according to the targeted cable characteristics of their platform.
> 
> Signed-off-by: Fidelio Lawson <fidelio.lawson@exotec.com>
> ---
>  .../devicetree/bindings/net/dsa/microchip,ksz.yaml     | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 

My bot found errors running 'make dt_binding_check' on your patch:

yamllint warnings/errors:
./Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml:90:111: [warning] line too long (121 > 110 characters) (line-length)
./Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml:91:111: [warning] line too long (128 > 110 characters) (line-length)
./Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml:93:111: [warning] line too long (118 > 110 characters) (line-length)

dtschema/dtc warnings/errors:
/builds/robherring/dt-review-ci/linux/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml: microchip,low-loss-errata: missing type definition

doc reference errors (make refcheckdocs):

See https://patchwork.kernel.org/project/devicetree/patch/20260326-ksz87xx_errata_low_loss_connections-v1-1-79a698f43626@exotec.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.

Re: [PATCH 1/3] dt-bindings: dsa: microchip: add KSZ low-loss cable errata properties

[Andrew Lunn]

On Thu, Mar 26, 2026 at 10:10:21AM +0100, Fidelio Lawson wrote:
> Microchip KSZ87xx switches are affected by the "Module 3: Equalizer fix
> for short cables" erratum described in DS80000687C.
> The embedded PHY receivers are tuned for long, high-loss cables,
> which may cause signal distortion when operated with short or low-loss
> cabling such as CAT5e or CAT6. In these cases,
> the PHY may fail to establish a link due to internal over-amplification.
> 
> Two workarounds are provided by Microchip, each configuring a different
> indirect register value to adjust the PHY equalizer settings.
> 
> This patch introduces two new device tree properties to enable and
> select the appropriate workaround:
> 
>   - microchip,low-loss-errata-enable: boolean enabling the feature
>   - microchip,low-loss-errata: selects workaround 1 or 2 (default: 1)
> 
> These properties allow board designers to opt into the errata fix
> according to the targeted cable characteristics of their platform.

Does the errata give any indication how the two different workarounds
differ? How would a user decided which to use?

I also question if this should be a DT property. The length of the
cables is not a property of the board.

A PHY tunable would better reflect the same board can be used with
different cables, with different lengths/quality.

	  Andrew

Re: [PATCH 1/3] dt-bindings: dsa: microchip: add KSZ low-loss cable errata properties

[kernel test robot]

:::::: 
:::::: Manual check reason: "dtcheck: binding changes may go via different trees"
:::::: 

BCC: lkp@intel.com
CC: oe-kbuild-all@lists.linux.dev
In-Reply-To: <20260326-ksz87xx_errata_low_loss_connections-v1-1-79a698f43626@exotec.com>
References: <20260326-ksz87xx_errata_low_loss_connections-v1-1-79a698f43626@exotec.com>
TO: Fidelio Lawson <lawson.fidelio@gmail.com>
TO: Woojung Huh <woojung.huh@microchip.com>
TO: UNGLinuxDriver@microchip.com
TO: Andrew Lunn <andrew@lunn.ch>
TO: Vladimir Oltean <olteanv@gmail.com>
TO: "David S. Miller" <davem@davemloft.net>
CC: netdev@vger.kernel.org
TO: Eric Dumazet <edumazet@google.com>
TO: Jakub Kicinski <kuba@kernel.org>
TO: Paolo Abeni <pabeni@redhat.com>
TO: Rob Herring <robh@kernel.org>
TO: Krzysztof Kozlowski <krzk@kernel.org>
TO: Conor Dooley <conor+dt@kernel.org>
TO: Marek Vasut <marex@denx.de>
TO: Maxime Chevallier <maxime.chevallier@bootlin.com>
CC: devicetree@vger.kernel.org
CC: linux-kernel@vger.kernel.org
CC: Fidelio Lawson <fidelio.lawson@exotec.com>

Hi Fidelio,

kernel test robot noticed the following build warnings:

[auto build test WARNING on 2d1373e4246da3b58e1df058374ed6b101804e07]

url:    https://github.com/intel-lab-lkp/linux/commits/Fidelio-Lawson/dt-bindings-dsa-microchip-add-KSZ-low-loss-cable-errata-properties/20260327-131337
base:   2d1373e4246da3b58e1df058374ed6b101804e07
patch link:    https://lore.kernel.org/r/20260326-ksz87xx_errata_low_loss_connections-v1-1-79a698f43626%40exotec.com
patch subject: [PATCH 1/3] dt-bindings: dsa: microchip: add KSZ low-loss cable errata properties
:::::: branch date: 11 hours ago
:::::: commit date: 11 hours ago
config: openrisc-randconfig-2051-20260327 (https://download.01.org/0day-ci/archive/20260327/202603271740.iSyifyN9-lkp@intel.com/config)
compiler: or1k-linux-gcc (GCC) 15.1.0
dtschema: 2025.13.dev8+g0515abdd9
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20260327/202603271740.iSyifyN9-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/r/202603271740.iSyifyN9-lkp@intel.com/

dtcheck warnings: (new ones prefixed by >>)
>> Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml: microchip,low-loss-errata: missing type definition
--
>> Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml:90:111: [warning] line too long (121 > 110 characters) (line-length)
   Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml:91:111: [warning] line too long (128 > 110 characters) (line-length)
   Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml:93:111: [warning] line too long (118 > 110 characters) (line-length)
   Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.yaml:52:2: [warning] wrong indentation: expected 2 but found 1 (indentation)
   Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.yaml:84:1: [warning] too many blank lines (2 > 1) (empty-lines)

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCH 1/3] dt-bindings: dsa: microchip: add KSZ low-loss cable errata properties

[Fidelio LAWSON]

On 3/26/26 13:14, Andrew Lunn wrote:
> On Thu, Mar 26, 2026 at 10:10:21AM +0100, Fidelio Lawson wrote:
>> Microchip KSZ87xx switches are affected by the "Module 3: Equalizer fix
>> for short cables" erratum described in DS80000687C.
>> The embedded PHY receivers are tuned for long, high-loss cables,
>> which may cause signal distortion when operated with short or low-loss
>> cabling such as CAT5e or CAT6. In these cases,
>> the PHY may fail to establish a link due to internal over-amplification.
>>
>> Two workarounds are provided by Microchip, each configuring a different
>> indirect register value to adjust the PHY equalizer settings.
>>
>> This patch introduces two new device tree properties to enable and
>> select the appropriate workaround:
>>
>>    - microchip,low-loss-errata-enable: boolean enabling the feature
>>    - microchip,low-loss-errata: selects workaround 1 or 2 (default: 1)
>>
>> These properties allow board designers to opt into the errata fix
>> according to the targeted cable characteristics of their platform.
> 
> Does the errata give any indication how the two different workarounds
> differ? How would a user decided which to use?
> 
> I also question if this should be a DT property. The length of the
> cables is not a property of the board.
> 
> A PHY tunable would better reflect the same board can be used with
> different cables, with different lengths/quality.
> 
> 	  Andrew

Hi Andrew,
Thanks for the review.
Regarding the difference between the two workarounds:
Microchip’s errata does provide some insight into how they behave and 
when each should be used.
Workaround 1 modifies the PHY equalizer settings by adjusting an 
indirect register (0x3c).
According to Microchip’s support article:

“The above register change makes the equalizer’s compensation range 
wider, and therefore cables with various characteristics can be 
tolerated. Adjust equalizer EQ training algorithm to cover a few type of 
short cables issue. Also is appropriate for board‑to‑board connection 
and port‑to‑port connection with the capacitor AC coupling mode.”

Microchip also explains that although the default value in register 0x3c 
handles standard short Ethernet cables (CAT‑5/CAT‑5e), a more optimized 
value (0x15) provides better tolerance for corner cases, especially very 
short or board‑to‑board links:

“Based on tests, a more optimized equalizer adjustment value 0x15 is 
better for all corner cases of the short cable and short distance 
connection for port‑to‑port or board‑to‑board cases.”

So Workaround 1 primarily widens and optimizes the DSP equalizer EQ 
compensation range, and is expected to solve most short/low‑loss cable 
issues.
Workaround 2 is intended for the cases where Workaround 1 is not sufficient.
This one adjusts the receiver low‑pass filter bandwidth, effectively 
reducing the high‑frequency component of the received signal:

“Based on the root cause above, adjust the receiver low pass filter to 
reduce the high frequency component to keep the receive signal within a 
reasonable range when using CAT‑5E and CAT‑6 cable.”

So Workaround 2 is a more aggressive filtering approach, applied only 
when the EQ adjustment alone does not stabilize the link on CAT‑5e/CAT‑6 
short cable scenarios.


Regarding the question of whether this should be exposed through a PHY 
tunable:
I understand your concern. The erratum is indeed linked to cable 
characteristics, not the board itself.
Since this patch modifies registers that belong to the DSA switch 
itself, and not the PHY driver, I’m not entirely sure it would be 
architecturally correct to expose these adjustments as PHY tunables. The 
workarounds target internal receiver/equalizer settings inside the 
KSZ87xx switch block, accessed via the switch’s indirect register 
mechanism, not via a standard phy_device.
Given that, I’m unsure whether mapping these switch‑level registers into 
the PHY tunables framework would be appropriate or even feasible.
What do you think?

Best regards,
Fidelio

Re: [PATCH 1/3] dt-bindings: dsa: microchip: add KSZ low-loss cable errata properties

[Andrew Lunn]

> Regarding the difference between the two workarounds:
> Microchip’s errata does provide some insight into how they behave and when
> each should be used.
> Workaround 1 modifies the PHY equalizer settings by adjusting an indirect
> register (0x3c).
> According to Microchip’s support article:

....


Thanks for the documentation. This needs to go somewhere.

Not sure where yet. If we stay with a DT setting, it should be in the
DT binding. If we make it a PHY tuneable, maybe a comment in the PHY
driver, and in the commit message?

> Regarding the question of whether this should be exposed through a PHY
> tunable:
> I understand your concern. The erratum is indeed linked to cable
> characteristics, not the board itself.
> Since this patch modifies registers that belong to the DSA switch itself,
> and not the PHY driver,

I need to go look at the code, but maybe we can make use of the fact
the PHY is embedded within the switch, rather than being a discrete
device. So we can safely break the layering, even if it is
architecturally wrong.

	Andrew