MDIO bus and PHYs in ACPI

MDIO PHY 등록과 MAC 연결

MDIO bus [phy]에 있는 PHY는 `fwnode_mdiobus_register_phy()`를 사용해 probe하고 등록한다. 이후 각 PHY를 대응하는 MAC에 연결하려면 MDIO bus에 등록된 PHY를 firmware description에서 참조할 수 있어야 한다.

이 문서는 MDIO bus의 PHY [dsd-properties-rules]를 MAC layer에 연결할 때 사용하는 `_DSD` property들을 소개한다. 원문은 두 property를 소개한다고 표현하며 핵심 연결 property는 `phy-handle`과 `phy-mode`다. 뒤에서는 선택적인 `managed`와 data-only `fixed-link` 표현도 함께 설명한다.

이 property들은 `Device Properties UUID For _DSD` [dsd-guide]에 맞춰 정의된다. 이를 담는 Device Data Descriptor에는 Device Properties UUID `daffd814-6eba-4d8c-8a91-bc9bbf4aa301`을 사용해야 한다.

.. SPDX-License-Identifier: GPL-2.0

=========================
MDIO bus and PHYs in ACPI
=========================

The PHYs on an MDIO bus [phy] are probed and registered using
fwnode_mdiobus_register_phy().

Later, for connecting these PHYs to their respective MACs, the PHYs registered
on the MDIO bus have to be referenced.

This document introduces two _DSD properties that are to be used
for connecting PHYs on the MDIO bus [dsd-properties-rules] to the MAC layer.

These properties are defined in accordance with the "Device
Properties UUID For _DSD" [dsd-guide] document and the
daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device
Data Descriptors containing them.

phy-handle·phy-mode·managed·fixed-link

각 MAC node는 MDIO bus에 등록된 PHY를 참조하기 위해 `phy-handle` device property를 사용한다. MDIO bus를 통해 MAC에 PHY가 연결된 network interface에는 이 property가 필수다.

MDIO bus driver 초기화 중에는 PHY를 `_ADR` object로 probe해 bus에 등록한다. 예제의 `Scope(\_SB.MDI0)` 아래 `PHY1`은 `_ADR=0x1`, `PHY2`는 `_ADR=0x2`를 사용한다.

그 뒤 MAC driver 초기화 중에는 MDIO bus에서 이미 등록된 PHY device를 다시 가져와야 한다. MAC driver에 필요한 참조는 `\_SB.MDI0.PHY1` 같은 ACPI device object reference 형태로 제공한다.

`phy-mode` `_DSD` property는 PHY와의 connection 방식을 기술한다. 유효한 `phy-mode` 값은 [ethernet-controller]에 정의되어 있다. `managed`는 PHY management type을 지정하는 선택 property이며, 그 유효한 값도 같은 binding에 정의된다.

`fixed-link`는 MAC port의 data-only subnode로 기술한다. 이 subnode는 DSD Guide에 따른 Hierarchical Data Extension UUID `dbb8e3e6-5886-4ba6-8795-1319f52a966b`으로 `_DSD` package에 연결한다.

`fixed-link` subnode에는 필수 property `speed`가 있어야 하며 선택 property도 포함할 수 있다. 가능한 parameter의 전체 목록과 값은 [ethernet-controller]에 정의되어 있으므로 ACPI 예제에 나온 property만이 전부라고 가정해서는 안 된다.

phy-handle
----------
For each MAC node, a device property "phy-handle" is used to reference
the PHY that is registered on an MDIO bus. This is mandatory for
network interfaces that have PHYs connected to MAC via MDIO bus.

During the MDIO bus driver initialization, PHYs on this bus are probed
using the _ADR object as shown below and are registered on the MDIO bus.

.. code-block:: none

      Scope(\_SB.MDI0)
      {
        Device(PHY1) {
          Name (_ADR, 0x1)
        } // end of PHY1

        Device(PHY2) {
          Name (_ADR, 0x2)
        } // end of PHY2
      }

