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

[Yao Zi]

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>

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.

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
>