[PATCH net-next v2 0/2] Support unaligned RTL8224 PHY packages

[PATCH net-next v2 0/2] Support unaligned RTL8224 PHY packages

[Oskari Lemmela]

RTL8224 packages contain four PHYs at consecutive MDIO addresses, but
their first address need not be a multiple of four. The Hasivo
S1100WP-8GT-2S+ uses two such packages at addresses 1-4 and 5-8.

This series documents how to describe RTL8224 packages using the existing
ethernet-phy-package binding and extends the driver to use the explicit
package base when provided. The package-relative port index selects the
MDI pair order and polarity fields. Existing configurations without a
package node retain the aligned-address assumption.

The package-addressing change was tested on a Hasivo S1100WP-8GT-2S+
using an OpenWrt kernel. The rebased net-next version has not been
runtime-tested.

Changes since v1:
- Target net-next, as suggested by Andrew Lunn.
- Remove the Fixes tag and describe the change as extending support
  rather than fixing a regression.
- Rebased on net-next/main
- Add a separate DT binding documentation patch with an unaligned
  four-port package example, placed before the driver patch.

The driver behavior is unchanged from v1; the rebase only updates patch
context.

v1:
https://lore.kernel.org/netdev/20261004204637.721148-1-oskari@lemmela.net/

Manuel Stocker (1):
  net: phy: realtek: support unaligned RTL8224 PHY packages

Oskari Lemmela (1):
  dt-bindings: net: realtek,rtl82xx: document RTL8224 packages

 .../bindings/net/realtek,rtl82xx.yaml         | 52 +++++++++++++++++--
 drivers/net/phy/realtek/realtek_main.c        | 49 +++++++++++++++--
 2 files changed, 93 insertions(+), 8 deletions(-)


base-commit: 8b4e7209c842d8cb9516f1f5ef0a88aa2d8831a6
-- 
2.55.0

[PATCH net-next v2 1/2] dt-bindings: net: realtek,rtl82xx: document RTL8224 packages

[Oskari Lemmela]

RTL8224 packages contain four PHYs at consecutive MDIO addresses,
but the first address need not be a multiple of four. Document how
to describe these packages using the existing ethernet-phy-package
binding so their base address is explicit.

Clarify that child PHY addresses are absolute and that MDI pair
order and polarity properties describe the individual ports. Add
an example with a package starting at address 1.

Signed-off-by: Oskari Lemmela <oskari@lemmela.net>
---
 .../bindings/net/realtek,rtl82xx.yaml         | 52 +++++++++++++++++--
 1 file changed, 49 insertions(+), 3 deletions(-)

diff --git a/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml b/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
index 07b39ef1fc62..ca52c3ae19f7 100644
--- a/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
+++ b/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
@@ -12,7 +12,17 @@ maintainers:
   - Heiner Kallweit <hkallweit1@gmail.com>
 
 description:
-  Bindings for Realtek RTL82xx PHYs
+  Bindings for Realtek RTL82xx PHYs.
+
+  The RTL8224 contains four PHYs at consecutive MDIO addresses. Its PHY
+  nodes may be grouped under an ethernet-phy-package node as described
+  in ethernet-phy-package.yaml. The package reg must identify the first
+  PHY's MDIO address, even if that PHY has no child node. This address
+  need not be a multiple of four. Each child PHY reg is its absolute
+  MDIO address, not an offset from the package base.
+
+  The enet-phy-pair-order and enet-phy-pair-polarity properties belong
+  to the individual PHY nodes and describe each port's MDI wiring.
 
 properties:
   compatible:
@@ -90,9 +100,45 @@ examples:
         #address-cells = <1>;
         #size-cells = <0>;
 
