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 64e4d571ce378565e63dbf80597216e17f39a8c9
Author: zhangkai25 <[email protected]>
AuthorDate: Mon Jul 27 15:13:26 2026 +0800

    net/phy: add PHY abstraction layer (PHYLIB) framework
    
    Add a PHY Abstraction Layer (PHYLIB) framework to NuttX. This introduces
    the PHY device model, PHY driver framework with generic Clause 22/45 PHY
    drivers, and a work-queue-driven PHY state machine. The subsystem
    decouples PHY management from individual MAC drivers and integrates with
    the existing upper/lower half network driver pattern via ethtool and MII
    ioctl support. Gated by CONFIG_NET_PHYLIB, fully backward compatible when
    disabled.
    
    Builds on the MDIO bus Clause 45 / reset-level support added previously.
    Vendor PHY drivers (e.g. Realtek) are added in following commits.
    
    Signed-off-by: zhangkai25 <[email protected]>
---
 drivers/net/CMakeLists.txt           |   11 +
 drivers/net/Kconfig                  |   38 ++
 drivers/net/Make.defs                |   12 +
 drivers/net/netdev_upperhalf.c       |   15 +
 drivers/net/phy/phy.h                |  158 ++++++
 drivers/net/phy/phy_access.c         |  269 +++++++++
 drivers/net/phy/phy_core.c           | 1010 ++++++++++++++++++++++++++++++++++
 drivers/net/phy/phy_device.c         |  605 ++++++++++++++++++++
 drivers/net/phy/phy_gen.c            |  373 +++++++++++++
 drivers/net/phy/phy_genc45.c         |  272 +++++++++
 include/nuttx/ethtool.h              |  102 +++-
 include/nuttx/net/mii.h              |   71 +++
 include/nuttx/net/netdev_lowerhalf.h |    6 +
 include/nuttx/net/phy.h              |  232 +++++++-
 14 files changed, 3172 insertions(+), 2 deletions(-)

diff --git a/drivers/net/CMakeLists.txt b/drivers/net/CMakeLists.txt
index 8a0d0d3105c..2faa773cf6d 100644
--- a/drivers/net/CMakeLists.txt
+++ b/drivers/net/CMakeLists.txt
@@ -123,6 +123,17 @@ if(CONFIG_NET)
     list(APPEND SRCS wifi_sim.c)
   endif()
 
+  if(CONFIG_NET_PHYLIB)
+    list(APPEND SRCS phy/phy_core.c phy/phy_access.c phy/phy_device.c
+         phy/phy_gen.c)
+
+    target_include_directories(drivers PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/phy)
+
+    if(CONFIG_MDIO_CLAUSE_45)
+      list(APPEND SRCS phy/phy_genc45.c)
+    endif()
+  endif()
+
   target_sources(drivers PRIVATE ${SRCS})
 
   nuttx_add_subdirectory()
diff --git a/drivers/net/Kconfig b/drivers/net/Kconfig
index 3b0c3da673d..bccc09d533c 100644
--- a/drivers/net/Kconfig
+++ b/drivers/net/Kconfig
@@ -837,4 +837,42 @@ endif # NET_IGC
 
 source "drivers/net/oa_tc6/Kconfig"
 
+comment "PHY Support"
+
+menuconfig NET_PHYLIB
+       bool "PHY Abstraction Layer (PHYLIB)"
+       default n
+       depends on NET
+       depends on MDIO_BUS
+       ---help---
+               Enable the PHY Abstraction Layer (PHYLIB) which provides a
+               standardized MDIO bus abstraction, PHY device model, PHY driver
+               framework, and PHY state machine. This decouples PHY management
+               from individual MAC drivers.
+
+if NET_PHYLIB
+
+config NET_PHYLIB_POLL_INTERVAL
+       int "PHY state machine poll interval (ms)"
+       default 1000
+       ---help---
+               The interval in milliseconds at which the PHY state machine
+               polls the PHY link status.
+
+config NET_PHYLIB_MAX_DRIVERS
+       int "Maximum number of PHY drivers"
+       default 8
+       ---help---
+               Maximum number of PHY drivers that can be registered
+               simultaneously.
+
+config NET_PHYLIB_MAX_PHYS
+       int "Maximum number of PHY devices"
+       default 8
+       ---help---
+               Maximum number of PHY devices that can be tracked
+               simultaneously.
+
+endif # NET_PHYLIB
+
 endif # NETDEVICES
diff --git a/drivers/net/Make.defs b/drivers/net/Make.defs
index 6fc1a0816be..7583985094f 100644
--- a/drivers/net/Make.defs
+++ b/drivers/net/Make.defs
@@ -128,6 +128,18 @@ endif
 
 include net/oa_tc6/Make.defs
 
+ifeq ($(CONFIG_NET_PHYLIB),y)
+  CSRCS += phy_core.c phy_access.c phy_device.c
+  CSRCS += phy_gen.c
+  DEPPATH += --dep-path net/phy
+  VPATH += :net/phy
+  CFLAGS += ${INCDIR_PREFIX}$(TOPDIR)$(DELIM)drivers$(DELIM)net$(DELIM)phy
+
+ifeq ($(CONFIG_MDIO_CLAUSE_45),y)
+  CSRCS += phy_genc45.c
+endif
+endif
+
 # Include network build support
 
 DEPPATH += --dep-path net
diff --git a/drivers/net/netdev_upperhalf.c b/drivers/net/netdev_upperhalf.c
index 7e4fced2be2..db35e8c114e 100644
--- a/drivers/net/netdev_upperhalf.c
+++ b/drivers/net/netdev_upperhalf.c
@@ -44,6 +44,10 @@
 #include <nuttx/semaphore.h>
 #include <nuttx/spinlock.h>
 
+#ifdef CONFIG_NET_PHYLIB
+#  include <nuttx/net/phy.h>
+#endif
+
 #ifdef CONFIG_DRIVERS_NOTENET
 #  include "netdev_drivers.h"
 #endif
