diff mbox series

[net-next,v8,01/15] Documentation: ACPI: DSD: Document MDIO PHY

Message ID 20210610163917.4138412-2-ciorneiioana@gmail.com (mailing list archive)
State Superseded
Delegated to: Netdev Maintainers
Headers show
Series ACPI support for dpaa2 driver | expand

Checks

Context Check Description
netdev/cover_letter success Link
netdev/fixes_present success Link
netdev/patch_count success Link
netdev/tree_selection success Clearly marked for net-next
netdev/subject_prefix success Link
netdev/cc_maintainers success CCed 5 of 5 maintainers
netdev/source_inline success Was 0 now: 0
netdev/verify_signedoff success Link
netdev/module_param success Was 0 now: 0
netdev/build_32bit success Errors and warnings before: 0 this patch: 0
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/verify_fixes success Link
netdev/checkpatch warning WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
netdev/build_allmodconfig_warn success Errors and warnings before: 0 this patch: 0
netdev/header_inline success Link

Commit Message

Ioana Ciornei June 10, 2021, 4:39 p.m. UTC 
From: Calvin Johnson <calvin.johnson@oss.nxp.com>

Introduce ACPI mechanism to get PHYs registered on a MDIO bus and
provide them to be connected to MAC.

Describe properties "phy-handle" and "phy-mode".

Signed-off-by: Calvin Johnson <calvin.johnson@oss.nxp.com>
Signed-off-by: Ioana Ciornei <ioana.ciornei@nxp.com>
---

Changes in v8: None
Changes in v7: None
Changes in v6:
- Minor cleanup

Changes in v5:
- More cleanup

Changes in v4:
- More cleanup

Changes in v3: None
Changes in v2:
- Updated with more description in document

 Documentation/firmware-guide/acpi/dsd/phy.rst | 133 ++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 Documentation/firmware-guide/acpi/dsd/phy.rst

Comments

Rafael J. Wysocki June 10, 2021, 6:05 p.m. UTC | #1 
On Thu, Jun 10, 2021 at 6:40 PM Ioana Ciornei <ciorneiioana@gmail.com> wrote:
>
> From: Calvin Johnson <calvin.johnson@oss.nxp.com>
>
> Introduce ACPI mechanism to get PHYs registered on a MDIO bus and
> provide them to be connected to MAC.

This is not an "ACPI mechanism", because it is not part of the ACPI
specification or support documentation thereof.

I would call it "a mechanism based on generic ACPI _DSD device
properties definition []1]".  And provide a reference to the _DSD
properties definition document.

With that changed, you can add

Acked-by: Rafael J. Wysocki <rafael@kernel.org>

to this patch.

Note, however, that within the traditional ACPI framework, the _DSD
properties are consumed by the driver that binds to the device
represented by the ACPI device object containing the _DSD in question
in its scope, while in this case IIUC the properties are expected to
be consumed by the general networking code in the kernel.  That is not
wrong in principle, but it means that operating systems other than
Linux are not likely to be using them.