-        ethphy1: ethernet-phy@1 {
+        ethernet-phy@1 {
             reg = <1>;
-            realtek,clkout-disable;
             realtek,aldps-enable;
+            realtek,clkout-disable;
+        };
+    };
+  - |
+    mdio {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        ethernet-phy-package@1 {
+            reg = <1>;
+            #address-cells = <1>;
+            #size-cells = <0>;
+
+            ethernet-phy@1 {
+                compatible = "ethernet-phy-ieee802.3-c45";
+                reg = <1>;
+                enet-phy-pair-order = <0>;
+            };
+
+            ethernet-phy@2 {
+                compatible = "ethernet-phy-ieee802.3-c45";
+                reg = <2>;
+                enet-phy-pair-order = <0>;
+            };
+
+            ethernet-phy@3 {
+                compatible = "ethernet-phy-ieee802.3-c45";
+                reg = <3>;
+                enet-phy-pair-order = <1>;
+            };
+
+            ethernet-phy@4 {
+                compatible = "ethernet-phy-ieee802.3-c45";
+                reg = <4>;
+                enet-phy-pair-order = <1>;
+                enet-phy-pair-polarity = <0x1>;
+            };
         };
     };
-- 
2.55.0

Re: [PATCH net-next v2 1/2] dt-bindings: net: realtek,rtl82xx: document RTL8224 packages

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] dt-bindings: net: generic compatible in example fails schema validation
--

commit 6e9280e0153fb3196c44f745f9db18bcf7971400
Author: Oskari Lemmela <oskari@lemmela.net>

dt-bindings: net: realtek,rtl82xx: document RTL8224 packages

This commit updates the realtek,rtl82xx bindings to document RTL8224 PHY
packages and adds an example demonstrating multiple child PHY nodes within an
ethernet-phy-package.

