SPRADS2 August   2025 DRA821U , TDA4VH-Q1 , TDA4VM , TDA4VM-Q1

 

  1.   1
  2.   2
  3.   Trademarks

Introduction

The Ethernet Firmware debug guide provides a structured approach for troubleshooting Ethernet Firmware issues during integration with custom boards and enabling custom configurations. This outlines key debugging steps, configurations checks, and diagnostics procedures to make sure of seamless working of network functionality.

Debugging Approach

Check Debug Logs

  • Analyze Ethernet Firmware debug logs if any error messages and assertions.

See the following failure logs from Ethernet firmware (ETHFW) corresponding to various errors.

Case 1: Mismatch of CPSW MAC port interface configured and the interface selected in CTRL MMR register corresponding to the MAC port.

ETHFW Log:
CpswMacPort_open: MAC 5: MII mismatch with SoC setting
EnetMod_open: cpsw9g.macport5: Failed to open: -3

Fix: Make sure the interface of the Ethernet port is selected from the board specifically and is the same as the configuration of the port.

Case 2: SerDes PLL lock failure. 

ETHFW Log:
CpswMacPort_setSgmiiInterface: MAC 8: SERDES PLL is not locked 
CpswMacPort_setSgmiiInterface
 Assertion at Line: 2287 in src/mod/cpsw_macport.c: false

Fix: Make sure the Ethernet Port configured with Serial Interface is the same as the SerDes Instance, Lane selected (IP instance) from the SerDes configuration.

Case 3: gPTP Sync Failure

ETHFW Log:
 Cpsw_ioctl: No PHY for MAC port 1
-1
ERR:cbase:Failed to get link info: -1
ERR:cbase:cbl_query_response:failed to get speed and duplex : tilld1
 INF:cbase:cbl_query_response:tilld1: link UP, speed=0, duplex=0 !!!!

Fix: Make Sure the CPSW MAC Port is mapped to gPTP has a valid link. If using a MAC 2 MAC connection, integrate the patch shared in the link.

Case 4: Failure to open PHY 

ETHFW Log:
Cpsw_openPortLinkWithPhy: Port 8 : Failed to open PHY.

Fix: Make sure the PHY driver is added to ENET as per the PHY Integration Guide from the TI PDK API Guide and MDIO mode configuration.

Note: If the user is unable to solve the error observed from the ETHFW debug log, search in the TI E2E forum. If any issues related to the error observed were already discussed, apply the workaround or fix suggested in the forum. If there is no relevant fix, create a new thread in the E2E forum to ask for help from TI

Configuration Validation

  • Make sure the PAD setting for RGMII/RMII (mux selection) matches the configuration. See the Sysconfig tool to confirm the pins used.
  • Confirm SerDes Lanes for Serial interfaces (SGMII/QSGMII/USXGMII/XAUI/XFI) from SERDES_LN_CTRL registers.
  • Validate the CPSW Ports and gPTP Ports listed in the Ethernet Firmware application as per the requirements or not.
  • Check static VLAN and MAC (shared/reserved) configurations with proper masking (MAC Ports, Virtual Ports).
  • Make sure the MAC Port and PHY configurations align with the system connectivity, MAC ports enabled, and PHY Address/Invalid PHY (for MAC to MAC), speed, duplexity.
  • Verify Link and Auto-negotiation configuration through control registers.
    • SGMII control (SGMII/XAUI)
    • Advertise Ability
  • Confirm ALE and classifier settings match with network expectations.
  • Confirm SerDes configuration(lane mapping, SerDes clock).
    • SerDes clock of 100MHz for SGMII/QSGMII, 156.25MHz for XAUI/USXGMII/XFI
    • When multi-link is required, make sure the proper clock is enabled from the SerDes reference clock and reference1 clock, and PLL mapping.
  • Make sure PHY supports in-band signaling for 10Mbps Link speed support, if not communication does not function well.

Interface Verification

  • Validate Port interface selection (RGMII/RMII/SGMII/QSGMII/USXGMII/XAUI/XFI) from the ENET_CTRL registers.
  • Check the RGMII delay selection for CPSW ports from the ENET_CTRL registers.
  • Make sure the SerDes instance is configured to align with connectivity.
  • Make sure PHY details under the MAC port configuration aligns with connectivity.
  • Verify PLL selection for SerDes Lanes via SERDES_CLK_CTRL registers.
  • Confirm PLL locks status, IP selection, and clock mapping in SerDes registers.
  • Verify Link/Auto-negotiation status from status registers of RMGII/SGMII/XGMII.

Data Path Verification

  • Validate CRC correctness and debug CPSW error statistics with the HW team.
  • Check ALE counters against expected statistics as per the configuration.
  • Monitor Tx/Rx statistics for Host and External ports.
    • Host Port Rx incremental is equivalent to External Port Tx (if ALE is configured).
    • External Port Rx incremental is equivalent to Host Port Tx (if ALE is configured to forward the packet to Host Port).