> Describe properties "phy-handle" and "phy-mode".
>
> Signed-off-by: Calvin Johnson <calvin.johnson@oss.nxp.com>
> Signed-off-by: Ioana Ciornei <ioana.ciornei@nxp.com>
> ---
>
> Changes in v8: None
> Changes in v7: None
> Changes in v6:
> - Minor cleanup
>
> Changes in v5:
> - More cleanup
>
> Changes in v4:
> - More cleanup
>
> Changes in v3: None
> Changes in v2:
> - Updated with more description in document
>
>  Documentation/firmware-guide/acpi/dsd/phy.rst | 133 ++++++++++++++++++
>  1 file changed, 133 insertions(+)
>  create mode 100644 Documentation/firmware-guide/acpi/dsd/phy.rst
>
> diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst
> new file mode 100644
> index 000000000000..7d01ae8b3cc6
> --- /dev/null
> +++ b/Documentation/firmware-guide/acpi/dsd/phy.rst
> @@ -0,0 +1,133 @@
> +.. 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 their respective MACs, the PHYs registered
> +on the MDIO bus have to be referenced.
> +
> +This document introduces two _DSD properties that are to be used
> +for connecting PHYs on the MDIO bus [3] to the MAC layer.
> +
> +These properties are defined in accordance with the "Device
> +Properties UUID For _DSD" [2] document and the
> +daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
> +Data Descriptors containing them.
> +
> +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, the MAC driver needs
> +references to the previously registered PHYs which are provided
> +as device object references (e.g. \_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].
> +
> +The following ASL example illustrates the usage of these properties.
> +
> +DSDT entry for MDIO node
> +------------------------
> +
> +The MDIO bus has an SoC component (MDIO controller) and a platform
> +component (PHYs on the MDIO bus).
> +
> +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
> +The PHY1 and PHY2 nodes represent the PHYs connected to MDIO bus MDI0
> +---------------------------------------------------------------------
> +::
> +       Scope(\_SB.MDI0)
> +       {
> +         Device(PHY1) {
> +           Name (_ADR, 0x1)
> +         } // end of PHY1
> +
> +         Device(PHY2) {
> +           Name (_ADR, 0x2)
> +         } // end of PHY2
> +       }
> +
> +DSDT entries representing MAC nodes
> +-----------------------------------
> +
> +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
> --
> 2.31.1
>
Grant Likely June 10, 2021, 6:11 p.m. UTC | #2 
On 10/06/2021 17:39, Ioana Ciornei wrote:
> From: Calvin Johnson <calvin.johnson@oss.nxp.com>
> 
> Introduce ACPI mechanism to get PHYs registered on a MDIO bus and
> provide them to be connected to MAC.
> 
> Describe properties "phy-handle" and "phy-mode".
> 
> Signed-off-by: Calvin Johnson <calvin.johnson@oss.nxp.com>
> Signed-off-by: Ioana Ciornei <ioana.ciornei@nxp.com>

Looks reasonable to me. I'm not a kernel maintainer any more, so my 
Acked-by: may not be very valuable, but here it is anyway:

Acked-by: Grant Likely <grant.likely@arm.com>

