Part 1 of this series covered EthSwt’s state machine and its place in the architecture. This part shows the concrete API — and clears up a common simplification along the way: EthSwt_Init does not synchronously initialize the entire switch hardware. According to the SWS (chapter 8.3.1), that can take too long to be called from EcuM or BswM — the actual hardware configuration is handled by a separate background task.

The init sequence in detail

EthSwt_Init(CfgPtr)
   │
   ├─ Stores a pointer to the configuration structure
   ├─ State: ETHSWT_STATE_UNINIT → ETHSWT_STATE_INIT
   ├─ All EthSwtPorts → ETH_MODE_DOWN
   └─ Unconfigured hardware ports are switched off
       (and stay off for the entire runtime)

   ... repeated calls ...

EthSwt_BackgroundTask()             ◄── call "as often as possible"
   │                                     whenever no other task runs
   ├─ Takes over switch/port initialization if
   │  EthSwt_Init would take too long for it
   ├─ Checks register access (otherwise: ETHSWT_E_ACCESS)
   ├─ Activates any configured port mirroring
   │  (SWS_EthSwt_00421/00422)
   └─ State: ETHSWT_STATE_INIT → ETHSWT_STATE_PORTINIT_COMPLETED

   ... afterwards, depending on EthSwtLowPowerModeSupport ...

   ├─ TRUE  → switch initially stays in a low-power/inactive state
   └─ FALSE → switch goes directly into an active state

EthSwt_SetSwitchPortMode(SwitchIdx, PortIdx, ETH_MODE_ACTIVE)
   │                                    ◄── call explicitly per port
   ├─ If EthSwtPort references an EthTrcv:
   │  additional call to EthTrcv_SetTransceiverMode
   │  (via the EthIf API abstraction)
   └─ State: ETHSWT_STATE_PORTINIT_COMPLETED → ETHSWT_STATE_ACTIVE

The simple ordering assumed in the original planning issue — “EthSwt_Init` → Eth_Init → EthIf_Init” — falls short. The real SWS models `EthSwt_Init as pure state and pointer initialization; the time-critical hardware configuration runs asynchronously via EthSwt_BackgroundTask — analogous to EthSwt_MainFunction, which the SWS describes as supporting "asynchronous behavior of API calls" and which is called directly by the BSW scheduler.

Key APIs at a glance

APIPurpose

EthSwt_Init(CfgPtr)

State and pointer initialization; sets all ports to ETH_MODE_DOWN

EthSwt_BackgroundTask()

Takes over the actual switch/port hardware initialization if needed

EthSwt_SetSwitchPortMode(SwitchIdx, PortIdx, PortMode)

Switch a port to ETH_MODE_DOWN / ETH_MODE_ACTIVE / ETH_MODE_ACTIVE_WITH_WAKEUP_REQUEST

EthSwt_GetSwitchPortMode(SwitchIdx, PortIdx, SwitchModePtr)

Read the current port mode

EthSwt_GetLinkState(SwitchIdx, PortIdx, LinkStatePtr)

Query a port’s link state

EthSwt_GetPortMacAddr(SwitchIdx, PortIdx, MacAddrPtr)

Read a port’s MAC address

EthSwt_MainFunction()

Called cyclically by the BSW scheduler, supports asynchronous API behavior (e.g. delayed EthIf_SwitchPortModeIndication)

Port modes in detail

EthSwt_SetSwitchPortMode expects one of three Eth_ModeType values:

ModeMeaning

ETH_MODE_DOWN

Disable the port — per spec, as directly as possible to reduce power consumption

ETH_MODE_ACTIVE

Enable the port

ETH_MODE_ACTIVE_WITH_WAKEUP_REQUEST

Enable the port and trigger a wake-up on the network — per SWS relevant e.g. for hardware compatible with OPEN Alliance TC10

If an EthSwtPort references an EthTrcv (i.e. a real PHY chip on that port), EthSwt_SetSwitchPortMode additionally calls EthTrcv_SetTransceiverMode internally via the EthIf abstraction — the two drivers are deliberately kept in sync here. For a MAC-only port without an EthTrcv reference, this second call is skipped.

Link state: with and without EthTrcv

EthSwt_GetLinkState behaves differently depending on whether the port references an EthTrcv:

  • With an EthTrcv reference — the link state comes from EthTrcv_GetLinkState (via EthIf), exactly as in a plain transceiver setup

  • Without an EthTrcv reference (e.g. an internal port to an embedded PHY that the switch chip manages itself) — the state comes from the port’s MAC interface; if the hardware can’t provide that, it’s derived from the current port mode: ETH_MODE_ACTIVE → link active, ETH_MODE_DOWN → link down

If the port mode and the PHY mode don’t match, EthSwt_GetSwitchPortMode reports the extended production error ETHSWT_E_SYNCPORT2PHY and returns E_NOT_OK — a useful signal when debugging a case where the switch and the transceiver report different states for different reasons.

Error handling & determinism

Per the SWS, every API covered in this post first checks register access to the switch hardware; if that fails, the extended production error ETHSWT_E_ACCESS is raised and E_NOT_OK is returned. Additionally, every API returns E_NOT_OK if called in state ETHSWT_STATE_UNINIT or ETHSWT_STATE_INIT (i.e. before port initialization has completed).

Practical consequence: calling EthSwt_GetLinkState right after EthSwt_Init, without letting the background task run first, reliably returns E_NOT_OK — not because something is broken, but because the state machine hasn’t reached PORTINIT_COMPLETED yet.

Minimal example: init call sequence for a 4-port switch

EthSwt_Init(&EthSwtConfig_0);
// ... run background task cycles until PORTINIT_COMPLETED ...
EthSwt_BackgroundTask();   // possibly multiple times, depending on scheduling

for (portIdx = 0; portIdx < 4; portIdx++) {
    EthSwt_SetSwitchPortMode(0, portIdx, ETH_MODE_ACTIVE);
}

// Cyclic operation:
EthSwt_MainFunction();     // called regularly by the BSW scheduler

Series

PartTopicStatus

1

Fundamentals, SWS & architecture

done

2

API & initialization

this post

3

ARXML configuration

upcoming

4

VLAN management, mirroring & diagnostics

upcoming

Next in the EthSwt series: EthSwt Part 3 — ARXML Configuration in Practice