Diagnostic APIs are crucial for bring-up and field failures (see this series' bring-up post). Fact-checking against the real SWS reveals a surprise here that corrects the original plan ("switched at the switch level instead of the PHY level").

Most of the EthSwt diagnostic APIs presented here are, per the SWS, pure forwarders to the corresponding EthTrcv_* function of the referenced transceiver instance — not a standalone switch implementation. That makes sense content-wise: cable diagnostics, loopback and signal quality are PHY-layer concepts that EthSwt merely makes addressable, rather than reimplementing itself.

The forwarding APIs at a glance

EthSwt APIForwards to

EthSwt_RunPortCableDiagnostic

EthTrcv_RunCableDiagnostic (asynchronous, reentrant per switch/port combination)

EthSwt_GetPortCableDiagnosticsResult

EthTrcv_GetCableDiagnosticsResult

EthSwt_SetPortTestMode

EthTrcv_SetPhyTestMode

EthSwt_SetPortLoopbackMode

EthTrcv_SetPhyLoopbackMode

EthSwt_SetPortTxMode

EthTrcv_SetPhyTxMode

EthSwt_GetPortSignalQuality

EthTrcv_GetPhySignalQuality

Each of these functions uses the EthIf driver abstraction to pass the call through to the EthTrcv instance referenced via EthSwtPortTrcvRef (see Part 3 of this series).

Practical consequence: if an EthSwtPort references no EthTrcv (e.g. because the PHY is fully internal to the switch, see the hardware architecture post), these APIs return E_NOT_OK accordingly — or, in the case of EthSwt_GetPortSignalQuality, the sentinel value 0xFFFFFFFF.

EthSwt_GetPortIdentifier: a clever detail

This function returns the port’s OUI (Organizationally Unique Identifier, 24 bits) — with a notable encoding rule:

  • If the OUI can be obtained from the referenced EthTrcv via EthTrcv_GetPhyIdentifier, EthSwt_GetPortIdentifier sets the 8 most significant bits to 0x00xxxxxx

  • If it can’t be obtained, or comes directly from the switch port itself, the 8 most significant bits are set to 0xFFxxxxxx

This encoding lets you tell where the OUI came from just from the return value alone — a useful diagnostic feature for distinguishing whether you got information about a real external PHY chip or about the switch port itself.

Switch-native diagnostics: GetSwitchIdentifier

Unlike the pure forwarding APIs, EthSwt_GetSwitchIdentifier actually identifies the switch chip itself — relevant for multi-switch systems where several identical chips need to be distinguished. EthSwt_GetPortIdentifier, by contrast, is a hybrid: it prefers the OUI from the referenced EthTrcv, but falls back to a switch-native identifier if no transceiver is referenced or it can’t provide an OUI (see the encoding rule above).

Case study: a port shows sporadic failures

  1. Check signal quality — EthSwt_GetPortSignalQuality; if the call returns 0xFFFFFFFF, either the transceiver reference is missing or the PHY doesn’t support signal quality measurement

  2. Trigger cable diagnostics — EthSwt_RunPortCableDiagnostic (asynchronous), then fetch the result via EthSwt_GetPortCableDiagnosticsResult

  3. Loopback test — EthSwt_SetPortLoopbackMode to narrow the fault down to the PHY/line level, independent of the switch fabric

  4. Verify port identity — EthSwt_GetPortIdentifier, to make sure the expected port or PHY chip is actually being addressed

Summary

AspectKey takeaway

Forwarding APIs

Cable diagnostics, test/loopback/Tx mode, and signal quality are pure wrappers around the corresponding EthTrcv_* function

Without a transceiver reference

These APIs return E_NOT_OK or sentinel values like 0xFFFFFFFF

OUI encoding

0x00xxxxxx = obtained from EthTrcv, 0xFFxxxxxx = different origin

Switch-native diagnostics

GetSwitchIdentifier identifies the switch itself, not the PHY