> diff --git a/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml b/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
> index 07b39ef1fc624..ca52c3ae19f7a 100644
> --- a/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
> +++ b/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
[ ... ]
> @@ -90,9 +100,45 @@ examples:
>          #address-cells = <1>;
>          #size-cells = <0>;
>  
[ ... ]
> +        ethernet-phy-package@1 {
> +            reg = <1>;
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +
> +            ethernet-phy@1 {
> +                compatible = "ethernet-phy-ieee802.3-c45";

[Severity: Low]
Does this generic compatible string cause a schema validation warning during
make dt_binding_check? 

Because this generic string is not listed in the schema's compatible enum,
the implicit select logic generated for this schema fails to match the
example node. The dt-schema tool strictly requires examples to match their
enclosing schema, so this mismatch will trigger a validation error.

> +                reg = <1>;
> +                enet-phy-pair-order = <0>;
> +            };
> +
> +            ethernet-phy@2 {
> +                compatible = "ethernet-phy-ieee802.3-c45";
> +                reg = <2>;
> +                enet-phy-pair-order = <0>;
> +            };
[ ... ]

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261005201540.913977-1-oskari@lemmela.net?part=1

Re: [PATCH net-next v2 1/2] dt-bindings: net: realtek,rtl82xx: document RTL8224 packages

[netdev-bot+sashiko]

Thank you for your contribution! Sashiko AI review found more severe
issue(s) in other patches of this series. This mail is only an FYI, in case
you want to address the nit picks below when you respin.

Low priority / nit picks for your consideration:

- [Low] Not a bug in the final series state; dismissed after
  verification.
- [Low] In Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml,
  the new RTL8224 example gives each PHY node only compatible =…

--

dt-bindings: net: realtek,rtl82xx: document RTL8224 packages

This patch documents how RTL8224 parts are described with the existing
ethernet-phy-package binding. Each part has four PHYs at consecutive MDIO
addresses, and the package base need not be a multiple of four. It also
adds an example with a package that starts at MDIO address 1.

> diff --git a/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml b/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
> index 07b39ef1fc624..ca52c3ae19f7a 100644
> --- a/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
> +++ b/Documentation/devicetree/bindings/net/realtek,rtl82xx.yaml
> @@ -12,7 +12,17 @@ maintainers:

[ ... ]

> +  The RTL8224 contains four PHYs at consecutive MDIO addresses. Its PHY
> +  nodes may be grouped under an ethernet-phy-package node as described
> +  in ethernet-phy-package.yaml. The package reg must identify the first
> +  PHY's MDIO address, even if that PHY has no child node. This address
> +  need not be a multiple of four. Each child PHY reg is its absolute
> +  MDIO address, not an offset from the package base.

[Severity: Low]
At this commit, can the driver handle a package whose base is not a
multiple of four? rtl8224_probe() in drivers/net/phy/realtek/realtek_main.c
ignores the package reg and works out the base itself:

    devm_phy_package_join(dev, phydev, phydev->mdio.addr & ~3, 0)

Also, rtl8224_mdi_config_order() and rtl8224_mdi_config_polarity() pick
the port lane with addr & 3.

The example below has a package at 1 with PHYs 1-4. With that layout:

- PHYs 1-3 would join a package at base 0.
- PHY 4 would join a separate package at base 4.
- The VEND1 0xa90/0xa94 read-modify-writes would go to MDIO address 0.
- The lane bits would be wrong.

The next patch in the series, "net: phy: realtek: support unaligned RTL8224
PHY packages", fixes this:

- It reads the package reg into base_addr.
- It joins through devm_of_phy_package_join().
- It sets priv->port_offset = phydev->mdio.addr - base_addr for the MDI
  helpers.

With the full series applied, this layout is handled correctly. Merging the
binding before the driver change is also the usual order.

[ ... ]

> @@ -90,9 +100,45 @@ examples:

[ ... ]

> +  - |
> +    mdio {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        ethernet-phy-package@1 {
> +            reg = <1>;
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +
> +            ethernet-phy@1 {
> +                compatible = "ethernet-phy-ieee802.3-c45";

[Severity: Low]
Are these nodes ever checked against this schema? Their only compatible
is "ethernet-phy-ieee802.3-c45", and that string is not in this binding's
compatible enum.

realtek,rtl82xx.yaml has no explicit select, so dtschema builds one from
that enum. As a result, the four ethernet-phy@N nodes never match this
schema during dt_binding_check.

Only two schemas check these nodes:

- ethernet-phy.yaml, which selects on $nodename.
- ethernet-phy-package.yaml, which has additionalProperties: true.

That means this schema's own constraints never run on the new example.
This includes unevaluatedProperties: false, the leds conditional and the
realtek,* properties. The example also has nothing that marks the device
as an RTL8224.

Would a compatible like this work instead?

    compatible = "ethernet-phy-id001c.cad0", "ethernet-phy-ieee802.3-c45";

> +                reg = <1>;
> +                enet-phy-pair-order = <0>;
> +            };

[ ... ]

-- 
Sashiko AI review · https://netdev-ai.bots.linux.dev/sashiko/#/patchset/20261005201540.913977-1-oskari%40lemmela.net

[PATCH net-next v2 2/2] net: phy: realtek: support unaligned RTL8224 PHY packages

[Oskari Lemmela]

From: Manuel Stocker <mensi@mensi.ch>

The RTL8224 driver groups its four ports by rounding each PHY address
down to a multiple of four and uses the low two address bits as the
port index. This assumes that the first port's MDIO address is aligned
to a multiple of four.

The Hasivo S1100WP-8GT-2S+ uses two RTL8224 packages at MDIO addresses
1-4 and 5-8. Extend the driver to support such configurations by using
the base address from an ethernet-phy-package node when present and
calculating each port's offset relative to that address.

Use the package-relative port index to select the MDI pair order and
polarity fields. Reject PHY addresses outside the four-port package
and propagate explicit package errors rather than falling back to
another base address.

Keep the existing aligned-address assumption when no package node
is present.

Signed-off-by: Manuel Stocker <mensi@mensi.ch>
[Oskari: rebased on net-next/main, reworded commit message]
Signed-off-by: Oskari Lemmela <oskari@lemmela.net>
---
 drivers/net/phy/realtek/realtek_main.c | 49 +++++++++++++++++++++++---
 1 file changed, 44 insertions(+), 5 deletions(-)

diff --git a/drivers/net/phy/realtek/realtek_main.c b/drivers/net/phy/realtek/realtek_main.c
index e14960192e79..91cf34d13420 100644
--- a/drivers/net/phy/realtek/realtek_main.c
+++ b/drivers/net/phy/realtek/realtek_main.c
@@ -355,6 +355,10 @@ struct rtl821x_priv {
 	u16 iner;
 };
 
+struct rtl8224_priv {
+	u8 port_offset;
+};
+
 struct rtl8261x_priv {
 	const char *fw_name;
 	u32 fw_sub_magic;
@@ -2723,7 +2727,8 @@ static int rtl8224_package_modify_mmd(struct phy_device *phydev, int devad,
 static int rtl8224_mdi_config_order(struct phy_device *phydev)
 {
 	struct device_node *np = phydev->mdio.dev.of_node;
-	u8 port_offset = phydev->mdio.addr & 3;
+	struct rtl8224_priv *priv = phydev->priv;
+	u8 port_offset = priv->port_offset;
 	u32 order = 0;
 	int ret;
 
@@ -2748,7 +2753,8 @@ static int rtl8224_mdi_config_order(struct phy_device *phydev)
 static int rtl8224_mdi_config_polarity(struct phy_device *phydev)
 {
 	struct device_node *np = phydev->mdio.dev.of_node;
-	u8 offset = (phydev->mdio.addr & 3) * 4;
+	struct rtl8224_priv *priv = phydev->priv;
+	u8 offset = priv->port_offset * 4;
 	u32 polarity = 0;
 	int ret;
 
@@ -2783,9 +2789,42 @@ static int rtl8224_config_init(struct phy_device *phydev)
 
 static int rtl8224_probe(struct phy_device *phydev)
 {
-	/* Chip exposes 4 ports, join all of them in the same package */
-	return devm_phy_package_join(&phydev->mdio.dev, phydev,
-				     phydev->mdio.addr & ~3, 0);
+	struct device *dev = &phydev->mdio.dev;
+	u32 base_addr = phydev->mdio.addr & ~3;
+	struct rtl8224_priv *priv;
+	struct device_node *np;
+	int ret;
+
+	priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
+	if (!priv)
+		return -ENOMEM;
+
+	np = of_get_parent(dev->of_node);
+	if (of_node_name_eq(np, "ethernet-phy-package")) {
+		ret = of_property_read_u32(np, "reg", &base_addr);
+		of_node_put(np);
+		if (ret)
+			return dev_err_probe(dev, ret,
+					     "Missing or invalid PHY package reg\n");
+
+		if (phydev->mdio.addr < base_addr ||
+		    phydev->mdio.addr - base_addr >= 4)
+			return dev_err_probe(dev, -EINVAL,
+					     "PHY address outside RTL8224 package\n");
+
+		ret = devm_of_phy_package_join(dev, phydev, 0);
+	} else {
+		of_node_put(np);
+		/* Without a package node, assume four aligned PHY addresses. */
+		ret = devm_phy_package_join(dev, phydev, base_addr, 0);
+	}
+	if (ret)
+		return dev_err_probe(dev, ret, "Failed to join PHY package\n");
+
+	priv->port_offset = phydev->mdio.addr - base_addr;
+	phydev->priv = priv;
+
+	return 0;
 }
 
 static bool rtlgen_supports_2_5gbps(struct phy_device *phydev)
-- 
2.55.0

Re: [PATCH net-next v2 2/2] net: phy: realtek: support unaligned RTL8224 PHY packages

[netdev-bot+sashiko]

Thank you for your contribution! Sashiko AI review found 2 potential
issue(s) to consider.

Critical: 0 · High: 0 · Medium: 1 · Low: 1

If you believe none of the issues are legitimate, please reply to each
issue of Medium severity or higher and explain why the AI is wrong.
If any of them are legitimate and you plan to respin, please let patchwork
know by including "pw-bot: cr" as a separate line at the end of your reply
(one such reply per series is enough).

- [Medium] The RTL8224 text added to realtek,rtl82xx.yaml (preceding
  commit "dt-bindings: net: realtek,rtl82xx: document RTL8224 packages")…
- [Low] The new RTL8224 package example in realtek,rtl82xx.yaml
  (preceding commit "dt-bindings: net: realtek,rtl82xx: document RTL8224…

--

net: phy: realtek: support unaligned RTL8224 PHY packages

This commit makes the RTL8224 driver take the package base address from
the reg property of an ethernet-phy-package parent node, rather than
always rounding the PHY address down to a multiple of four. The port
index relative to the package is stored in a new struct rtl8224_priv and
used to pick the MDI pair order and polarity fields. When there is no
package node, the old aligned-address assumption still applies.

> diff --git a/drivers/net/phy/realtek/realtek_main.c b/drivers/net/phy/realtek/realtek_main.c
> index e14960192e791..91cf34d134202 100644
> --- a/drivers/net/phy/realtek/realtek_main.c
> +++ b/drivers/net/phy/realtek/realtek_main.c

[ ... ]

> @@ -2783,9 +2789,42 @@ static int rtl8224_config_init(struct phy_device *phydev)
>  
>  static int rtl8224_probe(struct phy_device *phydev)
>  {
> -	/* Chip exposes 4 ports, join all of them in the same package */
> -	return devm_phy_package_join(&phydev->mdio.dev, phydev,
> -				     phydev->mdio.addr & ~3, 0);
> +	struct device *dev = &phydev->mdio.dev;
> +	u32 base_addr = phydev->mdio.addr & ~3;
> +	struct rtl8224_priv *priv;
> +	struct device_node *np;
> +	int ret;

[ ... ]

> +	np = of_get_parent(dev->of_node);
> +	if (of_node_name_eq(np, "ethernet-phy-package")) {
> +		ret = of_property_read_u32(np, "reg", &base_addr);
> +		of_node_put(np);
> +		if (ret)
> +			return dev_err_probe(dev, ret,
> +					     "Missing or invalid PHY package reg\n");
> +
> +		if (phydev->mdio.addr < base_addr ||
> +		    phydev->mdio.addr - base_addr >= 4)
> +			return dev_err_probe(dev, -EINVAL,
> +					     "PHY address outside RTL8224 package\n");
> +
> +		ret = devm_of_phy_package_join(dev, phydev, 0);
> +	} else {
> +		of_node_put(np);
> +		/* Without a package node, assume four aligned PHY addresses. */
> +		ret = devm_phy_package_join(dev, phydev, base_addr, 0);

[Severity: Medium]
What happens in this fallback when an RTL8224 is unaligned and has no
ethernet-phy-package parent?

The binding text added in the preceding commit "dt-bindings: net:
realtek,rtl82xx: document RTL8224 packages" says the package node is
optional:

  Its PHY nodes may be grouped under an ethernet-phy-package node ...
  This address need not be a multiple of four.

That text never says the package node is required when the first PHY
address is not a multiple of four. So a DT for the Hasivo
S1100WP-8GT-2S+ layout (chips at 1-4 and 5-8) that has no package nodes
still passes the schema.

For that DT, this branch uses base_addr = addr & ~3 with no check:

  PHYs 1-3 join base 0, which is not part of either chip
  PHY 4 joins base 4 with port_offset 0
  PHYs 5-7 (ports 0-2 of chip B) also join base 4, with offsets 1-3

rtl8224_package_modify_mmd() then does a read-modify-write of
RTL8224_VND1_MDI_PAIR_SWAP and RTL8224_VND1_MDI_POLARITY_SWAP at package
address 0:

	val = __phy_package_read_mmd(phydev, 0, devad, regnum);
	...
	ret = __phy_package_write_mmd(phydev, 0, devad, regnum, val);

Wouldn't chip B's pair order and polarity settings end up in chip A's
registers? They would also overwrite the settings for chip A port 3, and
nothing reports an error or warning.

Commit 330296ea9e15 ("net: phy: realtek: add RTL8224 pair order
support") says the swap "has to be set correctly for each of the 4 ports
before the chip can detect a link". The affected copper ports may
therefore fail to link.

Could the binding require the package node when the first PHY address
is not a multiple of four? Alternatively, could this fallback reject or
warn about the ambiguous case?

> +	}
> +	if (ret)
> +		return dev_err_probe(dev, ret, "Failed to join PHY package\n");

[Severity: Low]
This isn't a bug, but I have a question about the RTL8224 package
example added to realtek,rtl82xx.yaml in the preceding commit
"dt-bindings: net: realtek,rtl82xx: document RTL8224 packages".

The only compatible on each child PHY in that example is:

	compatible = "ethernet-phy-ieee802.3-c45";

The schema has no explicit select, and its compatible enum lists only
ethernet-phy-id001c.xxxx values.

Doesn't that mean dt-schema never applies realtek,rtl82xx.yaml to these
nodes? They would then be checked only against ethernet-phy-package.yaml
and ethernet-phy.yaml.

If so, the example never exercises the RTL8224-specific rules in this
file: unevaluatedProperties: false, the leds: false rule and the vendor
properties. A wrong property in the example would still pass
dt_binding_check.

This is partly an existing limitation. The first example has no
compatible either, and cameo-rtl9302c-2x-rtl8224-2xge.dts also uses only
the c45 compatible for RTL8224.

> +
> +	priv->port_offset = phydev->mdio.addr - base_addr;
> +	phydev->priv = priv;
> +
> +	return 0;
>  }

-- 
Sashiko AI review · https://netdev-ai.bots.linux.dev/sashiko/#/patchset/20261005201540.913977-1-oskari%40lemmela.net

Re: [PATCH net-next v2 2/2] net: phy: realtek: support unaligned RTL8224 PHY packages

[Oskari Lemmelä]

On 10/8/26 11:18, netdev-bot+sashiko@kernel.org wrote:
> Thank you for your contribution! Sashiko AI review found 2 potential
> issue(s) to consider.
> 
> Critical: 0 · High: 0 · Medium: 1 · Low: 1
> 
> If you believe none of the issues are legitimate, please reply to each
> issue of Medium severity or higher and explain why the AI is wrong.
> If any of them are legitimate and you plan to respin, please let patchwork
> know by including "pw-bot: cr" as a separate line at the end of your reply
> (one such reply per series is enough).
> 
> - [Medium] The RTL8224 text added to realtek,rtl82xx.yaml (preceding
>    commit "dt-bindings: net: realtek,rtl82xx: document RTL8224 packages")…
> - [Low] The new RTL8224 package example in realtek,rtl82xx.yaml
>    (preceding commit "dt-bindings: net: realtek,rtl82xx: document RTL8224…
> 
> --
> 
The aligned-address fallback is retained for existing device trees
without package nodes. Without an explicit package description, the
driver cannot reliably distinguish aligned and unaligned layouts from
individual PHY addresses.

Would clarifying that a package node is required for unaligned RTL8224
layouts be sufficient to address the medium finding, while preserving
the fallback for existing aligned layouts?

For the schema-coverage concern, would adding a dedicated RTL8224
package binding with a compatible such as "realtek,rtl8224-package"
be the preferred approach? This could follow the QCA807x package-binding
pattern and provide explicit validation of the package and child PHYs.

I would appreciate maintainer guidance before preparing v3.

Re: [PATCH net-next v2 2/2] net: phy: realtek: support unaligned RTL8224 PHY packages

[Andrew Lunn]

On Thu, Oct 08, 2026 at 08:12:24PM +0300, Oskari Lemmelä wrote:
> 
> On 10/8/26 11:18, netdev-bot+sashiko@kernel.org wrote:
> > Thank you for your contribution! Sashiko AI review found 2 potential
> > issue(s) to consider.
> > 
> > Critical: 0 · High: 0 · Medium: 1 · Low: 1
> > 
> > If you believe none of the issues are legitimate, please reply to each
> > issue of Medium severity or higher and explain why the AI is wrong.
> > If any of them are legitimate and you plan to respin, please let patchwork
> > know by including "pw-bot: cr" as a separate line at the end of your reply
> > (one such reply per series is enough).
> > 
> > - [Medium] The RTL8224 text added to realtek,rtl82xx.yaml (preceding
> >    commit "dt-bindings: net: realtek,rtl82xx: document RTL8224 packages")…
> > - [Low] The new RTL8224 package example in realtek,rtl82xx.yaml
> >    (preceding commit "dt-bindings: net: realtek,rtl82xx: document RTL8224…
> > 
> > --
> > 
> The aligned-address fallback is retained for existing device trees
> without package nodes. Without an explicit package description, the
> driver cannot reliably distinguish aligned and unaligned layouts from
> individual PHY addresses.
> 
> Would clarifying that a package node is required for unaligned RTL8224
> layouts be sufficient to address the medium finding, while preserving
> the fallback for existing aligned layouts?

Probably. This is the AI being a bit picky. 

> 
> For the schema-coverage concern, would adding a dedicated RTL8224
> package binding with a compatible such as "realtek,rtl8224-package"
> be the preferred approach? This could follow the QCA807x package-binding
> pattern and provide explicit validation of the package and child PHYs.

A dedicated realtek,rtl8224-package binding probably does make
sense. You need some documentation anyway.

       Andrew