This is an automated email from the ASF dual-hosted git repository.

xiaoxiang781216 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit e7577223ea4865e5bc5d0755465fb09dcf58635e
Author: Jari Nippula <[email protected]>
AuthorDate: Fri Nov 6 16:28:44 2026 +0200

    Doc: os/networking/phylib
    
    - RTL8211F & RTL8201F devices added
    
    Signed-off-by: Jari Nippula <[email protected]>
---
 Documentation/os/drivers/special/net/index.rst     |  1 +
 Documentation/os/drivers/special/net/phy.rst       | 29 ++++++++++++++++++++++
 Documentation/os/networking/phylib.rst             |  3 +++
 .../os/networking/phylib_vendor_porting.rst        | 24 ++++++++++++++++++
 4 files changed, 57 insertions(+)

diff --git a/Documentation/os/drivers/special/net/index.rst 
b/Documentation/os/drivers/special/net/index.rst
index 03ec5461bae..15b61a1dbcd 100644
--- a/Documentation/os/drivers/special/net/index.rst
+++ b/Documentation/os/drivers/special/net/index.rst
@@ -11,4 +11,5 @@ Network interface drivers
   :caption: Supported Drivers
 
   ethernet.rst
+  phy.rst
   vlan.rst
diff --git a/Documentation/os/drivers/special/net/phy.rst 
b/Documentation/os/drivers/special/net/phy.rst
new file mode 100644
index 00000000000..3d550260dc0
--- /dev/null
+++ b/Documentation/os/drivers/special/net/phy.rst
@@ -0,0 +1,29 @@
+==================
+PHY Device Drivers
+==================
+
+These drivers use the :doc:`PHYLIB framework </os/networking/phylib>`.
+
+Realtek RTL8201F and RTL8211F
+=============================
+
+``CONFIG_NET_PHY_REALTEK_RTL8201F`` enables the Clause 22 MII/RMII driver;
+``CONFIG_NET_PHY_REALTEK_RTL8211F`` enables the RTL8211F-VD and RTL8211F/FDI
+RGMII driver. Register them with ``rtl8201f_register()`` or
+``rtl8211f_register()`` from ``<nuttx/net/realtek_phy.h>`` before creating
+PHY devices. Repeated registration is safe.
+
+Set ``phydev->interface`` before ``phy_connect()``. For RTL8201F, select
+``PHY_INTERFACE_RMII`` when the reference clock is supplied to the PHY,
+or ``PHY_INTERFACE_RMII_PHY_CLK_OUT`` when the PHY supplies the clock.
+The interface mode determines clock direction in both the MAC and PHY
+drivers; no separate clock flag or driver-private configuration is needed.
+The RTL8201F driver preserves RMII timing and oscillator settings.
+RTL8211F programs both delay
+bits according to ``PHY_INTERFACE_RGMII``, ``RGMII_ID``, ``RGMII_TXID`` or
+``RGMII_RXID`` (no internal delay, both, TX only or RX only). Both drivers
+use generic Clause 22 capability discovery, auto-negotiation, negotiated
+link-status resolution and power control. Register-page operations are
+serialized by the PHYLIB paged-access helpers. These drivers use polling
+and auto-negotiation; forced link modes and PHY interrupts are not
+implemented.
diff --git a/Documentation/os/networking/phylib.rst 
b/Documentation/os/networking/phylib.rst
index 7710ee23640..a0fec137f77 100644
--- a/Documentation/os/networking/phylib.rst
+++ b/Documentation/os/networking/phylib.rst
@@ -129,6 +129,9 @@ of PHYLIB:
    CONFIG_NET_PHYLIB_MAX_DRIVERS=8        # Maximum number of PHY drivers
    CONFIG_NET_PHYLIB_MAX_PHYS=8           # Maximum number of PHY devices
 
+See :doc:`PHY Device Drivers </os/drivers/special/net/phy>` for
+device-specific configuration and registration.
+
 5. Core Data Structures
 =======================
 
diff --git a/Documentation/os/networking/phylib_vendor_porting.rst 
b/Documentation/os/networking/phylib_vendor_porting.rst
index f783e882565..c81eff46731 100644
--- a/Documentation/os/networking/phylib_vendor_porting.rst
+++ b/Documentation/os/networking/phylib_vendor_porting.rst
@@ -168,6 +168,22 @@ A successful ``phy_connect(phydev, &priv->dev)`` also sets
 ``priv->dev.phydev``, so the netdev upper-half dispatches standard PHY
 ioctls to ``phy_ioctl()``.
 
+For switch ports, or MACs that must apply their link mode before reporting
+carrier, ``phy_connect(phydev, NULL)`` creates a connection without automatic
+carrier notification or netdev ioctl dispatch. The MAC consumes
+``state/link/speed/duplex`` under ``phydev->lock``, applies its hardware
+configuration, and reports carrier itself. It must forward PHY ioctls
+explicitly and release the device with ``phy_disconnect()``. This also
+allows several independently negotiated switch PHYs to contribute to one
+network interface's carrier without overwriting ``lower->phydev``.
+
+Set ``phydev->interface`` before connecting. For RMII, select
+``PHY_INTERFACE_RMII`` when the reference clock is supplied to the PHY,
+or ``PHY_INTERFACE_RMII_PHY_CLK_OUT`` when the PHY supplies the clock.
+MAC and PHY drivers must handle both modes as RMII signaling, with opposite
+reference-clock directions. The PHY driver owns ``phydev->priv``; MAC and
+board code must not overwrite or free it.
+
 5. Implementing the MDIO Lower-half
 ===================================
 
@@ -370,6 +386,14 @@ Match rule:
      - Update ``link/speed/duplex``, update ``lp_advertising`` as needed
      - OK on link down; negative errno only on access failure
 
+Clause 22 drivers can reuse ``genphy_c22_config_init()``,
+``genphy_c22_config_aneg()``, ``genphy_c22_read_status()``,
+``genphy_c22_config_power()`` and ``genphy_c22_soft_reset()`` from the
+internal ``drivers/net/phy/phy.h`` interface. Callback tables can reference
+these shared operations directly; forwarding wrappers are unnecessary.
+Implementation-only helpers remain static. Clause 45 operations use the
+separate ``genphy_c45_*`` naming.
+
 6.4 Capability-dependent Callbacks
 ----------------------------------
 

Reply via email to