Add document for the SATA AHCI controller on the EIC7700 SoC platform,
including descriptions of its hardware configurations.

Signed-off-by: Yulin Lu <luyulin@eswincomputing.com>
---
 .../bindings/ata/eswin,eic7700-ahci.yaml      | 80 +++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/ata/eswin,eic7700-ahci.yaml

diff --git a/Documentation/devicetree/bindings/ata/eswin,eic7700-ahci.yaml b/Documentation/devicetree/bindings/ata/eswin,eic7700-ahci.yaml
new file mode 100644
index 000000000000..9266f8f2543e
--- /dev/null
+++ b/Documentation/devicetree/bindings/ata/eswin,eic7700-ahci.yaml
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/ata/eswin,eic7700-ahci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Eswin EIC7700 SoC SATA Controller
+
+maintainers:
+  - Yulin Lu <luyulin@eswincomputing.com>
+  - Huan He <hehuan1@eswincomputing.com>
+
+description:
+  This document defines device tree bindings for the Synopsys DWC
+  implementation of the AHCI SATA controller found in Eswin's
+  Eic7700 SoC platform.
+
+select:
+  properties:
+    compatible:
+      const: eswin,eic7700-ahci
+  required:
+    - compatible
+
+allOf:
+  - $ref: snps,dwc-ahci-common.yaml#
+
+properties:
+  compatible:
+    items:
+      - const: eswin,eic7700-ahci
+      - const: snps,dwc-ahci
+
+  clocks:
+    minItems: 2
+    maxItems: 2
+
+  clock-names:
+    items:
+      - const: pclk
+      - const: aclk
+
+  resets:
+    maxItems: 1
+
+  reset-names:
+    const: arst
+
+  ports-implemented:
+    const: 1
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+  - resets
+  - reset-names
+  - phys
+  - phy-names
+  - ports-implemented
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    sata@50420000 {
+        compatible = "eswin,eic7700-ahci", "snps,dwc-ahci";
+        reg = <0x50420000 0x10000>;
+        interrupt-parent = <&plic>;
+        interrupts = <58>;
+        clocks = <&clock 171>, <&clock 186>;
+        clock-names = "pclk", "aclk";
+        phys = <&sata_phy>;
+        phy-names = "sata-phy";
+        ports-implemented = <0x1>;
+        resets = <&reset 96>;
+        reset-names = "arst";
+    };
-- 
2.25.1

On 04/09/2025 08:37, Yulin Lu wrote:
> Add document for the SATA AHCI controller on the EIC7700 SoC platform,

Subject: drop "for", wrong grammar. "Document" is a verb.

> including descriptions of its hardware configurations.
> 
> Signed-off-by: Yulin Lu <luyulin@eswincomputing.com>


...

> +
> +maintainers:
> +  - Yulin Lu <luyulin@eswincomputing.com>
> +  - Huan He <hehuan1@eswincomputing.com>
> +
> +description:
> +  This document defines device tree bindings for the Synopsys DWC

Describe the hardware, not the document. Entire line is completely
redundant.

> +  implementation of the AHCI SATA controller found in Eswin's
> +  Eic7700 SoC platform.
> +



...

> +  clock-names:
> +    items:
> +      - const: pclk
> +      - const: aclk
> +
> +  resets:
> +    maxItems: 1
> +
> +  reset-names:
> +    const: arst
> +
> +  ports-implemented:
> +    const: 1

I do not see how you addressed request about firmware. Nothing changed
here, no explanation in the commit msg.


Best regards,
Krzysztof

Hello Krzysztof, Rob,

On Thu, Sep 04, 2025 at 09:10:34AM +0200, Krzysztof Kozlowski wrote:
> > +
> > +  ports-implemented:
> > +    const: 1
> 
> I do not see how you addressed request about firmware. Nothing changed
> here, no explanation in the commit msg.

In Yulin's defence, he did comment that when having the Ports Implemented
register initialized by firmware, the Ports Implemented register apparently
gets cleared to zero when rmmoding the driver (probably because it disables
the clocks and regulators to the controller), thus this suggestion breaks
the use case of being able to reload the driver (rmmod + insmod).

He mentioned this, and asked for advice here:
https://lore.kernel.org/linux-ide/2cc9f2ff.6a2.198e04fd36e.Coremail.luyulin@eswincomputing.com/

After no reply he asked the same question again:
https://lore.kernel.org/linux-ide/692e11ca.843.198f0337528.Coremail.luyulin@eswincomputing.com/

I assume that Rob simply missed those messages.

