[PATCH RESEND 4/4] doc: bindings: add Aquantia PHY node's "firmware-name" binding

[Yao Zi]

On Fri, Sep 26, 2025 at 05:30:03PM +0800, Beiyan Yun wrote:
> 
> 
> > On 26 Sep 2025, at 4:22 PM, Beiyan Yun <root at infi.wang> wrote:
> > 
> > 
> > 
> >> On 23 Sep 2025, at 8:44 PM, Yao Zi <ziyao at disroot.org <mailto:ziyao at disroot.org>> wrote:
> >> 
> >> On Tue, Sep 23, 2025 at 03:13:01PM +0800, Beiyan Yun wrote:
> >>> With the switch to generic firmware loader, "firmware-name" binding
> >>> was introduced to define the firmware filename.
> >>> Provide the document and usage examples.
> >>> 
> >>> Signed-off-by: Beiyan Yun <root at infi.wang <mailto:root at infi.wang> <mailto:root at infi.wang>>
> >> 
> >> IMO this patch should go before the driver change.
> >> 
> >>> ---
> >>> 
> >>> doc/device-tree-bindings/net/aquantia-phy.txt | 30 +++++++++++++++++++
> >>> 1 file changed, 30 insertions(+)
> >>> 
> >>> diff --git a/doc/device-tree-bindings/net/aquantia-phy.txt b/doc/device-tree-bindings/net/aquantia-phy.txt
> >>> index 7dd3d45df12..1227c04d04f 100644
> >>> --- a/doc/device-tree-bindings/net/aquantia-phy.txt
> >>> +++ b/doc/device-tree-bindings/net/aquantia-phy.txt
> >>> @@ -11,15 +11,45 @@ a custom firmware is needed for each integration of a PHY.
> >>> Several optional bindings are defined that allow these configuration points to
> >>> be driven by the PHY driver and reduce dependency on specific FW versions.
> >>> 
> >>> +Aquantia PHY's firmware is often provided by PHY-resident SPI flash; if absent
> >>> +or outdated, U-Boot can upload firmware over MDIO during PHY initialization.
> >>> +The driver uploads only when the PHY reports missing firmware or a fault.
> >>> +
> >>> Optional properties:
> >>> mdi-reversal: 0 or 1 indicating that reversal must be disabled/enabled.
> >>>              Firmware default is used if the property is missing.
> >>> smb-addr:     I2C/SMBus address to use, firmware default is used if the property
> >>>              is missing.
> >>> +firmware-name: String containing the filename of the PHY firmware to load
> >>> +               (only when CONFIG_PHY_AQUANTIA_UPLOAD_FW is enabled).
> >> 
> >> This looks good to me, but I have a question: should we switch to the
> >> upstream binding for aquantia phys? It's already documented as
> >> marvell,aquantia.yaml, and we could avoid the burden of maintaining a
> >> separate binding file.
> >> 
> >> The "firmware-name" property is already described in the upstream
> >> marvell,aquantia.yaml, and it only misses the smb-addr property. The
> >> only U-Boot boards making use of this property are fsl-sch-30841 and
> >> fsl-sch-30842, thus such conversion shouldn't be a big job.
> > 
> > Good point. I’ll add a bit more info in related Kconfig options and drop the doc.
> 
> Hmm, I’m a bit lost. Here’s some of my concerns:
> 
> - Upstream binding has an optional nvmem cell as firmware source, such mechanism
>    simply doesn’t exist in U-Boot. This could be misleading.

I think it's okay to support part of the binding in U-Boot: the goal is
to reuse upstream binding, avoiding the burden of maintaining a
duplication, and making it possible to share devicetree between kernel
and firmware (same binding means same ABI).

I did a brief search in the upstream dts tree, and found no consumer
of this nvmem-cells property, thus I don't think it's a problem, at
least for now.

> - About “smb-addr”, what’s the best move? Do we upstream them to Linux?

Yes, if it's really necesary for the phy to work. If you decide to
adapt the upstream binding in the series, then I suggest upstreaming the
property to dt-bindings first.

Anyway I think your original patch looks good to me as well, it isn't a
must (at least to me) to switch to the upstream binding.

> Any idea on how to fix these issues?
> 
> Thanks,
> Beiyan Yun

Best regards,
Yao Zi