> --- >
> Changes in v8: None
> Changes in v7: None
> Changes in v6:
> - Minor cleanup
> 
> Changes in v5:
> - More cleanup
> 
> Changes in v4:
> - More cleanup
> 
> Changes in v3: None
> Changes in v2:
> - Updated with more description in document
> 
>   Documentation/firmware-guide/acpi/dsd/phy.rst | 133 ++++++++++++++++++
>   1 file changed, 133 insertions(+)
>   create mode 100644 Documentation/firmware-guide/acpi/dsd/phy.rst
> 
> diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst
> new file mode 100644
> index 000000000000..7d01ae8b3cc6
> --- /dev/null
> +++ b/Documentation/firmware-guide/acpi/dsd/phy.rst
> @@ -0,0 +1,133 @@
> +.. 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 their respective MACs, the PHYs registered
> +on the MDIO bus have to be referenced.
> +
> +This document introduces two _DSD properties that are to be used
> +for connecting PHYs on the MDIO bus [3] to the MAC layer.
> +
> +These properties are defined in accordance with the "Device
> +Properties UUID For _DSD" [2] document and the
> +daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
> +Data Descriptors containing them.
> +
> +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, the MAC driver needs
> +references to the previously registered PHYs which are provided
> +as device object references (e.g. \_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].
> +
> +The following ASL example illustrates the usage of these properties.
> +
> +DSDT entry for MDIO node
> +------------------------
> +
> +The MDIO bus has an SoC component (MDIO controller) and a platform
> +component (PHYs on the MDIO bus).
> +
> +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
> +The PHY1 and PHY2 nodes represent the PHYs connected to MDIO bus MDI0
> +---------------------------------------------------------------------
> +::
> +	Scope(\_SB.MDI0)
> +	{
> +	  Device(PHY1) {
> +	    Name (_ADR, 0x1)
> +	  } // end of PHY1
> +
> +	  Device(PHY2) {
> +	    Name (_ADR, 0x2)
> +	  } // end of PHY2
> +	}
> +
> +DSDT entries representing MAC nodes
> +-----------------------------------
> +
> +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
>
Grant Likely June 10, 2021, 6:23 p.m. UTC | #3 
On 10/06/2021 19:05, Rafael J. Wysocki wrote:
> On Thu, Jun 10, 2021 at 6:40 PM Ioana Ciornei <ciorneiioana@gmail.com> wrote:
>>
>> From: Calvin Johnson <calvin.johnson@oss.nxp.com>
>>
>> Introduce ACPI mechanism to get PHYs registered on a MDIO bus and
>> provide them to be connected to MAC.
> 
> This is not an "ACPI mechanism", because it is not part of the ACPI
> specification or support documentation thereof.
> 
> I would call it "a mechanism based on generic ACPI _DSD device
> properties definition []1]".  And provide a reference to the _DSD
> properties definition document.
> 
> With that changed, you can add
> 
> Acked-by: Rafael J. Wysocki <rafael@kernel.org>
> 
> to this patch.
> 
> Note, however, that within the traditional ACPI framework, the _DSD
> properties are consumed by the driver that binds to the device
> represented by the ACPI device object containing the _DSD in question
> in its scope, while in this case IIUC the properties are expected to
> be consumed by the general networking code in the kernel.  That is not
> wrong in principle, but it means that operating systems other than
> Linux are not likely to be using them.
> 

Doesn't this land at the level of device drivers though? None of this 
data needs to be consumed by the OS generic ACPI parsing code, but the 
network device driver can use it to parse the MDIO and MAC configuraiton 
and set itself up appropriately.

The only difference in the Linux case is that the code is implemented in 
a way that can be leveraged by other network drivers instead of being 
entirely contained within the dpaa driver.

g.

