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 ::
  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
  42 Later, during the MAC driver initialization, the registered PHY devices
  43 have to be retrieved from the MDIO bus. For this, the MAC driver needs
  44 references to the previously registered PHYs which are provided
  45 as device object references (e.g. \_SB.MDI0.PHY1).
  46
  47 phy-mode
  48 --------
  49 The "phy-mode" _DSD property is used to describe the connection to
  50 the PHY. The valid values for "phy-mode" are defined in [4].
  51
  52 The following ASL example illustrates the usage of these properties.
  53
  54 DSDT entry for MDIO node
  55 ------------------------
  56
  57 The MDIO bus has an SoC component (MDIO controller) and a platform
  58 component (PHYs on the MDIO bus).
  59
  60 a) Silicon Component
  61 This 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
  80 b) Platform Component
  81 The 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
  95 DSDT entries representing MAC nodes
  96 -----------------------------------
  97
  98 Below are the MAC nodes where PHY nodes are referenced.
  99 phy-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
 124 References
 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