xref: /openbmc/linux/Documentation/firmware-guide/acpi/dsd/phy.rst (revision f7af616c632ee2ac3af0876fe33bf9e0232e665a) 
1.. SPDX-License-Identifier: GPL-2.0
2
3=========================
4MDIO bus and PHYs in ACPI
5=========================
6
7The PHYs on an MDIO bus [1] are probed and registered using
8fwnode_mdiobus_register_phy().
9
10Later, for connecting these PHYs to their respective MACs, the PHYs registered
11on the MDIO bus have to be referenced.
12
13This document introduces two _DSD properties that are to be used
14for connecting PHYs on the MDIO bus [3] to the MAC layer.
15
16These properties are defined in accordance with the "Device
17Properties UUID For _DSD" [2] document and the
18daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
19Data Descriptors containing them.
20
21phy-handle
22----------
23For each MAC node, a device property "phy-handle" is used to reference
24the PHY that is registered on an MDIO bus. This is mandatory for
25network interfaces that have PHYs connected to MAC via MDIO bus.
26
27During the MDIO bus driver initialization, PHYs on this bus are probed
28using the _ADR object as shown below and are registered on the MDIO bus.
29
30::
31      Scope(\_SB.MDI0)
32      {
33        Device(PHY1) {
34          Name (_ADR, 0x1)
35        } // end of PHY1
36
37        Device(PHY2) {
38          Name (_ADR, 0x2)
39        } // end of PHY2
40      }
41
42Later, during the MAC driver initialization, the registered PHY devices
43have to be retrieved from the MDIO bus. For this, the MAC driver needs
44references to the previously registered PHYs which are provided
45as device object references (e.g. \_SB.MDI0.PHY1).
46
47phy-mode
48--------
49The "phy-mode" _DSD property is used to describe the connection to
50the PHY. The valid values for "phy-mode" are defined in [4].
51
52The following ASL example illustrates the usage of these properties.
53
54DSDT entry for MDIO node
55------------------------
56
57The MDIO bus has an SoC component (MDIO controller) and a platform
58component (PHYs on the MDIO bus).
59
60a) Silicon Component
61This node describes the MDIO controller, MDI0
62---------------------------------------------
63::
64	Scope(_SB)
65	{
66	  Device(MDI0) {
67	    Name(_HID, "NXP0006")
68	    Name(_CCA, 1)
69	    Name(_UID, 0)
70	    Name(_CRS, ResourceTemplate() {
71	      Memory32Fixed(ReadWrite, MDI0_BASE, MDI_LEN)
72	      Interrupt(ResourceConsumer, Level, ActiveHigh, Shared)
73	       {
74		 MDI0_IT
75	       }
76	    }) // end of _CRS for MDI0
77	  } // end of MDI0
78	}
79
80b) Platform Component
81The PHY1 and PHY2 nodes represent the PHYs connected to MDIO bus MDI0
82---------------------------------------------------------------------
83::
84	Scope(\_SB.MDI0)
85	{
86	  Device(PHY1) {
87	    Name (_ADR, 0x1)
88	  } // end of PHY1
89
90	  Device(PHY2) {
91	    Name (_ADR, 0x2)
92	  } // end of PHY2
93	}
94
95DSDT entries representing MAC nodes
96-----------------------------------
97
98Below are the MAC nodes where PHY nodes are referenced.
99phy-mode and phy-handle are used as explained earlier.
100------------------------------------------------------
101::
102	Scope(\_SB.MCE0.PR17)
103	{
104	  Name (_DSD, Package () {
105	     ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
106		 Package () {
107		     Package (2) {"phy-mode", "rgmii-id"},
108		     Package (2) {"phy-handle", \_SB.MDI0.PHY1}
109	      }
110	   })
111	}
112
113	Scope(\_SB.MCE0.PR18)
114	{
115	  Name (_DSD, Package () {
116	    ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
117		Package () {
118		    Package (2) {"phy-mode", "rgmii-id"},
119		    Package (2) {"phy-handle", \_SB.MDI0.PHY2}}
120	    }
121	  })
122	}
123
124References
125==========
126
127[1] Documentation/networking/phy.rst
128
129[2] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
130
131[3] Documentation/firmware-guide/acpi/DSD-properties-rules.rst
132
133[4] Documentation/devicetree/bindings/net/ethernet-controller.yaml
134