>> Describe properties "phy-handle" and "phy-mode".
>>
>> Signed-off-by: Calvin Johnson <calvin.johnson@oss.nxp.com>
>> Signed-off-by: Ioana Ciornei <ioana.ciornei@nxp.com>
>> ---
>>
>> Changes in v8: None
>> Changes in v7: None
>> Changes in v6:
>> - Minor cleanup
>>
>> Changes in v5:
>> - More cleanup
>>
>> Changes in v4:
>> - More cleanup
>>
>> Changes in v3: None
>> Changes in v2:
>> - Updated with more description in document
>>
>>   Documentation/firmware-guide/acpi/dsd/phy.rst | 133 ++++++++++++++++++
>>   1 file changed, 133 insertions(+)
>>   create mode 100644 Documentation/firmware-guide/acpi/dsd/phy.rst
>>
>> diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst
>> new file mode 100644
>> index 000000000000..7d01ae8b3cc6
>> --- /dev/null
>> +++ b/Documentation/firmware-guide/acpi/dsd/phy.rst
>> @@ -0,0 +1,133 @@
>> +.. 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 their respective MACs, the PHYs registered
>> +on the MDIO bus have to be referenced.
>> +
>> +This document introduces two _DSD properties that are to be used
>> +for connecting PHYs on the MDIO bus [3] to the MAC layer.
>> +
>> +These properties are defined in accordance with the "Device
>> +Properties UUID For _DSD" [2] document and the
>> +daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
>> +Data Descriptors containing them.
>> +
>> +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, the MAC driver needs
>> +references to the previously registered PHYs which are provided
>> +as device object references (e.g. \_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].
>> +
>> +The following ASL example illustrates the usage of these properties.
>> +
>> +DSDT entry for MDIO node
>> +------------------------
>> +
>> +The MDIO bus has an SoC component (MDIO controller) and a platform
>> +component (PHYs on the MDIO bus).
>> +
>> +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
>> +The PHY1 and PHY2 nodes represent the PHYs connected to MDIO bus MDI0
>> +---------------------------------------------------------------------
>> +::
>> +       Scope(\_SB.MDI0)
>> +       {
>> +         Device(PHY1) {
>> +           Name (_ADR, 0x1)
>> +         } // end of PHY1
>> +
>> +         Device(PHY2) {
>> +           Name (_ADR, 0x2)
>> +         } // end of PHY2
>> +       }
>> +
>> +DSDT entries representing MAC nodes
>> +-----------------------------------
>> +
>> +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
>> --
>> 2.31.1
>>
Rafael J. Wysocki June 10, 2021, 6:31 p.m. UTC | #4 
On Thu, Jun 10, 2021 at 8:23 PM Grant Likely <grant.likely@arm.com> wrote:
>
> On 10/06/2021 19:05, Rafael J. Wysocki wrote:
> > On Thu, Jun 10, 2021 at 6:40 PM Ioana Ciornei <ciorneiioana@gmail.com> wrote:
> >>
> >> From: Calvin Johnson <calvin.johnson@oss.nxp.com>
> >>
> >> Introduce ACPI mechanism to get PHYs registered on a MDIO bus and
> >> provide them to be connected to MAC.
> >
> > This is not an "ACPI mechanism", because it is not part of the ACPI
> > specification or support documentation thereof.
> >
> > I would call it "a mechanism based on generic ACPI _DSD device
> > properties definition []1]".  And provide a reference to the _DSD
> > properties definition document.
> >
> > With that changed, you can add
> >
> > Acked-by: Rafael J. Wysocki <rafael@kernel.org>
> >
> > to this patch.
> >
> > Note, however, that within the traditional ACPI framework, the _DSD
> > properties are consumed by the driver that binds to the device
> > represented by the ACPI device object containing the _DSD in question
> > in its scope, while in this case IIUC the properties are expected to
> > be consumed by the general networking code in the kernel.  That is not
> > wrong in principle, but it means that operating systems other than
> > Linux are not likely to be using them.
> >
>
> Doesn't this land at the level of device drivers though? None of this
> data needs to be consumed by the OS generic ACPI parsing code, but the
> network device driver can use it to parse the MDIO and MAC configuraiton
> and set itself up appropriately.

That's right in general, which is why I said that doing it this way
wasn't wrong.
diff mbox series

Patch

diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst
new file mode 100644
index 000000000000..7d01ae8b3cc6
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/dsd/phy.rst
@@ -0,0 +1,133 @@ 
+.. 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 their respective MACs, the PHYs registered
+on the MDIO bus have to be referenced.
+
+This document introduces two _DSD properties that are to be used
+for connecting PHYs on the MDIO bus [3] to the MAC layer.
+
+These properties are defined in accordance with the "Device
+Properties UUID For _DSD" [2] document and the
+daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
+Data Descriptors containing them.
+
+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, the MAC driver needs
+references to the previously registered PHYs which are provided
+as device object references (e.g. \_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].
+
+The following ASL example illustrates the usage of these properties.
+
+DSDT entry for MDIO node
+------------------------
+
+The MDIO bus has an SoC component (MDIO controller) and a platform
+component (PHYs on the MDIO bus).
+
+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
+The PHY1 and PHY2 nodes represent the PHYs connected to MDIO bus MDI0
+---------------------------------------------------------------------
+::
+	Scope(\_SB.MDI0)
+	{
+	  Device(PHY1) {
+	    Name (_ADR, 0x1)
+	  } // end of PHY1
+
+	  Device(PHY2) {
+	    Name (_ADR, 0x2)
+	  } // end of PHY2
+	}
+
+DSDT entries representing MAC nodes
+-----------------------------------
+
+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