[PATCH net v1 1/2] dt-bindings: ethernet: eswin: refine delay model and HSP register description

[lizhi2 at eswincomputing.com]

From: Zhi Li <lizhi2 at eswincomputing.com>

Refine the EIC7700 Ethernet dt-binding based on observed hardware behavior
and clarify the original delay model for eth0.

The previous binding used an enum-based definition for
rx-internal-delay-ps and tx-internal-delay-ps. Replace it with a
range-based model using:

  - minimum: 0
  - maximum: 2540
  - multipleOf: 20

This better reflects the actual hardware implementation, which
supports 20ps granularity delay steps in the MAC RGMII interface.

The tx/rx internal delay values are clarified as MAC-side programmable
delay components applied on the RGMII clock/data path, representing
the effective delay seen at the MAC interface.

This does not change the intended hardware semantics, but aligns the
binding with the actual hardware implementation.

These properties are optional and only required when MAC-side fine
tuning is needed; otherwise delay alignment is provided by PHY or
board design.

Depending on the selected RGMII timing mode, delay alignment may be
provided by the PHY (e.g. rgmii-id) or by board/MAC-side configuration.
When PHY or board design already provides the required delay, these
MAC-side properties may be omitted. When MAC-side fine tuning is
required, they should be provided to describe the internal RGMII
timing adjustment.

Additionally, extend the description of the HSP subsystem register
layout used by the MAC glue logic. This includes explicit TXD and RXD
delay control registers to ensure deterministic initialization and
to override any residual configuration potentially left by bootloaders.

Add reference to the EIC7700X SoC Technical Reference Manual,
Chapter 10 ("High-Speed Interface"), Part 4 for background of the
HSP CSR block:
https://github.com/eswincomputing/EIC7700X-SoC-Technical-Reference-Manual/releases

There are no in-tree users of this binding, so no ABI impact is
expected.

Fixes: 888bd0eca93c ("dt-bindings: ethernet: eswin: Document for EIC7700 SoC")
Signed-off-by: Zhi Li <lizhi2 at eswincomputing.com>
---
 .../bindings/net/eswin,eic7700-eth.yaml       | 50 +++++++++++++------
 1 file changed, 36 insertions(+), 14 deletions(-)

diff --git a/Documentation/devicetree/bindings/net/eswin,eic7700-eth.yaml b/Documentation/devicetree/bindings/net/eswin,eic7700-eth.yaml
index 91e8cd1db67b..fab95603bd82 100644
--- a/Documentation/devicetree/bindings/net/eswin,eic7700-eth.yaml
+++ b/Documentation/devicetree/bindings/net/eswin,eic7700-eth.yaml
@@ -63,16 +63,39 @@ properties:
       - const: stmmaceth
 
   rx-internal-delay-ps:
-    enum: [0, 200, 600, 1200, 1600, 1800, 2000, 2200, 2400]
+    minimum: 0
+    maximum: 2540
+    multipleOf: 20
+    description:
+      RX internal delay in picoseconds applied on the RGMII clock at the MAC
+      side. The hardware supports 20 ps steps.
+      This property is optional and only needed when MAC-side delay tuning
+      is required.
 
   tx-internal-delay-ps:
-    enum: [0, 200, 600, 1200, 1600, 1800, 2000, 2200, 2400]
+    minimum: 0
+    maximum: 2540
+    multipleOf: 20
+    description:
+      TX internal delay in picoseconds applied on the RGMII clock at the MAC
+      side. The hardware supports 20 ps steps.
+      This property is optional and only needed when MAC-side delay tuning
+      is required.
 
   eswin,hsp-sp-csr:
     description:
       HSP CSR is to control and get status of different high-speed peripherals
       (such as Ethernet, USB, SATA, etc.) via register, which can tune
       board-level's parameters of PHY, etc.
+
+      Additional background information about the High-Speed Subsystem
+      and the HSP CSR block is available in Chapter 10 ("High-Speed Interface")
+      of the EIC7700X SoC Technical Reference Manual, Part 4
+      (EIC7700X_SoC_Technical_Reference_Manual_Part4.pdf). The manual is
+      publicly available at
+      https://github.com/eswincomputing/EIC7700X-SoC-Technical-Reference-Manual/releases
+
+      This reference is provided for background information only.
     $ref: /schemas/types.yaml#/definitions/phandle-array
     items:
       - items:
@@ -82,6 +105,8 @@ properties:
           - description: Offset of AXI clock controller Low-Power request
                          register
           - description: Offset of register controlling TX/RX clock delay
+          - description: Offset of register controlling TXD delay
+          - description: Offset of register controlling RXD delay
 
 required:
   - compatible
@@ -93,8 +118,6 @@ required:
   - phy-mode
   - resets
   - reset-names
-  - rx-internal-delay-ps
-  - tx-internal-delay-ps
   - eswin,hsp-sp-csr
 
 unevaluatedProperties: false
@@ -104,24 +127,23 @@ examples:
     ethernet at 50400000 {
         compatible = "eswin,eic7700-qos-eth", "snps,dwmac-5.20";
         reg = <0x50400000 0x10000>;
-        clocks = <&d0_clock 186>, <&d0_clock 171>, <&d0_clock 40>,
-                <&d0_clock 193>;
-        clock-names = "axi", "cfg", "stmmaceth", "tx";
         interrupt-parent = <&plic>;
         interrupts = <61>;
         interrupt-names = "macirq";
-        phy-mode = "rgmii-id";
-        phy-handle = <&phy0>;
+        clocks = <&d0_clock 186>, <&d0_clock 171>, <&d0_clock 40>,
+                <&d0_clock 193>;
+        clock-names = "axi", "cfg", "stmmaceth", "tx";
         resets = <&reset 95>;
         reset-names = "stmmaceth";
-        rx-internal-delay-ps = <200>;
-        tx-internal-delay-ps = <200>;
-        eswin,hsp-sp-csr = <&hsp_sp_csr 0x100 0x108 0x118>;
-        snps,axi-config = <&stmmac_axi_setup>;
+        eswin,hsp-sp-csr = <&hsp_sp_csr 0x100 0x108 0x118 0x114 0x11c>;
+        phy-handle = <&phy0>;
+        phy-mode = "rgmii-id";
         snps,aal;
         snps,fixed-burst;
         snps,tso;
-        stmmac_axi_setup: stmmac-axi-config {
+        snps,axi-config = <&stmmac_axi_setup_gmac0>;
+
+        stmmac_axi_setup_gmac0: stmmac-axi-config {
             snps,blen = <0 0 0 0 16 8 4>;
             snps,rd_osr_lmt = <2>;
             snps,wr_osr_lmt = <2>;
-- 
2.25.1