Later, during the MAC driver initialization, the registered PHY devices
have to be retrieved from the MDIO bus. For this, the MAC driver needs
references to the previously registered PHYs which are provided
as device object references (e.g. \_SB.MDI0.PHY1).

phy-mode
--------
The "phy-mode" _DSD property is used to describe the connection to
the PHY. The valid values for "phy-mode" are defined in [ethernet-controller].

managed
-------
Optional property, which specifies the PHY management type.
The valid values for "managed" are defined in [ethernet-controller].

fixed-link
----------
The "fixed-link" is described by a data-only subnode of the
MAC port, which is linked in the _DSD package via
hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b
in accordance with [dsd-guide] "_DSD Implementation Guide" document).
The subnode should comprise a required property ("speed") and
possibly the optional ones - complete list of parameters and
their values are specified in [ethernet-controller].

MDIO controller와 PHY platform node

이어지는 ASL 예제는 위 property의 사용법을 보여준다. MDIO bus는 SoC component인 MDIO controller와 platform component인 bus 위 PHY들로 구성된다.

Silicon component node는 MDIO controller `MDI0`을 기술한다. `Scope(_SB)` 아래 `Device(MDI0)`은 `_HID="NXP0006"`, `_CCA=1`, `_UID=0`을 제공한다.

`MDI0._CRS` ResourceTemplate은 `Memory32Fixed(ReadWrite, MDI0_BASE, MDI_LEN)` memory resource와 `Interrupt(ResourceConsumer, Level, ActiveHigh, Shared)` interrupt resource를 정의하며 interrupt ID는 `MDI0_IT`다.

Platform component는 `Scope(\_SB.MDI0)` 아래의 `PHY1`과 `PHY2` node다. 이들은 MDI0 bus에 연결된 물리 PHY를 나타내며 각각 `_ADR=0x1`, `_ADR=0x2`로 bus address를 선언한다.

The following ASL example illustrates the usage of these properties.

DSDT entry for MDIO node
------------------------

The MDIO bus has an SoC component (MDIO controller) and a platform
component (PHYs on the MDIO bus).

a) Silicon Component
This node describes the MDIO controller, MDI0
---------------------------------------------

.. code-block:: none

        Scope(_SB)
        {
          Device(MDI0) {
            Name(_HID, "NXP0006")
            Name(_CCA, 1)
            Name(_UID, 0)
            Name(_CRS, ResourceTemplate() {
              Memory32Fixed(ReadWrite, MDI0_BASE, MDI_LEN)
              Interrupt(ResourceConsumer, Level, ActiveHigh, Shared)
               {
                 MDI0_IT
               }
            }) // end of _CRS for MDI0
          } // end of MDI0
        }

b) Platform Component
The PHY1 and PHY2 nodes represent the PHYs connected to MDIO bus MDI0
---------------------------------------------------------------------

.. code-block:: none

        Scope(\_SB.MDI0)
        {
          Device(PHY1) {
            Name (_ADR, 0x1)
          } // end of PHY1

          Device(PHY2) {
            Name (_ADR, 0x2)
          } // end of PHY2
        }

MAC node의 PHY 참조

다음 DSDT entry들은 PHY node를 참조하는 MAC node다. 앞에서 설명한 `phy-mode`와 `phy-handle`을 Device Properties UUID package 안에 함께 둔다.

`Scope(\_SB.MCE0.PR17)`은 `phy-mode="rgmii-id"`와 `phy-handle=\_SB.MDI0.PHY1`을 제공한다. 따라서 PR17 MAC port는 RGMII internal delay mode로 MDIO address 1의 PHY1에 연결된다.

`Scope(\_SB.MCE0.PR18)`은 같은 `phy-mode="rgmii-id"`를 사용하지만 `phy-handle=\_SB.MDI0.PHY2`를 제공한다. 따라서 PR18은 address 2의 PHY2를 사용한다.