Anyway, I provided my 50 cents here:
https://lore.kernel.org/linux-ide/aLBUC116MdJqDGIJ@flawful.org/

(I would like to add that I think it is the disabling of clocks and
regulators that causes the register to be cleared, since we do call
ahci_platform_assert_rsts() during the first probe, so if it was the reset
that cleared the register, the first probe should also not have worked.)


Not sure if it relevant to mention this reply to Rob's review comment in the
commit message, but perhaps it should have been mentioned in the change log.


Kind regards,
Niklas

On 04/09/2025 11:14, Niklas Cassel wrote:
> Hello Krzysztof, Rob,
> 
> On Thu, Sep 04, 2025 at 09:10:34AM +0200, Krzysztof Kozlowski wrote:
>>> +
>>> +  ports-implemented:
>>> +    const: 1
>>
>> I do not see how you addressed request about firmware. Nothing changed
>> here, no explanation in the commit msg.
> 
> In Yulin's defence, he did comment that when having the Ports Implemented
> register initialized by firmware, the Ports Implemented register apparently
> gets cleared to zero when rmmoding the driver (probably because it disables
> the clocks and regulators to the controller), thus this suggestion breaks
> the use case of being able to reload the driver (rmmod + insmod).
> 
> He mentioned this, and asked for advice here:
> https://lore.kernel.org/linux-ide/2cc9f2ff.6a2.198e04fd36e.Coremail.luyulin@eswincomputing.com/
> 
> After no reply he asked the same question again:
> https://lore.kernel.org/linux-ide/692e11ca.843.198f0337528.Coremail.luyulin@eswincomputing.com/
> 
> I assume that Rob simply missed those messages.
> 
> Anyway, I provided my 50 cents here:
> https://lore.kernel.org/linux-ide/aLBUC116MdJqDGIJ@flawful.org/
> 
> (I would like to add that I think it is the disabling of clocks and
> regulators that causes the register to be cleared, since we do call
> ahci_platform_assert_rsts() during the first probe, so if it was the reset
> that cleared the register, the first probe should also not have worked.)
> 
> 
> Not sure if it relevant to mention this reply to Rob's review comment in the
> commit message, but perhaps it should have been mentioned in the change log.

Reviewer questions for more serious stuff happen for a reason, so when
discussion is resolved somehow differently than reviewer suggested, it
pretty often deserves explanation in commit msg.

Well, in changelog as absolute minimum. No explanation happened here in
the changelog, nor in the commit msg.

Best regards,
Krzysztof

Hello Krzysztof, Niklas, Rob,

Thank you very much for your suggestions and reply.

> 
> On 04/09/2025 11:14, Niklas Cassel wrote:
> > Hello Krzysztof, Rob,
> > 
> > On Thu, Sep 04, 2025 at 09:10:34AM +0200, Krzysztof Kozlowski wrote:
> >>> +
> >>> +  ports-implemented:
> >>> +    const: 1
> >>
> >> I do not see how you addressed request about firmware. Nothing changed
> >> here, no explanation in the commit msg.
> > 

...

> > 
> > Anyway, I provided my 50 cents here:
> > https://lore.kernel.org/linux-ide/aLBUC116MdJqDGIJ@flawful.org/
> > 
> > (I would like to add that I think it is the disabling of clocks and
> > regulators that causes the register to be cleared, since we do call
> > ahci_platform_assert_rsts() during the first probe, so if it was the reset
> > that cleared the register, the first probe should also not have worked.)
> > 

Thank you very much for your explanation. To add some context:
In our system, the ports-implemented register has already been configured by the firmware
(which is U-Boot on the HiFive Premier P550 board).
Therefore, when entering the kernel, the value of this register is correctly set to 0x1.

During probe, ahci_platform_enable_resources → ahci_platform_deassert_rsts is called.
And when the driver is removed, ahci_platform_disable_resources
→ ahci_platform_assert_rsts is triggered.
This reset operation causes the register to be restored to 0.
According to the IP databook, this register is indeed set to 0 after reset.

This is my understanding. I'd greatly appreciate it if you point out any issues.

> > 
> > Not sure if it relevant to mention this reply to Rob's review comment in the
> > commit message, but perhaps it should have been mentioned in the change log.
> 
> Reviewer questions for more serious stuff happen for a reason, so when
> discussion is resolved somehow differently than reviewer suggested, it
> pretty often deserves explanation in commit msg.
> 
> Well, in changelog as absolute minimum. No explanation happened here in
> the changelog, nor in the commit msg.

Thank you very much for your suggestion.
I'll add explanations in the commit message and changelogs for the next patch.

Best regards,
Yulin