Re: [PATCH net-next v8 01/15] Documentation: ACPI: DSD: Document MDIO PHY

[Grant Likely <grant.likely@arm.com>]

On 10/06/2021 19:05, Rafael J. Wysocki wrote:
> On Thu, Jun 10, 2021 at 6:40 PM Ioana Ciornei <ciorneiioana@gmail.com> wrote:
>>
>> From: Calvin Johnson <calvin.johnson@oss.nxp.com>
>>
>> Introduce ACPI mechanism to get PHYs registered on a MDIO bus and
>> provide them to be connected to MAC.
> 
> This is not an "ACPI mechanism", because it is not part of the ACPI
> specification or support documentation thereof.
> 
> I would call it "a mechanism based on generic ACPI _DSD device
> properties definition []1]".  And provide a reference to the _DSD
> properties definition document.
> 
> With that changed, you can add
> 
> Acked-by: Rafael J. Wysocki <rafael@kernel.org>
> 
> to this patch.
> 
> Note, however, that within the traditional ACPI framework, the _DSD
> properties are consumed by the driver that binds to the device
> represented by the ACPI device object containing the _DSD in question
> in its scope, while in this case IIUC the properties are expected to
> be consumed by the general networking code in the kernel.  That is not
> wrong in principle, but it means that operating systems other than
> Linux are not likely to be using them.
> 

Doesn't this land at the level of device drivers though? None of this 
data needs to be consumed by the OS generic ACPI parsing code, but the 
network device driver can use it to parse the MDIO and MAC configuraiton 
and set itself up appropriately.

The only difference in the Linux case is that the code is implemented in 
a way that can be leveraged by other network drivers instead of being 
entirely contained within the dpaa driver.

g.

>> Describe properties "phy-handle" and "phy-mode".
>>
>> Signed-off-by: Calvin Johnson <calvin.johnson@oss.nxp.com>
>> Signed-off-by: Ioana Ciornei <ioana.ciornei@nxp.com>
>> ---
>>
>> Changes in v8: None
>> Changes in v7: None
>> Changes in v6:
>> - Minor cleanup
>>
>> Changes in v5:
>> - More cleanup
>>
>> Changes in v4:
>> - More cleanup
>>
>> Changes in v3: None
>> Changes in v2:
>> - Updated with more description in document
>>
>>   Documentation/firmware-guide/acpi/dsd/phy.rst | 133 ++++++++++++++++++
>>   1 file changed, 133 insertions(+)
>>   create mode 100644 Documentation/firmware-guide/acpi/dsd/phy.rst
>>
>> 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
>> --
>> 2.31.1
>>