ALE and Classifiers

  • Verify unicast MAC ALE entries for packet forwarding to the port number specified.
  • Confirm Multicast and Broadcast ALE Port Masks (0th bit is Host Port, bit-1 onwards represents external ports).
  • Make sure that VLAN ALE entries with member list, registered multicast, unregistered multicast, and untagged egress are configured as required.
  • Align ALE and classifier settings with expected network behavior.

PHY Debugging

  • Make sure PHY is out of reset.
  • Confirm PHY driver integration as per the Integration guide specified in the PDK API Manual.
  • Read PHY registers for Link/Auto-negotiation related information.
  • Check the Tx/Rx statistics of the PHY, if available.
  • Validate PHY configuration and status against the PHY vendor.

Basic register set to be checked while debugging the any networking issue as per configuration.

Registers related to CPSW port specific configuration, link control, and status

CTRLMMR Registers

Table 1 CTRLMMR Registers Related to ENET MAC Ports
Register Name Address Description
CTRL_MMR_ENETx_CTRL 0x00104044 + (x × 0x4) For checking the functional mode selected for CPSW MAC Port x
x: CPSW MAC Port number (0 to 7)
Check whether RGMII delay is enabled or not from the MAC in case of the RGMII interface.

See the How to configure RGMII clock delay on J7 devices for RGMII delay-related configuration.

Link Specific Registers

Table 2 CPSW Port Link Control and Status Registers
Register Name Offset Address Description
SGMII CTRL 0x110 + (x × 0x100) Configuration register for Master Mode and Auto-negotiation corresponding to CPSW MAC Port x
x : CPSW MAC Port number (0 to 7)
SGMII STATUS 0x114 + (x × 0x100) Status register indicates Link status, SerDes PLL lock status corresponding to CPSW MAC Port x
x: CPSW MAC Port number (0 to 7)
SGMII Advertise Ability 0x118 + (x × 0x100) SGMII Advertise ability to set speed mode, Duplexity, and Link status corresponding to CPSW MAC Port x
x: CPSW MAC Port number (0 to 7)
RGMII STATUS 0x30 + (x × 0x4) Status register indicates Link speed, Duplexity, and Link status corresponding to CPSW MAC Port x
x: CPSW MAC Port number (0 to 7)
XGMII Link Register 0x74 XGMII Link status of XGMII-enabled Ports.
Bit 0: CPSW MAC Port-1
Bit 1: CPSW MAC Port-2.
CPSW MAC CTRL 0x22330 + (x × 0x1000) MAC control register holds the Speed, Duplex Mode, GMII/XGMII Enable, and mode of CPSW MAC Port x
x: CPSW MAC Port number (0 to 7)

Refer to the CPSW register specifications for more register details related to ALE, CPSW Statistics, and control registers

Registers related to SerDes clock selection, lane mapping and configuration.

SerDes CTRLMMR Registers

Table 3 CTRLMMR Registers Related to SerDes
Register Name Address Description
CTRL_MMR_SERDESx_LNy_CTRL 0x00104080 + (x × 0x10) + (y × 0x04) For checking the functional mode selected for SerDesx Laney
x: SerDes Instance
y: SerDes lane number
CTRL_MMR_SERDESx_CLKSEL 0x00108400 + (x × 0x10) For checking the clock source selected for the SerDesx core_refclk input
x: SerDes Instance MAIN_PLL3_HSDIV4_CLKOUT/ MAIN_PLL2_HSDIV4_CLKOUT is preferable.
CTRL_MMR_SERDESx_CLK1SEL 0x00108404 + (x × 0x10) -For checking the clock source selected for the SerDesx core_refclk1input
x: SerDes Instance MAIN_PLL3_HSDIV4_CLKOUT/ MAIN_PLL2_HSDIV4_CLKOUT is preferable.

SerDes Configuration Registers

Table 4 SerDes Lane Configuration and PLL Mapping Registers
Register Name Offset Address Description
SERDES_TOP_CTRL 0x408 Clock mode configuration
SERDES_RST 0x40C Reference clock selection
LANECTLx 0x480 + (x × 0x40) Lanex configuration
x: SerDes lane number
LANESTSx 0x48C + (x × 0x40) Lanex state
x: SerDes lane number
PHY_PMA_CMN_REGISTER 0xE000 PLL lock status

Registers related to CPSW port specific configuration, link control, and link status

Note: Add the base address of SerDes to the above Offset Address to access registers as SerDes base address + Offset Address above
See the TRM of the SoC to get the Base address of the SerDes instance.

Conclusion

This guide serves as a comprehensive resource for Ethernet Firmware troubleshooting, making sure of smooth custom board integration, configuration management, and SDK migrations. Follow these systematic checks to efficiently diagnose and resolve Ethernet-related issues.

References