.. SPDX-License-Identifier: GPL-2.0

=========================
MDIO bus and PHYs in ACPI
=========================

The PHYs on an MDIO bus [1] are probed and registered using
fwnode_mdiobus_register_phy().
Later, for connecting these PHYs to MAC, the PHYs registered on the
mdiobus have to be referenced.

UUID given below should be used as mentioned in the "Device Properties
UUID For _DSD" [2] document.
   - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301

This document introduces two _DSD properties that are to be used
for PHYs on the MDIO bus.[3]

phy-handle
----------
For each MAC node, a device property "phy-handle" is used to reference
the PHY that is registered on an MDIO bus. This is mandatory for
network interfaces that have PHYs connected to MAC via MDIO bus.

During the MDIO bus driver initialization, PHYs on this bus are probed
using the _ADR object as shown below and are registered on the mdio bus.

::
      Scope(\_SB.MDI0)
      {
        Device(PHY1) {
          Name (_ADR, 0x1)
        } // end of PHY1

        Device(PHY2) {
          Name (_ADR, 0x2)
        } // end of PHY2
      }

Later, during the MAC driver initialization, the registered PHY devices
have to be retrieved from the mdio bus. For this, MAC driver needs
reference to the previously registered PHYs which are provided
using reference to the device as {\_SB.MDI0.PHY1}.

phy-mode
--------
The "phy-mode" _DSD property is used to describe the connection to
the PHY. The valid values for "phy-mode" are defined in [4].


An ASL example of this is shown below.

DSDT entry for MDIO node
------------------------
The MDIO bus has an SoC component(mdio controller) and a platform
component(PHYs on the mdiobus).

a) Silicon Component
This node describes the MDIO controller,MDI0
--------------------------------------------
::
	Scope(_SB)
	{
	  Device(MDI0) {
	    Name(_HID, "NXP0006")
	    Name(_CCA, 1)
	    Name(_UID, 0)
	    Name(_CRS, ResourceTemplate() {
	      Memory32Fixed(ReadWrite, MDI0_BASE, MDI_LEN)
	      Interrupt(ResourceConsumer, Level, ActiveHigh, Shared)
	       {
		 MDI0_IT
	       }
	    }) // end of _CRS for MDI0
	  } // end of MDI0
	}

b) Platform Component
This node defines the PHYs that are connected to the MDIO bus, MDI0
-------------------------------------------------------------------
::
	Scope(\_SB.MDI0)
	{
	  Device(PHY1) {
	    Name (_ADR, 0x1)
	  } // end of PHY1

	  Device(PHY2) {
	    Name (_ADR, 0x2)
	  } // end of PHY2
	}


Below are the MAC nodes where PHY nodes are referenced.
phy-mode and phy-handle are used as explained earlier.
------------------------------------------------------
::
	Scope(\_SB.MCE0.PR17)
	{
	  Name (_DSD, Package () {
	     ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
		 Package () {
		     Package (2) {"phy-mode", "rgmii-id"},
		     Package (2) {"phy-handle", \_SB.MDI0.PHY1}
	      }
	   })
	}

	Scope(\_SB.MCE0.PR18)
	{
	  Name (_DSD, Package () {
	    ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
		Package () {
		    Package (2) {"phy-mode", "rgmii-id"},
		    Package (2) {"phy-handle", \_SB.MDI0.PHY2}}
	    }
	  })
	}

References
==========

[1] Documentation/networking/phy.rst

[2] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf

[3] Documentation/firmware-guide/acpi/DSD-properties-rules.rst

[4] Documentation/devicetree/bindings/net/ethernet-controller.yaml
