1.. SPDX-License-Identifier: GPL-2.0
2
3=========================
4MDIO bus and PHYs in ACPI
5=========================
6
7The PHYs on an MDIO bus [phy] 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 [dsd-properties-rules] to the MAC layer.
15
16These properties are defined in accordance with the "Device
17Properties UUID For _DSD" [dsd-guide] 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.. code-block:: none
31
32      Scope(\_SB.MDI0)
33      {
34        Device(PHY1) {
35          Name (_ADR, 0x1)
36        } // end of PHY1
37
38        Device(PHY2) {
39          Name (_ADR, 0x2)
40        } // end of PHY2
41      }
42
43Later, during the MAC driver initialization, the registered PHY devices
44have to be retrieved from the MDIO bus. For this, the MAC driver needs
45references to the previously registered PHYs which are provided
46as device object references (e.g. \_SB.MDI0.PHY1).
47
48phy-mode
49--------
50The "phy-mode" _DSD property is used to describe the connection to
51the PHY. The valid values for "phy-mode" are defined in [ethernet-controller].
52
53managed
54-------
55Optional property, which specifies the PHY management type.
56The valid values for "managed" are defined in [ethernet-controller].
57
58fixed-link
59----------
60The "fixed-link" is described by a data-only subnode of the
61MAC port, which is linked in the _DSD package via
62hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b
63in accordance with [dsd-guide] "_DSD Implementation Guide" document).
64The subnode should comprise a required property ("speed") and
65possibly the optional ones - complete list of parameters and
66their values are specified in [ethernet-controller].
67
68The following ASL example illustrates the usage of these properties.
69
70DSDT entry for MDIO node
71------------------------
72
73The MDIO bus has an SoC component (MDIO controller) and a platform
74component (PHYs on the MDIO bus).
75
76a) Silicon Component
77This node describes the MDIO controller, MDI0
78---------------------------------------------
79
80.. code-block:: none
81
82	Scope(_SB)
83	{
84	  Device(MDI0) {
85	    Name(_HID, "NXP0006")
86	    Name(_CCA, 1)
87	    Name(_UID, 0)
88	    Name(_CRS, ResourceTemplate() {
89	      Memory32Fixed(ReadWrite, MDI0_BASE, MDI_LEN)
90	      Interrupt(ResourceConsumer, Level, ActiveHigh, Shared)
91	       {
92		 MDI0_IT
93	       }
94	    }) // end of _CRS for MDI0
95	  } // end of MDI0
96	}
97
98b) Platform Component
99The PHY1 and PHY2 nodes represent the PHYs connected to MDIO bus MDI0
100---------------------------------------------------------------------
101
102.. code-block:: none
103
104	Scope(\_SB.MDI0)
105	{
106	  Device(PHY1) {
107	    Name (_ADR, 0x1)
108	  } // end of PHY1
109
110	  Device(PHY2) {
111	    Name (_ADR, 0x2)
112	  } // end of PHY2
113	}
114
115DSDT entries representing MAC nodes
116-----------------------------------
117
118Below are the MAC nodes where PHY nodes are referenced.
119phy-mode and phy-handle are used as explained earlier.
120------------------------------------------------------
121
122.. code-block:: none
123
124	Scope(\_SB.MCE0.PR17)
125	{
126	  Name (_DSD, Package () {
127	     ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
128		 Package () {
129		     Package (2) {"phy-mode", "rgmii-id"},
130		     Package (2) {"phy-handle", \_SB.MDI0.PHY1}
131	      }
132	   })
133	}
134
135	Scope(\_SB.MCE0.PR18)
136	{
137	  Name (_DSD, Package () {
138	    ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
139		Package () {
140		    Package (2) {"phy-mode", "rgmii-id"},
141		    Package (2) {"phy-handle", \_SB.MDI0.PHY2}}
142	    }
143	  })
144	}
145
146MAC node example where "managed" property is specified.
147-------------------------------------------------------
148
149.. code-block:: none
150
151	Scope(\_SB.PP21.ETH0)
152	{
153	  Name (_DSD, Package () {
154	     ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
155		 Package () {
156		     Package () {"phy-mode", "sgmii"},
157		     Package () {"managed", "in-band-status"}
158		 }
159	   })
160	}
161
162MAC node example with a "fixed-link" subnode.
163---------------------------------------------
164
165.. code-block:: none
166
167	Scope(\_SB.PP21.ETH1)
168	{
169	  Name (_DSD, Package () {
170	    ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
171		 Package () {
172		     Package () {"phy-mode", "sgmii"},
173		 },
174	    ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
175		 Package () {
176		     Package () {"fixed-link", "LNK0"}
177		 }
178	  })
179	  Name (LNK0, Package(){ // Data-only subnode of port
180	    ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
181		 Package () {
182		     Package () {"speed", 1000},
183		     Package () {"full-duplex", 1}
184		 }
185	  })
186	}
187
188References
189==========
190
191[phy] Documentation/networking/phy.rst
192
193[dsd-properties-rules]
194    Documentation/firmware-guide/acpi/DSD-properties-rules.rst
195
196[ethernet-controller]
197    Documentation/devicetree/bindings/net/ethernet-controller.yaml
198
199[dsd-guide] DSD Guide.
200    https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
201    2021-11-30.
202