ASL 원문에는 PR18 package 주변의 닫는 중괄호 배치가 PR17과 다르게 보인다. 전문 번역에서는 의미를 설명하되 아래 영어 원문과 줄별 source block은 그대로 보존해 구현자가 원본을 직접 대조할 수 있게 한다.

DSDT entries representing MAC nodes
-----------------------------------

Below are the MAC nodes where PHY nodes are referenced.
phy-mode and phy-handle are used as explained earlier.
------------------------------------------------------

.. code-block:: none

        Scope(\_SB.MCE0.PR17)
        {
          Name (_DSD, Package () {
             ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                 Package () {
                     Package (2) {"phy-mode", "rgmii-id"},
                     Package (2) {"phy-handle", \_SB.MDI0.PHY1}
              }
           })
        }

        Scope(\_SB.MCE0.PR18)
        {
          Name (_DSD, Package () {
            ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                Package () {
                    Package (2) {"phy-mode", "rgmii-id"},
                    Package (2) {"phy-handle", \_SB.MDI0.PHY2}}
            }
          })
        }

Managed PHY와 fixed-link 예제

`managed` property를 지정한 MAC 예제는 `Scope(\_SB.PP21.ETH0)`이다. Device Properties UUID package에서 `phy-mode="sgmii"`와 `managed="in-band-status"`를 제공한다. 이 구성은 SGMII link 상태를 in-band signaling으로 관리함을 나타낸다.

`fixed-link` subnode 예제는 `Scope(\_SB.PP21.ETH1)`이다. 첫 Device Properties UUID package는 `phy-mode="sgmii"`를 제공하고, 이어지는 Hierarchical Data Extension UUID package는 `"fixed-link" → "LNK0"`을 연결한다.

`LNK0`는 port의 data-only subnode다. 자체 Device Properties UUID package에 필수 `speed=1000`과 선택 `full-duplex=1`을 제공하므로, 1000 단위 속도의 full-duplex 고정 link를 기술한다.

MAC node example where "managed" property is specified.
-------------------------------------------------------

.. code-block:: none

        Scope(\_SB.PP21.ETH0)
        {
          Name (_DSD, Package () {
             ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                 Package () {
                     Package () {"phy-mode", "sgmii"},
                     Package () {"managed", "in-band-status"}
                 }
           })
        }

MAC node example with a "fixed-link" subnode.
---------------------------------------------

.. code-block:: none

        Scope(\_SB.PP21.ETH1)
        {
          Name (_DSD, Package () {
            ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                 Package () {
                     Package () {"phy-mode", "sgmii"},
                 },
            ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
                 Package () {
                     Package () {"fixed-link", "LNK0"}
                 }
          })
          Name (LNK0, Package(){ // Data-only subnode of port
            ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                 Package () {
                     Package () {"speed", 1000},
                     Package () {"full-duplex", 1}
                 }
          })
        }

참고 문서

[phy]는 `Documentation/networking/phy.rst`이며 Linux PHY subsystem의 동작을 설명한다. [dsd-properties-rules]는 `Documentation/firmware-guide/acpi/DSD-properties-rules.rst`로 `_DSD` property의 유효성 규칙을 제공한다.

[ethernet-controller]는 `Documentation/devicetree/bindings/net/ethernet-controller.yaml`이다. `phy-mode`, `managed`, `fixed-link`의 전체 parameter와 유효 값은 이 binding을 기준으로 확인한다.

[dsd-guide]는 `https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc`의 DSD Guide이며 문서에 기록된 참조일은 2021-11-30이다.

References
==========

[phy] Documentation/networking/phy.rst

[dsd-properties-rules]
    Documentation/firmware-guide/acpi/DSD-properties-rules.rst

[ethernet-controller]
    Documentation/devicetree/bindings/net/ethernet-controller.yaml

[dsd-guide] DSD Guide.
    https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
    2021-11-30.