[net-next: PATCH 09/12] Documentation: ACPI: DSD: introduce DSA description

From: Marcin Wojtas
Date: Mon Jun 20 2022 - 11:13:21 EST

Describe the Distributed Switch Architecture (DSA) - compliant
MDIO devices. In ACPI world they are represented as children
of the MDIO busses, which are responsible for their enumeration
based on the standard _ADR fields and description in _DSD objects
under device properties UUID [1].

[1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf

Signed-off-by: Marcin Wojtas <mw@xxxxxxxxxxxx>
---
Documentation/firmware-guide/acpi/dsd/dsa.rst | 359 ++++++++++++++++++++
Documentation/firmware-guide/acpi/index.rst | 1 +
2 files changed, 360 insertions(+)
create mode 100644 Documentation/firmware-guide/acpi/dsd/dsa.rst

diff --git a/Documentation/firmware-guide/acpi/dsd/dsa.rst b/Documentation/firmware-guide/acpi/dsd/dsa.rst
new file mode 100644
index 000000000000..dba76d89f4e6
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/dsd/dsa.rst
@@ -0,0 +1,359 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+DSA in ACPI
+===========
+
+The **Distributed Switch Architecture (DSA)** devices on an MDIO bus [dsa]
+are enumerated using fwnode_mdiobus_register_device() and later probed
+by a dedicated driver based on the ACPI ID match result.
+
+In DSDT/SSDT the scope of switch device is extended by the front-panel
+and one or more so called 'CPU' switch ports. Additionally
+subsequent MDIO busses with attached PHYs can be described.
+
+This document presents the switch description with the required subnodes
+and _DSD properties.
+
+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.
+
+Switch device
+=============
+
+The switch device is represented as a child node of the MDIO bus.
+It must comprise the _HID (and optionally _CID) field, so to allow matching
+with appropriate driver via ACPI ID. The other obligatory field is
+_ADR with the device address on the MDIO bus [adr]. Below example
+shows 'SWI0' switch device at address 0x4 on the 'SMI0' bus.
+
+.. code-block:: none
+
+ Scope (\_SB.SMI0)
+ {
+ Name (_HID, "MRVL0100")
+ Name (_UID, 0x00)
+ Method (_STA)
+ {
+ Return (0xF)
+ }
+ Name (_CRS, ResourceTemplate ()
+ {
+ Memory32Fixed (ReadWrite,
+ 0xf212a200,
+ 0x00000010,
+ )
+ })
+ Device (SWI0)
+ {
+ Name (_HID, "MRVL0120")
+ Name (_UID, 0x00)
+ Name (_ADR, 0x4)
+ <...>
+ }
+ }
+
+Switch MDIO bus
+===============
+
+A switch internal MDIO bus, please refer to 'MDIO bus and PHYs in ACPI' [phy]
+document for more details. Its name must be set to **MDIO** for proper
+enumeration by net/dsa API.
+
+Switch MDIO bus declaration example:
+------------------------------------
+
+.. code-block:: none
+
+ Scope (\_SB.SMI0.SWI0)
+ {
+ Name (_HID, "MRVL0120")
+ Name (_UID, 0x00)
+ Name (_ADR, 0x4)
+ Device (MDIO) {
+ Name (_ADR, 0x0)
+ Device (S0P0)
+ {
+ Name (_ADR, 0x11)
+ }
+ Device (S0P1)
+ {
+ Name (_ADR, 0x12)
+ }
+ Device (S0P2)
+ {
+ Name (_ADR, 0x13)
+ }
+ Device (S0P3)
+ {
+ Name (_ADR, 0x14)
+ }
+ }
+ <...>
+ }
+
+Switch ports
+============
+
+The ports must be grouped under **PRTS** switch child device. They
+should comprise a _ADR field with a port enumerator [adr] and
+other properties in a standard _DSD object [dsa-properties].
+
+label
+-----
+A property with a string value describing port's name in the OS. In case the
+port is connected to the MAC ('CPU' port), its value should be set to "cpu".
+
+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.
+See [phy] for more details.
+
+ethernet
+--------
+A property valid for the so called 'CPU' port and should comprise a reference
+to the MAC object declared in the DSDT/SSDT.
+
+fixed-link
+----------
+The 'fixed-link' is described by a data-only subnode of the
+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].
+See [phy] for more details.
+
+Switch ports' description example:
+----------------------------------
+
+.. code-block:: none
+
+ Scope (\_SB.SMI0.SWI0)
+ {
+ Name (_HID, "MRVL0120")
+ Name (_UID, 0x00)
+ Name (_ADR, 0x4)
+ Device (PRTS) {
+ Name (_ADR, 0x0)
+ Device (PRT1)
+ {
+ Name (_ADR, 0x1)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "lan2"},
+ Package () { "phy-handle", \_SB.SMI0.SWI0.MDIO.S0P0},
+ }
+ })
+ }
+ Device (PRT2)
+ {
+ Name (_ADR, 0x2)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "lan1"},
+ },
+ 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}
+ }
+ })
+ }
+ Device (PRT3)
+ {
+ Name (_ADR, 0x3)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "lan4"},
+ Package () { "phy-handle", \_SB.SMI0.SWI0.MDIO.S0P2},
+ }
+ })
+ }
+ Device (PRT4)
+ {
+ Name (_ADR, 0x4)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "lan3"},
+ Package () { "phy-handle", \_SB.SMI0.SWI0.MDIO.S0P3},
+ }
+ })
+ }
+ Device (PRT5)
+ {
+ Name (_ADR, 0x5)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "cpu"},
+ Package () { "ethernet", \_SB.PP20.ETH2},
+ }
+ })
+ }
+ }
+ <...>
+ }
+
+Full DSA description example
+============================
+
+Below example comprises MDIO bus ('SMI0') with a PHY at address 0x0 ('PHY0')
+and a switch ('SWI0') at 0x4. The so called 'CPU' port ('PRT5') is connected to
+the SoC's MAC (\_SB.PP20.ETH2). 'PRT2' port is configured as 1G fixed-link.
+
+.. code-block:: none
+
+ Scope (\_SB.SMI0)
+ {
+ Name (_HID, "MRVL0100")
+ Name (_UID, 0x00)
+ Method (_STA)
+ {
+ Return (0xF)
+ }
+ Name (_CRS, ResourceTemplate ()
+ {
+ Memory32Fixed (ReadWrite,
+ 0xf212a200,
+ 0x00000010,
+ )
+ })
+ Device (PHY0)
+ {
+ Name (_ADR, 0x0)
+ }
+ Device (SWI0)
+ {
+ Name (_HID, "MRVL0120")
+ Name (_UID, 0x00)
+ Name (_ADR, 0x4)
+ Device (PRTS) {
+ Name (_ADR, 0x0)
+ Device (PRT1)
+ {
+ Name (_ADR, 0x1)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "lan2"},
+ Package () { "phy-handle", \_SB.SMI0.SWI0.MDIO.S0P0},
+ }
+ })
+ }
+ Device (PRT2)
+ {
+ Name (_ADR, 0x2)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "lan1"},
+ },
+ 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}
+ }
+ })
+ }
+ Device (PRT3)
+ {
+ Name (_ADR, 0x3)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "lan4"},
+ Package () { "phy-handle", \_SB.SMI0.SWI0.MDIO.S0P2},
+ }
+ })
+ }
+ Device (PRT4)
+ {
+ Name (_ADR, 0x4)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "lan3"},
+ Package () { "phy-handle", \_SB.SMI0.SWI0.MDIO.S0P3},
+ }
+ })
+ }
+ Device (PRT5)
+ {
+ Name (_ADR, 0x5)
+ Name (_DSD, Package () {
+ ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+ Package () {
+ Package () { "label", "cpu"},
+ Package () { "ethernet", \_SB.PP20.ETH2},
+ }
+ })
+ }
+ }
+ Device (MDIO) {
+ Name (_ADR, 0x0)
+ Device (S0P0)
+ {
+ Name (_ADR, 0x11)
+ }
+ Device (S0P2)
+ {
+ Name (_ADR, 0x13)
+ }
+ Device (S0P3)
+ {
+ Name (_ADR, 0x14)
+ }
+ }
+ }
+ }
+
+TODO
+====
+
+* Add support for cascade switch connections via port's 'link' property [dsa-properties].
+
+References
+==========
+
+[adr] ACPI Specifications, Version 6.4 - Paragraph 6.1.1 _ADR Address
+ https://uefi.org/specs/ACPI/6.4/06_Device_Configuration/Device_Configuration.html#adr-address
+
+[dsa]
+ Documentation/networking/dsa/dsa.rst
+
+[dsa-properties]
+ Documentation/devicetree/bindings/net/dsa/dsa-port.yaml
+
+[dsd-guide] DSD Guide.
+ https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
+ 2022-06-20.
+
+[dsd-properties-rules]
+ Documentation/firmware-guide/acpi/DSD-properties-rules.rst
+
+[ethernet-controller]
+ Documentation/devicetree/bindings/net/ethernet-controller.yaml
+
+[phy] Documentation/networking/phy.rst
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index b6a42f4ffe03..a6ed5ba90cdd 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -10,6 +10,7 @@ ACPI Support
namespace
dsd/graph
dsd/data-node-references
+ dsd/dsa
dsd/leds
dsd/phy
enumeration
--
2.29.0