@@ -1404,6 +1408,17 @@ static int netdev_upper_ioctl(FAR struct net_driver_s 
*dev, int cmd,
   FAR struct netdev_lowerhalf_s *lower = upper->lower;
   int ret = -ENOTTY;
 
+#ifdef CONFIG_NET_PHYLIB
+  if (lower->phydev != NULL)
+    {
+      ret = phy_ioctl(lower->phydev, cmd, arg);
+      if (ret != -ENOTTY)
+        {
+          return ret;
+        }
+    }
+#endif
+
 #ifdef CONFIG_NETDEV_WIRELESS_HANDLER
   if (lower->iw_ops)
     {
diff --git a/drivers/net/phy/phy.h b/drivers/net/phy/phy.h
new file mode 100644
index 00000000000..a7cfa242cd5
--- /dev/null
+++ b/drivers/net/phy/phy.h
@@ -0,0 +1,158 @@
+/****************************************************************************
+ * drivers/net/phy/phy.h
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+#ifndef __DRIVERS_NET_PHY_PHY_H
+#define __DRIVERS_NET_PHY_PHY_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#include <nuttx/net/phy.h>
+
+#ifdef CONFIG_NET_PHYLIB
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+/* PHY driver callbacks.
+ *
+ * This is the interface a vendor PHY driver implements and hands to
+ * phy_driver_register().  It is internal to the phylib core and the vendor
+ * PHY drivers under drivers/net/phy; it is not part of the public API in
+ * include/nuttx/net/phy.h (which carries only a forward declaration for the
+ * phydev->drv back-pointer).
+ */
+
+struct phy_driver_s
+{
+  FAR const char *name;
+  uint32_t phy_id;
+  uint32_t phy_id_mask;
+
+  CODE int (*config_init)(FAR struct phy_device_s *phydev);
+  CODE int (*config_aneg)(FAR struct phy_device_s *phydev);
+  CODE int (*read_status)(FAR struct phy_device_s *phydev);
+
+  /* config_power - Power the PHY hardware up or down.  'enable' selects
+   *                power up (true) or power down (false).  Optional: a
+   *                driver with no power-management support leaves this NULL
+   *                (treated as a no-op).
+   */
+
+  CODE int (*config_power)(FAR struct phy_device_s *phydev, bool enable);
+
+  /* Interrupt support (optional).
+   *
+   * config_intr      - Enable or disable the PHY's interrupt output (INTB),
+   *                    e.g. program the PHY interrupt-enable register.
+   *                    'enable' selects enable (true) or disable (false).
+   *                    Should also clear any pending interrupts before
+   *                    enabling and after disabling.
+   *
+   * handle_interrupt - PHY interrupt handler.  The driver reads its own
+   *                    vendor interrupt-status register, decodes ALL pending
+   *                    sources, services/acknowledges them, and decides what
+   *                    to do.  Return value:
+   *                      >0 : a link-relevant event is pending -> the state
+   *                           machine then re-reads link status.
+   *                       0 : no link-relevant event           -> link state
+   *                           left untouched (e.g. a pure diagnostic event
+   *                           handled internally by the driver).
+   *                      <0 : MDIO/HW failure (PHY unreachable) -> the state
+   *                           machine enters PHY_ERROR.
+   *                    Non-link events (undervoltage / overtemp / jabber /
+   *                    remote-fault) are handled inside this callback and
+   *                    must NOT be pushed into the link state machine; if
+   *                    such an event also drops the link, return >0 so link
+   *                    status is re-read and reflected truthfully.
+   *
+   * Both NULL => the PHY can only be used in polling mode.
+   */
+
+  CODE int (*config_intr)(FAR struct phy_device_s *phydev, bool enable);
+  CODE int (*handle_interrupt)(FAR struct phy_device_s *phydev);
+};
+
+/****************************************************************************
+ * Public Data
+ ****************************************************************************/
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+/* Generic PHY driver instances shared across the phylib core (used by
+ * phy_find_driver() as the C22/C45 fallbacks).
+ */
+
+extern const struct phy_driver_s g_genphy_driver;
+#ifdef CONFIG_MDIO_CLAUSE_45
+extern const struct phy_driver_s g_genphy_c45_driver;
+#endif
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+/* PHY driver registration (phy_device.c).  Called by vendor PHY drivers to
+ * register their phy_driver_s callback table; not part of the public API.
+ */
+
+int phy_driver_register(FAR const struct phy_driver_s *drv);
+
+/* PHY register utilities (phy_access.c).  Internal to the phylib core and
+ * the vendor PHY drivers under drivers/net/phy; not part of the public API.
+ */
+
+int phy_read(FAR struct phy_device_s *phydev, uint8_t regaddr);
+int phy_write(FAR struct phy_device_s *phydev,
+              uint8_t regaddr, uint16_t val);
+int phy_modify(FAR struct phy_device_s *phydev,
+               uint8_t regaddr, uint16_t mask, uint16_t set);
+int phy_set_bits(FAR struct phy_device_s *phydev,
+                 uint8_t regaddr, uint16_t bits);
+int phy_clear_bits(FAR struct phy_device_s *phydev,
+                   uint8_t regaddr, uint16_t bits);
+#ifdef CONFIG_MDIO_CLAUSE_45
+int phy_read_mmd(FAR struct phy_device_s *phydev,
+                 uint8_t devad, uint16_t regaddr);
+int phy_write_mmd(FAR struct phy_device_s *phydev,
+                  uint8_t devad, uint16_t regaddr, uint16_t val);
+int phy_modify_mmd(FAR struct phy_device_s *phydev,
+                   uint8_t devad, uint16_t regaddr,
+                   uint16_t mask, uint16_t set);
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* CONFIG_NET_PHYLIB */
+#endif /* __DRIVERS_NET_PHY_PHY_H */
diff --git a/drivers/net/phy/phy_access.c b/drivers/net/phy/phy_access.c
new file mode 100644
index 00000000000..72d5806d86a
--- /dev/null
+++ b/drivers/net/phy/phy_access.c
@@ -0,0 +1,269 @@
+/****************************************************************************
+ * drivers/net/phy/phy_access.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <errno.h>
+#include <debug.h>
+
+#include <nuttx/net/phy.h>
+#include <nuttx/net/mdio.h>
+
+#include "phy.h"
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: phy_read
+ *
+ * Description:
+ *   Read a PHY register via the MDIO bus.
+ *
+ * Input Parameters:
+ *   phydev  - Pointer to the PHY device structure
+ *   regaddr - MII register address to read
+ *
+ * Returned Value:
+ *   Register value (16-bit) on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_read(FAR struct phy_device_s *phydev, uint8_t regaddr)
+{
+  uint16_t value;
+  int ret;
+
+  ret = mdio_read(phydev->bus, phydev->mdio_addr, regaddr, &value);
+  if (ret < 0)
+    {
+      return ret;
+    }
+
+  return value;
+}
+
+/****************************************************************************
+ * Name: phy_write
+ *
+ * Description:
+ *   Write a value to a PHY register via the MDIO bus.
+ *
+ * Input Parameters:
+ *   phydev  - Pointer to the PHY device structure
+ *   regaddr - MII register address to write
+ *   val     - 16-bit value to write
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_write(FAR struct phy_device_s *phydev,
+              uint8_t regaddr, uint16_t val)
+{
+  return mdio_write(phydev->bus, phydev->mdio_addr, regaddr, val);
+}
+
+/****************************************************************************
+ * Name: phy_modify
+ *
+ * Description:
+ *   Perform a read-modify-write on a PHY register. The bits selected
+ *   by mask are cleared and then set according to the set parameter.
+ *
+ * Input Parameters:
+ *   phydev  - Pointer to the PHY device structure
+ *   regaddr - MII register address to modify
+ *   mask    - Bitmask of bits to clear
+ *   set     - Bitmask of bits to set (masked by mask)
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_modify(FAR struct phy_device_s *phydev,
+               uint8_t regaddr, uint16_t mask, uint16_t set)
+{
+  int ret;
+  uint16_t value;
+
+  ret = mdio_read(phydev->bus, phydev->mdio_addr, regaddr, &value);
+  if (ret < 0)
+    {
+      return ret;
+    }
+
+  value = (value & ~mask) | (set & mask);
+  return mdio_write(phydev->bus, phydev->mdio_addr, regaddr, value);
+}
+
+/****************************************************************************
+ * Name: phy_set_bits
+ *
+ * Description:
+ *   Set specific bits in a PHY register without affecting other bits.
+ *
+ * Input Parameters:
+ *   phydev  - Pointer to the PHY device structure
+ *   regaddr - MII register address to modify
+ *   bits    - Bitmask of bits to set
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_set_bits(FAR struct phy_device_s *phydev,
+                 uint8_t regaddr, uint16_t bits)
+{
+  return phy_modify(phydev, regaddr, bits, bits);
+}
+
+/****************************************************************************
+ * Name: phy_clear_bits
+ *
+ * Description:
+ *   Clear specific bits in a PHY register without affecting other bits.
+ *
+ * Input Parameters:
+ *   phydev  - Pointer to the PHY device structure
+ *   regaddr - MII register address to modify
+ *   bits    - Bitmask of bits to clear
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_clear_bits(FAR struct phy_device_s *phydev,
+                   uint8_t regaddr, uint16_t bits)
+{
+  return phy_modify(phydev, regaddr, bits, 0);
+}
+
+#ifdef CONFIG_MDIO_CLAUSE_45
+
+/****************************************************************************
+ * Name: phy_read_mmd
+ *
+ * Description:
+ *   Read a PHY MMD (MDIO Manageable Device) register using Clause 45
+ *   access over Clause 22.  Only available when CONFIG_MDIO_CLAUSE_45 set.
+ *
+ * Input Parameters:
+ *   phydev  - Pointer to the PHY device structure
+ *   devad   - MMD device address (e.g. MII_MMD_PCS)
+ *   regaddr - Register address within the MMD device
+ *
+ * Returned Value:
+ *   Register value (16-bit) on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_read_mmd(FAR struct phy_device_s *phydev,
+                 uint8_t devad, uint16_t regaddr)
+{
+  uint16_t value;
+  int ret;
+
+  ret = mdio_c45_read(phydev->bus, phydev->mdio_addr, devad, regaddr,
+                      &value);
+  if (ret < 0)
+    {
+      return ret;
+    }
+
+  return value;
+}
+
+/****************************************************************************
+ * Name: phy_write_mmd
+ *
+ * Description:
+ *   Write a PHY MMD (MDIO Manageable Device) register using Clause 45
+ *   access over Clause 22.
+ *
+ * Input Parameters:
+ *   phydev  - Pointer to the PHY device structure
+ *   devad   - MMD device address (e.g. MII_MMD_PCS)
+ *   regaddr - Register address within the MMD device
+ *   val     - 16-bit value to write
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_write_mmd(FAR struct phy_device_s *phydev,
+                  uint8_t devad, uint16_t regaddr, uint16_t val)
+{
+  return mdio_c45_write(phydev->bus, phydev->mdio_addr,
+                        devad, regaddr, val);
+}
+
+/****************************************************************************
+ * Name: phy_modify_mmd
+ *
+ * Description:
+ *   Read-modify-write a PHY MMD (MDIO Manageable Device) register using
+ *   Clause 45 access over Clause 22.  The bits selected by mask are cleared
+ *   and then set according to the set parameter.
+ *
+ * Input Parameters:
+ *   phydev  - Pointer to the PHY device structure
+ *   devad   - MMD device address (e.g. MII_MMD_PCS)
+ *   regaddr - Register address within the MMD device
+ *   mask    - Bitmask of bits to clear
+ *   set     - Bitmask of bits to set (masked by mask)
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_modify_mmd(FAR struct phy_device_s *phydev,
+                   uint8_t devad, uint16_t regaddr,
+                   uint16_t mask, uint16_t set)
+{
+  uint16_t value;
+  int ret;
+
+  ret = mdio_c45_read(phydev->bus, phydev->mdio_addr, devad, regaddr,
+                      &value);
+  if (ret < 0)
+    {
+      return ret;
+    }
+
+  value = (value & ~mask) | (set & mask);
+  return mdio_c45_write(phydev->bus, phydev->mdio_addr, devad, regaddr,
+                        value);
+}
+
+#endif /* CONFIG_MDIO_CLAUSE_45 */
diff --git a/drivers/net/phy/phy_core.c b/drivers/net/phy/phy_core.c
new file mode 100644
index 00000000000..a227209385d
--- /dev/null
+++ b/drivers/net/phy/phy_core.c
@@ -0,0 +1,1010 @@
+/****************************************************************************
+ * drivers/net/phy/phy_core.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <errno.h>
+#include <debug.h>
+#include <inttypes.h>
+#include <string.h>
+#include <sys/types.h>
+#include <syslog.h>
+
+#include <nuttx/irq.h>
+#include <nuttx/arch.h>
+#include <nuttx/wqueue.h>
+#include <nuttx/net/phy.h>
+#include <nuttx/net/mii.h>
+#include <nuttx/net/ioctl.h>
+#include <nuttx/net/netdev_lowerhalf.h>
+#include <nuttx/ethtool.h>
+
+#include <net/if.h>
+
+#include "phy.h"
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+#define PHY_POLL_TICKS MSEC2TICK(CONFIG_NET_PHYLIB_POLL_INTERVAL)
+
+/* The PHY core currently stores each link mode mask in one 32-bit word. */
+
+#define PHY_LINK_MODE_MASK_NWORDS 1
+
+/* phy_interrupt_is_valid - true only when phy_device_s.irq is a real,
+ * attachable interrupt number.  Both sentinels (PHY_POLL, PHY_MAC_INTERRUPT)
+ * are negative, so a non-negative irq is a real, attachable IRQ number.
+ */
+
+#define phy_interrupt_is_valid(p) ((p)->irq >= 0)
+
+/****************************************************************************
+ * Private Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: phy_check_link
+ *
+ * Description:
+ *   Read the current PHY status and run the link up/down state transitions,
+ *   updating phydev->state.  Shared by both the polling work and the
+ *   interrupt work so the two paths behave identically.
+ *
+ *   Carrier notification (netdev_lower_carrier_on/off) is NOT performed
+ *   here: it takes the netdev d_lock and would invert the lock order used
+ *   by the ioctl path (d_lock then phydev->lock), risking an AB-BA
+ *   deadlock.  The caller therefore compares phydev->state before and after
+ *   this call and performs the carrier notification after releasing
+ *   phydev->lock.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   None.  The new link state is reflected in phydev->state.
+ *
+ ****************************************************************************/
+
+static void phy_check_link(FAR struct phy_device_s *phydev)
+{
+  int ret;
+
+  /* In interrupt mode, service the PHY interrupt source first so INTB
+   * de-asserts and a fresh edge can be latched.  Both the polling and the
+   * interrupt paths share this single state machine entry point: the
+   * interrupt path only kicks the state machine, and the driver's
+   * handle_interrupt() does the actual decode/ack.
+   *
+   *   handle_interrupt - the driver reads its own vendor interrupt-status
+   *     register, decodes ALL pending sources (link and non-link), services
+   *     non-link diagnostic events internally, and returns:
+   *     >0 : a link-relevant event is pending -> re-read link status below
+   *      0 : no link-relevant event           -> skip the link re-read
+   *     <0 : MDIO/HW failure (PHY unreachable) -> enter PHY_ERROR
+   *
+   * The PHY_UP state is the one exception: it is the first run scheduled by
+   * phy_start(), whose purpose is to latch the initial link state.  At that
+   * point config_intr() has just cleared the interrupt status, so
+   * handle_interrupt() would report "no event" and we would never read the
+   * initial status (leaving a link that is already up undetected).  Skip the
+   * interrupt decode in PHY_UP and always read status below.
+   */
+
+  if (phydev->irq != PHY_POLL && phydev->drv->handle_interrupt &&
+      phydev->state != PHY_UP)
+    {
+      ret = phydev->drv->handle_interrupt(phydev);
+      if (ret < 0)
+        {
+          /* The PHY is unreachable (could not even read its interrupt
+           * status register).  Enter the error state: force the carrier
+           * off and stop rescheduling.  Recovery needs an explicit
+           * stop/start cycle.
+           */
+
+          nerr("ERROR: handle_interrupt failed: %d\n", ret);
+          phydev->state = PHY_ERROR;
+          return;
+        }
+      else if (ret == 0)
+        {
+          /* No link-relevant event (e.g. a pure diagnostic interrupt that
+           * the driver already serviced internally).  Leave the link state
+           * untouched and do not re-read status.
+           */
+
+          return;
+        }
+
+      /* ret > 0: fall through to re-read link status. */
+    }
+
+  /* Read current PHY status */
+
+  if (phydev->drv->read_status)
+    {
+      ret = phydev->drv->read_status(phydev);
+      if (ret < 0)
+        {
+          /* A failed status read means the PHY is unreachable.  Enter the
+           * error state rather than silently retrying every poll period.
+           */
+
+          nerr("ERROR: read_status failed: %d\n", ret);
+          phydev->state = PHY_ERROR;
+          return;
+        }
+    }
+
+  /* Handle state transitions based on link status */
+
+  switch (phydev->state)
+    {
+      case PHY_UP:
+      case PHY_NOLINK:
+        if (phydev->link)
+          {
+            phydev->state = PHY_RUNNING;
+            ninfo("PHY link up: %" PRIu32 " Mbps %s\n", phydev->speed,
+                  phydev->duplex == DUPLEX_FULL ? "full" : "half");
+          }
+        else if (phydev->state == PHY_UP)
+          {
+            phydev->state = PHY_NOLINK;
+          }
+        break;
+
+      case PHY_RUNNING:
+        if (!phydev->link)
+          {
+            phydev->state = PHY_NOLINK;
+            ninfo("PHY link down\n");
+          }
+        break;
+
+      default:
+        break;
+    }
+}
+
+/****************************************************************************
+ * Name: phy_work
+ *
+ * Description:
+ *   Work queue callback for PHY state machine polling. Reads the current
+ *   PHY link status and handles state transitions between UP, RUNNING,
+ *   and NOLINK. Notifies the attached network device of carrier changes.
+ *
+ *   In polling mode this runs every PHY_POLL_TICKS.  In interrupt mode it
+ *   runs only when kicked by a PHY interrupt and does not reschedule
+ *   itself, trusting the PHY interrupt to report every link change.
+ *
+ * Input Parameters:
+ *   arg - Pointer to the PHY device structure (cast to void *)
+ *
+ * Returned Value:
+ *   None.
+ *
+ ****************************************************************************/
+
+static void phy_work(FAR void *arg)
+{
+  FAR struct phy_device_s *phydev = (FAR struct phy_device_s *)arg;
+  FAR struct netdev_lowerhalf_s *lower;
+  enum phy_state_e oldstate;
+  enum phy_state_e newstate;
+
+  if (phydev == NULL)
+    {
+      return;
+    }
+
+  nxmutex_lock(&phydev->lock);
+
+  /* Run the link state transitions.  phy_check_link() only updates
+   * phydev->state; the carrier notification is derived from the state
+   * change and performed after the unlock (see below).  Both the old and
+   * new state are snapshotted under the lock so the comparison below does
+   * not race with a concurrent phy_stop()/phy_start().
+   */
+
+  oldstate = phydev->state;
+  phy_check_link(phydev);
+  newstate = phydev->state;
+
+  /* Snapshot the attached device while holding the lock; the carrier
+   * notification itself must run after the unlock (see below).
+   */
+
+  lower = phydev->lower;
+
+  /* If we own a real interrupt line, the source has now been decoded and
+   * acknowledged inside phy_check_link()->handle_interrupt(), so it is safe
+   * to unmask the line that phy_isr() disabled (one-shot
+   * equivalent).  Skip this while halted/errored: phy_stop() detaches the
+   * IRQ, and in PHY_ERROR the PHY is unreachable so leaving the line masked
+   * avoids an interrupt storm until an explicit stop/start recovery.
+   */
+
+  if (phy_interrupt_is_valid(phydev) &&
+      phydev->state != PHY_HALTED && phydev->state != PHY_ERROR)
+    {
+      up_enable_irq(phydev->irq);
+    }
+
+  /* In polling mode, reschedule the next poll while in an active state.
+   * In interrupt mode we trust the PHY interrupt to kick the state machine
+   * on every link change, so no periodic poll is queued.
+   */
+
+  if (phydev->irq == PHY_POLL &&
+      (phydev->state == PHY_UP ||
+       phydev->state == PHY_RUNNING ||
+       phydev->state == PHY_NOLINK))
+    {
+      work_queue(LPWORK, &phydev->state_work,
+                 phy_work, phydev, PHY_POLL_TICKS);
+    }
+
+  nxmutex_unlock(&phydev->lock);
+
+  /* Perform the carrier notification outside the phydev->lock critical
+   * section, driven by the state change observed above.  Entering
+   * PHY_RUNNING means link up; leaving it means link down.
+   *
+   * netdev_lower_carrier_on/off() take the netdev d_lock, while the ioctl
+   * path takes d_lock before phydev->lock.  The carrier notification is
+   * synchronous, so calling it while holding phydev->lock would invert that
+   * order and risk an AB-BA deadlock.  Performing it here, after the
+   * unlock, avoids that.  This mirrors phy_stop().
+   */
+
+  if (newstate != oldstate)
+    {
+      if (newstate == PHY_RUNNING)
+        {
+          netdev_lower_carrier_on(lower);
+        }
+      else if (oldstate == PHY_RUNNING)
+        {
+          netdev_lower_carrier_off(lower);
+        }
+    }
+}
+
+/****************************************************************************
+ * Name: phy_isr
+ *
+ * Description:
+ *   Low-level interrupt handler attached to a real PHY interrupt line
+ *   (phy_device_s.irq >= 0) by phy_request_interrupt().  Runs in hard
+ *   interrupt context, so it must NOT touch the MDIO bus (reading the PHY
+ *   would block).  It only kicks the shared state machine work, mirroring
+ *   the "trigger only" half.  The actual PHY
+ *   interrupt-status decode/ack happens later in phy_check_link() ->
+ *   handle_interrupt(), which runs in the LPWORK thread context.
+ *
+ *   NuttX has no threaded-IRQ primitive, so the work-queue
+ *   hand-off is what gives us the sleepable context needed to read MDIO.
+ *
+ * Input Parameters:
+ *   irq     - The interrupt number (unused)
+ *   context - Saved register context (unused)
+ *   arg     - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK.
+ *
+ ****************************************************************************/
+
+static int phy_isr(int irq, FAR void *context, FAR void *arg)
+{
+  FAR struct phy_device_s *phydev = (FAR struct phy_device_s *)arg;
+
+  /* Mask the line until the worker has serviced (and de-asserted) the PHY
+   * interrupt source.  This emulates a one-shot interrupt: without it a
+   * level-triggered INTB that stays asserted until the status register is
+   * read in the worker would re-enter this handler forever.  The worker
+   * re-enables the line once handle_interrupt() has cleared the source.
+   */
+
+  up_disable_irq(irq);
+
+  /* Kick the shared state machine work to run immediately.  If the work is
+   * already pending/running, work_queue() simply re-queues it; the PHY
+   * status is read freshly when it runs, so coalescing is harmless.
+   */
+
+  work_queue(LPWORK, &phydev->state_work, phy_work, phydev, 0);
+  return OK;
+}
+
+/****************************************************************************
+ * Name: phy_free_interrupt
+ *
+ * Description:
+ *   Disable and detach the phylib-owned ISR previously attached by
+ *   phy_request_interrupt().  A no-op
+ *   if this PHY does not own an attached line.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   None.
+ *
+ ****************************************************************************/
+
+static void phy_free_interrupt(FAR struct phy_device_s *phydev)
+{
+  /* Only a real PHY line (irq >= 0) has a phylib-owned ISR to detach.  A
+   * MAC-owned line (PHY_MAC_INTERRUPT) or polling (PHY_POLL) has none.
+   * Mask the line, then detach the phylib handler from the interrupt
+   * number supplied by the MAC driver.
+   */
+
+  if (phy_interrupt_is_valid(phydev))
+    {
+      up_disable_irq(phydev->irq);
+      irq_detach(phydev->irq);
+
+      ninfo("PHY ISR detached from irq %d\n", phydev->irq);
+    }
+}
+
+/****************************************************************************
+ * Name: phy_request_interrupt
+ *
+ * Description:
+ *   Bring the PHY up in interrupt-driven mode: for a real PHY interrupt
+ *   line (phy_device_s.irq >= 0) attach the phylib-owned ISR, then program
+ *   the PHY's interrupt-enable register via config_intr().  A MAC-owned
+ *   line (PHY_MAC_INTERRUPT) skips the ISR attach (the MAC ISR calls
+ *   phy_interrupt() itself) but still enables the PHY interrupt output.
+ *
+ *   A failure here is not hidden by degrading to polling: attaching a bad
+ *   irq is a board misconfiguration, and a config_intr failure means the
+ *   PHY is unreachable over MDIO (polling would fail the same way).  The
+ *   error is returned so phy_start() can drive the PHY into PHY_ERROR.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Assumptions:
+ *   Called from phy_start() with phydev->irq != PHY_POLL and a non-NULL
+ *   config_intr callback.
+ *
+ * Returned Value:
+ *   OK on success; a negated errno if the interrupt could not be set up.
+ *
+ ****************************************************************************/
+
+static int phy_request_interrupt(FAR struct phy_device_s *phydev)
+{
+  int ret;
+
+  /* A real PHY interrupt line (irq >= 0) needs a phylib-owned ISR attached
+   * to the interrupt number supplied by the MAC/board driver.  A MAC-owned
+   * line (PHY_MAC_INTERRUPT) has no phylib ISR; the MAC driver calls
+   * phy_interrupt() itself.
+   */
+
+  if (phy_interrupt_is_valid(phydev))
+    {
+      ret = irq_attach(phydev->irq, phy_isr, phydev);
+      if (ret < 0)
+        {
+          /* A bad interrupt number is a board/integration error.  Report it
+           * instead of silently falling back to polling: the caller
+           * requested interrupt mode with a concrete irq, so honour that
+           * contract and surface the misconfiguration.
+           */
+
+          nerr("ERROR: irq_attach(%d) failed: %d\n", phydev->irq, ret);
+          return ret;
+        }
+
+      up_enable_irq(phydev->irq);
+    }
+
+  /* Program the PHY's interrupt-enable register.  Both a real PHY line and
+   * a MAC-owned line need this.
+   */
+
+  ret = phydev->drv->config_intr(phydev, true);
+  if (ret < 0)
+    {
+      /* config_intr programs the PHY's interrupt-enable register over MDIO.
+       * A failure here is a genuine setup error (PHY unreachable over MDIO,
+       * or the driver cannot enable the PHY's interrupt).  Do not mask it by
+       * degrading to polling: the polling path (read_status) shares the same
+       * MDIO bus, so the fault would only resurface as a link that never
+       * comes up.  Detach the ISR and report the error so phy_start() drives
+       * the PHY into PHY_ERROR, consistent with how phy_check_link() treats
+       * a read_status/handle_interrupt failure.
+       */
+
+      nerr("ERROR: config_intr failed: %d\n", ret);
+      phy_free_interrupt(phydev);
+      return ret;
+    }
+
+  ninfo("PHY interrupt mode enabled (irq=%d)\n", phydev->irq);
+  return OK;
+}
+
+/****************************************************************************
+ * Name: phy_ethtool_get_link_settings
+ *
+ * Description:
+ *   Get the current link settings from the PHY device, including speed,
+ *   duplex, auto-negotiation state, and advertising capabilities.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *   cmd    - Pointer to ethtool link settings structure to fill
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int phy_ethtool_get_link_settings(
+      FAR struct phy_device_s *phydev,
+      FAR struct ethtool_link_settings *cmd)
+{
+  /* Negotiate the number of 32-bit words in each link mode mask. */
+
+  if (cmd->link_mode_masks_nwords != PHY_LINK_MODE_MASK_NWORDS)
+    {
+      memset(cmd, 0, sizeof(*cmd));
+      cmd->cmd = ETHTOOL_GLINKSETTINGS;
+      cmd->link_mode_masks_nwords = -PHY_LINK_MODE_MASK_NWORDS;
+      return OK;
+    }
+
+  nxmutex_lock(&phydev->lock);
+
+  memset(cmd, 0, sizeof(*cmd));
+  cmd->cmd            = ETHTOOL_GLINKSETTINGS;
+  cmd->speed          = phydev->speed;
+  cmd->duplex         = phydev->duplex;
+  cmd->autoneg        = phydev->autoneg ? AUTONEG_ENABLE : AUTONEG_DISABLE;
+  cmd->phy_address    = phydev->mdio_addr;
+  cmd->mdio_support   = phydev->c45 ? ETH_MDIO_SUPPORTS_C45 :
+                                      ETH_MDIO_SUPPORTS_C22;
+  cmd->link_mode_masks_nwords = PHY_LINK_MODE_MASK_NWORDS;
+  cmd->link_mode_masks[0] = phydev->supported;
+  cmd->link_mode_masks[1] = phydev->advertising;
+  cmd->link_mode_masks[2] = phydev->lp_advertising;
+
+  nxmutex_unlock(&phydev->lock);
+
+  return OK;
+}
+
+/****************************************************************************
+ * Name: phy_ethtool_set_link_settings
+ *
+ * Description:
+ *   Set the link settings on the PHY device. Updates the advertising
+ *   capabilities and restarts auto-negotiation if configured.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *   cmd    - Pointer to ethtool link settings with desired values
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int phy_ethtool_set_link_settings(
+      FAR struct phy_device_s *phydev,
+      FAR const struct ethtool_link_settings *cmd)
+{
+  uint32_t advertising;
+  int ret = OK;
+
+  if (cmd->link_mode_masks_nwords != PHY_LINK_MODE_MASK_NWORDS)
+    {
+      return -EINVAL;
+    }
+
+  /* link_mode_masks[] layout matches the get path:
+   *   [0] supported      (read-only)
+   *   [1] advertising    (writable - the value being set here)
+   *   [2] lp_advertising (read-only)
+   */
+
+  advertising = cmd->link_mode_masks[1];
+
+  nxmutex_lock(&phydev->lock);
+
+  /* Validate advertising is subset of supported */
+
+  if (advertising & ~phydev->supported)
+    {
+      nxmutex_unlock(&phydev->lock);
+      return -EINVAL;
+    }
+
+  phydev->advertising = advertising;
+  phydev->autoneg = (cmd->autoneg == AUTONEG_ENABLE);
+
+  /* Restart auto-negotiation */
+
+  if (phydev->drv->config_aneg)
+    {
+      ret = phydev->drv->config_aneg(phydev);
+    }
+
+  nxmutex_unlock(&phydev->lock);
+  return ret;
+}
+
+/****************************************************************************
+ * Name: phy_ethtool_nway_reset
+ *
+ * Description:
+ *   Restart auto-negotiation on the PHY device by calling the driver's
+ *   config_aneg callback.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; -EOPNOTSUPP if no config_aneg callback is available;
+ *   negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int phy_ethtool_nway_reset(FAR struct phy_device_s *phydev)
+{
+  int ret;
+
+  nxmutex_lock(&phydev->lock);
+
+  if (phydev->drv->config_aneg)
+    {
+      ret = phydev->drv->config_aneg(phydev);
+    }
+  else
+    {
+      ret = -EOPNOTSUPP;
+    }
+
+  nxmutex_unlock(&phydev->lock);
+  return ret;
+}
+
+/****************************************************************************
+ * Name: phy_mii_ioctl
+ *
+ * Description:
+ *   Handle MII ioctls when a PHY device is connected. Supports
+ *   SIOCGMIIPHY, SIOCGMIIREG, and SIOCSMIIREG commands.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *   cmd    - MII ioctl command
+ *   arg    - Pointer to mii_ioctl_data_s structure
+ *
+ * Returned Value:
+ *   OK on success; -ENOTTY if not handled; negated errno on error.
+ *
+ ****************************************************************************/
+
+static int phy_mii_ioctl(FAR struct phy_device_s *phydev,
+                         int cmd, unsigned long arg)
+{
+  FAR struct mii_ioctl_data_s *mii =
+    (FAR struct mii_ioctl_data_s *)(uintptr_t)arg;
+  int ret;
+
+  if (mii == NULL)
+    {
+      return -ENOTTY;
+    }
+
+  switch (cmd)
+    {
+      case SIOCGMIIPHY:
+        mii->phy_id = phydev->mdio_addr;
+        return OK;
+
+      case SIOCGMIIREG:
+        ret = phy_read(phydev, mii->reg_num);
+        if (ret < 0)
+          {
+            return ret;
+          }
+
+        mii->val_out = ret;
+        return OK;
+
+      case SIOCSMIIREG:
+        return phy_write(phydev, mii->reg_num, mii->val_in);
+
+      default:
+        return -ENOTTY;
+    }
+}
+
+/****************************************************************************
+ * Name: phy_ethtool_ioctl
+ *
+ * Description:
+ *   Handle ethtool ioctls when a PHY device is connected. Dispatches
+ *   ETHTOOL_GLINKSETTINGS, ETHTOOL_SLINKSETTINGS, ETHTOOL_NWAY_RST,
+ *   and ETHTOOL_GLINK commands.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *   arg    - Pointer to the ethtool command structure
+ *
+ * Returned Value:
+ *   OK on success; -ENOTTY if the command is not handled;
+ *   negated errno on error.
+ *
+ ****************************************************************************/
+
+static int phy_ethtool_ioctl(FAR struct phy_device_s *phydev,
+                             unsigned long arg)
+{
+  uint32_t cmd;
+
+  if (arg == 0)
+    {
+      return -ENOTTY;
+    }
+
+  cmd = *(FAR const uint32_t *)(uintptr_t)arg;
+
+  switch (cmd)
+    {
+      case ETHTOOL_GLINKSETTINGS:
+        return phy_ethtool_get_link_settings(phydev,
+                 (FAR struct ethtool_link_settings *)(uintptr_t)arg);
+
+      case ETHTOOL_SLINKSETTINGS:
+        return phy_ethtool_set_link_settings(phydev,
+                 (FAR const struct ethtool_link_settings *)(uintptr_t)arg);
+
+      case ETHTOOL_NWAY_RST:
+        return phy_ethtool_nway_reset(phydev);
+
+      case ETHTOOL_GLINK:
+        {
+          FAR struct ethtool_value *val =
+            (FAR struct ethtool_value *)(uintptr_t)arg;
+
+          nxmutex_lock(&phydev->lock);
+          val->data = phydev->link ? 1 : 0;
+          nxmutex_unlock(&phydev->lock);
+          return OK;
+        }
+
+      default:
+        return -ENOTTY;
+    }
+}
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: phy_start
+ *
+ * Description:
+ *   Start the PHY state machine. Configures auto-negotiation and starts
+ *   link status monitoring on the low-priority work queue: periodic polling
+ *   in polling mode, or interrupt-driven updates in interrupt mode.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; -EINVAL if phydev is NULL;
+ *   -EBUSY if the PHY is not in READY, HALTED or ERROR state.
+ *
+ ****************************************************************************/
+
+int phy_start(FAR struct phy_device_s *phydev)
+{
+  int ret;
+
+  if (phydev == NULL)
+    {
+      return -EINVAL;
+    }
+
+  nxmutex_lock(&phydev->lock);
+
+  /* Allow starting from READY (fresh connect), HALTED (after phy_stop) or
+   * ERROR (recovery from an unreachable-PHY condition).
+   */
+
+  if (phydev->state != PHY_READY && phydev->state != PHY_HALTED &&
+      phydev->state != PHY_ERROR)
+    {
+      nxmutex_unlock(&phydev->lock);
+      return -EBUSY;
+    }
+
+  /* Power the PHY hardware up before programming it.  phy_stop() powers it
+   * down, so this is what brings it back for a restart.  A driver with no
+   * power-management support leaves the callback NULL (a no-op).
+   */
+
+  if (phydev->drv->config_power)
+    {
+      ret = phydev->drv->config_power(phydev, true);
+      if (ret < 0)
+        {
+          nerr("ERROR: power on failed: %d\n", ret);
+          nxmutex_unlock(&phydev->lock);
+          return ret;
+        }
+    }
+
+  /* Configure auto-negotiation */
+
+  if (phydev->drv->config_aneg)
+    {
+      ret = phydev->drv->config_aneg(phydev);
+      if (ret < 0)
+        {
+          nerr("ERROR: config_aneg failed: %d\n", ret);
+          nxmutex_unlock(&phydev->lock);
+          return ret;
+        }
+    }
+
+  phydev->state = PHY_UP;
+
+  /* Enable interrupt-driven operation when an interrupt source is available
+   * and the driver provides interrupt callbacks.  Two source kinds:
+   *
+   *   irq >= 0          - a real PHY interrupt line: phylib attaches its own
+   *                       ISR (phy_request_interrupt) which kicks the state
+   *                       machine.
+   *   PHY_MAC_INTERRUPT - the MAC driver owns the interrupt and calls
+   *                       phy_interrupt() itself; no ISR attached here.
+   *
+   * Either way we program the PHY's interrupt-enable register via
+   * config_intr.  The state machine then runs only on interrupt, with no
+   * periodic poll.  A genuine no-interrupt PHY takes the PHY_POLL path and
+   * never reaches here.  If interrupt setup fails for a PHY that was
+   * supposed to use interrupts, that is a real fault (bad irq, or an
+   * unreachable PHY) and is NOT masked by degrading to polling: enter
+   * PHY_ERROR and fail the start so the caller sees the problem.
+   */
+
+  if (phydev->irq != PHY_POLL && phydev->drv->config_intr)
+    {
+      ret = phy_request_interrupt(phydev);
+      if (ret < 0)
+        {
+          phydev->state = PHY_ERROR;
+          nxmutex_unlock(&phydev->lock);
+          return ret;
+        }
+    }
+
+  ninfo("PHY state machine started (%s mode)\n",
+        phydev->irq != PHY_POLL ? "interrupt" : "polling");
+
+  nxmutex_unlock(&phydev->lock);
+
+  /* Run the state machine once, right now, to read the initial link state.
+   * A PHY (or MAC) interrupt only fires on a link *change*, so if the cable
+   * is already up when phy_start() runs no interrupt would ever arrive and
+   * the carrier would never come up without this initial run.
+   *
+   * phy_work() acquires phydev->lock itself, so it is invoked here after
+   * the unlock rather than while the lock is held.  In polling mode
+   * phy_work() reschedules itself every PHY_POLL_TICKS; in interrupt mode
+   * it runs just this once and afterwards only when an interrupt kicks it.
+   */
+
+  phy_work(phydev);
+  return OK;
+}
+
+/****************************************************************************
+ * Name: phy_stop
+ *
+ * Description:
+ *   Stop the PHY state machine. Cancels pending work queue polling and
+ *   transitions the PHY to the HALTED state. Notifies the attached
+ *   network device that the carrier is off.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_stop(FAR struct phy_device_s *phydev)
+{
+  if (phydev == NULL)
+    {
+      return -EINVAL;
+    }
+
+  nxmutex_lock(&phydev->lock);
+
+  if (phydev->irq != PHY_POLL && phydev->drv->config_intr)
+    {
+      phydev->drv->config_intr(phydev, false);
+    }
+
+  phy_free_interrupt(phydev);
+
+  /* Mark the state machine as halted while holding the lock so that any
+   * concurrent state-machine work observes the new state and does not
+   * reschedule itself.
+   */
+
+  phydev->state = PHY_HALTED;
+
+  /* Cancel the state-machine work, but only now that every source that
+   * could (re)queue it has been shut off above:
+   *
+   *   - config_intr(false) + phy_free_interrupt() stop any PHY/MAC
+   *     interrupt from calling work_queue(phy_work) again;
+   *   - PHY_HALTED stops phy_work() from rescheduling itself.
+   *
+   * This ordering is why the cancel cannot simply be done first: if it ran
+   * before the interrupt was disabled, a PHY interrupt in the gap could
+   * re-queue phy_work() after the cancel and defeat it.
+   *
+   * The lock must be released before the cancel: work_cancel_sync() blocks
+   * until an already-running phy_work() finishes, and phy_work() takes
+   * phydev->lock as its first action, so cancelling while holding the lock
+   * would deadlock (AB-BA).
+   *
+   * NOTE: phy_stop() must not be called from interrupt or idle context,
+   * because work_cancel_sync() may block waiting for a running callback.
+   */
+
+  nxmutex_unlock(&phydev->lock);
+
+  work_cancel_sync(LPWORK, &phydev->state_work);
+
+  /* Power the PHY hardware down.  This is done after work_cancel_sync() so
+   * that no in-flight phy_work() can still touch the PHY (PHY_HALTED only
+   * stops the work from re-queuing, not one already blocked on the lock),
+   * but re-acquiring phydev->lock so the power-down MDIO access is still
+   * serialised against any other access to this phydev (e.g. a concurrent
+   * phy_start() or ioctl path).  This mirrors phy_start(), which powers the
+   * PHY up under the lock.  A driver with no power-management support leaves
+   * the callback NULL (a no-op).
+   */
+
+  nxmutex_lock(&phydev->lock);
+
+  if (phydev->drv->config_power)
+    {
+      phydev->drv->config_power(phydev, false);
+    }
+
+  nxmutex_unlock(&phydev->lock);
+
+  if (phydev->lower)
+    {
+      netdev_lower_carrier_off(phydev->lower);
+    }
+
+  ninfo("PHY state machine stopped\n");
+  return OK;
+}
+
+/****************************************************************************
+ * Name: phy_interrupt
+ *
+ * Description:
+ *   Entry point for a MAC/board driver to call from its own ISR when it
+ *   detects that the PHY link has changed (the PHY_MAC_INTERRUPT case where
+ *   the PHY has no independent interrupt line owned by phylib).  It simply
+ *   triggers the shared state machine.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   None.
+ *
+ ****************************************************************************/
+
+void phy_interrupt(FAR struct phy_device_s *phydev)
+{
+  /* Only kick the state machine when interrupt-driven operation is active
+   * (irq != PHY_POLL) and the state machine is still running.  The state
+   * check matters for a MAC-owned line (PHY_MAC_INTERRUPT), whose interrupt
+   * source phylib cannot mask: after phy_stop() sets PHY_HALTED (or on
+   * PHY_ERROR) a late MAC ISR must not re-queue state_work behind the
+   * work_cancel_sync() done in phy_stop().  For a real PHY line phy_stop()
+   * already detached the ISR, so this is belt-and-suspenders there.
+   *
+   * Safe from interrupt context: work_queue() just schedules the shared
+   * state machine work to run immediately, and coalesces if it is already
+   * pending.
+   */
+
+  if (phydev->irq != PHY_POLL &&
+      phydev->state != PHY_HALTED && phydev->state != PHY_ERROR)
+    {
+      work_queue(LPWORK, &phydev->state_work, phy_work, phydev, 0);
+    }
+}
+
+/****************************************************************************
+ * Name: phy_ioctl
+ *
+ * Description:
+ *   Single entry point for PHY-related ioctls from the network upper half.
+ *   Dispatches ethtool commands (SIOCETHTOOL) and MII register commands
+ *   (SIOCGMIIPHY, SIOCGMIIREG, SIOCSMIIREG) to their respective handlers.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *   cmd    - The ioctl command
+ *   arg    - Command-specific argument
+ *
+ * Returned Value:
+ *   OK on success; -ENOTTY if the command is not handled by the PHY layer;
+ *   negated errno on error.
+ *
+ ****************************************************************************/
+
+int phy_ioctl(FAR struct phy_device_s *phydev, int cmd, unsigned long arg)
+{
+  if (phydev == NULL)
+    {
+      return -ENOTTY;
+    }
+
+  switch (cmd)
+    {
+      case SIOCETHTOOL:
+        return phy_ethtool_ioctl(phydev, arg);
+
+      case SIOCGMIIPHY:
+      case SIOCGMIIREG:
+      case SIOCSMIIREG:
+        return phy_mii_ioctl(phydev, cmd, arg);
+
+      default:
+        return -ENOTTY;
+    }
+}
diff --git a/drivers/net/phy/phy_device.c b/drivers/net/phy/phy_device.c
new file mode 100644
index 00000000000..586849ed1a2
--- /dev/null
+++ b/drivers/net/phy/phy_device.c
@@ -0,0 +1,605 @@
+/****************************************************************************
+ * drivers/net/phy/phy_device.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <errno.h>
+#include <inttypes.h>
+#include <debug.h>
+#include <string.h>
+#include <syslog.h>
+
+#include <nuttx/mutex.h>
+#include <nuttx/kmalloc.h>
+#include <nuttx/net/phy.h>
+#include <nuttx/net/mii.h>
+#include <nuttx/net/netdev_lowerhalf.h>
+#include <nuttx/ethtool.h>
+
+#include "phy.h"
+
+/****************************************************************************
+ * Private Data
+ ****************************************************************************/
+
+static FAR const struct phy_driver_s *
+g_phy_drivers[CONFIG_NET_PHYLIB_MAX_DRIVERS];
+static FAR struct phy_device_s *g_phy_devices[CONFIG_NET_PHYLIB_MAX_PHYS];
+static mutex_t g_phy_lock = NXMUTEX_INITIALIZER;
+
+/****************************************************************************
+ * Private Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: phy_find_driver
+ *
+ * Description:
+ *   Find a matching PHY driver for the given PHY ID.
+ *
+ * Input Parameters:
+ *   phy_id - 32-bit PHY identifier read from MII registers
+ *
+ * Returned Value:
+ *   Pointer to the matching PHY driver, or the generic PHY driver
+ *   if no specific match is found.
+ *
+ ****************************************************************************/
+
+static FAR const struct phy_driver_s *phy_find_driver(uint32_t phy_id,
+                                                      bool c45)
+{
+  int i;
+
+  nxmutex_lock(&g_phy_lock);
+  for (i = 0; i < CONFIG_NET_PHYLIB_MAX_DRIVERS; i++)
+    {
+      FAR const struct phy_driver_s *drv = g_phy_drivers[i];
+
+      if (drv != NULL && drv->phy_id_mask != 0 &&
+          (drv->phy_id & drv->phy_id_mask) ==
+          (phy_id & drv->phy_id_mask))
+        {
+          nxmutex_unlock(&g_phy_lock);
+          return drv;
+        }
+    }
+
+  nxmutex_unlock(&g_phy_lock);
+
+  /* Fallback: use genphy_c45 for C45 PHYs, genphy for C22 PHYs */
+
+#ifdef CONFIG_MDIO_CLAUSE_45
+  if (c45)
+    {
+      return &g_genphy_c45_driver;
+    }
+#else
+  UNUSED(c45);
+#endif
+
+  return &g_genphy_driver;
+}
+
+/****************************************************************************
+ * Name: phy_alloc_device
+ *
+ * Description:
+ *   Allocate a PHY device and register it in the device table.
+ *
+ * Input Parameters:
+ *   bus - MDIO bus to stamp into the slot as the in-use marker
+ *
+ * Returned Value:
+ *   Pointer to a newly allocated PHY device structure, or NULL if the
+ *   table is full or the allocation fails.
+ *
+ ****************************************************************************/
+
+static FAR struct phy_device_s *phy_alloc_device(FAR struct mdio_bus_s *bus)
+{
+  FAR struct phy_device_s *phydev;
+  int i;
+
+  nxmutex_lock(&g_phy_lock);
+  for (i = 0; i < CONFIG_NET_PHYLIB_MAX_PHYS; i++)
+    {
+      if (g_phy_devices[i] == NULL)
+        {
+          phydev = kmm_zalloc(sizeof(struct phy_device_s));
+          if (phydev == NULL)
+            {
+              nxmutex_unlock(&g_phy_lock);
+              return NULL;
+            }
+
+          /* Claim the slot while still holding g_phy_lock by publishing the
+           * pointer now.  Releasing the lock with the slot still NULL would
+           * let a concurrent allocator on another core grab the same slot.
+           */
+
+          phydev->bus = bus;
+          g_phy_devices[i] = phydev;
+          nxmutex_unlock(&g_phy_lock);
+          return phydev;
+        }
+    }
+
+  nxmutex_unlock(&g_phy_lock);
+  return NULL;
+}
+
+/****************************************************************************
+ * Name: phy_release_device
+ *
+ * Description:
+ *   Remove a PHY device from the device table, tear down its lock and free
+ *   it.  Shared by phy_device_free() (create/scan path) and
+ *   phy_disconnect() (connected path).  The caller must have already
+ *   detached the device (lower == NULL) and stopped the state
+ *   machine.  Any driver-private state referenced by phydev->priv is owned
+ *   by the vendor driver, which releases it (e.g. in its teardown path)
+ *   before the device reaches here.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure to release
+ *
+ * Returned Value:
+ *   None.
+ *
+ ****************************************************************************/
+
+static void phy_release_device(FAR struct phy_device_s *phydev)
+{
+  int i;
+
+  /* Remove the device from the table and tear down its lock under
+   * g_phy_lock, the same lock phy_alloc_device() uses to scan for a free
+   * slot.  Doing both here serializes slot reuse: no other core can observe
+   * the freed slot, reuse it and nxmutex_init() a fresh lock while we are
+   * still destroying this one.
+   */
+
+  nxmutex_lock(&g_phy_lock);
+  for (i = 0; i < CONFIG_NET_PHYLIB_MAX_PHYS; i++)
+    {
+      if (g_phy_devices[i] == phydev)
+        {
+          g_phy_devices[i] = NULL;
+          break;
+        }
+    }
+
+  nxmutex_destroy(&phydev->lock);
+  nxmutex_unlock(&g_phy_lock);
+
+  kmm_free(phydev);
+}
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: phy_driver_register
+ *
+ * Description:
+ *   Register a PHY driver in the global driver table. The driver will
+ *   be matched against PHY devices by PHY ID during device creation.
+ *
+ * Input Parameters:
+ *   drv - Pointer to the PHY driver structure to register
+ *
+ * Returned Value:
+ *   OK on success; -EINVAL if drv is NULL;
+ *   -ENOMEM if the driver table is full.
+ *
+ ****************************************************************************/
+
+int phy_driver_register(FAR const struct phy_driver_s *drv)
+{
+  int ret;
+  int i;
+
+  if (drv == NULL)
+    {
+      return -EINVAL;
+    }
+
+  ret = nxmutex_lock(&g_phy_lock);
+  if (ret < 0)
+    {
+      return ret;
+    }
+
+  /* Store the driver in the first free slot of the fixed-size table. */
+
+  for (i = 0; i < CONFIG_NET_PHYLIB_MAX_DRIVERS; i++)
+    {
+      if (g_phy_drivers[i] == NULL)
+        {
+          g_phy_drivers[i] = drv;
+          nxmutex_unlock(&g_phy_lock);
+
+          ninfo("PHY driver '%s' registered "
+                "(id=0x%08" PRIx32 " mask=0x%08" PRIx32 ")\n",
+                drv->name, drv->phy_id, drv->phy_id_mask);
+          return OK;
+        }
+    }
+
+  nxmutex_unlock(&g_phy_lock);
+  return -ENOMEM;
+}
+
+/****************************************************************************
+ * Name: phy_device_create
+ *
+ * Description:
+ *   Create a PHY device by reading its PHY ID from the MDIO bus and
+ *   assigning a matching driver. The device is dynamically allocated and
+ *   registered in the device table.
+ *
+ * Input Parameters:
+ *   bus  - Pointer to the MDIO bus structure
+ *   addr - PHY address on the bus (0-31)
+ *
+ * Returned Value:
+ *   Pointer to the created PHY device on success; NULL on failure.
+ *
+ ****************************************************************************/
+
+FAR struct phy_device_s *phy_device_create(FAR struct mdio_bus_s *bus,
+                                           uint8_t addr)
+{
+  FAR struct phy_device_s *phydev;
+  uint16_t id1;
+  uint16_t id2;
+  uint32_t phy_id;
+  bool c45 = false;
+  int ret;
+
+  if (bus == NULL)
+    {
+      return NULL;
+    }
+
+#ifdef CONFIG_MDIO_CLAUSE_45
+  /* Try native/indirect Clause 45 first: read the PHY ID from MMD1
+   * (PMA/PMD).  This handles MDIO controllers configured in C45-only mode
+   * where plain C22 reads would fail.  Fall back to C22 on error.
+   */
+
+  ret = mdio_c45_read(bus, addr, 1, MII_PHYID1, &id1);
+  if (ret >= 0)
+    {
+      ret = mdio_c45_read(bus, addr, 1, MII_PHYID2, &id2);
+    }
+
+  if (ret >= 0 && !((id1 == 0x0000 && id2 == 0x0000) ||
+                    (id1 == 0xffff && id2 == 0xffff)))
+    {
+      c45 = true;
+    }
+  else
+#endif
+    {
+      ret = mdio_read(bus, addr, MII_PHYID1, &id1);
+      if (ret < 0)
+        {
+          return NULL;
+        }
+
+      ret = mdio_read(bus, addr, MII_PHYID2, &id2);
+      if (ret < 0)
+        {
+          return NULL;
+        }
+    }
+
+  /* Reject invalid PHY IDs */
+
+  if ((id1 == 0x0000 && id2 == 0x0000) ||
+      (id1 == 0xffff && id2 == 0xffff))
+    {
+      return NULL;
+    }
+
+  phy_id = ((uint32_t)id1 << 16) | (uint32_t)id2;
+
+  phydev = phy_alloc_device(bus);
+  if (phydev == NULL)
+    {
+      nerr("ERROR: Failed to allocate PHY device\n");
+      return NULL;
+    }
+
+  phydev->c45       = c45;
+  phydev->phy_id    = phy_id;
+  phydev->mdio_addr = addr;
+  phydev->drv       = phy_find_driver(phy_id, phydev->c45);
+  phydev->state     = PHY_DOWN;
+  phydev->speed     = 0;
+  phydev->duplex    = DUPLEX_UNKNOWN;
+  phydev->link      = false;
+  phydev->autoneg   = true;
+  phydev->irq       = PHY_POLL;  /* Default to polling; MAC sets a real IRQ
+                                  * number to enable interrupt mode. */
+
+  nxmutex_init(&phydev->lock);
+
+  ninfo("PHY device created: id=0x%08" PRIx32 " addr=%d drv='%s' c45=%d\n",
+        phy_id, addr, phydev->drv->name, phydev->c45);
+
+  return phydev;
+}
+
+/****************************************************************************
+ * Name: phy_device_scan
+ *
+ * Description:
+ *   Probe all 32 addresses on an MDIO bus and create a PHY device for
+ *   every address that returns a valid PHY ID. Discovered devices are
+ *   stored into the caller-provided array. The caller takes ownership of
+ *   each returned phydev: connect the ones it uses with phy_connect() (and
+ *   release them with phy_disconnect() on teardown), and release any
+ *   discovered-but-unused phydev with phy_device_free().  A phydev that is
+ *   neither connected nor freed leaks both its device-table slot and the
+ *   memory backing it.
+ *
+ *   Use this only when PHY addresses are not known in advance. When the
+ *   address is known (the common NuttX case, from board defconfig or the
+ *   datasheet), call phy_device_create(bus, addr) directly instead.
+ *
+ * Input Parameters:
+ *   bus     - Pointer to the MDIO bus structure to scan
+ *   devs    - Caller-provided array to receive discovered phydev pointers
+ *   maxdevs - Capacity of the devs[] array
+ *
+ * Returned Value:
+ *   Number of PHY devices discovered (>= 0); negated errno on failure.
+ *
+ ****************************************************************************/
+
+ssize_t phy_device_scan(FAR struct mdio_bus_s *bus,
+                        FAR struct phy_device_s **devs, size_t maxdevs)
+{
+  size_t count = 0;
+  uint8_t addr;
+  FAR struct phy_device_s *phydev;
+
+  if (bus == NULL || devs == NULL || maxdevs == 0)
+    {
+      return -EINVAL;
+    }
+
+  for (addr = 0; addr < 32 && count < maxdevs; addr++)
+    {
+      phydev = phy_device_create(bus, addr);
+      if (phydev != NULL)
+        {
+          devs[count++] = phydev;
+        }
+    }
+
+  ninfo("MDIO bus scan: found %zu PHY(s)\n", count);
+  return count;
+}
+
+/****************************************************************************
+ * Name: phy_connect
+ *
+ * Description:
+ *   Connect a PHY device to a network device. Calls the PHY driver's
+ *   config_init callback and transitions the PHY to the READY state.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *   lower  - Pointer to the network device lower half
+ *
+ * Returned Value:
+ *   OK on success; -EINVAL if arguments are NULL;
+ *   -EBUSY if the PHY is already attached.
+ *
+ ****************************************************************************/
+
+int phy_connect(FAR struct phy_device_s *phydev,
+                FAR struct netdev_lowerhalf_s *lower)
+{
+  int ret;
+
+  if (phydev == NULL || lower == NULL)
+    {
+      return -EINVAL;
+    }
+
+  nxmutex_lock(&phydev->lock);
+
+  if (phydev->lower != NULL)
+    {
+      nxmutex_unlock(&phydev->lock);
+      return -EBUSY;
+    }
+
+  phydev->lower = lower;
+  lower->phydev = phydev;
+
+  /* Deassert the PHY hardware reset (release the RESET_N line) before
+   * running config_init.  This is idempotent: if the MAC driver
+   * already released the reset before reading the PHY ID, the underlying
+   * mdio_reset() recognizes the state is unchanged and returns without
+   * re-toggling.  A PHY with no controllable reset line is a quiet no-op.
+   */
+
+  phy_reset(phydev, 0);
+
+  /* Call config_init */
+
+  if (phydev->drv->config_init)
+    {
+      ret = phydev->drv->config_init(phydev);
+      if (ret < 0)
+        {
+          phydev->lower = NULL;
+          lower->phydev = NULL;
+          nxmutex_unlock(&phydev->lock);
+          return ret;
+        }
+    }
+
+  phydev->state = PHY_READY;
+  ninfo("PHY connected: addr=%d -> %s\n",
+        phydev->mdio_addr, lower->netdev.d_ifname);
+  nxmutex_unlock(&phydev->lock);
+  return OK;
+}
+
+/****************************************************************************
+ * Name: phy_disconnect
+ *
+ * Description:
+ *   Disconnect a PHY device from its attached network device. Stops the
+ *   state machine if running and transitions the PHY to the DOWN state.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+int phy_disconnect(FAR struct phy_device_s *phydev)
+{
+  uint8_t addr;
+
+  if (phydev == NULL)
+    {
+      return -EINVAL;
+    }
+
+  /* Always stop the state machine before tearing the device down.
+   *
+   * phy_stop() is idempotent and safe to call from any state: it disables
+   * PHY interrupts, detaches the phylib-owned ISR (phy_free_interrupt() is
+   * a no-op when nothing is attached) and cancels any pending work.  This
+   * must run unconditionally: a PHY that reached PHY_ERROR (or was never
+   * started) still has its ISR attached in interrupt mode, and skipping
+   * phy_stop() would leave that ISR pointing at a phydev we are about to
+   * free.  phy_stop() takes phydev->lock and runs work_cancel_sync()
+   * itself, so it must not be called while holding phydev->lock.
+   */
+
+  phy_stop(phydev);
+
+  nxmutex_lock(&phydev->lock);
+
+  phydev->state = PHY_DOWN;
+
+  if (phydev->lower != NULL)
+    {
+      phydev->lower->phydev = NULL;
+      phydev->lower = NULL;
+    }
+
+  /* Assert the PHY hardware reset (drive RESET_N active) as the device is
+   * torn down.  No-op when the lower half provides no reset op.
+   */
+
+  phy_reset(phydev, 1);
+
+  /* Snapshot the address for the trace below: once the device is freed its
+   * memory may be reused (and mdio_addr overwritten) by a concurrent
+   * phy_device_create() on another core.
+   */
+
+  addr = phydev->mdio_addr;
+
+  nxmutex_unlock(&phydev->lock);
+
+  /* Free the device and release its table slot. */
+
+  phy_release_device(phydev);
+
+  ninfo("PHY disconnected: addr=%d\n", addr);
+  return OK;
+}
+
+/****************************************************************************
+ * Name: phy_device_free
+ *
+ * Description:
+ *   Release a PHY device that was obtained from phy_device_create() or
+ *   phy_device_scan() but never connected to a network device.  This is
+ *   the symmetric counterpart to phy_device_create(): the caller must use
+ *   it to free any discovered phydev it does not go on to phy_connect(),
+ *   otherwise the device and its table slot leak.
+ *
+ *   A connected PHY (lower != NULL) must be released with
+ *   phy_disconnect() instead, which stops the state machine first.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure to free
+ *
+ * Returned Value:
+ *   OK on success; -EINVAL if phydev is NULL;
+ *   -EBUSY if the PHY is still connected (use phy_disconnect() instead).
+ *
+ ****************************************************************************/
+
+int phy_device_free(FAR struct phy_device_s *phydev)
+{
+  uint8_t addr;
+
+  if (phydev == NULL)
+    {
+      return -EINVAL;
+    }
+
+  nxmutex_lock(&phydev->lock);
+
+  /* A connected device must go through phy_disconnect(): it owns a running
+   * state machine and a carrier notification that this path does not
+   * handle.
+   */
+
+  if (phydev->lower != NULL)
+    {
+      nxmutex_unlock(&phydev->lock);
+      return -EBUSY;
+    }
+
+  addr = phydev->mdio_addr;
+
+  nxmutex_unlock(&phydev->lock);
+
+  /* Free the device and release its table slot. */
+
+  phy_release_device(phydev);
+
+  ninfo("PHY device freed: addr=%d\n", addr);
+  return OK;
+}
diff --git a/drivers/net/phy/phy_gen.c b/drivers/net/phy/phy_gen.c
new file mode 100644
index 00000000000..9d3ac2f477a
--- /dev/null
+++ b/drivers/net/phy/phy_gen.c
@@ -0,0 +1,373 @@
+/****************************************************************************
+ * drivers/net/phy/phy_gen.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <debug.h>
+
+#include <nuttx/net/phy.h>
+#include <nuttx/net/mii.h>
+#include <nuttx/ethtool.h>
+
+#include "phy.h"
+
+/****************************************************************************
+ * Private Function Prototypes
+ ****************************************************************************/
+
+static int genphy_config_init(FAR struct phy_device_s *phydev);
+static int genphy_config_aneg(FAR struct phy_device_s *phydev);
+static int genphy_read_status(FAR struct phy_device_s *phydev);
+static int genphy_config_power(FAR struct phy_device_s *phydev, bool enable);
+
+/****************************************************************************
+ * Public Data
+ ****************************************************************************/
+
+const struct phy_driver_s g_genphy_driver =
+{
+  .name         = "Generic PHY",
+  .config_init  = genphy_config_init,
+  .config_aneg  = genphy_config_aneg,
+  .read_status  = genphy_read_status,
+  .config_power = genphy_config_power,
+};
+
+/****************************************************************************
+ * Private Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: genphy_config_init
+ *
+ * Description:
+ *   Read MSR and ESTATUS to determine supported link modes.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int genphy_config_init(FAR struct phy_device_s *phydev)
+{
+  int msr;
+  int estatus;
+  uint32_t supported = 0;
+
+  msr = phy_read(phydev, MII_MSR);
+  if (msr < 0)
+    {
+      return msr;
+    }
+
+  if (msr & MII_MSR_10BASETXHALF)
+    {
+      supported |= SUPPORTED_10BASET_HALF;
+    }
+
+  if (msr & MII_MSR_10BASETXFULL)
+    {
+      supported |= SUPPORTED_10BASET_FULL;
+    }
+
+  if (msr & MII_MSR_100BASETXHALF)
+    {
+      supported |= SUPPORTED_100BASET_HALF;
+    }
+
+  if (msr & MII_MSR_100BASETXFULL)
+    {
+      supported |= SUPPORTED_100BASET_FULL;
+    }
+
+  if (msr & MII_MSR_ANEGABLE)
+    {
+      supported |= SUPPORTED_AUTONEG;
+    }
+
+  /* Check for extended status register for 1000BASE-T */
+
+  if (msr & MII_MSR_ESTATEN)
+    {
+      estatus = phy_read(phydev, MII_ESTATUS);
+      if (estatus >= 0)
+        {
+          if (estatus & MII_ESTATUS_1000BASETHALF)
+            {
+              supported |= SUPPORTED_1000BASET_HALF;
+            }
+
+          if (estatus & MII_ESTATUS_1000BASETFULL)
+            {
+              supported |= SUPPORTED_1000BASET_FULL;
+            }
+        }
+    }
+
+  supported |= SUPPORTED_TP | SUPPORTED_MII;
+
+  phydev->supported = supported;
+  phydev->advertising = supported;
+
+  return OK;
+}
+
+/****************************************************************************
+ * Name: genphy_config_aneg
+ *
+ * Description:
+ *   Configure and restart auto-negotiation.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int genphy_config_aneg(FAR struct phy_device_s *phydev)
+{
+  uint16_t adv = MII_ADVERTISE_CSMA;
+  uint16_t msctrl = 0;
+  int ret;
+
+  /* Build ADVERTISE register value from advertising bitmask */
+
+  if (phydev->advertising & SUPPORTED_10BASET_HALF)
+    {
+      adv |= MII_ADVERTISE_10BASETXHALF;
+    }
+
+  if (phydev->advertising & SUPPORTED_10BASET_FULL)
+    {
+      adv |= MII_ADVERTISE_10BASETXFULL;
+    }
+
+  if (phydev->advertising & SUPPORTED_100BASET_HALF)
+    {
+      adv |= MII_ADVERTISE_100BASETXHALF;
+    }
+
+  if (phydev->advertising & SUPPORTED_100BASET_FULL)
+    {
+      adv |= MII_ADVERTISE_100BASETXFULL;
+    }
+
+  ret = phy_write(phydev, MII_ADVERTISE, adv);
+  if (ret < 0)
+    {
+      return ret;
+    }
+
+  /* Write 1000BASE-T advertisement if supported */
+
+  if (phydev->supported & (SUPPORTED_1000BASET_HALF |
+                           SUPPORTED_1000BASET_FULL))
+    {
+      if (phydev->advertising & SUPPORTED_1000BASET_HALF)
+        {
+          msctrl |= MII_MSCONTROL_1000BASETHALF;
+        }
+
+      if (phydev->advertising & SUPPORTED_1000BASET_FULL)
+        {
+          msctrl |= MII_MSCONTROL_1000BASETFULL;
+        }
+
+      ret = phy_write(phydev, MII_MSCONTROL, msctrl);
+      if (ret < 0)
+        {
+          return ret;
+        }
+    }
+
+  /* Restart auto-negotiation: set ANENABLE and ANRESTART in MCR */
+
+  return phy_modify(phydev, MII_MCR,
+                    MII_MCR_ANENABLE | MII_MCR_ANRESTART,
+                    MII_MCR_ANENABLE | MII_MCR_ANRESTART);
+}
+
+/****************************************************************************
+ * Name: genphy_read_status
+ *
+ * Description:
+ *   Read PHY link status, speed, and duplex from MII registers.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int genphy_read_status(FAR struct phy_device_s *phydev)
+{
+  int msr;
+  int lpa;
+  int msstatus;
+  uint32_t common;
+
+  /* Read MSR twice - link status is latched low */
+
+  msr = phy_read(phydev, MII_MSR);
+  if (msr < 0)
+    {
+      return msr;
+    }
+
+  msr = phy_read(phydev, MII_MSR);
+  if (msr < 0)
+    {
+      return msr;
+    }
+
+  phydev->link = !!(msr & MII_MSR_LINKSTATUS);
+
+  if (!phydev->link)
+    {
+      phydev->speed = 0;
+      phydev->duplex = DUPLEX_UNKNOWN;
+      return OK;
+    }
+
+  /* Read link partner ability */
+
+  lpa = phy_read(phydev, MII_LPA);
+  if (lpa < 0)
+    {
+      return lpa;
+    }
+
+  phydev->lp_advertising = 0;
+  if (lpa & MII_LPA_10BASETXHALF)
+    {
+      phydev->lp_advertising |= SUPPORTED_10BASET_HALF;
+    }
+
+  if (lpa & MII_LPA_10BASETXFULL)
+    {
+      phydev->lp_advertising |= SUPPORTED_10BASET_FULL;
+    }
+
+  if (lpa & MII_LPA_100BASETXHALF)
+    {
+      phydev->lp_advertising |= SUPPORTED_100BASET_HALF;
+    }
+
+  if (lpa & MII_LPA_100BASETXFULL)
+    {
+      phydev->lp_advertising |= SUPPORTED_100BASET_FULL;
+    }
+
+  /* Check 1000BASE-T if supported */
+
+  if (phydev->supported & (SUPPORTED_1000BASET_HALF |
+                           SUPPORTED_1000BASET_FULL))
+    {
+      msstatus = phy_read(phydev, MII_MSSTATUS);
+      if (msstatus >= 0)
+        {
+          if (msstatus & MII_MSSTATUS_LP1000BASETHALF)
+            {
+              phydev->lp_advertising |= SUPPORTED_1000BASET_HALF;
+            }
+
+          if (msstatus & MII_MSSTATUS_LP1000BASETFULL)
+            {
+              phydev->lp_advertising |= SUPPORTED_1000BASET_FULL;
+            }
+        }
+    }
+
+  /* Resolve speed and duplex from common capabilities */
+
+  common = phydev->advertising & phydev->lp_advertising;
+
+  if (common & SUPPORTED_1000BASET_FULL)
+    {
+      phydev->speed = 1000;
+      phydev->duplex = DUPLEX_FULL;
+    }
+  else if (common & SUPPORTED_1000BASET_HALF)
+    {
+      phydev->speed = 1000;
+      phydev->duplex = DUPLEX_HALF;
+    }
+  else if (common & SUPPORTED_100BASET_FULL)
+    {
+      phydev->speed = 100;
+      phydev->duplex = DUPLEX_FULL;
+    }
+  else if (common & SUPPORTED_100BASET_HALF)
+    {
+      phydev->speed = 100;
+      phydev->duplex = DUPLEX_HALF;
+    }
+  else if (common & SUPPORTED_10BASET_FULL)
+    {
+      phydev->speed = 10;
+      phydev->duplex = DUPLEX_FULL;
+    }
+  else if (common & SUPPORTED_10BASET_HALF)
+    {
+      phydev->speed = 10;
+      phydev->duplex = DUPLEX_HALF;
+    }
+  else
+    {
+      phydev->speed = 0;
+      phydev->duplex = DUPLEX_UNKNOWN;
+    }
+
+  return OK;
+}
+
+/****************************************************************************
+ * Name: genphy_config_power
+ *
+ * Description:
+ *   Power the PHY up or down via the power-down bit in MCR.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *   enable - true to power up (clear PDOWN); false to power down (set PDOWN)
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int genphy_config_power(FAR struct phy_device_s *phydev, bool enable)
+{
+  return enable ? phy_clear_bits(phydev, MII_MCR, MII_MCR_PDOWN)
+                : phy_set_bits(phydev, MII_MCR, MII_MCR_PDOWN);
+}
diff --git a/drivers/net/phy/phy_genc45.c b/drivers/net/phy/phy_genc45.c
new file mode 100644
index 00000000000..f0e3ff8f1a1
--- /dev/null
+++ b/drivers/net/phy/phy_genc45.c
@@ -0,0 +1,272 @@
+/****************************************************************************
+ * drivers/net/phy/phy_genc45.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <debug.h>
+#include <syslog.h>
+
+#include <nuttx/net/phy.h>
+#include <nuttx/net/mii.h>
+#include <nuttx/ethtool.h>
+
+#include "phy.h"
+
+/****************************************************************************
+ * Private Function Prototypes
+ ****************************************************************************/
+
+static int genphy_c45_read_link(FAR struct phy_device_s *phydev);
+static int genphy_c45_read_status(FAR struct phy_device_s *phydev);
+static int genphy_c45_config_aneg(FAR struct phy_device_s *phydev);
+static int genphy_c45_pma_read_abilities(FAR struct phy_device_s *phydev);
+
+/****************************************************************************
+ * Public Data
+ ****************************************************************************/
+
+const struct phy_driver_s g_genphy_c45_driver =
+{
+  .name        = "Generic C45 PHY",
+  .config_init = genphy_c45_pma_read_abilities,
+  .config_aneg = genphy_c45_config_aneg,
+  .read_status = genphy_c45_read_status,
+};
+
+/****************************************************************************
+ * Private Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: genphy_c45_read_link
+ *
+ * Description:
+ *   Read link status from PCS (MMD3) status register. The link status
+ *   bit is latched-low, so we read twice to get current state.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int genphy_c45_read_link(FAR struct phy_device_s *phydev)
+{
+  int val;
+
+  /* Read PCS status - latched low, read twice */
+
+  val = phy_read_mmd(phydev, MII_MMD_PCS, MII_MMD_STAT1);
+  if (val < 0)
+    {
+      return val;
+    }
+
+  val = phy_read_mmd(phydev, MII_MMD_PCS, MII_MMD_STAT1);
+  if (val < 0)
+    {
+      return val;
+    }
+
+  phydev->link = !!(val & MII_MMD_STAT1_LSTATUS);
+  return OK;
+}
+
+/****************************************************************************
+ * Name: genphy_c45_read_status
+ *
+ * Description:
+ *   Read PHY link status, speed, and duplex from C45 MMD registers.
+ *   Reads PCS for link, PMA for speed, AN for negotiation result.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int genphy_c45_read_status(FAR struct phy_device_s *phydev)
+{
+  int ret;
+  int val;
+  int ctrl2;
+
+  /* Read link status from PCS */
+
+  ret = genphy_c45_read_link(phydev);
+  if (ret < 0)
+    {
+      return ret;
+    }
+
+  if (!phydev->link)
+    {
+      phydev->speed = 0;
+      phydev->duplex = DUPLEX_UNKNOWN;
+      return OK;
+    }
+
+  /* Read speed from PMA/PMD CTRL1 */
+
+  val = phy_read_mmd(phydev, MII_MMD_PMAPMD, MII_MMD_CTRL1);
+  if (val < 0)
+    {
+      return val;
+    }
+
+  /* Decode speed from CTRL1 speed selection bits 6 and 13 (mask 0x2040),
+   * per IEEE 802.3 Clause 45 PMA/PMD control register 1.
+   *   {13,6} = 00 -> 10M, 10 -> 100M, 01 -> 1000M, 11 -> 10G or higher
+   */
+
+  switch (val & 0x2040)
+    {
+      case 0x0000:                 /* bits {13,6} = 00 */
+        phydev->speed = 10;
+        break;
+
+      case 0x2000:                 /* bits {13,6} = 10 (bit13 set) */
+        phydev->speed = 100;
+        break;
+
+      case 0x0040:                 /* bits {13,6} = 01 (bit6 set) */
+        phydev->speed = 1000;
+        break;
+
+      case 0x2040:                 /* bits {13,6} = 11 -> consult CTRL2 */
+        ctrl2 = phy_read_mmd(phydev, MII_MMD_PMAPMD, MII_MMD_CTRL2);
+        if (ctrl2 < 0)
+          {
+            return ctrl2;
+          }
+
+        if ((ctrl2 & MII_MMD_PMA_CTRL2_TYPE) == MII_MMD_PMA_CTRL2_10GBT)
+          {
+            phydev->speed = 10000;
+          }
+        else
+          {
+            phydev->speed = 0;
+          }
+
+        break;
+
+      default:
+        phydev->speed = 0;
+        break;
+    }
+
+  /* C45 PHYs are typically full duplex */
+
+  phydev->duplex = DUPLEX_FULL;
+
+  return OK;
+}
+
+/****************************************************************************
+ * Name: genphy_c45_config_aneg
+ *
+ * Description:
+ *   Enable and restart auto-negotiation via AN MMD (MMD7).
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int genphy_c45_config_aneg(FAR struct phy_device_s *phydev)
+{
+  /* Enable and restart AN */
+
+  return phy_write_mmd(phydev, MII_MMD_AN, MII_MMD_AN_CTRL1,
+                       MII_MMD_AN_CTRL1_ENABLE | MII_MMD_AN_CTRL1_RESTART);
+}
+
+/****************************************************************************
+ * Name: genphy_c45_pma_read_abilities
+ *
+ * Description:
+ *   Read PMA extended abilities to determine supported speeds.
+ *   Used as config_init for the generic C45 driver.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *
+ * Returned Value:
+ *   OK on success; negated errno on failure.
+ *
+ ****************************************************************************/
+
+static int genphy_c45_pma_read_abilities(FAR struct phy_device_s *phydev)
+{
+  int val;
+  uint32_t supported = 0;
+
+  /* Read PMA/PMD extended abilities (reg 11) */
+
+  val = phy_read_mmd(phydev, MII_MMD_PMAPMD, MII_MMD_PMA_EXTABLE);
+  if (val < 0)
+    {
+      /* If not available, assume the same basic 10/100/1000 capabilities
+       * as the normal path below so the advertised set is consistent.
+       */
+
+      supported = SUPPORTED_10BASET_FULL |
+                  SUPPORTED_100BASET_FULL |
+                  SUPPORTED_1000BASET_FULL |
+                  SUPPORTED_AUTONEG |
+                  SUPPORTED_TP | SUPPORTED_MII;
+      phydev->supported = supported;
+      phydev->advertising = supported;
+      return OK;
+    }
+
+  /* Always assume 10/100/1000 capable for C45 PHYs */
+
+  supported = SUPPORTED_10BASET_FULL |
+              SUPPORTED_100BASET_FULL |
+              SUPPORTED_1000BASET_FULL |
+              SUPPORTED_AUTONEG;
+
+  if (val & MII_MMD_PMA_EXTABLE_10GBT)
+    {
+      supported |= SUPPORTED_10000BASET_FULL;
+    }
+
+  supported |= SUPPORTED_TP | SUPPORTED_MII;
+
+  phydev->supported = supported;
+  phydev->advertising = supported;
+
+  return OK;
+}
diff --git a/include/nuttx/ethtool.h b/include/nuttx/ethtool.h
index 87cd3f0e1d5..79da67762cb 100644
--- a/include/nuttx/ethtool.h
+++ b/include/nuttx/ethtool.h
@@ -134,6 +134,56 @@
 #define DUPLEX_FULL           0x01
 #define DUPLEX_UNKNOWN        0xff
 
