Hi Rafael,

Thanks for the review. I'll work on all the comments.

On Fri, Jan 22, 2021 at 08:22:21PM +0100, Rafael J. Wysocki wrote:

On Fri, Jan 22, 2021 at 4:43 PM Calvin Johnson
[off-list ref] wrote:

quoted

Introduce ACPI mechanism to get PHYs registered on a MDIO bus and
provide them to be connected to MAC.

Describe properties "phy-handle" and "phy-mode".

Signed-off-by: Calvin Johnson <redacted>
---

Changes in v4:
- More cleanup

This looks much better that the previous versions IMV, some nits below.

quoted

Changes in v3: None
Changes in v2:
- Updated with more description in document

 Documentation/firmware-guide/acpi/dsd/phy.rst | 129 ++++++++++++++++++
 1 file changed, 129 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..76fca994bc99
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/dsd/phy.rst

@@ -0,0 +1,129 @@
+.. 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().

Empty line here, please.

quoted

+Later, for connecting these PHYs to MAC, the PHYs registered on the
+MDIO bus have to be referenced.
+
+The UUID given below should be used as mentioned in the "Device Properties
+UUID For _DSD" [2] document.
+   - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301

I would drop the above paragraph.

quoted

+
+This document introduces two _DSD properties that are to be used
+for PHYs on the MDIO bus.[3]

I'd say "for connecting PHYs on the MDIO bus [3] to the MAC layer."
above and add the following here:

"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."

quoted

+
+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.

Do you want to mention the "reg" property here?  I think it would be
useful to do that.

No. I think we should adhere to _ADR in MDIO case. The "reg" property for ACPI
may be useful for other use cases that Andy is aware of.

Regards
Calvin