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

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

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.