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

[Beiyan Yun]

> On 23 Sep 2025, at 8:44 PM, Yao Zi <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>>
> 
> 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.

> 
> 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