phy.rst

  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.