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

[Beiyan Yun]

> 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.
- About “smb-addr”, what’s the best move? Do we upstream them to Linux?

Any idea on how to fix these issues?

Thanks,
Beiyan Yun

> 
>> 
>> Best regards,
>> Yao Zi
>> 
>>> Example node:
>>> phy at 00 {
>>> 	reg = <0x00>;
>>> 	mdi-reversal = <1>;
>>> 	smb-addr = <0x25>;
>>> +	firmware-name = "aqr-firmware.cld";
>>> +};
>>> +
>>> +Example using the generic firmware loader:
>>> +/	{
>>> +	chosen {
>>> +		/* Select default firmware loader instance */
>>> +		firmware-loader = &fs_loader0;
>>> +	};
>>> +
>>> +	fs_loader0: fs-loader at 0 {
>>> +		bootph-all;
>>> +		compatible = "u-boot,fs-loader";
>>> +		/* Load from MMC0, partition 1 */
>>> +		phandlepart = <&mmc_0 1>;
>>> +	};
>>> +
>>> +	mdio {
>>> +		phy at 0 {
>>> +			reg = <0>;
>>> +			/* Load this file via the selected fs-loader */
>>> +			firmware-name = "aqr-firmware.cld";
>>> +		};
>>> +	};
>>> };
>>> -- 
>>> 2.47.3
> 
> Cheers,
> Beiyan Yun