+/* Which connector port, for the port field of struct ethtool_link_settings.
+ * Values match the userspace ethtool PORT_* ABI.
+ */
+
+#define PORT_TP               0x00
+#define PORT_AUI              0x01
+#define PORT_MII              0x02
+#define PORT_FIBRE            0x03
+#define PORT_BNC              0x04
+#define PORT_DA               0x05
+#define PORT_NONE             0xef
+#define PORT_OTHER            0xff
+
+/* Enable or disable autonegotiation, for the autoneg field of
+ * struct ethtool_link_settings.  Values match the userspace ethtool ABI.
+ */
+
+#define AUTONEG_DISABLE       0x00
+#define AUTONEG_ENABLE        0x01
+
+/* MDIO protocols supported by the interface, for the mdio_support field of
+ * struct ethtool_link_settings.  Values match the userspace ethtool ABI.
+ */
+
+#define ETH_MDIO_SUPPORTS_C22 1
+#define ETH_MDIO_SUPPORTS_C45 2
+
+/* Link mode bitmasks stored in
+ * struct ethtool_link_settings::link_mode_masks.  These are PHYLIB-internal
+ * capability flags shared between the kernel and applications built into the
+ * same image; the bit positions are assigned locally (packed, no gaps) and
+ * are NOT guaranteed to match the userspace ethtool ABI bit ordering.
+ */
+
+#define SUPPORTED_10BASET_HALF    (1 << 0)
+#define SUPPORTED_10BASET_FULL    (1 << 1)
+#define SUPPORTED_100BASET_HALF   (1 << 2)
+#define SUPPORTED_100BASET_FULL   (1 << 3)
+#define SUPPORTED_1000BASET_HALF  (1 << 4)
+#define SUPPORTED_1000BASET_FULL  (1 << 5)
+#define SUPPORTED_AUTONEG         (1 << 6)
+#define SUPPORTED_TP              (1 << 7)
+#define SUPPORTED_AUI             (1 << 8)
+#define SUPPORTED_MII             (1 << 9)
+#define SUPPORTED_FIBRE           (1 << 10)
+#define SUPPORTED_BNC             (1 << 11)
+#define SUPPORTED_10000BASET_FULL (1 << 12)
+#define SUPPORTED_100BASET1_FULL  (1 << 13)
+#define SUPPORTED_1000BASET1_FULL (1 << 14)
+
 /****************************************************************************
  * Public Type Definitions
  ****************************************************************************/
@@ -252,4 +302,54 @@ struct ethtool_ts_info
   uint32_t rx_reserved[3];
 };
 
-#endif
+/* struct ethtool_link_settings - link settings for ethtool
+ * cmd: ETHTOOL_GLINKSETTINGS or ETHTOOL_SLINKSETTINGS
+ * speed: Link speed in Mbps
+ * duplex: Duplex mode (DUPLEX_HALF, DUPLEX_FULL, DUPLEX_UNKNOWN)
+ * port: Physical connector type (PORT_* in this header)
+ * phy_address: MDIO address of PHY
+ * autoneg: Auto-negotiation enable/disable (AUTONEG_* in this header)
+ * mdio_support: MDIO protocols supported by the interface
+ *               (ETH_MDIO_SUPPORTS_* in this header); read-only
+ * link_mode_masks_nwords: Number of 32-bit words in each link mode mask
+ * link_mode_masks: Supported, advertising and link partner advertising
+ *                  masks, in that order
+ */
+
+struct ethtool_link_settings
+{
+  uint32_t cmd;
+  uint32_t speed;
+  uint8_t  duplex;
+  uint8_t  port;
+  uint8_t  phy_address;
+  uint8_t  autoneg;
+  uint8_t  mdio_support;
+  uint8_t  eth_tp_mdix;
+  uint8_t  eth_tp_mdix_ctrl;
+  int8_t   link_mode_masks_nwords;
+  uint8_t  transceiver;
+  uint8_t  master_slave_cfg;
+  uint8_t  master_slave_state;
+  uint8_t  rate_matching;
+  uint32_t reserved[7];
+
+  /* supported / advertising / lp_advertising, one 32-bit word each
+   * (link_mode_masks_nwords == 1).
+   */
+
+  uint32_t link_mode_masks[3];
+};
+
+/* struct ethtool_value - simple value container for ethtool
+ * cmd: Command number
+ * data: Value
+ */
+
+struct ethtool_value
+{
+  uint32_t cmd;
+  uint32_t data;
+};
+
+#endif /* __INCLUDE_NUTTX_ETHTOOL_H */
diff --git a/include/nuttx/net/mii.h b/include/nuttx/net/mii.h
index 327105f7cd9..1cdd50bc23d 100644
--- a/include/nuttx/net/mii.h
+++ b/include/nuttx/net/mii.h
@@ -345,6 +345,16 @@
 #define MII_LPA_LPACK                (1 << 14) /* Bit 14: Link partner 
acknowledgement */
 #define MII_LPA_NXTPAGE              (1 << 15) /* Bit 15: Next page requested 
*/
 
+/* Master/slave control register bit definitions (1000BASE-T) */
+
+#define MII_MSCONTROL_1000BASETHALF  (1 << 8)  /* Bit 8:  Advertise 1000BASE-T 
half duplex */
+#define MII_MSCONTROL_1000BASETFULL  (1 << 9)  /* Bit 9:  Advertise 1000BASE-T 
full duplex */
+
+/* Master/slave status register bit definitions (1000BASE-T) */
+
+#define MII_MSSTATUS_LP1000BASETHALF (1 << 10) /* Bit 10: LP 1000BASE-T half 
duplex able */
+#define MII_MSSTATUS_LP1000BASETFULL (1 << 11) /* Bit 11: LP 1000BASE-T full 
duplex able */
+
 /* Link partner ability in next page format */
 
 #define MII_LPANP_MESSAGE            0x07ff    /* Bits 0-10: Link partner's 
message code */
@@ -391,6 +401,67 @@
 #define MII_ESTATUS_1000BASEXHALF    (1 << 14) /* Bit 14: 1000BASE-X Half 
Duplex able */
 #define MII_ESTATUS_1000BASEXFULL    (1 << 15) /* Bit 15: 1000BASE-X Full 
Duplex able */
 
+/* IEEE 802.3 Clause 45 MDIO Manageable Device (MMD) definitions ************/
+
+/* MMD device addresses (IEEE 802.3 Clause 45, 45.2) */
+
+#define MII_MMD_PMAPMD               1         /* PMA/PMD */
+#define MII_MMD_PCS                  3         /* PCS */
+#define MII_MMD_AN                   7         /* Auto-Negotiation */
+#define MII_MMD_VEND1                30        /* Vendor-specific 1 */
+#define MII_MMD_VEND2                31        /* Vendor-specific 2 */
+
+/* MMD register addresses (common across MMDs, IEEE 802.3 45.2.1) */
+
+#define MII_MMD_CTRL1                0         /* Control register 1 */
+#define MII_MMD_STAT1                1         /* Status register 1 */
+#define MII_MMD_DEVID1               2         /* Device identifier 1 (upper) 
*/
+#define MII_MMD_DEVID2               3         /* Device identifier 2 (lower) 
*/
+#define MII_MMD_SPEED                4         /* Speed ability */
+#define MII_MMD_DEVS1                5         /* Devices in package 1 */
+#define MII_MMD_DEVS2                6         /* Devices in package 2 */
+#define MII_MMD_CTRL2                7         /* Control register 2 */
+#define MII_MMD_STAT2                8         /* Status register 2 */
+#define MII_MMD_PMA_EXTABLE          11        /* PMA/PMD extended abilities */
+
+/* AN MMD registers (IEEE 802.3 45.2.7) */
+
+#define MII_MMD_AN_CTRL1             0         /* AN Control */
+#define MII_MMD_AN_STAT1             1         /* AN Status */
+#define MII_MMD_AN_ADV1              16        /* AN Advertisement 1 */
+#define MII_MMD_AN_ADV2              17        /* AN Advertisement 2 */
+#define MII_MMD_AN_ADV3              18        /* AN Advertisement 3 */
+#define MII_MMD_AN_LPA1              19        /* AN LP Ability 1 */
+#define MII_MMD_AN_LPA2              20        /* AN LP Ability 2 */
+#define MII_MMD_AN_LPA3              21        /* AN LP Ability 3 */
+
+/* MMD STAT1 register bits */
+
+#define MII_MMD_STAT1_LSTATUS        (1 << 2)  /* Bit 2:  Link status (latched 
low) */
+
+/* MMD CTRL1 register bits */
+
+#define MII_MMD_CTRL1_RESET          (1 << 15) /* Bit 15: Reset */
+
+/* AN CTRL1 register bits */
+
+#define MII_MMD_AN_CTRL1_ENABLE      (1 << 12) /* Bit 12: AN enable */
+#define MII_MMD_AN_CTRL1_RESTART     (1 << 9)  /* Bit 9:  AN restart */
+
+/* AN STAT1 register bits */
+
+#define MII_MMD_AN_STAT1_COMPLETE    (1 << 5)  /* Bit 5:  AN complete */
+#define MII_MMD_AN_STAT1_LPABLE      (1 << 0)  /* Bit 0:  LP AN able */
+
+/* PMA CTRL2 PMA/PMD type field (IEEE 802.3 45.2.1.11) */
+
+#define MII_MMD_PMA_CTRL2_TYPE       0x000f    /* Bits 0-3: PMA/PMD type */
+#define MII_MMD_PMA_CTRL2_10GBT      0x0009    /*         10GBASE-T */
+
+/* PMA extended ability bits (within PMA EXTABLE, reg 11) */
+
+#define MII_MMD_PMA_EXTABLE_10GBT    (1 << 2)  /* Bit 2:  10GBASE-T able */
+
 /* MII PHYADDR register bit definitions */
 
 #define DP83840_PHYADDR_DUPLEX       (1 << 7)
diff --git a/include/nuttx/net/netdev_lowerhalf.h 
b/include/nuttx/net/netdev_lowerhalf.h
index 04c4ed9d04e..54ab96a6b14 100644
--- a/include/nuttx/net/netdev_lowerhalf.h
+++ b/include/nuttx/net/netdev_lowerhalf.h
@@ -109,6 +109,8 @@ enum netdev_rx_e
 
 struct netdev_ops_s;
 struct wireless_ops_s;
+struct phy_device_s;
+
 struct netdev_lowerhalf_s
 {
   FAR const struct netdev_ops_s *ops;
@@ -134,6 +136,10 @@ struct netdev_lowerhalf_s
    *   d_ifup, d_ifdown, d_txavail, d_addmac, d_rmmac, d_ioctl, d_private
    */
 
+#ifdef CONFIG_NET_PHYLIB
+  FAR struct phy_device_s *phydev;
+#endif
+
   struct net_driver_s netdev;
 };
 
diff --git a/include/nuttx/net/phy.h b/include/nuttx/net/phy.h
index 5131ee400f1..0a7d67acfaf 100644
--- a/include/nuttx/net/phy.h
+++ b/include/nuttx/net/phy.h
@@ -32,8 +32,15 @@
 #include <signal.h>
 #include <sys/types.h>
 
+#include <nuttx/mutex.h>
+
+#ifdef CONFIG_NET_PHYLIB
+#  include <nuttx/net/mdio.h>
+#  include <nuttx/wqueue.h>
+#endif
+
 /****************************************************************************
- * Public Type Definitions
+ * Pre-processor Definitions
  ****************************************************************************/
 
 /* Configuration ************************************************************/
@@ -44,6 +51,154 @@
 #  define CONFIG_PHY_NOTIFICATION_NCLIENTS 1
 #endif
 
+#ifdef CONFIG_NET_PHYLIB
+
+/* Sentinel values for phy_device_s.irq:
+ *
+ *   PHY_POLL          - No interrupt source available/desired.  Link state
+ *                       is discovered purely by periodic MDIO polling.
+ *   PHY_MAC_INTERRUPT - The PHY has no independent interrupt line; the
+ *                       attached MAC driver detects the PHY event in its
+ *                       own ISR and calls phy_interrupt().  The phylib
+ *                       core does NOT attach an ISR in this case.
+ *   >= 0              - A real interrupt number (e.g. an INTB pin routed to
+ *                       a GPIO/IRQ).  The phylib core attaches its own ISR
+ *                       to this line internally from phy_start().
+ *
+ * In interrupt mode the state machine runs only when a PHY interrupt kicks
+ * it; no periodic poll is used.
+ */
+
+#define PHY_POLL                      (-1)
+#define PHY_MAC_INTERRUPT             (-2)
+
+#endif /* CONFIG_NET_PHYLIB */
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+#ifdef CONFIG_NET_PHYLIB
+
+/* PHY states */
+
+enum phy_state_e
+{
+  PHY_DOWN = 0,
+  PHY_READY,
+  PHY_UP,
+  PHY_RUNNING,
+  PHY_NOLINK,
+  PHY_HALTED,
+  PHY_ERROR
+};
+
+/* PHY interface modes */
+
+enum phy_interface_e
+{
+  PHY_INTERFACE_MII = 0,
+  PHY_INTERFACE_GMII,
+  PHY_INTERFACE_RMII,
+  PHY_INTERFACE_RGMII,
+  PHY_INTERFACE_RGMII_ID,
+  PHY_INTERFACE_RGMII_TXID,
+  PHY_INTERFACE_RGMII_RXID,
+  PHY_INTERFACE_SGMII,
+  PHY_INTERFACE_MAX
+};
+
+/* PHY device.
+ *
+ * struct phy_driver_s (the vendor driver callback table) is an internal
+ * interface used only by PHY drivers under drivers/net/phy; its full
+ * definition lives in drivers/net/phy/phy.h.  Only a forward declaration is
+ * needed here for the phydev->drv back-pointer.
+ */
+
+struct phy_driver_s;
+struct netdev_lowerhalf_s;
+
+struct phy_device_s
+{
+  uint32_t phy_id;
+  uint8_t  mdio_addr;
+  FAR struct mdio_bus_s *bus;
+  FAR const struct phy_driver_s *drv;
+  FAR struct netdev_lowerhalf_s *lower;
+
+  /* Link state */
+
+  bool     c45;
+  bool     link;
+  uint8_t  duplex;
+  uint32_t speed;
+  enum phy_interface_e interface;
+
+  /* Capabilities */
+
+  uint32_t supported;
+  uint32_t advertising;
+  uint32_t lp_advertising;
+  bool     autoneg;
+
+  /* State machine */
+
+  enum phy_state_e state;
+  struct work_s state_work;
+
+  /* Per-device lock.
+   *
+   * Serializes access to the PHY state fields (state/link/speed/duplex/
+   * autoneg/advertising) between the state-machine work, ethtool/ioctl
+   * callers and the start/stop/connect/disconnect lifecycle operations.
+   * Serializes state transitions against ethtool/ioctl access.
+   */
+
+  mutex_t  lock;
+
+  /* Interrupt mode.
+   *
+   * irq - PHY interrupt source, and the single source of truth for the
+   *       runtime interrupt mode:
+   *         PHY_POLL (-1)          - Polling mode: no interrupt source.
+   *         PHY_MAC_INTERRUPT (-2) - The MAC driver owns the line and calls
+   *                                  phy_interrupt; phylib attaches no ISR.
+   *         >= 0                   - A real PHY interrupt line: the MAC
+   *                                  driver supplies the SoC-specific INTB
+   *                                  vector here before phy_start; phylib
+   *                                  attaches its own ISR (phy_isr) via
+   *                                  irq_attach().
+   *
+   *       The three cases are distinguished with phy_interrupt_is_valid()
+   *       (irq >= 0, a real PHY line) and a plain PHY_POLL comparison
+   *       (polling vs interrupt-driven), so no separate runtime-state field
+   *       is needed.
+   *
+   * In interrupt mode the PHY ISR kicks state_work directly (delay 0); the
+   * same work handle is reused for the polling and the interrupt-triggered
+   * path, so no separate IRQ work is needed.
+   */
+
+  int      irq;
+
+  /* Driver-private data.
+   *
+   * An opaque, driver-owned pointer set by the vendor PHY driver when it
+   * needs per-device state that must survive across state-machine
+   * callbacks.  Left NULL by drivers that are stateless.
+   *
+   * The phylib core treats this pointer as opaque: it neither dereferences
+   * nor frees it.  A driver that stores heap-allocated state here is
+   * responsible for releasing it in its own teardown path; a driver may
+   * also use it as a simple per-device flag without allocating.
+   */
+
+  FAR void *priv;
+};
+
+#endif /* CONFIG_NET_PHYLIB */
+
 /****************************************************************************
  * Public Data
  ****************************************************************************/
@@ -109,6 +264,81 @@ int phy_notify_subscribe(FAR const char *intf, pid_t pid,
 int phy_notify_unsubscribe(FAR const char *intf, pid_t pid);
 #endif
 
+/****************************************************************************
+ * PHYLIB Subsystem Declarations
+ ****************************************************************************/
+
+#ifdef CONFIG_NET_PHYLIB
+
+/* PHY device lifecycle */
+
+FAR struct phy_device_s *phy_device_create(FAR struct mdio_bus_s *bus,
+                                           uint8_t addr);
+int phy_device_free(FAR struct phy_device_s *phydev);
+ssize_t phy_device_scan(FAR struct mdio_bus_s *bus,
+                        FAR struct phy_device_s **devs, size_t maxdevs);
+
+/* PHY connect/disconnect */
+
+int phy_connect(FAR struct phy_device_s *phydev,
+                FAR struct netdev_lowerhalf_s *lower);
+int phy_disconnect(FAR struct phy_device_s *phydev);
+
+/* PHY state machine */
+
+int phy_start(FAR struct phy_device_s *phydev);
+int phy_stop(FAR struct phy_device_s *phydev);
+
+/* PHY interrupt handling
+ *
+ * phy_interrupt() is the entry point a MAC/board driver calls from its
+ * own ISR (the PHY_MAC_INTERRUPT case); it simply triggers the PHY state
+ * machine.  It is safe to call from interrupt context.
+ *
+ * The phylib-owned ISR for a real PHY interrupt line (phy_device_s.irq >= 0)
+ * is attached/detached internally by phy_start()/phy_stop(); on attach
+ * failure the PHY silently falls back to PHY_POLL.  For PHY_POLL and
+ * PHY_MAC_INTERRUPT the MAC ISR is expected to call phy_interrupt()
+ * directly.
+ */
+
+void phy_interrupt(FAR struct phy_device_s *phydev);
+
+/* Upper half integration (phy_core.c) */
+
+int phy_ioctl(FAR struct phy_device_s *phydev, int cmd, unsigned long arg);
+
+/****************************************************************************
+ * Inline Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: phy_reset
+ *
+ * Description:
+ *   Control the PHY hardware reset line.  Thin wrapper over the MDIO bus
+ *   reset op (forwards to mdio_reset()).
+ *   value != 0 asserts reset, value == 0 deasserts.
+ *   The per-PHY settle delay and any idempotency are handled by the lower
+ *   half; a PHY without a reset line is a quiet no-op.
+ *
+ * Input Parameters:
+ *   phydev - Pointer to the PHY device structure
+ *   value  - Non-zero to assert reset, zero to deassert
+ *
+ ****************************************************************************/
+
+static inline void phy_reset(FAR struct phy_device_s *phydev,
+                             int value)
+{
+  if (phydev != NULL && phydev->bus != NULL)
+    {
+      mdio_reset(phydev->bus, phydev->mdio_addr, value);
+    }
+}
+
+#endif /* CONFIG_NET_PHYLIB */
+
 #ifdef __cplusplus
 }
 #endif

Reply via email to