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

[Tom Rini]

On Sun, Sep 28, 2025 at 01:04:16PM +0000, Yao Zi wrote:
> 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.

Figuring out how to use the upstream binding, and addressing issues /
short-comings there is the best path forward. Maybe U-Boot will need
some method for being able to load firmware blobs from nvme cells in the
future for example.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20250929/881a8a7f/attachment.sig>