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 32bad13a97cb16ada57d62883d05d9377a7f09b1 Author: zhangkai25 <[email protected]> AuthorDate: Thu Nov 5 19:10:52 2026 +0800 Documentation/net: add PHYLIB design and vendor porting guides Add two reStructuredText documents under the networking documentation, alongside the existing MDIO bus page: - phylib.rst: PHYLIB design - background, architecture, core data structures, device lifecycle, the link state machine (polling vs interrupt), the concurrency model, MAC driver integration, user-space ioctl/ethtool call chains and the implemented framework extensions. - phylib_vendor_porting.rst: a vendor porting guide for integrating the MDIO lower-half and a dedicated PHY model driver, with ready-to-adapt templates, a delivery checklist, an acceptance gate and common mistakes. Both are registered in the networking index toctree. Signed-off-by: zhangkai25 <[email protected]> --- Documentation/os/networking/index.rst | 2 + Documentation/os/networking/mdio.rst | 5 +- Documentation/os/networking/phylib.rst | 1675 ++++++++++++++++++++ .../os/networking/phylib_vendor_porting.rst | 1351 ++++++++++++++++ 4 files changed, 3031 insertions(+), 2 deletions(-) diff --git a/Documentation/os/networking/index.rst b/Documentation/os/networking/index.rst index 9f4a9668424..6d39fe0275f 100644 --- a/Documentation/os/networking/index.rst +++ b/Documentation/os/networking/index.rst @@ -71,6 +71,8 @@ Network Support netpoll.rst note.rst mdio.rst + phylib.rst + phylib_vendor_porting.rst netguardsize.rst netlink.rst slip.rst diff --git a/Documentation/os/networking/mdio.rst b/Documentation/os/networking/mdio.rst index 2c6fa15347e..8006a7ec73b 100644 --- a/Documentation/os/networking/mdio.rst +++ b/Documentation/os/networking/mdio.rst @@ -8,7 +8,7 @@ MDIO Bus Driver The NuttX MDIO bus driver provides a standardized interface for communicating with Ethernet PHY (Physical Layer) transceivers. It employs a classic upper-half/lower-half architecture to abstract hardware-specific logic from the generic MDIO protocol, -which is currently compliant with Clause 22 of the IEEE 802.3 standard. +which supports both Clause 22 and (optionally, under ``CONFIG_MDIO_CLAUSE_45``) Clause 45 of the IEEE 802.3 standard. The primary implementation of the upper-half can be found in ``drivers/net/mdio.c``. Driver Architecture @@ -44,7 +44,8 @@ Key Data Structures 1. ``struct mdio_ops_s``: A structure containing function pointers that the lower-half driver must implement to perform hardware-level operations. * ``read``: Performs a Clause 22 MDIO read operation. * ``write``: Performs a Clause 22 MDIO write operation. - * ``reset``: An optional function to execute a hardware-specific PHY reset. + * ``read_c45`` / ``write_c45``: Optional native Clause 45 (MMD) read/write operations, available when ``CONFIG_MDIO_CLAUSE_45`` is enabled. When a lower-half leaves them NULL, the upper-half falls back to indirect MMD access over the Clause 22 registers 13/14. + * ``reset``: An optional PHY hardware reset-line control. It is a level control, not a one-shot pulse: ``value != 0`` asserts reset (drives the PHY into reset) and ``value == 0`` deasserts it (releases the PHY). The lower-half owns pin polarity and the datasheet-mandated settle delays, and is responsible for any idempotency since a single bus may host several PHY addresses. 2. ``struct mdio_lowerhalf_s``: The container for the lower-half instance, which holds a pointer to the ``mdio_ops_s`` vtable and an optional private data pointer for the driver's internal state. diff --git a/Documentation/os/networking/phylib.rst b/Documentation/os/networking/phylib.rst new file mode 100644 index 00000000000..42a83021966 --- /dev/null +++ b/Documentation/os/networking/phylib.rst @@ -0,0 +1,1675 @@ +.. _phylib: + +.. include:: /substitutions.rst + +========================================== +PHY Abstraction Layer (PHYLIB) +========================================== + +This document describes the design of the PHY Abstraction Layer (PHYLIB) +for NuttX. It covers: design background, overall architecture, core data +structures, the state machine, the generic PHY driver, MAC driver +integration, ethtool integration, vendor drivers, and debugging. + +1. Design Background +==================== + +1.1 Current Problems +-------------------- + +In the current NuttX network drivers, PHY management logic is scattered +inside each MAC driver. Drawbacks of having no PHYLIB: + +#. **Large amount of duplicated code** — every MAC driver implements its + own MDIO read/write, PHY init and link detection; the logic is similar + but rewritten each time. +#. **Changing the PHY means changing the MAC** — PHY register definitions + are spread across MAC drivers, so swapping a chip requires editing MAC + source. +#. **Inconsistent link management** — each driver uses a different poll + interval, and carrier notification timing is not unified. +#. **PHY drivers cannot be reused** — the same PHY on a different SoC has + its init code copied again. +#. **Inconsistent ioctl behavior** — MII/ethtool commands are interpreted + by each driver on its own. + +1.2 Design Goals +---------------- + +#. Decouple PHY management from the MAC driver. +#. Provide a standardized MDIO bus, PHY device and PHY driver framework. +#. Support Clause 22 and Clause 45 PHYs. +#. Support both polling and interrupt link-monitoring modes, selectable + by hardware capability. +#. Expose link state uniformly through ethtool ioctl. +#. Allow PHY drivers to be reused across platforms. + +.. note:: + + Core value: a MAC driver only needs to implement the MDIO lower-half + (the ``mdio_ops_s`` read/write callbacks) and call a few PHYLIB APIs to + complete PHY integration, without caring about the register details of + a specific PHY chip. The MDIO bus itself is managed by the community + upper-half framework (``drivers/net/mdio.c``). + +1.3 Provenance +-------------- + +This implementation is written independently based on the IEEE 802.3 +standard and chip datasheets (such as the RTL8221B). Register addresses, +bit definitions and access timing are IEEE standard / hardware facts. +The interface naming follows common PHYLIB conventions for readability. +The underlying implementation (state machine, concurrency model, memory +management) is a native NuttX design. + +2. Overall Architecture +======================= + +The framework follows the ``netdev -> phydev -> mdio`` layering. Benefits +of PHYLIB: + +#. **Zero change to swap a PHY** — only add a vendor driver file; the MAC + driver is untouched. +#. **Unified state machine** — one piece of logic serves all MACs; link + changes are reported to the stack automatically. +#. **PHY drivers reusable across platforms** — a vendor driver works on any + MAC platform. +#. **Fast bring-up on new platforms** — implement the MDIO lower-half + (``mdio_ops_s``) and call a few PHYLIB APIs. +#. **Standardized ioctl** — PHYLIB handles MII/ethtool commands uniformly. +#. **Polling / interrupt dual mode** — polling by default; if the hardware + wires INTB, switching to interrupt-driven is free. + +3. Core Source Files +==================== + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - File + - Role + * - ``drivers/net/phy/phy.c`` + - State machine: start/stop/poll worker, interrupt handling + (``phy_mac_interrupt``), suspend/resume. + * - ``drivers/net/phy/phy_device.c`` + - PHY device model: create, match, connect, scan. + * - ``drivers/net/mdio.c`` + - MDIO bus upper-half (community framework): ``mdio_register``, + ``mdio_read``/``write``, ``mdio_c45`` access, serialized by a lock. + * - ``drivers/net/phy/phy_core.c`` + - Low-level helpers: ``phy_read``/``write``/``modify``/``set_bits``/``mmd``. + * - ``drivers/net/phy/phy_ioctl.c`` + - MII ioctl + ethtool link-settings dispatch. + * - ``drivers/net/phy/genphy.c`` + - Generic Clause 22 PHY driver (IEEE 802.3 standard registers). + * - ``drivers/net/phy/genphy_c45.c`` + - Generic Clause 45 PHY driver (MMD registers). + * - ``drivers/net/phy/realtek/`` + - RTL8221B vendor driver. + * - ``include/nuttx/net/phy.h`` + - Public header: structures + API declarations. + * - ``include/nuttx/net/mdio.h`` + - MDIO upper/lower-half contract: ``mdio_ops_s``, + ``mdio_lowerhalf_s``, ``mdio_register`` etc. + +4. Kconfig +========== + +.. code-block:: kconfig + + # Framework core + CONFIG_NET_PHYLIB=y # Enable the PHYLIB subsystem + # Auto-selects the two options below: + CONFIG_MDIO_BUS=y # MDIO bus upper-half (drivers/net/mdio.c) + CONFIG_MDIO_CLAUSE_45=y # MDIO Clause 45 support (needed by C45 PHYs) + + # Tunables + CONFIG_NET_PHYLIB_POLL_INTERVAL=1000 # State-machine poll interval (ms) + CONFIG_NET_PHYLIB_MAX_DRIVERS=8 # Maximum number of PHY drivers + CONFIG_NET_PHYLIB_MAX_PHYS=8 # Maximum number of PHY devices + +5. Core Data Structures +======================= + +5.1 MDIO Bus +------------ + +The MDIO bus uses the standard upper/lower-half layering +(``drivers/net/mdio.c`` + ``include/nuttx/net/mdio.h``). The upper-half +owns the bus core object (lock, read/write forwarding, lifecycle); the +MAC driver only implements the lower-half hardware callbacks. + +Design points: + +- **Upper/lower layering**: the bus core object (including the lock) lives + in the upper-half ``drivers/net/mdio.c`` and is allocated dynamically by + ``mdio_register()``. The MAC driver only holds a ``mdio_lowerhalf_s`` and + the handle returned by ``mdio_register()``. +- **Locking**: the read/write mutex is held by the upper-half, guaranteeing + concurrency safety between ethtool ioctl and the state machine. +- **C45**: ``read_c45``/``write_c45`` are optional — when NULL, the + upper-half automatically uses the Clause 22 reg 13/14 indirect access; + implementing them when the hardware natively supports C45 (e.g. AURIX + GETH) avoids the indirect transactions. Controlled by + ``CONFIG_MDIO_CLAUSE_45`` (see "C45 Extension" below). + +Lower-half callback table ``mdio_ops_s`` (implemented by the MAC driver): + +.. code-block:: c + + struct mdio_ops_s + { + /* Clause 22 read/write */ + int (*read)(FAR struct mdio_lowerhalf_s *lower, uint8_t phyaddr, + uint8_t regaddr, FAR uint16_t *value); + int (*write)(FAR struct mdio_lowerhalf_s *lower, uint8_t phyaddr, + uint8_t regaddr, uint16_t value); + + #ifdef CONFIG_MDIO_CLAUSE_45 + /* Native Clause 45 read/write - optional; when NULL the upper-half + * uses reg13/14 indirect access. + */ + int (*read_c45)(FAR struct mdio_lowerhalf_s *lower, uint8_t phyaddr, + uint8_t devad, uint16_t regaddr, FAR uint16_t *value); + int (*write_c45)(FAR struct mdio_lowerhalf_s *lower, uint8_t phyaddr, + uint8_t devad, uint16_t regaddr, uint16_t value); + #endif + + /* PHY hardware reset line control - optional. Controls the PHY RESET_N + * by logic level rather than a one-shot pulse. value != 0 asserts + * (into reset); value == 0 deasserts (release). The lower-half handles + * pin polarity (active-low RESET_N handled internally) and the + * datasheet-specified assert/deassert settle delays; the upper-half + * mdio_reset() handles idempotency (skips when already at the target + * state). + */ + int (*reset)(FAR struct mdio_lowerhalf_s *lower, uint8_t phyaddr, + int value); + }; + + /* Lower-half instance: allocated by the MAC driver; ops must be the + * first member. + */ + struct mdio_lowerhalf_s + { + FAR const struct mdio_ops_s *ops; + }; + +Upper-half implementation (``drivers/net/mdio.c``) and public API. The +upper-half collapses the bus core into ``struct mdio_bus_s`` (defined +privately inside mdio.c, not visible externally), holding only a +"lower-half pointer + mutex": + +.. code-block:: c + + /* Register the lower-half */ + FAR struct mdio_bus_s *mdio_register(FAR struct mdio_lowerhalf_s *lower); + int mdio_unregister(FAR struct mdio_bus_s *dev); + + /* Read/write (serialized by the upper-half internal lock) */ + int mdio_read(FAR struct mdio_bus_s *dev, uint8_t phyaddr, + uint8_t regaddr, FAR uint16_t *value); + int mdio_write(FAR struct mdio_bus_s *dev, uint8_t phyaddr, + uint8_t regaddr, uint16_t value); + + #ifdef CONFIG_MDIO_CLAUSE_45 + int mdio_c45_read(FAR struct mdio_bus_s *dev, uint8_t phyaddr, + uint8_t devad, uint16_t regaddr, FAR uint16_t *value); + int mdio_c45_write(FAR struct mdio_bus_s *dev, uint8_t phyaddr, + uint8_t devad, uint16_t regaddr, uint16_t value); + #endif + + /* PHY hardware reset line control (assert/deassert) */ + int mdio_reset(FAR struct mdio_bus_s *dev, uint8_t phyaddr, int value); + + struct mdio_bus_s + { + FAR struct mdio_lowerhalf_s *lower; + mutex_t lock; /* Bus mutex */ + }; + +C45 Extension +~~~~~~~~~~~~~ + +The original community upper-half implemented only Clause 22 (C45 was left +as an empty ``#ifdef CONFIG_MDIO_CLAUSE_45``). Since the RTL8221B is a C45 +PHY, C45 was completed on top of the community framework: + +#. **``mdio_ops_s`` gains** two optional callbacks ``read_c45`` / + ``write_c45`` (see the structure above). +#. **``mdio.c`` gains** ``mdio_c45_read`` / ``mdio_c45_write``: when the + lower-half provides native C45 ops they are called directly; otherwise + it **falls back automatically** to the Clause 22 reg13/14 indirect + access (MMD indirect addressing), transparent to upper layers: + + .. code-block:: c + + int mdio_c45_read(FAR struct mdio_bus_s *dev, uint8_t phyaddr, + uint8_t devad, uint16_t regaddr, FAR uint16_t *value) + { + nxmutex_lock(&dev->lock); + + if (dev->lower->ops->read_c45 != NULL) + { + /* Native C45: one transaction in the lower-half */ + int ret = dev->lower->ops->read_c45(dev->lower, phyaddr, devad, + regaddr, value); + nxmutex_unlock(&dev->lock); + return ret; + } + + /* Fallback: indirect via C22 reg13(MMDCTRL)/reg14(MMDDATA) */ + dev->lower->ops->write(dev->lower, phyaddr, MII_MMDCONTROL, devad); + dev->lower->ops->write(dev->lower, phyaddr, MII_MMDADDRDATA, regaddr); + dev->lower->ops->write(dev->lower, phyaddr, MII_MMDCONTROL, + devad | MII_MMDCONTROL_FUNC_NOINCR); + int ret = dev->lower->ops->read(dev->lower, phyaddr, + MII_MMDADDRDATA, value); + nxmutex_unlock(&dev->lock); + return ret; + } + +#. **Kconfig gains** a ``CONFIG_MDIO_CLAUSE_45`` switch, which + ``NET_PHYLIB`` auto-selects. + +.. note:: + + Meaning of the C45 fallback: when the hardware natively supports C45 + (e.g. AURIX GETH), implementing ``read_c45``/``write_c45`` completes the + access in one bus transaction; a MAC without native C45 need not write + indirect-access logic itself, as the upper-half falls back to reg13/14 + automatically (4 C22 transactions). The PHYLIB caller + (``phy_read_mmd`` -> ``mdio_c45_read``) is completely unaware. + +reg13/14 indirect addressing (IEEE 802.3 Clause 22 extension, the standard +mechanism for accessing MMD registers): the C22 register space only has a +5-bit address (reg 0-31) and cannot directly address the 16-bit MMD +register space of C45. IEEE 802.3 uses **reg 13 (MMDCONTROL) + reg 14 +(MMDADDRDATA)** as an indirect channel, so each C45 access takes 4 steps: + +.. list-table:: + :header-rows: 1 + :widths: 10 15 40 35 + + * - Step + - Operation + - reg 13 ``MMDCONTROL`` + - reg 14 ``MMDADDRDATA`` + * - 1 + - C22 write + - devad (address mode, FUNC=00) + - — + * - 2 + - C22 write + - — + - Write the target 16-bit MMD register address + * - 3 + - C22 write + - devad | data mode (FUNC=01, no post-increment) + - — + * - 4 + - C22 read / write + - — + - Read / write the 16-bit data of the target MMD register + +Each C45 read/write needs 4 C22 bus transactions, 4x the cost of native +C45 (one frame of 5-bit OP + 16-bit address + 16-bit data). So implementing +``read_c45``/``write_c45`` when the hardware supports native C45 (e.g. +AURIX GETH) saves 75% of the bus transactions, a significant optimization. + +Interface provenance (community original / added by this design): + +.. list-table:: + :header-rows: 1 + :widths: 35 15 50 + + * - Interface / field + - Source + - Notes + * - ``mdio_register`` / ``mdio_unregister`` + - community + - Dynamically allocate/free the bus handle, bind the lower-half. + * - ``mdio_read`` / ``mdio_write`` + - community + - Clause 22 read/write, forward to ``lower->ops`` under the lock. + * - ``mdio_reset`` + - community + - PHY hardware reset line control: changed to ``(lower, phyaddr, + value)`` level control; idempotency is left to the lower half. + * - ``mdio_ops_s.read`` / ``.write`` / ``.reset`` + - community + - Lower-half C22 + reset callback contract. + * - ``mdio_ops_s.read_c45`` / ``.write_c45`` + - added here + - Lower-half native C45 callbacks (optional, + ``#ifdef CONFIG_MDIO_CLAUSE_45``). + * - ``mdio_c45_read`` / ``mdio_c45_write`` + - added here + - C45 read/write: native preferred, falls back to reg13/14 indirect. + * - ``CONFIG_MDIO_CLAUSE_45`` + - added here + - C45 switch, auto-selected by ``NET_PHYLIB``. + +5.2 struct phy_device_s +----------------------- + +The PHY device instance, holding all runtime state: + +.. code-block:: c + + struct phy_device_s + { + uint32_t phy_id; /* (PHYID1<<16)|PHYID2 */ + uint8_t mdio_addr; /* MDIO address 0-31 */ + FAR struct mdio_bus_s *bus; /* The MDIO bus it is on */ + FAR const struct phy_driver_s *drv; /* Matched PHY driver */ + FAR struct netdev_lowerhalf_s *attached_dev; /* Associated MAC */ + + /* Link state */ + bool is_c45; /* Whether it is a Clause 45 PHY */ + bool link; /* Current link state */ + uint32_t speed; /* Current speed (10/100/1000/2500) */ + uint8_t duplex; /* Current duplex mode */ + enum phy_interface_e interface; /* Interface mode (RGMII/SGMII/...) */ + + /* Capability bitmaps */ + uint32_t supported; /* Modes supported by the PHY */ + uint32_t advertising; /* Currently advertised modes */ + uint32_t lp_advertising; /* Link-partner advertised modes */ + bool autoneg; /* Auto-negotiation enable */ + + /* State machine */ + enum phy_state_e state; /* Current state */ + struct work_s state_work; /* LPWORK poll work */ + bool state_machine_running; + mutex_t lock; /* Device lock, serializes state fields */ + + /* Interrupt mode (optional) */ + int irq; /* PHY IRQ; PHY_POLL(-1) = polling */ + bool interrupts; /* Whether interrupt-driven now */ + + /* Driver private data (optional) */ + FAR void *priv; /* PHY driver private state, + * owned by the driver */ + }; + +Field groups: + +.. list-table:: + :header-rows: 1 + :widths: 15 35 50 + + * - Group + - Key fields + - Notes + * - Identity + - ``phy_id``, ``is_c45``, ``drv`` + - Who the PHY is, what protocol, which driver it binds to. + * - Link state + - ``link``, ``speed``, ``duplex``, ``autoneg`` + - Refreshed every second by the state machine; the MAC configures + hardware accordingly. + * - Capability bitmaps + - ``supported``, ``advertising``, ``lp_advertising`` + - Core of auto-negotiation: local advertise ∩ partner advertise = + final speed. + * - State machine + - ``state``, ``state_work``, ``lock`` + - The engine driving the PHY lifecycle; ``lock`` serializes state + field access. + * - Connections + - ``attached_dev``, ``bus`` + - Association with the netdev and the MDIO bus. + +5.3 struct phy_driver_s +----------------------- + +The PHY driver callback interface: + +.. code-block:: c + + 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); + CODE int (*suspend)(FAR struct phy_device_s *phydev); + CODE int (*resume)(FAR struct phy_device_s *phydev); + + /* Interrupt support (optional; polling only if unimplemented) */ + CODE int (*config_intr)(FAR struct phy_device_s *phydev, bool enable); + CODE int (*handle_interrupt)(FAR struct phy_device_s *phydev); + }; + +.. note:: + + Key design: all callbacks are optional. An unimplemented callback + automatically falls back to the generic genphy implementation. A PHY + compliant with IEEE 802.3 works without any vendor driver. + +Match rule: ``(phydev->phy_id & drv->phy_id_mask) == drv->phy_id`` + +Callback execution frequency: + +.. list-table:: + :header-rows: 1 + :widths: 35 20 45 + + * - Callback + - Frequency + - Notes + * - ``config_init`` + - once + - Executed at connect. + * - ``config_aneg`` + - on demand + - When the user changes link settings. + * - ``read_status`` + - **once per second (default)** + - State-machine polling, the hottest path. + * - ``suspend`` / ``resume`` + - on demand + - On system sleep/wake. + * - ``config_intr`` / ``handle_interrupt`` + - on demand (optional) + - Enable INTB in interrupt mode / decode and handle all interrupt + sources when triggered; falls back to polling if unimplemented. + +6. Device Lifecycle +=================== + +The full PHY device lifecycle: **discover -> connect -> start -> run -> +stop -> free**. + +.. note:: + + NuttX MAC drivers usually already know the PHY address (from the board + defconfig or datasheet), so they call ``phy_device_create(bus, + known_addr)`` to create it precisely, without scanning addresses 0-31. + ``mdio_bus_scan()`` is kept as an optional tool for the + unknown-address case. + +6.1 Discovery and Registration +------------------------------ + +.. code-block:: text + + MAC driver init / ifup: + mdio_register(&priv->mdio_lower) // register MDIO lower-half, get bus handle + phy_device_create(handle, known_addr) // create directly with known address + -> read PHYID1 (reg 2) / PHYID2 (reg 3) (C45 PHY tries MMD1 indirect first) + -> concat: phy_id = (PHYID1 << 16) | PHYID2 + -> reject invalid (0x0000/0xFFFF) + -> allocate phy_device_s from the static pool + -> match driver by (id & mask) -> fall back to genphy if none + -> phydev->bus = handle (save bus handle for later access) + +6.2 Connect +----------- + +.. code-block:: text + + phy_connect(netdev_lower, phydev) + -> check phydev is not in use (else -EBUSY) + -> set bidirectional link: phydev->attached_dev = dev, dev->phydev = phydev + -> phy_reset(phydev, 0) // deassert, release hard reset + -> call drv->config_init() to init the chip + -> transition to PHY_READY + +6.3 Start and Stop +------------------ + +.. code-block:: text + + phy_start(phydev) // called by the MAC driver in ifup + -> check state == PHY_READY or PHY_HALTED + -> call drv->config_aneg() // start auto-negotiation + -> state = PHY_UP + -> if irq != PHY_POLL and config_intr present: enable interrupts + -> work_queue(LPWORK) schedules polling + - polling mode: 1s period + - interrupt mode: 8x period (missed-interrupt backstop only) + + phy_stop(phydev) // called by the MAC driver in ifdown + -> if interrupts: config_intr(false) disables interrupts + -> work_cancel_sync(LPWORK) cancels state_work (waits for running work, prevents UAF) + -> state = PHY_HALTED + -> netdev_lower_carrier_off() notifies the MAC + +6.4 Disconnect and Free +----------------------- + +.. code-block:: text + + phy_disconnect(phydev) + -> phy_stop() to ensure the state machine stopped + -> clear bidirectional link (attached_dev = NULL, dev->phydev = NULL) + -> phy_reset(phydev, 1) // assert hard reset to finish + -> state = PHY_DOWN + + mdio_unregister(handle) // MAC driver frees the bus on remove + +7. State Machine +================ + +The state machine is the core engine of PHYLIB, managing the complete PHY +lifecycle. + +7.1 State Definitions +--------------------- + +.. code-block:: c + + enum phy_state_e + { + PHY_DOWN = 0, // Device/driver not ready + PHY_READY, // PHY ready, MAC not started + PHY_UP, // Auto-negotiation started, waiting for link + PHY_RUNNING, // Link established + PHY_NOLINK, // PHY working but no link + PHY_HALTED, // PHY stopped + PHY_ERROR // Unrecoverable error (e.g. MDIO lost); forces carrier + // off and stops polling + }; + +7.2 State Descriptions +---------------------- + +.. list-table:: + :header-rows: 1 + :widths: 12 28 30 30 + + * - State + - Meaning + - Entry condition + - Exit condition + * - DOWN + - Device/driver not ready + - Initial state / after disconnect + - phy_connect succeeds + * - READY + - PHY ready, MAC not open + - config_init succeeds + - phy_start + * - UP + - Auto-negotiation started, waiting for link + - phy_start called + - link detection result determined + * - RUNNING + - Link established, normal traffic + - read_status returns link=1 + - link lost / phy_stop + * - NOLINK + - PHY working but no link + - read_status returns link=0 + - link restored / phy_stop + * - HALTED + - Stopped, PHY suspended + - phy_stop called + - phy_start / disconnect + * - ERROR + - Unrecoverable error (MDIO lost etc.) + - read_status / handle_interrupt returns < 0 + - phy_start (recover via stop/start or disconnect/connect) + +7.3 Link Monitoring: Polling vs Interrupt +----------------------------------------- + +PHYLIB supports two link-state monitoring modes, decided by the +``phy_device_s.irq`` field. Both share the same state-transition logic +(``phy_check_link``), differing only in the trigger source. + +.. list-table:: + :header-rows: 1 + :widths: 12 44 44 + + * - Dimension + - Polling + - Interrupt + * - Enable condition + - ``irq == PHY_POLL`` (default) + - ``irq != PHY_POLL`` and the driver implements ``config_intr`` + * - Trigger source + - LPWORK timer, every ``CONFIG_NET_PHYLIB_POLL_INTERVAL`` (default 1s) + - PHY INTB pin interrupt, fired immediately on link change + * - Response latency + - Worst case one poll period (default 1s) + - Near real-time (interrupt -> work schedule latency) + * - CPU cost + - One MDIO read per period, constant + - Reads only on link change, zero cost when idle + * - Backstop + - Is the backstop itself + - Keeps 8x low-frequency polling to catch missed interrupts + +Interrupt sources — three kinds. The interrupt mode can be further +subdivided by the physical source, distinguished by the value of +``phy_device_s.irq``: + +.. list-table:: + :header-rows: 1 + :widths: 12 22 26 20 20 + + * - Source + - irq value + - Where the interrupt comes from + - Who attaches the ISR + - Who calls phy_mac_interrupt + * - Pin source + - >= 0 (real IRQ number) + - PHY INTB pin -> SoC GPIO interrupt + - phylib (irq_attach) + - phylib's phy_interrupt ISR + * - MAC source + - PHY_MAC_INTERRUPT(-2) + - MAC detects link change internally (e.g. SGMII in-band) + - the MAC driver + - the MAC driver ISR + * - Polling + - PHY_POLL(-1) + - No interrupt, timed register reads + - none + - none (timed work backstop) + +.. note:: + + The phylib framework does not care about the physical source of the + interrupt; it only exposes the unified entry ``phy_mac_interrupt()``. + Who calls it decides the source — the pin source is called by phylib's + own ISR, the MAC source by the MAC driver's ISR. The IRQ number is + filled into ``phydev->irq`` by the MAC/board driver. All three sources + converge into the same ``phy_check_link``; the link decision logic + exists only once. + +irq field three-state encoding: + +.. code-block:: c + + /* phy.h: the two sentinels of the irq field */ + #define PHY_POLL (-1) /* no interrupt source, pure polling */ + #define PHY_MAC_INTERRUPT (-2) /* interrupt handled by the MAC driver, phylib does not attach */ + /* others (>= 0) = a real, attachable IRQ number (pin source) */ + + /* Whether it is a "real, attachable interrupt line" - i.e. a pin source */ + #define phy_interrupt_is_valid(p) \ + ((p)->irq != PHY_POLL && (p)->irq != PHY_MAC_INTERRUPT) + +.. note:: + + Key constraint: ``phy_interrupt`` (the pin-source ISR) runs in hard + interrupt context. NuttX has no threaded IRQ, so it must not read MDIO + (which would block). It therefore only "masks the line with + up_disable_irq + posts work via phy_mac_interrupt"; the real register + reads (handle_interrupt / read_status) are deferred to the LPWORK + thread. This is the only structural difference from a threaded-handler + design. The masked line is re-enabled by the worker (via up_enable_irq) + after handle_interrupt acknowledges the source (equivalent to + IRQF_ONESHOT). + +.. note:: + + In one sentence: ``phy_interrupt`` is the interrupt callback attached by + irq_attach and called directly by hardware; ``phy_mac_interrupt`` is the + notification API called from inside that callback (a thin forwarding + layer) — it does not decode, read registers or touch link state, it only + moves "something happened" safely from (possibly) interrupt context to + the LPWORK thread, where the unified ``phy_check_link`` does the real + work. The MAC source has no ``phy_interrupt``; the MAC driver's own ISR + calls ``phy_mac_interrupt`` directly. + +7.4 Link Detection Flow +----------------------- + +Whether triggered by polling or interrupt, everything converges to the +shared ``phy_check_link()``: read the real-time PHY link state -> compare +with the current ``state`` -> on an up/down transition, notify the netdev +carrier. + +7.5 Concurrency Model and Locks +------------------------------- + +Who accesses the PHY / MDIO bus: + +.. list-table:: + :header-rows: 1 + :widths: 40 20 40 + + * - Accessor + - Context + - When triggered + * - PHY state machine ``phy_check_link`` + - LPWORK thread + - Polling: every 1s; interrupt: INTB -> work_queue + * - MII ioctl (SIOCGMIIREG/SIOCSMIIREG) + - Application thread + - User space issues ioctl + * - ethtool ioctl + - Application thread + - User space ``ethtool eth0`` etc. + +Serialization mechanisms: + +- **MDIO bus lock** (``mdio_bus_s.lock``, held by the upper-half + ``mdio.c``): all ``mdio_read/write/c45_*`` run under this lock, ensuring + mutual exclusion between the LPWORK state machine and application threads. + When a MAC driver's ``mdio_ops_s`` callback is entered the upper-half + already holds the lock, so **the callback must not take that lock again**, + or it deadlocks. +- **PHY device lock** (``phy_device_s.lock``): protects the state fields of + a single ``phydev`` (``state``/``link``/``speed``/``duplex``/``autoneg``/ + ``advertising``). All paths that read-modify-write state run under this + lock, serializing state transitions and avoiding races between the state + machine and ioctl. Initialized in ``phy_device_create`` via + ``nxmutex_init``. +- **The state machine itself**: each ``phydev`` has only one ``state_work``, + executed serially by a single LPWORK thread. +- **Interrupt context never touches MDIO**: ``phy_mac_interrupt()`` only + ``work_queue()``'s a task to LPWORK (ISR-safe); the real register access + happens in the LPWORK thread. + +8. MAC Driver Integration +========================= + +This section uses the real AURIX TC4x + RTL8221B driver (``aurix_enet.c``) +as a case study to detail the changes a MAC driver needs to integrate +PHYLIB. + +.. note:: + + Core principle: a MAC driver only needs to do two things — (1) tell + PHYLIB how to read/write MDIO registers; (2) start/stop the state + machine at ifup/ifdown. All PHY-chip-specific init, auto-negotiation and + link detection are taken over by PHYLIB + the PHY driver. + +8.1 Interfaces the MAC Driver Must Implement +-------------------------------------------- + +When integrating PHYLIB, the MAC driver connects to two groups of +interfaces: the ``netdev_lowerhalf`` OPS facing the network stack (already +present; some callbacks now forward to PHYLIB), and the MDIO lower-half +(``mdio_ops_s`` callback table, the new core part). + +netdev_lowerhalf OPS (facing the stack): + +.. list-table:: + :header-rows: 1 + :widths: 30 20 50 + + * - OPS callback + - After PHYLIB + - Notes + * - ``ifup`` + - modified + - Calls ``mdio_register`` + ``phy_device_create`` + ``phy_connect`` + + ``phy_start``. + * - ``ifdown`` + - modified + - Calls ``phy_stop`` + ``phy_disconnect`` + ``mdio_unregister``. + * - ``ioctl`` + - simplified + - MII/ethtool commands intercepted by PHYLIB; private register code + can be removed. + * - ``transmit`` / ``receive`` / ``txpoll`` + - unchanged + - Pure data plane, unrelated to PHY management. + +MDIO lower-half callbacks ``mdio_ops_s`` (facing the PHY, the new core): + +.. list-table:: + :header-rows: 1 + :widths: 25 15 60 + + * - Callback + - Required / optional + - Notes + * - ``read`` / ``write`` + - **required** + - Clause 22 read/write; ``mdio_register`` validates ops is non-NULL. + * - ``read_c45`` / ``write_c45`` + - optional + - Native Clause 45; when NULL the framework uses reg13/14 indirect + access. Implement when hardware supports native C45 (e.g. AURIX + GETH) to save transactions. + +.. note:: + + Comparison: before, the MAC driver managed both the data plane and the + PHY control plane (init / link polling / MII ioctl / MDIO), making it + bloated and tightly coupled to the PHY chip; after, the MAC driver keeps + only the **data plane + one group of mdio_bus callbacks**, with all PHY + control-plane logic pushed down to PHYLIB. Swapping the PHY chip needs + zero MAC driver change. + +8.2 Change Overview +------------------- + +.. list-table:: + :header-rows: 1 + :widths: 10 50 40 + + * - Step + - What + - Where + * - 1 + - Add mdio_lowerhalf + handle members to the struct + - ``aurix_enet_dev_s`` + * - 2 + - Implement the MDIO read/write callbacks + - New static functions + * - 3 + - Register the bus + create the PHY at init + - ``aurix_enet_ifup`` or init + * - 4 + - connect + start in ifup + - ``aurix_enet_ifup`` + * - 5 + - stop in ifdown + - ``aurix_enet_ifdown`` + +8.3 Step 1: Add MDIO Lower-Half Members +--------------------------------------- + +.. code-block:: c + + struct aurix_enet_dev_s + { + struct netdev_lowerhalf_s dev; + struct aurix_enet_module_config_s config_d; + bool ifup; + bool mac_ready; + const struct aurix_enet_config_s *config; + struct work_s init_work; + + /* ===== New: MDIO lower-half + bus handle ===== */ + struct mdio_lowerhalf_s mdio_lower; /* lower-half instance (ops shell) */ + FAR struct mdio_bus_s *mdio; /* handle from mdio_register */ + + /* ... other fields unchanged ... */ + }; + +.. note:: + + The whole ``mdio_bus_s`` bus object is no longer embedded; only the + lower-half ``mdio_lowerhalf_s`` (a thin ops vtable shell) and the bus + handle pointer returned by the upper-half are kept. The bus core object + (including the lock) is allocated and held by the upper-half + ``drivers/net/mdio.c``. In multi-instance cases (BMP multi-core / + multi-port) each ``aurix_enet_dev_s`` has its own lower, and the callback + uses ``container_of`` to recover the instance. + +8.4 Step 2: Implement the MDIO Lower-Half Callbacks +--------------------------------------------------- + +Wrap the hardware MDIO controller into ``mdio_ops_s`` callbacks. Note the +community signature: ``lower`` is the lower-half instance, the read value +is returned via the ``value`` out-parameter, and the return is 0 / negative +errno. + +.. code-block:: c + + /* Clause 22 read - called via ops->read */ + static int aurix_mdio_c22_read(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t regaddr, + FAR uint16_t *value) + { + FAR struct aurix_enet_dev_s *priv = + container_of(lower, struct aurix_enet_dev_s, mdio_lower); + + if (IfxGeth_Eth_mdio_read_clause22(priv->config_d.geth, + priv->config->port, + phyaddr, regaddr, value)) + { + return -EIO; + } + + return OK; + } + + /* Clause 22 write */ + static int aurix_mdio_c22_write(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t regaddr, + uint16_t val) + { + FAR struct aurix_enet_dev_s *priv = + container_of(lower, struct aurix_enet_dev_s, mdio_lower); + + if (IfxGeth_Eth_mdio_write_clause22(priv->config_d.geth, + priv->config->port, + phyaddr, regaddr, val)) + { + return -EIO; + } + + return OK; + } + + /* Native Clause 45 read/write (AURIX GETH supports it, avoids reg13/14) */ + static int aurix_mdio_c45_read(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t devad, + uint16_t regaddr, FAR uint16_t *value) + { + FAR struct aurix_enet_dev_s *priv = + container_of(lower, struct aurix_enet_dev_s, mdio_lower); + + if (IfxGeth_Eth_mdio_read_clause45(priv->config_d.geth, + priv->config->port, + phyaddr, devad, regaddr, value)) + { + return -EIO; + } + + return OK; + } + + static int aurix_mdio_c45_write(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t devad, + uint16_t regaddr, uint16_t val) + { + FAR struct aurix_enet_dev_s *priv = + container_of(lower, struct aurix_enet_dev_s, mdio_lower); + + if (IfxGeth_Eth_mdio_write_clause45(priv->config_d.geth, + priv->config->port, + phyaddr, devad, regaddr, val)) + { + return -EIO; + } + + return OK; + } + +PHY hardware reset callback ``aurix_mdio_reset`` (level control): + +.. code-block:: c + + /* PHY hard reset line (PHYRSTB) control. value!=0 asserts (drive low, + * into reset); value==0 deasserts (drive high, release). The reset pin + * is selected by GETH port (port0->P10, port1->P11). The lower half + * performs the requested level flip + the datasheet assert/settle + * delays; any idempotency is the lower half's responsibility. + */ + static int aurix_mdio_reset(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, int value) + { + FAR struct aurix_enet_dev_s *priv = + container_of(lower, struct aurix_enet_dev_s, mdio_lower); + int pin = (priv->config->port == 0) ? 10 : 11; + + IfxPort_setPinModeOutput(priv->config_d.port_p, pin, + IfxPort_OutputMode_pushPull, + IfxPort_OutputIdx_general); + if (value) + { + IfxPort_setPinLow(priv->config_d.port_p, pin); /* assert */ + up_mdelay(10); /* Tgap >= 10ms */ + } + else + { + IfxPort_setPinHigh(priv->config_d.port_p, pin); /* deassert */ + up_mdelay(68); /* settle 68ms */ + } + + return OK; + } + +.. note:: + + PHYLIB also provides a thin inline wrapper ``phy_reset(phydev, value)`` + (forwarding to ``mdio_reset(phydev->bus, phydev->mdio_addr, value)``), + called by ``phy_connect`` (deassert) / ``phy_disconnect`` (assert) + during the lifecycle. + +8.5 Step 3: Register MDIO + Create PHY at ifup +---------------------------------------------- + +.. note:: + + MDIO callback execution-context constraint: ``read``/``write``/ + ``read_c45``/``write_c45`` are triggered by two kinds of callers — (1) + the PHY state machine's ``read_status`` (running in the **LPWORK + thread**); (2) ethtool/MII ioctl (running in an **application thread**). + Both are serialized by the upper-half bus lock. Therefore the callback + implementation may sleep/block (it is always in thread context, never + in interrupt/atomic context), and must not re-acquire the upper-half bus + lock (the framework already holds it; doing so deadlocks). + +.. code-block:: c + + /* In aurix_enet_ifup(), after aurix_mdio_init() */ + + static int aurix_phylib_setup(struct aurix_enet_dev_s *priv) + { + /* MDIO lower-half ops table (file-scope static const) */ + static const struct mdio_ops_s g_aurix_mdio_ops = + { + .read = aurix_mdio_c22_read, + .write = aurix_mdio_c22_write, + #ifdef CONFIG_MDIO_CLAUSE_45 + .read_c45 = aurix_mdio_c45_read, + .write_c45 = aurix_mdio_c45_write, + #endif + .reset = aurix_mdio_reset, /* PHY hard reset line (PHYRSTB) level control */ + }; + + int ret; + + /* 1. Register the vendor PHY driver (idempotent) */ + phy_realtek_register(); + + /* 2. Fill the lower-half and register with the upper-half, get the handle */ + priv->mdio_lower.ops = &g_aurix_mdio_ops; + + priv->mdio = mdio_register(&priv->mdio_lower); + if (priv->mdio == NULL) + { + nerr("ERROR: mdio_register failed\n"); + return -ENODEV; + } + + /* 3. Hard-reset the PHY (must complete before reading the PHY ID). + * assert->deassert forms a complete power-on pulse; the lower-half + * applies 10ms assert + 68ms settle delays. + */ + mdio_reset(priv->mdio, ETH_PHY_ADDRESS, 1); /* assert */ + mdio_reset(priv->mdio, ETH_PHY_ADDRESS, 0); /* deassert + settle */ + + /* 4. Create the PHY device (known address, read PHY ID, match RTL8221B) */ + priv->phydev = phy_device_create(priv->mdio, ETH_PHY_ADDRESS); + if (priv->phydev == NULL) + { + nerr("ERROR: phy_device_create failed\n"); + mdio_unregister(priv->mdio); + priv->mdio = NULL; + return -ENODEV; + } + + /* 5. Connect the PHY to the netdev (runs config_init / firmware patch) */ + ret = phy_connect(&priv->dev, priv->phydev); + if (ret < 0) + { + nerr("ERROR: phy_connect failed: %d\n", ret); + mdio_unregister(priv->mdio); + priv->mdio = NULL; + priv->phydev = NULL; + return ret; + } + + return OK; + } + +8.6 Step 4: Start the State Machine in ifup +------------------------------------------- + +.. code-block:: c + + static int aurix_enet_ifup(struct netdev_lowerhalf_s *dev) + { + struct aurix_enet_dev_s *priv = (struct aurix_enet_dev_s *)dev; + + /* ... hardware init (hsphy_init, geth_init, mdio_init) ... */ + + #ifdef CONFIG_NET_PHYLIB + /* Integrate PHYLIB: register bus + create PHY + connect */ + ret = aurix_phylib_setup(priv); + if (ret < 0) + { + return ret; + } + + /* Start the PHY state machine - begin auto-negotiation + link polling */ + phy_start(priv->dev.phydev); + + #else + /* Old path: call MCAL PHY init directly (kept for compatibility) */ + ret = aurix_realtekethphy_init(priv); + #endif + + /* ... remaining init (DMA, interrupts, MAC enable) ... */ + } + +.. note:: + + After ``phy_start()`` the link state is managed automatically by the + PHYLIB state machine. When the PHY detects link up, PHYLIB calls + ``netdev_lower_carrier_on()`` and the stack starts sending/receiving. + The MAC driver no longer judges link state manually. + +8.7 Step 5: Stop the State Machine in ifdown +-------------------------------------------- + +.. code-block:: c + + static int aurix_enet_ifdown(struct netdev_lowerhalf_s *dev) + { + struct aurix_enet_dev_s *priv = (struct aurix_enet_dev_s *)dev; + + #ifdef CONFIG_NET_PHYLIB + /* Stop the PHY state machine */ + if (priv->dev.phydev != NULL) + { + phy_stop(priv->dev.phydev); + } + #endif + + /* ... remaining cleanup (disable interrupts, stop MAC) ... */ + } + +8.8 Benefits After Integration +------------------------------ + +#. Removes about 200 lines of PHY management code + (``aurix_realtekethphy_init`` + ``aurix_ethlink_up`` + link-retry logic). +#. Gets ethtool support automatically (speed/duplex/autoneg query and set). +#. Link changes are reported to the stack automatically, no manual + carrier_on/off. +#. Swapping the PHY chip only needs a vendor driver file; zero MAC change. +#. Unified MII ioctl behavior, no longer implemented per driver. + +9. Master/Slave Core Link Sync in BMP Multi-core +================================================ + +9.1 Background: the Shared MAC Model under BMP +---------------------------------------------- + +AURIX TC4x in BMP (Bare Metal Porting / AMP) mode runs an independent +NuttX instance on each core (``CONFIG_NCPUS=6``, ``CONFIG_SMP_NCPUS=1`` per +core), communicating through shared memory. They share the same GETH MAC +hardware, but each core has its own ``aurix_enet_dev_s`` / netdev. + +.. note:: + + The MDIO controller and the PHY are a globally unique physical resource. + If 6 independent OS instances accessed MDIO / ran the PHY state machine + simultaneously, it would cause bus contention and state corruption. + Therefore a single owner must be established. + +Following the "control-plane / data-plane separation" principle of +SR-IOV (the PF manages the PHY, the VFs only send/receive and query the PF +for link), the BMP design is: + +.. list-table:: + :header-rows: 1 + :widths: 30 20 50 + + * - Role + - Maps to + - Responsibility + * - main_core + - SR-IOV PF + - Owns MDIO / PHY exclusively, runs the phylib state machine, + **publishes** link state. + * - non-main_core + - SR-IOV VF + - Does not touch the PHY, **subscribes** to link state, reflects it to + its own netdev carrier. + +The difference: SR-IOV uses a hardware mailbox; BMP uses **shared memory** +(``shared_data_manual``) to pass link state. + +Before (no phylib): there was no real master/slave link sync. main_core +polled the PHY UTP link via the iLLD ``aurix_ethlink_up()`` (with retry) +and did ``carrier_on``; non-main_core did an **unconditional** +``netdev_lower_carrier_on()``, i.e. assumed carrier was always up and never +knew the real physical link. + +After (phylib + shared memory): main_core's phylib state machine manages +the link uniformly and publishes it through the shared-memory flag +``eth_link_up``; non-main_core subscribes to that flag and **really +follows** the physical link up/down. + +9.2 Shared Memory Field +----------------------- + +Add a link flag to ``shared_data_manual_s`` in +``vendor/infineon/chips/aurix/include/chip.h``: + +.. code-block:: c + + typedef struct + { + volatile int tmadc_sync_barrier; + volatile int eth_sync_barrier; + volatile bool eth_mac_ready_flag; + + /* ENET PHY link state published by the main core (which owns the PHY + * and runs the phylib state machine) so that non-main cores can follow + * the real link status instead of assuming carrier is always up. + */ + volatile bool eth_link_up; + struct can_module_s can_module[CAN_MODULE_NUM]; + volatile int leth_sync_barrier; + } shared_data_manual_s; + +.. note:: + + ``eth_link_up`` is marked ``volatile``, consistent with the existing + ``eth_sync_barrier``. After main_core writes it, it calls ``UP_DMB()`` + for cross-core visibility. The shared region lives in the RPTUN shared + segment, visible to all cores. + +9.3 Writer: main_core Publishes Link State +------------------------------------------- + +main_core owns the PHY; the phylib state machine manages its own carrier. +It additionally runs a periodic ``aurix_enet_link_worker`` mirroring +``phydev->link`` to shared memory: + +.. code-block:: c + + static void aurix_enet_link_worker(void *arg) + { + struct aurix_enet_dev_s *priv = (struct aurix_enet_dev_s *)arg; + + /* ifdown cleared priv->ifup, so the worker stops naturally */ + if (!priv->ifup) + { + return; + } + + if (priv->config->main_core) + { + if (priv->phydev != NULL) + { + /* Publish the current link state for other cores to read */ + shared_data_manual.eth_link_up = priv->phydev->link; + UP_DMB(); + } + } + else + { + /* non-main_core: see below */ + } + + work_queue(LPWORK, &priv->link_work, aurix_enet_link_worker, + priv, MSEC2TICK(CONFIG_NET_PHYLIB_POLL_INTERVAL)); + } + +9.4 Reader: non-main_core Follows Link State +-------------------------------------------- + +non-main_core has no phydev and runs no state machine; in the same +``link_worker`` it reads the shared flag and, using edge detection +(``link_up_last``), updates its own carrier only on change: + +.. code-block:: c + + else + { + /* non-main_core: follow the link state published by main_core */ + bool link = shared_data_manual.eth_link_up; + + if (link != priv->link_up_last) + { + priv->link_up_last = link; + if (link) + { + netdev_lower_carrier_on(&priv->dev); + } + else + { + netdev_lower_carrier_off(&priv->dev); + } + } + } + +non-main_core does ``netdev_lower_carrier_off()`` first at ifup (initial +``link_up_last = false``), guaranteeing it starts from carrier-off +regardless of the current link, then the worker raises it per the shared +flag. + +.. note:: + + This mechanism is only enabled under ``CONFIG_AURIX_ENET_USE_PHY && + CONFIG_NET_PHYLIB``. Single-core or non-PHYLIB cases fall back to the + original behavior (direct carrier_on). + +10. User-space PHY Control Call Chains +====================================== + +User space controls the PHY through ioctl system calls, in two kinds by +cmd: + +- **SIOCETHTOOL**: link parameter query/set (used by the ethtool tool). +- **SIOCGMIIREG / SIOCSMIIREG**: direct PHY register read/write. + +10.1 Path 1: ethtool ioctl (link parameters) +--------------------------------------------- + +.. code-block:: text + + User: ethtool eth0 / ethtool -s eth0 speed 100 + | ioctl(fd, SIOCETHTOOL, &ifr) + Socket layer: net/netdev/netdev_ioctl.c -> netdev_ioctl() + | find net_device by ifr_name, cmd == SIOCETHTOOL + | call dev->d_ioctl(dev, cmd, arg) + Upper half: drivers/net/netdev_upperhalf.c -> netdev_upper_ioctl() + | cmd == SIOCETHTOOL && lower->phydev != NULL + PHYLIB: phy_upper_ethtool_ioctl(lower->phydev, arg) + | switch(ethtool_cmd) + |-- ETHTOOL_GLINKSETTINGS -> phy_ethtool_get_link_ksettings() + |-- ETHTOOL_SLINKSETTINGS -> phy_ethtool_set_link_ksettings() + |-- ETHTOOL_NWAY_RST -> phy_ethtool_nway_reset() + |-- ETHTOOL_GLINK -> phydev->link + | (if PHYLIB returns -ENOTTY, fall through to the MAC's own ioctl) + Upper half: lower->ops->ioctl(dev, cmd, arg) + +10.2 Path 2: MII ioctl (direct register access) +------------------------------------------------ + +.. code-block:: text + + User: ioctl(fd, SIOCGMIIREG, &ifr) + | struct mii_ioctl_data_s passes phy_id and reg_num + Socket layer: net/netdev/netdev_ioctl.c -> netdev_ioctl() + | cmd == SIOCGMIIREG/SIOCSMIIREG/SIOCGMIIPHY + | call dev->d_ioctl(dev, cmd, arg) + Upper half: drivers/net/netdev_upperhalf.c -> netdev_upper_ioctl() + | lower->phydev != NULL + PHYLIB: phy_upper_mii_ioctl(lower->phydev, cmd, arg) + |-- SIOCGMIIPHY -> return phydev->mdio_addr + |-- SIOCGMIIREG -> phy_read(phydev, reg_num) + |-- SIOCSMIIREG -> phy_write(phydev, reg_num, val) + | + phy_core.c: phy_read() / phy_write() + | + mdio.c (upper half): mdio_read/mdio_write - locked, calls lower->ops->read/write + | + MAC hardware MDIO controller -> PHY chip registers + +10.3 Command to Kernel Call Mapping +----------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 25 45 + + * - ethtool command + - Kernel CMD + - Final call + * - ``ethtool eth0`` + - ETHTOOL_GLINKSETTINGS + - ``phy_ethtool_get_link_ksettings()`` + * - ``ethtool -s eth0 speed 100`` + - ETHTOOL_SLINKSETTINGS + - ``phy_ethtool_set_link_ksettings()`` -> ``drv->config_aneg()`` + * - MII register read + - SIOCGMIIREG + - ``phy_upper_mii_ioctl()`` -> ``phy_read()`` -> ``mdio_read()`` + * - MII register write + - SIOCSMIIREG + - ``phy_upper_mii_ioctl()`` -> ``phy_write()`` -> ``mdio_write()`` + +.. note:: + + Key design: ``netdev_upper_ioctl`` first checks ``lower->phydev != + NULL`` and gives the command to PHYLIB first. Only when PHYLIB returns + ``-ENOTTY`` (does not handle this command) does it fall through to the + MAC driver's own ``lower->ops->ioctl``. This guarantees unified behavior + with PHYLIB and backward compatibility without it. + +11. Debugging and Verification +============================== + +11.1 ethtool Commands +--------------------- + +With ``CONFIG_SYSTEM_ETHTOOL=y``, in NSH: + +.. code-block:: text + + core1> ethtool eth0 + Settings for eth0: + Supported link modes: + 10baseT/Full 100baseT/Full 1000baseT/Full Autoneg 2500baseT/Full + Supports auto-negotiation: Yes + Speed: 1000Mb/s + Duplex: Full + Auto-negotiation: on + PHY Address: 2 + Link detected: yes + +Supported commands: + +- ``ethtool eth0`` — show link settings and status +- ``ethtool -s eth0 speed 100 duplex full`` — change link parameters +- ``ethtool -r eth0`` — restart auto-negotiation + +11.2 Kernel Log +--------------- + +PHYLIB emits key events via ``ninfo()``/``nerr()`` (needs +``CONFIG_DEBUG_NET_INFO=y``): + +.. code-block:: text + + [CPU1] phylib: PHY id=0x001cc849 addr=2 drv='RTL8221B 2.5Gbps PHY' c45=1 + [CPU1] phylib: phy_start config_aneg ret=0 + [CPU1] phylib: PHY link up: 1000 Mbps full + [CPU1] phylib: PHY link down + +12. Performance Overhead Evaluation +=================================== + +To quantify the extra overhead the PHYLIB abstraction adds to the PHY +register access path, the most common path — MII register read +(``SIOCGMIIREG``) — was measured. + +Method: a start timestamp is recorded at the entry of the user-space +``mdio`` tool and an end timestamp on the kernel-side path; the difference +is the software-path time of that access. Timestamps use +``perf_gettime() * 1000000 / perf_getfreq()`` in microseconds. Each path is +sampled 100 times and averaged. + +.. list-table:: + :header-rows: 1 + :widths: 15 70 15 + + * - Path + - Call chain + - Avg time + * - No PHYLIB + - ``ioctl`` -> netdev_upper_ioctl -> ``lower->ops->ioctl`` -> + aurix_enet_ioctl -> private MDIO read + - ~13 us + * - With PHYLIB + - ``ioctl`` -> netdev_upper_ioctl -> phy_upper_mii_ioctl -> phy_read + -> mdio_bus -> MDIO callback + - ~12 us + +.. note:: + + Conclusion: the PHYLIB abstraction adds almost no overhead to the MII + register access path. The two paths average essentially the same (13 us + vs 12 us), a difference on the order of 1 us. The bulk of the 13 us is + the user-to-kernel syscall cost of ioctl; the PHYLIB forwarding chain + itself is only a small part. Introducing PHYLIB does not observably + affect PHY register access performance. + +13. Framework Extensions (Implemented) +======================================= + +On top of the base framework, the following capabilities were added to +support paged PHYs and automotive single-pair Ethernet (100BASE-T1) PHYs. +All are backward compatible (removed at compile time when +``CONFIG_NET_PHYLIB=n``). + +13.1 Driver Private Data phy_device_s.priv +------------------------------------------ + +``struct phy_device_s`` gains a ``FAR void *priv`` pointer for a PHY driver +to keep chip-specific state across callbacks (config_init / read_status / +suspend / resume), such as DVDDIO voltage selection, operation state or +patch-load flags — fields beyond IEEE 802.3 that should not go into the +generic structure. + +- **Ownership**: ``phydev->priv`` is owned entirely by the PHY driver. The + framework only zero-initializes it in ``phy_device_create()`` and never + dereferences or frees it. A driver that stores heap memory here is + responsible for releasing it in its own teardown; a driver may also use + it as a plain per-device flag without allocating. + +13.2 100BASE-T1 / 1000BASE-T1 Capability Bits +--------------------------------------------- + +The link capability bitmap gains two automotive single-pair Ethernet modes: + +.. code-block:: c + + #define SUPPORTED_100BASET1_FULL (1 << 13) + #define SUPPORTED_1000BASET1_FULL (1 << 14) + +The PHY driver fills ``phydev->supported`` accordingly in config_init, and +it is passed to user space through ethtool. + +13.3 Paged Register Access +-------------------------- + +Some PHYs (e.g. Realtek) keep most registers on a non-default page; +accessing them needs "switch page (reg 31) -> read/write target -> restore +page", done atomically so MII ioctl cannot change the page register in +between. Three new APIs: + +.. code-block:: c + + int phy_read_paged(phydev, page, regaddr, value); + int phy_write_paged(phydev, page, regaddr, value); + int phy_modify_paged(phydev, page, regaddr, mask, set); + +Implementation points: + +- Built from internal helpers ``phy_select_page()`` (lock + save old page + + switch) and ``phy_restore_page()`` (restore old page + unlock + propagate + error); the three APIs just call this pair. +- Hold the **MDIO bus lock** throughout, mutually exclusive with MII ioctl; + switch only when the page differs (dedup). + +13.4 MDIO Bus Lock Primitives +----------------------------- + +To support the "hold the lock across multiple transactions" need of paged +access, the MDIO upper-half adds: + +.. code-block:: c + + int mdio_lock(dev); void mdio_unlock(dev); /* explicit lock/unlock */ + int mdio_read_nolock(dev, phyaddr, regaddr, value); /* lockless read when held */ + int mdio_write_nolock(dev, phyaddr, regaddr, value); /* lockless write when held */ + +A caller composes an atomic multi-transaction sequence (such as paged +access) between ``mdio_lock()`` / ``mdio_unlock()`` using the ``*_nolock`` +primitives; the lock encapsulation stays in the MDIO layer and phylib never +touches the bus lock object directly. + +14. Extensibility for PHY-side Features (PTP, WoL, EEE, ...) +============================================================ + +Some PHYs integrate features that traditionally live on the MAC side, such +as IEEE 1588 / PTP hardware timestamping (e.g. TI DP83630) and +Wake-on-LAN. PHYLIB supports such features as a framework-level +extensibility model rather than hard-coding each one into the core, so +every addition is opt-in and PHYs without the feature are unaffected. + +14.1 The Four Extension Points +------------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Extension point + - Role + * - Optional ``phy_driver_s`` callbacks + - The core (state machine, matching, lifecycle) only knows the callback + table. A new feature adds a group of *optional* callbacks, exactly + like ``config_intr`` / ``handle_interrupt`` / ``read_page`` today. + Unimplemented callbacks fall back to genphy; appending callbacks at + the end of the struct keeps the ABI stable for existing drivers. + * - ``phy_ioctl()`` dispatch + - All MII/ethtool commands are offered to ``phy_ioctl()`` first by the + netdev upper-half, falling back to the MAC only on ``-ENOTTY``. A new + feature adds its ethtool command branch here, reached from user space + through the standard ethtool interface. + * - ``phy_read_mmd`` / ``phy_*_paged`` + interrupt path + - Feature registers usually live in MMD or vendor pages, reached with + the existing accessors — no new mechanism needed. Asynchronous events + (timestamp ready, wake) reuse ``config_intr`` / ``handle_interrupt``. + * - ``phydev->priv`` + - Per-chip state outside IEEE 802.3 (PTP clock context, WoL match + rules, ...) lives here without polluting the generic + ``phy_device_s``. + +Adding a PHY-side feature therefore means: define the optional callbacks, +dispatch the matching ethtool command in ``phy_ioctl()``, reach the +registers via MMD/paged accessors, deliver events through the interrupt +path, and keep private state in ``phydev->priv``. The framework core does +not change. + +14.2 Worked Example: Wake-on-LAN +-------------------------------- + +WoL is a PHY-side-only capability and closes the loop entirely with the +extension points above: + +- Add optional ``get_wol`` / ``set_wol`` callbacks to the vendor driver, + mapped to the ethtool WoL commands. (Those ethtool commands would be added + to the NuttX ethtool layer when first needed; NuttX does not define them + yet.) +- Store the wake / magic-packet match rules in ``phydev->priv``. +- Deliver the wake event through ``handle_interrupt``. + +14.3 Worked Example: PTP / Timestamping +--------------------------------------- + +Capability discovery is reported from a PHY-side callback that fills +``struct ethtool_ts_info`` and is returned via ``ETHTOOL_GET_TS_INFO`` +(PHC index and the supported ``SOF_TIMESTAMPING_*`` modes). + +Full PTP, however, is more than a PHY callback. Per-packet hardware +timestamping also requires the networking data plane: + +- Per-packet ``SO_TIMESTAMPING`` delivery to user space (currently + incomplete in NuttX — the flags are accepted but not yet honoured + individually). +- A ``SIOCSHWTSTAMP``-style configuration interface, which NuttX does not + provide yet. + +So PHYLIB contributes the capability-discovery callback and the PHY 1588 +register configuration (over MMD), while the data-plane timestamp path is a +larger, separately tracked work item outside the PHY abstraction. + +.. note:: + + Scope: these callbacks (WoL ``get_wol``/``set_wol``, PTP ``ts_info`` and + timestamp config) are the reserved extension path and are not implemented + in the current series, which provides the base framework, link management + and the Realtek PHY drivers. Adding them requires no change to existing + PHY drivers. + +15. Future Plans +================ + +.. list-table:: + :header-rows: 1 + :widths: 30 20 50 + + * - Feature + - Priority + - Notes + * - Fixup mechanism + - high + - Board-level code to correct PHY behavior without changing driver + source. + * - PHY Package + - medium + - Multi-port PHY chips sharing global configuration. + * - ethtool + - high + - More ethtool command support. + * - PTP / WoL / EEE + - medium + - PHY-side extended features via the extension points in Section 14. diff --git a/Documentation/os/networking/phylib_vendor_porting.rst b/Documentation/os/networking/phylib_vendor_porting.rst new file mode 100644 index 00000000000..f783e882565 --- /dev/null +++ b/Documentation/os/networking/phylib_vendor_porting.rst @@ -0,0 +1,1351 @@ +.. _phylib_vendor_porting: + +.. include:: /substitutions.rst + +========================================== +PHYLIB Vendor Porting Guide +========================================== + +This guide is for vendors implementing a native NuttX Ethernet lower-half. +It explains how to integrate the MDIO upper-half, the PHYLIB lifecycle and a +dedicated PHY model driver. A vendor must ultimately deliver two parts: the +**lower-half PHYLIB integration** and the **dedicated PHY driver**. + +1. Scope and Boundaries +======================= + +What the vendor must do: + +- Keep the MDIO/PHYLIB objects in the driver private struct. +- Implement ``struct mdio_ops_s``. +- Implement and register a dedicated ``struct phy_driver_s``. +- Hook the PHYLIB lifecycle into ifup/ifdown. +- Provide the PHY address, interface, reset and IRQ mode. +- Implement complete error rollback. + +Out of scope for this integration: + +- Network packet TX/RX algorithms. +- MAC DMA descriptor implementation. +- PTP, QoS and other data-plane TSN capabilities. +- Middleware-specific adaptation. + +2. Layering and Call Relationships +================================== + +.. note:: + + Responsibility boundary: the lower-half handles "how to access the PHY, + when to create/start/destroy it"; the dedicated PHY driver handles "how + this model initializes, negotiates, reads status and handles events"; + NuttX handles the state machine, driver matching, standard ioctl, + carrier and MDIO bus mutual exclusion. + +3. The Two Mandatory Vendor Modules +=================================== + +.. list-table:: + :header-rows: 1 + :widths: 25 40 35 + + * - Module + - Must implement + - Core responsibility + * - Ethernet lower-half integration + - ``mdio_lowerhalf_s``, ``mdio_bus_s *``, ``phy_device_s *``, + ``mdio_ops_s``, PHYLIB lifecycle + - Provide MDIO transport; create, connect, start and destroy the PHY. + * - Dedicated PHY model driver + - ``phy_driver_s``, identity fields, base callbacks, register API, + build items + - Implement the behavior of the new PHY model. + +3.1 Lower-half Interface Checklist +---------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 35 45 + + * - Category + - Interface + - Requirement + * - MDIO C22 + - ``mdio_ops_s.read/write`` + - **Mandatory**; return OK on success, negative errno on failure. + * - PHY reset + - ``mdio_ops_s.reset`` + - **Implement when a controllable reset line exists**; non-zero + asserts, zero deasserts. + * - Native C45 + - ``read_c45/write_c45`` + - **Implement when the hardware supports it**; otherwise C22 indirect + can be used. + * - PHY chip registration + - ``model_register()`` + - Must be before ``phy_device_create()`` and called only once at boot. + * - ifup + - ``mdio_register/reset/create/connect/start`` + - Establish and start PHYLIB. + * - ifdown + - ``phy_disconnect/mdio_unregister`` + - Stop events first, then free the PHY and the MDIO bus. + * - PHY event + - ``phy_interrupt()`` + - Used for ISR-safe notification when the vendor owns the event source. + +3.2 Dedicated PHY Driver Interface Checklist +-------------------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Type + - Vendor must provide + * - Identity + - ``name``, ``phy_id``, ``phy_id_mask`` + * - Base behavior + - ``config_init``, ``config_aneg``, ``read_status`` + * - By chip capability + - ``config_power``, ``config_intr``, ``handle_interrupt``, + ``read_page``, ``write_page`` + * - Registration + - ``<model>_register()`` and a public header declaration + * - Build + - Kconfig, CMakeLists.txt, Make.defs + * - Optional resources + - firmware/parameter files, ``phydev->priv`` teardown convention + +4. File Organization and Key Structures +======================================= + +.. code-block:: text + + vendor/<vendor>/.../<ethernet_lowerhalf>.c + |-- struct vendor_eth_dev_s + |-- vendor_mdio_read/write/reset + |-- g_vendor_mdio_ops + |-- vendor_phy_setup_once + |-- vendor_phylib_ifup + |-- vendor_phylib_ifdown + `-- vendor_phy_event + + nuttx/drivers/net/phy/<phy_vendor>/ + |-- <model>.c + |-- <model>.h + `-- <model>_fw.c/.h # as needed + + nuttx/include/nuttx/net/<phy_vendor>_phy.h + nuttx/drivers/net/Kconfig + nuttx/drivers/net/CMakeLists.txt + nuttx/drivers/net/Make.defs + +The lower-half private struct must at least add: + +.. code-block:: c + + struct vendor_eth_dev_s + { + struct netdev_lowerhalf_s dev; + + /* Existing Vendor Ethernet state ... */ + + #ifdef CONFIG_NET_PHYLIB + struct mdio_lowerhalf_s mdio_lower; + FAR struct mdio_bus_s *mdio; + FAR struct phy_device_s *phydev; + + struct work_s phy_event_work; /* optional, per event mode */ + uint8_t phy_addr; + enum phy_interface_e phy_interface; + int phy_irq; + bool phy_ready; + #endif + }; + +A successful ``phy_connect(phydev, &priv->dev)`` also sets +``priv->dev.phydev``, so the netdev upper-half dispatches standard PHY +ioctls to ``phy_ioctl()``. + +5. Implementing the MDIO Lower-half +=================================== + +5.1 Clause 22 Read/Write (mandatory) +------------------------------------ + +.. code-block:: c + + static int vendor_mdio_read(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t regaddr, + FAR uint16_t *value) + { + FAR struct vendor_eth_dev_s *priv = + container_of(lower, struct vendor_eth_dev_s, mdio_lower); + + return vendor_hw_mdio_read(priv, phyaddr, regaddr, value) == 0 + ? OK : -EIO; + } + + static int vendor_mdio_write(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t regaddr, + uint16_t value) + { + FAR struct vendor_eth_dev_s *priv = + container_of(lower, struct vendor_eth_dev_s, mdio_lower); + + return vendor_hw_mdio_write(priv, phyaddr, regaddr, value) == 0 + ? OK : -EIO; + } + +Interface contract: + +- ``read/write`` return ``OK`` on success, negative errno on failure. +- ``read`` returns the register value via ``uint16_t *value``. +- Must support a 5-bit PHY address and Clause 22 register addresses. +- The MDIO upper-half already holds the bus mutex before calling the + callback; the callback must not take that lock again. +- When the hardware API has no independent error code, the vendor must + define a reliable timeout / no-response check and must not + unconditionally return success. + +5.2 PHY Reset (when a controllable reset line exists) +----------------------------------------------------- + +.. code-block:: c + + static int vendor_mdio_reset(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, int value) + { + FAR struct vendor_eth_dev_s *priv = + container_of(lower, struct vendor_eth_dev_s, mdio_lower); + + if (value != 0) + { + vendor_hw_phy_reset(priv, phyaddr, true); + up_mdelay(VENDOR_PHY_RESET_ASSERT_MS); + } + else + { + vendor_hw_phy_reset(priv, phyaddr, false); + up_mdelay(VENDOR_PHY_RESET_SETTLE_MS); + } + + return OK; + } + +- ``value != 0``: assert reset. +- ``value == 0``: deassert reset. +- Reset polarity is handled inside the vendor callback. +- The wait after assert and deassert must come from the PHY datasheet. +- With no controllable reset line, leave ``.reset`` NULL; ``mdio_reset()`` + returns ``-ENOSYS``. + +5.3 Clause 45 (by hardware capability) +-------------------------------------- + +Implement when the hardware supports native Clause 45: + +.. code-block:: c + + static int vendor_mdio_read_c45(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t devad, + uint16_t regaddr, + FAR uint16_t *value); + + static int vendor_mdio_write_c45(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t devad, + uint16_t regaddr, uint16_t value); + +When no native C45 callback is provided, the NuttX MDIO upper-half can use +Clause 22 registers 13/14 for indirect MMD access. + +5.4 The ``mdio_ops_s`` Table +---------------------------- + +.. code-block:: c + + static const struct mdio_ops_s g_vendor_mdio_ops = + { + .read = vendor_mdio_read, + .write = vendor_mdio_write, + #ifdef CONFIG_MDIO_CLAUSE_45 + .read_c45 = vendor_mdio_read_c45, /* as needed */ + .write_c45 = vendor_mdio_write_c45, + #endif + .reset = vendor_mdio_reset, /* as needed */ + }; + +.. note:: + + An MDIO callback must not call an API that re-acquires the same bus + lock. When an atomic multi-transaction sequence is needed, use + ``mdio_lock()`` together with ``mdio_*_nolock()``. + +6. The Dedicated PHY Model Driver +================================= + +.. note:: + + For a new PHY needing dedicated init, status parsing, operating modes, + firmware, paged registers or interrupt handling, the dedicated PHY model + driver is the vendor's core deliverable. You must not integrate only the + MDIO lower-half and leave the model logic in the Ethernet lower-half. + +6.1 Define ``struct phy_driver_s`` +---------------------------------- + +.. code-block:: c + + static const struct phy_driver_s g_model_driver = + { + /* Identity fields: mandatory */ + .name = "Vendor MODEL", + .phy_id = MODEL_PHY_ID, + .phy_id_mask = MODEL_PHY_ID_MASK, + + /* Base behavior: mandatory by model capability */ + .config_init = model_config_init, + .config_aneg = model_config_aneg, + .read_status = model_read_status, + + /* Implement when the chip supports the capability */ + .config_power = model_config_power, + .config_intr = model_config_intr, + .handle_interrupt = model_handle_interrupt, + .read_page = model_read_page, + .write_page = model_write_page, + }; + +6.2 Identity Fields +------------------- + +.. list-table:: + :header-rows: 1 + :widths: 25 40 35 + + * - Field + - Vendor requirement + - Acceptance + * - ``name`` + - Provide a recognizable vendor and model name + - Boot log can identify the bound driver + * - ``phy_id`` + - Define the 32-bit ID from PHYID1/PHYID2 + - Matches the hardware-measured value + * - ``phy_id_mask`` + - Mask only bits allowed to vary (e.g. revision) + - Does not mismatch other models + +Match rule: + +.. code-block:: c + + (drv->phy_id & drv->phy_id_mask) == + (phydev->phy_id & drv->phy_id_mask) + +6.3 Base Callbacks +------------------ + +.. list-table:: + :header-rows: 1 + :widths: 22 22 38 18 + + * - API + - When called + - Behavior the vendor must implement + - Return + * - ``config_init(phydev)`` + - ``phy_connect()`` + - Check ready; soft reset, firmware/parameter load, interface/timing, + master/slave, operating mode; fill ``supported/advertising/autoneg`` + - OK or negative errno + * - ``config_aneg(phydev)`` + - ``phy_start()``, ethtool set/reset + - If auto-negotiation is supported, configure per ``advertising`` and + restart; otherwise set a fixed mode + - OK or negative errno + * - ``read_status(phydev)`` + - Polling or PHY event work + - Update ``link/speed/duplex``, update ``lp_advertising`` as needed + - OK on link down; negative errno only on access failure + +6.4 Capability-dependent Callbacks +---------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - PHY feature + - Must implement + - Key constraint + * - Power down/up + - ``config_power(phydev, enable)`` + - true powers up, false powers down + * - PHY INTB + - ``config_intr`` + ``handle_interrupt`` + - Decode and clear all interrupt sources in LPWORK + * - Vendor page + - ``read_page`` + ``write_page`` + - Must be implemented as a pair, using ``mdio_*_nolock()`` internally + * - Clause 45/MMD + - Use ``phy_*_mmd()`` in callbacks + - Do not call platform-private MDIO APIs + * - Firmware/parameter tables + - ``<model>_fw.c/.h`` + - Separate from driver logic, compiled under the same Kconfig + * - Cross-callback state + - ``phydev->priv`` + - PHYLIB does not auto-free it currently; define a teardown + +6.5 Register APIs the PHY Driver Uses +------------------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Access type + - API to use + * - Clause 22 ordinary registers + - ``phy_read``, ``phy_write``, ``phy_modify``, ``phy_set_bits``, + ``phy_clear_bits`` + * - Clause 45/MMD + - ``phy_read_mmd``, ``phy_write_mmd``, ``phy_modify_mmd`` + * - Vendor page + - ``phy_read_paged``, ``phy_write_paged``, ``phy_modify_paged`` + * - Inside page-select callbacks + - ``mdio_read_nolock``, ``mdio_write_nolock`` + +6.6 Registration API +-------------------- + +.. code-block:: c + + int model_register(void) + { + return phy_driver_register(&g_model_driver); + } + +Declared in the public header: + +.. code-block:: c + + #ifdef CONFIG_NET_PHY_VENDOR_MODEL + int model_register(void); + #endif + +.. warning:: + + Do not put PHY registers, firmware, status parsing, operating modes or + INTB source decoding in the Ethernet lower-half. Model logic must belong + to ``phy_driver_s``. + +7. One-time Hardware Prep and Driver Registration +================================================= + +After the Ethernet/MDIO controller is initialized, initialize the MDIO +hardware and register the dedicated PHY driver before the first +``phy_device_create()``. + +.. code-block:: c + + static int vendor_phy_setup_once(FAR struct vendor_eth_dev_s *priv) + { + int ret; + + ret = vendor_hw_mdio_initialize(priv); + if (ret < 0) + { + return ret; + } + + #ifdef CONFIG_NET_PHY_VENDOR_MODEL + ret = model_register(); + if (ret < 0) + { + return ret; + } + #endif + + return OK; + } + +Registration rules: + +#. Must be earlier than ``phy_device_create()``. +#. Executed only once at boot. +#. Must not be placed in the repeatedly executed ``ifup()``. +#. Must check the return value; do not create the PHY after a failure. +#. ``phy_driver_register()`` currently does not deduplicate; repeated + registration exhausts ``CONFIG_NET_PHYLIB_MAX_DRIVERS``. + +8. Integrating PHYLIB in the Lower-half ifup +============================================ + +Standard implementation order: + +.. code-block:: c + + static int vendor_phylib_ifup(FAR struct vendor_eth_dev_s *priv) + { + uint16_t bmsr; + int ret; + + priv->phy_ready = false; + priv->mdio_lower.ops = &g_vendor_mdio_ops; + + priv->mdio = mdio_register(&priv->mdio_lower); + if (priv->mdio == NULL) + { + return -ENOMEM; + } + + ret = mdio_reset(priv->mdio, priv->phy_addr, 1); + if (ret < 0 && ret != -ENOSYS) + { + goto err_mdio; + } + + ret = mdio_reset(priv->mdio, priv->phy_addr, 0); + if (ret < 0 && ret != -ENOSYS) + { + goto err_mdio; + } + + ret = mdio_read(priv->mdio, priv->phy_addr, MII_MSR, &bmsr); + if (ret < 0 || bmsr == 0xffff) + { + ret = -EIO; + goto err_mdio; + } + + priv->phydev = phy_device_create(priv->mdio, priv->phy_addr); + if (priv->phydev == NULL) + { + ret = -ENODEV; + goto err_mdio; + } + + priv->phydev->interface = priv->phy_interface; + + ret = phy_connect(priv->phydev, &priv->dev); + if (ret < 0) + { + phy_device_free(priv->phydev); + priv->phydev = NULL; + goto err_mdio; + } + + priv->phydev->irq = priv->phy_irq; /* use PHY_POLL for first bring-up */ + + ret = phy_start(priv->phydev); + if (ret < 0) + { + goto err_disconnect; + } + + priv->phy_ready = true; + return OK; + + err_disconnect: + phy_disconnect(priv->phydev); + priv->phydev = NULL; + err_mdio: + mdio_unregister(priv->mdio); + priv->mdio = NULL; + return ret; + } + +.. note:: + + First integration should use ``PHY_POLL``. Verify MDIO, the dedicated + driver, init, auto-negotiation and status reads first, then add PHY + interrupts. + +9. Standard ifdown, Teardown and Failure Rollback +================================================= + +This guide mandates one standard flow: each ``ifup`` creates and starts the +MDIO/PHY objects, and each ``ifdown`` fully destroys them. + +.. code-block:: c + + static void vendor_phylib_ifdown(FAR struct vendor_eth_dev_s *priv) + { + priv->phy_ready = false; + + /* No callback/work may access phydev after this. */ + + vendor_phy_event_disable(priv); + work_cancel_sync(LPWORK, &priv->phy_event_work); + + if (priv->phydev != NULL) + { + /* phy_disconnect() already calls phy_stop() internally. */ + phy_disconnect(priv->phydev); + priv->phydev = NULL; + } + + if (priv->mdio != NULL) + { + mdio_unregister(priv->mdio); + priv->mdio = NULL; + } + } + +.. note:: + + You need not call ``phy_stop()`` explicitly first: ``phy_disconnect()`` + already stops the PHY, disables PHY interrupts and synchronously cancels + the PHYLIB state work. Calling stop before disconnect is redundant. + +9.1 Failure Rollback Table +-------------------------- + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Failure point + - Must roll back + * - ``mdio_register`` failed + - No bus; return directly + * - reset/probe/create failed + - ``mdio_unregister`` + * - create ok, connect failed + - ``phy_device_free`` -> ``mdio_unregister`` + * - connect ok, start failed + - ``phy_disconnect`` -> ``mdio_unregister`` + * - Vendor event/work already started + - Disable the event source, then ``work_cancel_sync``, then free the PHY + +.. warning:: + + Do not unregister the MDIO bus first. ``phy_disconnect()`` may still use + that bus to perform stop, power and reset operations. + +10. PHY Link Events and Interrupt Modes +======================================= + +.. list-table:: + :header-rows: 1 + :widths: 25 30 45 + + * - ``phydev->irq`` + - Mode + - What the vendor lower-half does + * - ``PHY_POLL (-1)`` + - No interrupt / first bring-up + - Provide no event ISR; PHYLIB calls ``read_status()`` periodically + * - ``PHY_MAC_INTERRUPT (-2)`` + - Vendor owns the GPIO/ICU/controller event source + - The ISR/callout only records the event and calls ``phy_interrupt()`` + * - ``>= 0`` + - A real IRQ attachable by NuttX ``irq_attach()`` + - Fill in the real IRQ; PHYLIB attaches/detaches the ISR + +10.1 Vendor Owns the Event Source +--------------------------------- + +.. code-block:: c + + static void vendor_phy_event(FAR struct vendor_eth_dev_s *priv) + { + if (priv->phy_ready && priv->phydev != NULL) + { + phy_interrupt(priv->phydev); + } + } + +``phy_interrupt()`` only posts state-machine work and may be called from +interrupt context; the real MDIO access happens in LPWORK. + +10.2 Interrupt Callbacks of the PHY Model Driver +------------------------------------------------ + +.. code-block:: c + + static int model_config_intr(FAR struct phy_device_s *phydev, + bool enable); + + static int model_handle_interrupt(FAR struct phy_device_s *phydev); + +``handle_interrupt()`` return values: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Return + - Meaning + * - ``> 0`` + - A link-related event occurred; PHYLIB continues to call ``read_status()`` + * - ``0`` + - No link-related event; keep the current link state + * - ``< 0`` + - MDIO/HW failure; PHYLIB enters ``PHY_ERROR`` + +.. warning:: + + Calling ``mdio_read/write`` in a hard IRQ is forbidden. If INTB is + level-triggered, ``handle_interrupt()`` must read and clear all active + PHY interrupt sources before returning, otherwise it causes an interrupt + storm. + +11. ioctl and Carrier +===================== + +``phy_connect()`` associates the PHY device with +``netdev_lowerhalf_s.phydev``. The NuttX netdev upper-half then calls first: + +.. code-block:: c + + if (lower->phydev != NULL) + { + ret = phy_ioctl(lower->phydev, cmd, arg); + if (ret != -ENOTTY) + { + return ret; + } + } + +PHYLIB already handles: + +- ``SIOCGMIIPHY`` +- ``SIOCGMIIREG`` +- ``SIOCSMIIREG`` +- ``ETHTOOL_GLINKSETTINGS`` +- ``ETHTOOL_SLINKSETTINGS`` +- ``ETHTOOL_NWAY_RST`` +- ``ETHTOOL_GLINK`` + +Therefore: + +- The vendor lower-half usually should not re-handle the standard MII + ioctls. +- Only private commands for which PHYLIB returns ``-ENOTTY`` continue to + the lower-half. +- The PHYLIB state machine calls ``netdev_lower_carrier_on/off()`` on link + change. +- The vendor should not run another standard link-polling loop or + repeatedly modify ``phydev->link`` or the carrier. + +12. Kconfig and Build Integration +================================== + +12.1 Base Configuration +----------------------- + +.. code-block:: kconfig + + CONFIG_NET=y + CONFIG_NETDEVICES=y + CONFIG_MDIO_BUS=y + CONFIG_NET_PHYLIB=y + CONFIG_NET_PHYLIB_POLL_INTERVAL=1000 + +``NET_PHYLIB`` currently depends on but does not auto-select +``MDIO_BUS``. Enable Clause 45/MMD as needed: + +.. code-block:: kconfig + + CONFIG_MDIO_CLAUSE_45=y + +12.2 Dedicated PHY Model Kconfig +-------------------------------- + +.. code-block:: kconfig + + config NET_PHY_VENDOR_MODEL + bool "Vendor MODEL Ethernet PHY" + default n + depends on NET_PHYLIB + ---help--- + Enable support for the Vendor MODEL Ethernet PHY. + +12.3 CMakeLists.txt +------------------- + +.. code-block:: cmake + + if(CONFIG_NET_PHY_VENDOR_MODEL) + list(APPEND SRCS phy/<phy_vendor>/<model>.c) + + # When the model needs firmware/parameter objects: + # list(APPEND SRCS phy/<phy_vendor>/<model>_fw.c) + endif() + +12.4 Make.defs +-------------- + +.. code-block:: makefile + + ifeq ($(CONFIG_NET_PHY_VENDOR_MODEL),y) + CSRCS += <phy_vendor>/<model>.c + # CSRCS += <phy_vendor>/<model>_fw.c + endif + +13. Vendor From-scratch SOP +=========================== + +#. **Confirm the lower-half**: the private struct has + ``netdev_lowerhalf_s``, and ifup/ifdown can integrate PHYLIB. +#. **Prepare MDIO hardware**: init pins, clock and controller; verify you + can read BMSR and PHYID1/PHYID2. +#. **Embed the three objects**: ``mdio_lower``, ``mdio``, ``phydev``. +#. **Implement mdio_ops_s**: C22 read/write mandatory; reset/C45 as the + hardware provides. +#. **Implement the dedicated PHY driver**: define ``phy_driver_s``, + implement identity fields, init/aneg/status and applicable advanced + callbacks. +#. **Add registration and build**: provide the public registration + declaration; edit Kconfig, CMakeLists.txt, Make.defs. +#. **Register once**: call ``model_register()`` before + ``phy_device_create()``, only once at boot. +#. **Hook ifup**: register -> reset -> probe -> create -> interface -> + connect -> IRQ -> start. +#. **Hook ifdown**: stop event/work -> disconnect -> unregister. +#. **Remove duplicate management**: leave standard MII ioctl, link polling + and carrier to PHYLIB. +#. **Polling first, interrupt later**: validate init/aneg/status first, + then the interrupt callbacks. + +14. Two Ready-to-adapt Templates +================================ + +.. note:: + + In the templates, ``vendor_hw_*``, the PHY address, interface, IRQ and + register macros are the vendor porting points. After replacing these + hardware hooks, add C45, page, INTB, power and firmware per the actual + chip capability. + +14.1 Vendor Ethernet Lower-half PHYLIB Template +----------------------------------------------- + +.. code-block:: c + + #include <nuttx/config.h> + + #include <errno.h> + #include <nuttx/arch.h> + #include <nuttx/net/mdio.h> + #include <nuttx/net/mii.h> + #include <nuttx/net/netdev_lowerhalf.h> + #include <nuttx/net/phy.h> + #include <nuttx/net/<phy_vendor>_phy.h> + #include <nuttx/wqueue.h> + + struct vendor_eth_dev_s + { + struct netdev_lowerhalf_s dev; + + /* Existing Vendor Ethernet state ... */ + + #ifdef CONFIG_NET_PHYLIB + struct mdio_lowerhalf_s mdio_lower; + FAR struct mdio_bus_s *mdio; + FAR struct phy_device_s *phydev; + struct work_s phy_event_work; + uint8_t phy_addr; + enum phy_interface_e phy_interface; + int phy_irq; + bool phy_ready; + #endif + }; + + static int vendor_mdio_read(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t regaddr, + FAR uint16_t *value) + { + FAR struct vendor_eth_dev_s *priv = + container_of(lower, struct vendor_eth_dev_s, mdio_lower); + + return vendor_hw_mdio_read(priv, phyaddr, regaddr, value) == 0 + ? OK : -EIO; + } + + static int vendor_mdio_write(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, uint8_t regaddr, + uint16_t value) + { + FAR struct vendor_eth_dev_s *priv = + container_of(lower, struct vendor_eth_dev_s, mdio_lower); + + return vendor_hw_mdio_write(priv, phyaddr, regaddr, value) == 0 + ? OK : -EIO; + } + + static int vendor_mdio_reset(FAR struct mdio_lowerhalf_s *lower, + uint8_t phyaddr, int value) + { + FAR struct vendor_eth_dev_s *priv = + container_of(lower, struct vendor_eth_dev_s, mdio_lower); + + if (value != 0) + { + vendor_hw_phy_reset(priv, phyaddr, true); + up_mdelay(VENDOR_PHY_RESET_ASSERT_MS); + } + else + { + vendor_hw_phy_reset(priv, phyaddr, false); + up_mdelay(VENDOR_PHY_RESET_SETTLE_MS); + } + + return OK; + } + + static const struct mdio_ops_s g_vendor_mdio_ops = + { + .read = vendor_mdio_read, + .write = vendor_mdio_write, + .reset = vendor_mdio_reset, + }; + + static int vendor_phy_setup_once(FAR struct vendor_eth_dev_s *priv) + { + int ret; + + ret = vendor_hw_mdio_initialize(priv); + if (ret < 0) + { + return ret; + } + + #ifdef CONFIG_NET_PHY_VENDOR_MODEL + ret = model_register(); + if (ret < 0) + { + return ret; + } + #endif + + return OK; + } + + static int vendor_phylib_ifup(FAR struct vendor_eth_dev_s *priv) + { + uint16_t bmsr; + int ret; + + priv->phy_ready = false; + priv->mdio_lower.ops = &g_vendor_mdio_ops; + + priv->mdio = mdio_register(&priv->mdio_lower); + if (priv->mdio == NULL) + { + return -ENOMEM; + } + + ret = mdio_reset(priv->mdio, priv->phy_addr, 1); + if (ret < 0 && ret != -ENOSYS) + { + goto err_mdio; + } + + ret = mdio_reset(priv->mdio, priv->phy_addr, 0); + if (ret < 0 && ret != -ENOSYS) + { + goto err_mdio; + } + + ret = mdio_read(priv->mdio, priv->phy_addr, MII_MSR, &bmsr); + if (ret < 0 || bmsr == 0xffff) + { + ret = -EIO; + goto err_mdio; + } + + priv->phydev = phy_device_create(priv->mdio, priv->phy_addr); + if (priv->phydev == NULL) + { + ret = -ENODEV; + goto err_mdio; + } + + priv->phydev->interface = priv->phy_interface; + + ret = phy_connect(priv->phydev, &priv->dev); + if (ret < 0) + { + phy_device_free(priv->phydev); + priv->phydev = NULL; + goto err_mdio; + } + + priv->phydev->irq = priv->phy_irq; + ret = phy_start(priv->phydev); + if (ret < 0) + { + goto err_disconnect; + } + + priv->phy_ready = true; + return OK; + + err_disconnect: + phy_disconnect(priv->phydev); + priv->phydev = NULL; + err_mdio: + mdio_unregister(priv->mdio); + priv->mdio = NULL; + return ret; + } + + static void vendor_phylib_ifdown(FAR struct vendor_eth_dev_s *priv) + { + priv->phy_ready = false; + vendor_phy_event_disable(priv); + work_cancel_sync(LPWORK, &priv->phy_event_work); + + if (priv->phydev != NULL) + { + phy_disconnect(priv->phydev); + priv->phydev = NULL; + } + + if (priv->mdio != NULL) + { + mdio_unregister(priv->mdio); + priv->mdio = NULL; + } + } + + static void vendor_phy_event(FAR struct vendor_eth_dev_s *priv) + { + if (priv->phy_ready && priv->phydev != NULL) + { + phy_interrupt(priv->phydev); + } + } + +14.2 Dedicated PHY Model Driver Template +---------------------------------------- + +.. code-block:: c + + /* drivers/net/phy/<phy_vendor>/<model>.c */ + #include <nuttx/config.h> + + #include <errno.h> + #include <nuttx/ethtool.h> + #include <nuttx/net/mii.h> + #include <nuttx/net/phy.h> + #include <nuttx/net/<phy_vendor>_phy.h> + + #include "phy.h" + #include "<model>.h" + + static int model_config_init(FAR struct phy_device_s *phydev); + static int model_config_aneg(FAR struct phy_device_s *phydev); + static int model_read_status(FAR struct phy_device_s *phydev); + + static const struct phy_driver_s g_model_driver = + { + .name = "Vendor MODEL", + .phy_id = MODEL_PHY_ID, + .phy_id_mask = MODEL_PHY_ID_MASK, + .config_init = model_config_init, + .config_aneg = model_config_aneg, + .read_status = model_read_status, + }; + + static int model_config_init(FAR struct phy_device_s *phydev) + { + int ret; + + ret = model_soft_reset(phydev); /* implement per datasheet */ + if (ret < 0) + { + return ret; + } + + phydev->supported = SUPPORTED_10BASET_FULL | + SUPPORTED_100BASET_FULL | + SUPPORTED_AUTONEG | + SUPPORTED_TP | + SUPPORTED_MII; + phydev->advertising = phydev->supported; + phydev->autoneg = true; + return OK; + } + + static int model_config_aneg(FAR struct phy_device_s *phydev) + { + uint16_t adv = MII_ADVERTISE_CSMA; + int ret; + + if (phydev->advertising & SUPPORTED_10BASET_FULL) + { + adv |= MII_ADVERTISE_10BASETXFULL; + } + + if (phydev->advertising & SUPPORTED_100BASET_FULL) + { + adv |= MII_ADVERTISE_100BASETXFULL; + } + + ret = phy_write(phydev, MII_ADVERTISE, adv); + if (ret < 0) + { + return ret; + } + + return phy_modify(phydev, MII_MCR, + MII_MCR_ANENABLE | MII_MCR_ANRESTART, + MII_MCR_ANENABLE | MII_MCR_ANRESTART); + } + + static int model_read_status(FAR struct phy_device_s *phydev) + { + int status; + + status = phy_read(phydev, MODEL_STATUS_REG); + if (status < 0 || status == 0xffff) + { + return -EIO; + } + + /* Read twice only when the status bit is latch-low. */ + status = phy_read(phydev, MODEL_STATUS_REG); + if (status < 0 || status == 0xffff) + { + return -EIO; + } + + phydev->link = (status & MODEL_STATUS_LINK) != 0; + if (!phydev->link) + { + phydev->speed = 0; + phydev->duplex = DUPLEX_UNKNOWN; + return OK; + } + + return model_decode_speed_duplex(phydev, (uint16_t)status); + } + + int model_register(void) + { + return phy_driver_register(&g_model_driver); + } + +If the chip needs power, INTB, page, MMD or firmware, add the corresponding +callbacks from the Section 6 decision tables to ``g_model_driver``; do not +move that model logic back to the lower-half. + +15. Mechanized Delivery Checklist (Two Patches) +=============================================== + +15.1 Patch 1: Dedicated PHY Model Driver +---------------------------------------- + +.. code-block:: text + + A drivers/net/phy/<phy_vendor>/<model>.c + A drivers/net/phy/<phy_vendor>/<model>.h + A include/nuttx/net/<phy_vendor>_phy.h + A drivers/net/phy/<phy_vendor>/<model>_fw.c/.h # as needed + M drivers/net/Kconfig + M drivers/net/CMakeLists.txt + M drivers/net/Make.defs + +Checklist: + +- ``phy_driver_s`` identity fields and callbacks complete. +- All registers, bits and timing have a datasheet basis. +- ``model_register()`` has a public declaration. +- Firmware has source, version and license notes. +- Standalone testing of the dedicated driver is done. + +15.2 Patch 2: Vendor Ethernet Lower-half PHYLIB Integration +----------------------------------------------------------- + +.. code-block:: text + + M <vendor Ethernet lower-half>.c + M <vendor Ethernet config/header> + M <board/project defconfig> + +Checklist: + +- The private struct contains the three PHYLIB/MDIO members. +- ``mdio_ops_s`` read/write/reset/C45 implemented by capability. +- ``model_register()`` has a one-time call site. +- ifup creates and starts in the standard order. +- ifdown stops events and destroys in the standard order. +- PHY event delivery is correct. +- Every failure point rolls back symmetrically. + +.. note:: + + Patch 1 is a PHY model driver reusable across Ethernet controllers; + Patch 2 contains only this vendor lower-half's MDIO transport, PHYLIB + lifecycle and board-level inputs. + +16. Reference Implementation Mapping +==================================== + +.. note:: + + The reference implementation confirms how the interfaces land. Reuse + only the NuttX PHYLIB pattern; do not copy platform registers, GPIO, + interrupt controllers, cross-core sync, DFX, recovery strategies or + another PHY's registers/firmware. + +Native NuttX Ethernet lower-half reference: +``vendor/infineon/chips/aurix/ethernet/aurix_leth.c`` + +.. list-table:: + :header-rows: 1 + :widths: 30 35 35 + + * - Reference code + - Generic requirement + - New vendor driver should implement + * - ``struct aurix_leth_dev_s`` + - Hold PHYLIB objects in the netdev private state + - ``mdio_lowerhalf_s``, ``mdio_bus_s *``, ``phy_device_s *``, event work + as needed + * - ``phylib_mdio_read/write`` + - Clause 22 MDIO lower-half + - Recover the instance with ``container_of``, forward to hardware, + return OK/negative errno + * - ``phylib_mdio_reset`` + - PHY reset level callback + - Non-zero asserts, zero deasserts; timing from the datasheet + * - ``g_phylib_mdio_ops`` + - MDIO lower-half vtable + - C22 mandatory; reset/C45 by capability + * - ``aurix_phy_setup`` + - One-time hardware prep and model registration + - Init the MDIO controller, then ``model_register()`` once + * - ``aurix_phylib_ifup`` + - PHYLIB establish and start + - register -> reset -> probe -> create -> connect -> IRQ -> start + * - ``aurix_leth_ifdown`` + - PHYLIB stop and destroy + - Stop event/work first, then disconnect -> unregister + * - ``phy_intb_callout`` + - Platform owns the PHY event source + - Latch/defer only, finally call ``phy_interrupt()`` + +Reference notes: + +#. ``phy_disconnect()`` already runs ``phy_stop()``; the generic template + does not repeat it. +#. ``model_register()`` and ``mdio_reset()`` must check return values. +#. Standard MII ioctl is already forwarded to ``phy_ioctl()`` by the netdev + upper-half; the lower-half should not re-implement it. +#. A platform link worker must not bypass PHYLIB to modify ``phydev->link`` + directly. +#. GPIO, ICU, middleware, cross-core shared memory, platform-specific + recovery and diagnostics are not generic requirements. + +Dedicated PHY model driver reference: +``drivers/net/phy/realtek/rtl9000b.c`` + +The in-tree RTL9000B driver (an automotive 100BASE-T1 PHY) is a complete +example of a dedicated PHY model driver: + +- A complete ``phy_driver_s`` covering ``config_init`` / ``config_aneg`` / + ``read_status`` / ``config_power`` / ``config_intr`` / + ``handle_interrupt`` / ``read_page`` / ``write_page``. +- ``config_init`` does the ready check, parameter write/verify, voltage + config, soft reset, operating-mode selection and capability publication. +- ``read_status`` updates ``link``/``speed``/``duplex`` and returns OK on a + normal link down. +- ``handle_interrupt`` decodes link / under-voltage / over-temperature and + recovery events and reports whether the link must be re-read. +- ``rtl9000b_register()`` wraps ``phy_driver_register(&g_rtl9000b_driver)``. +- The chip parameter tables live in a separate firmware file + (``rtl9000b_fw.c``), compiled conditionally by Kconfig. + +17. Acceptance Gate +=================== + +Lower-half integration: + +- Contains ``mdio_lower/mdio/phydev``. +- MDIO callbacks return OK/negative errno. +- ifup lifecycle order is correct. +- Every failure point releases resources symmetrically. +- ifdown stops events and work first. +- Disconnect happens before unregistering the bus. +- Standard MII ioctl is not re-implemented. + +Dedicated PHY driver: + +- ``phy_driver_s`` identity fields complete. +- ID/mask matches only the target model. +- ``config_init`` completes all model initialization. +- ``config_aneg`` matches the product mode. +- ``read_status`` correctly updates the three status items. +- Applicable power/interrupt/page callbacks implemented. +- Register declaration and the three build entries complete. +- No model logic remains in the lower-half. + +Joint function and stability: + +- Boot binds the dedicated driver, not the generic PHY. +- Carrier off with no cable. +- Carrier on after plugging; speed/duplex correct. +- Unplug and re-plug work correctly. +- 100 ifup/ifdown cycles. +- MII ioctl and ethtool work. +- No worker/IRQ/UAF/MDIO bus leaks. +- No storm or missed events in interrupt mode. + +18. Common Mistakes +=================== + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Symptom + - Cause and fix + * - PHY ID is ``0xffff/0x0000`` + - Check the MDIO controller, address, reset, clock and pins first + * - Matches the generic PHY + - Model not registered, registered too late, not compiled, or wrong + ID/mask + * - ``-ENOMEM`` after repeated registration + - ``model_register()`` placed in the repeated ifup; move it to the + one-time setup + * - Leak after connect failure + - Missing ``phy_device_free()`` + * - ifdown / UAF + - Event source not disabled or work not synchronously cancelled before + freeing the PHY + * - Paged access deadlock + - Page callback wrongly uses the locking ``mdio_read/write``; use + ``_nolock`` + * - Standard MII ioctl re-implemented + - Should be forwarded to ``phy_ioctl()`` by the netdev upper-half + * - Interrupt storm + - ``handle_interrupt()`` did not clear the PHY internal level source + * - PHY state correct but no data + - Keep checking the Ethernet data plane and controller config; do not + blame PHYLIB directly + +19. Current Source References +============================= + +.. code-block:: text + + nuttx/include/nuttx/net/netdev_lowerhalf.h + nuttx/include/nuttx/net/mdio.h + nuttx/include/nuttx/net/phy.h + nuttx/drivers/net/mdio.c + nuttx/drivers/net/phy/phy.h + nuttx/drivers/net/phy/phy_device.c + nuttx/drivers/net/phy/phy_core.c + nuttx/drivers/net/phy/phy_access.c + nuttx/drivers/net/phy/phy_gen.c + nuttx/drivers/net/phy/phy_genc45.c + nuttx/drivers/net/Kconfig + nuttx/drivers/net/CMakeLists.txt + nuttx/drivers/net/Make.defs
