From e71305acd81cac222c41849e538c5c661b12c584 Mon Sep 17 00:00:00 2001 From: Calvin Johnson Date: Fri, 11 Jun 2021 13:53:47 +0300 Subject: Documentation: ACPI: DSD: Document MDIO PHY Introduce a mechanism based on generic ACPI _DSD device properties definition [1] to get PHYs registered on a MDIO bus and provide them to be connected to MAC. [1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf Describe properties "phy-handle" and "phy-mode". Signed-off-by: Calvin Johnson Signed-off-by: Ioana Ciornei Acked-by: Rafael J. Wysocki Acked-by: Grant Likely Signed-off-by: David S. Miller --- Documentation/firmware-guide/acpi/dsd/phy.rst | 133 ++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 Documentation/firmware-guide/acpi/dsd/phy.rst (limited to 'Documentation/firmware-guide') diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst new file mode 100644 index 000000000000..7d01ae8b3cc6 --- /dev/null +++ b/Documentation/firmware-guide/acpi/dsd/phy.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +MDIO bus and PHYs in ACPI +========================= + +The PHYs on an MDIO bus [1] 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 [3] to the MAC layer. + +These properties are defined in accordance with the "Device +Properties UUID For _DSD" [2] document and the +daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device +Data Descriptors containing them. + +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. + +:: + 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 [4]. + +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 +--------------------------------------------- +:: + 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 +--------------------------------------------------------------------- +:: + Scope(\_SB.MDI0) + { + Device(PHY1) { + Name (_ADR, 0x1) + } // end of PHY1 + + Device(PHY2) { + Name (_ADR, 0x2) + } // end of PHY2 + } + +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. +------------------------------------------------------ +:: + 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}} + } + }) + } + +References +========== + +[1] Documentation/networking/phy.rst + +[2] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf + +[3] Documentation/firmware-guide/acpi/DSD-properties-rules.rst + +[4] Documentation/devicetree/bindings/net/ethernet-controller.yaml -- cgit v1.2.3 From 79ab2b37034b7790bd598597faddf689f5b10676 Mon Sep 17 00:00:00 2001 From: Ioana Ciornei Date: Thu, 17 Jun 2021 18:55:51 +0300 Subject: Documentation: ACPI: DSD: include phy.rst in the toctree Include the new phy.rst into the index of the ACPI support documentation. Fixes: e71305acd81c ("Documentation: ACPI: DSD: Document MDIO PHY") Reported-by: Stephen Rothwell Signed-off-by: Ioana Ciornei Signed-off-by: David S. Miller --- Documentation/firmware-guide/acpi/index.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/firmware-guide') diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index f72b5f1769fb..a99ee402b212 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -11,6 +11,7 @@ ACPI Support dsd/graph dsd/data-node-references dsd/leds + dsd/phy enumeration osi method-customizing -- cgit v1.2.3 From 5a336f97f1f5011cdca5467ef96372fd6d2fd128 Mon Sep 17 00:00:00 2001 From: Ioana Ciornei Date: Thu, 17 Jun 2021 18:55:52 +0300 Subject: Documentation: ACPI: DSD: fix block code comments Use the '.. code-block:: none' to properly highlight the documented DSDT entries. This also fixes warnings in the documentation build process. Fixes: e71305acd81c ("Documentation: ACPI: DSD: Document MDIO PHY") Reported-by: Stephen Rothwell Signed-off-by: Ioana Ciornei Signed-off-by: David S. Miller --- Documentation/firmware-guide/acpi/dsd/phy.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) (limited to 'Documentation/firmware-guide') diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst index 7d01ae8b3cc6..0d49bad2ea9c 100644 --- a/Documentation/firmware-guide/acpi/dsd/phy.rst +++ b/Documentation/firmware-guide/acpi/dsd/phy.rst @@ -27,7 +27,8 @@ 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) { @@ -60,7 +61,9 @@ component (PHYs on the MDIO bus). a) Silicon Component This node describes the MDIO controller, MDI0 --------------------------------------------- -:: + +.. code-block:: none + Scope(_SB) { Device(MDI0) { @@ -80,7 +83,9 @@ This node describes the MDIO controller, 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) { @@ -98,7 +103,9 @@ 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 () { -- cgit v1.2.3 From 7c4d7ca8cce3c8167e10f52a5afb553851f2086b Mon Sep 17 00:00:00 2001 From: Marcin Wojtas Date: Mon, 21 Jun 2021 19:30:23 +0200 Subject: Documentation: ACPI: DSD: describe additional MAC configuration Document additional MAC configuration modes which can be processed by the existing fwnode_ phylink helpers: * "managed" standard ACPI _DSD property [1] * "fixed-link" data-only subnode linked in the _DSD package via generic mechanism of the hierarchical data extension [2] [1] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf [2] https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf Signed-off-by: Marcin Wojtas Signed-off-by: David S. Miller --- Documentation/firmware-guide/acpi/dsd/phy.rst | 59 +++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) (limited to 'Documentation/firmware-guide') diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst index 0d49bad2ea9c..680ad179e5f9 100644 --- a/Documentation/firmware-guide/acpi/dsd/phy.rst +++ b/Documentation/firmware-guide/acpi/dsd/phy.rst @@ -50,6 +50,21 @@ 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 [4]. +managed +------- +Optional property, which specifies the PHY management type. +The valid values for "managed" are defined in [4]. + +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 [5] "_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 [4]. + The following ASL example illustrates the usage of these properties. DSDT entry for MDIO node @@ -128,6 +143,48 @@ phy-mode and phy-handle are used as explained earlier. }) } +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} + } + }) + } + References ========== @@ -138,3 +195,5 @@ References [3] Documentation/firmware-guide/acpi/DSD-properties-rules.rst [4] Documentation/devicetree/bindings/net/ethernet-controller.yaml + +[5] https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf -- cgit v1.2.3