Documentation/firmware-guide/acpi/dsd/phy.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =========================
   4 MDIO bus and PHYs in ACPI
   5 =========================
   6
   7 The PHYs on an MDIO bus [1] are probed and registered using
   8 fwnode_mdiobus_register_phy().
   9
  10 Later, for connecting these PHYs to their respective MACs, the PHYs registered
  11 on the MDIO bus have to be referenced.
  12
  13 This document introduces two _DSD properties that are to be used
  14 for connecting PHYs on the MDIO bus [3] to the MAC layer.
  15
  16 These properties are defined in accordance with the "Device
  17 Properties UUID For _DSD" [2] document and the
  18 daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
  19 Data Descriptors containing them.
  20
  21 phy-handle
  22 ----------
  23 For each MAC node, a device property "phy-handle" is used to reference
  24 the PHY that is registered on an MDIO bus. This is mandatory for
  25 network interfaces that have PHYs connected to MAC via MDIO bus.
  26
  27 During the MDIO bus driver initialization, PHYs on this bus are probed
  28 using 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
  43 Later, during the MAC driver initialization, the registered PHY devices
  44 have to be retrieved from the MDIO bus. For this, the MAC driver needs
  45 references to the previously registered PHYs which are provided
  46 as device object references (e.g. \_SB.MDI0.PHY1).
  47
  48 phy-mode
  49 --------
  50 The "phy-mode" _DSD property is used to describe the connection to
  51 the PHY. The valid values for "phy-mode" are defined in [4].
  52
  53 managed
  54 -------
  55 Optional property, which specifies the PHY management type.
  56 The valid values for "managed" are defined in [4].
  57
  58 fixed-link
  59 ----------
  60 The "fixed-link" is described by a data-only subnode of the
  61 MAC port, which is linked in the _DSD package via
  62 hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b
  63 in accordance with [5] "_DSD Implementation Guide" document).
  64 The subnode should comprise a required property ("speed") and
  65 possibly the optional ones - complete list of parameters and
  66 their values are specified in [4].
  67
  68 The following ASL example illustrates the usage of these properties.
  69
  70 DSDT entry for MDIO node
  71 ------------------------
  72
  73 The MDIO bus has an SoC component (MDIO controller) and a platform
  74 component (PHYs on the MDIO bus).
  75
  76 a) Silicon Component
  77 This 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
  98 b) Platform Component
  99 The 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
 115 DSDT entries representing MAC nodes
 116 -----------------------------------
 117
 118 Below are the MAC nodes where PHY nodes are referenced.
 119 phy-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
 146 MAC 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
 162 MAC 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
 188 References
 189 ==========
 190
 191 [1] Documentation/networking/phy.rst
 192
 193 [2] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
 194
 195 [3] Documentation/firmware-guide/acpi/DSD-properties-rules.rst
 196
 197 [4] Documentation/devicetree/bindings/net/ethernet-controller.yaml
 198
 199 [5] https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf