0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =========================
0004 MDIO bus and PHYs in ACPI
0005 =========================
0006
0007 The PHYs on an MDIO bus [phy] are probed and registered using
0008 fwnode_mdiobus_register_phy().
0009
0010 Later, for connecting these PHYs to their respective MACs, the PHYs registered
0011 on the MDIO bus have to be referenced.
0012
0013 This document introduces two _DSD properties that are to be used
0014 for connecting PHYs on the MDIO bus [dsd-properties-rules] to the MAC layer.
0015
0016 These properties are defined in accordance with the "Device
0017 Properties UUID For _DSD" [dsd-guide] document and the
0018 daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
0019 Data Descriptors containing them.
0020
0021 phy-handle
0022 ----------
0023 For each MAC node, a device property "phy-handle" is used to reference
0024 the PHY that is registered on an MDIO bus. This is mandatory for
0025 network interfaces that have PHYs connected to MAC via MDIO bus.
0026
0027 During the MDIO bus driver initialization, PHYs on this bus are probed
0028 using the _ADR object as shown below and are registered on the MDIO bus.
0029
0030 .. code-block:: none
0031
0032 Scope(\_SB.MDI0)
0033 {
0034 Device(PHY1) {
0035 Name (_ADR, 0x1)
0036 } // end of PHY1
0037
0038 Device(PHY2) {
0039 Name (_ADR, 0x2)
0040 } // end of PHY2
0041 }
0042
0043 Later, during the MAC driver initialization, the registered PHY devices
0044 have to be retrieved from the MDIO bus. For this, the MAC driver needs
0045 references to the previously registered PHYs which are provided
0046 as device object references (e.g. \_SB.MDI0.PHY1).
0047
0048 phy-mode
0049 --------
0050 The "phy-mode" _DSD property is used to describe the connection to
0051 the PHY. The valid values for "phy-mode" are defined in [ethernet-controller].
0052
0053 managed
0054 -------
0055 Optional property, which specifies the PHY management type.
0056 The valid values for "managed" are defined in [ethernet-controller].
0057
0058 fixed-link
0059 ----------
0060 The "fixed-link" is described by a data-only subnode of the
0061 MAC port, which is linked in the _DSD package via
0062 hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b
0063 in accordance with [dsd-guide] "_DSD Implementation Guide" document).
0064 The subnode should comprise a required property ("speed") and
0065 possibly the optional ones - complete list of parameters and
0066 their values are specified in [ethernet-controller].
0067
0068 The following ASL example illustrates the usage of these properties.
0069
0070 DSDT entry for MDIO node
0071 ------------------------
0072
0073 The MDIO bus has an SoC component (MDIO controller) and a platform
0074 component (PHYs on the MDIO bus).
0075
0076 a) Silicon Component
0077 This node describes the MDIO controller, MDI0
0078 ---------------------------------------------
0079
0080 .. code-block:: none
0081
0082 Scope(_SB)
0083 {
0084 Device(MDI0) {
0085 Name(_HID, "NXP0006")
0086 Name(_CCA, 1)
0087 Name(_UID, 0)
0088 Name(_CRS, ResourceTemplate() {
0089 Memory32Fixed(ReadWrite, MDI0_BASE, MDI_LEN)
0090 Interrupt(ResourceConsumer, Level, ActiveHigh, Shared)
0091 {
0092 MDI0_IT
0093 }
0094 }) // end of _CRS for MDI0
0095 } // end of MDI0
0096 }
0097
0098 b) Platform Component
0099 The PHY1 and PHY2 nodes represent the PHYs connected to MDIO bus MDI0
0100 ---------------------------------------------------------------------
0101
0102 .. code-block:: none
0103
0104 Scope(\_SB.MDI0)
0105 {
0106 Device(PHY1) {
0107 Name (_ADR, 0x1)
0108 } // end of PHY1
0109
0110 Device(PHY2) {
0111 Name (_ADR, 0x2)
0112 } // end of PHY2
0113 }
0114
0115 DSDT entries representing MAC nodes
0116 -----------------------------------
0117
0118 Below are the MAC nodes where PHY nodes are referenced.
0119 phy-mode and phy-handle are used as explained earlier.
0120 ------------------------------------------------------
0121
0122 .. code-block:: none
0123
0124 Scope(\_SB.MCE0.PR17)
0125 {
0126 Name (_DSD, Package () {
0127 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0128 Package () {
0129 Package (2) {"phy-mode", "rgmii-id"},
0130 Package (2) {"phy-handle", \_SB.MDI0.PHY1}
0131 }
0132 })
0133 }
0134
0135 Scope(\_SB.MCE0.PR18)
0136 {
0137 Name (_DSD, Package () {
0138 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0139 Package () {
0140 Package (2) {"phy-mode", "rgmii-id"},
0141 Package (2) {"phy-handle", \_SB.MDI0.PHY2}}
0142 }
0143 })
0144 }
0145
0146 MAC node example where "managed" property is specified.
0147 -------------------------------------------------------
0148
0149 .. code-block:: none
0150
0151 Scope(\_SB.PP21.ETH0)
0152 {
0153 Name (_DSD, Package () {
0154 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0155 Package () {
0156 Package () {"phy-mode", "sgmii"},
0157 Package () {"managed", "in-band-status"}
0158 }
0159 })
0160 }
0161
0162 MAC node example with a "fixed-link" subnode.
0163 ---------------------------------------------
0164
0165 .. code-block:: none
0166
0167 Scope(\_SB.PP21.ETH1)
0168 {
0169 Name (_DSD, Package () {
0170 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0171 Package () {
0172 Package () {"phy-mode", "sgmii"},
0173 },
0174 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
0175 Package () {
0176 Package () {"fixed-link", "LNK0"}
0177 }
0178 })
0179 Name (LNK0, Package(){ // Data-only subnode of port
0180 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0181 Package () {
0182 Package () {"speed", 1000},
0183 Package () {"full-duplex", 1}
0184 }
0185 })
0186 }
0187
0188 References
0189 ==========
0190
0191 [phy] Documentation/networking/phy.rst
0192
0193 [dsd-properties-rules]
0194 Documentation/firmware-guide/acpi/DSD-properties-rules.rst
0195
0196 [ethernet-controller]
0197 Documentation/devicetree/bindings/net/ethernet-controller.yaml
0198
0199 [dsd-guide] DSD Guide.
0200 https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
0201 2021-11-30.
