STM32N6 Ethernet / lwIP

Follow frames from the MAC through DMA descriptors and lwIP; distinguish receive pressure, wire errors and stack drops.

Download domain JSON · GitHub source · Domain catalog

Probe sampled · Descriptor com.bkpt.stm32-ethernet · version 0.9.0 · domain API 1.

Purpose and prerequisites

Targets the STM32N6570-DK Ethernet/lwIP demo, using STM32N657 secure SVD names ETH_S and RCC_S. Requires the exact ELF/layout: four RX descriptors with 24-byte stride, ownership at +12, and 16-bit lwIP statistics at the offsets listed below. It is not a generic pack for every STM32 Ethernet controller. The Ethernet clock guard must pass. Firmware statistics must be enabled and the debug view of memory must be coherent.

Engineering interpretation

Compare MAC arrivals, software-owned descriptors and lwIP counters to locate receive pressure. MAC packets advancing while IP progress stops suggests the receive path is not keeping up, but cache visibility and different traffic populations must be considered. FIFO overflow, descriptor backlog and UDP drops identify different layers. A quiet receive counter is not necessarily failure when no peer sends traffic. This firmware keeps DMA descriptors in non-cacheable AXISRAM while lwip_stats can lag through cache write-back. The two clear-on-read inputs consume counts that another reader would otherwise see; this is a meaningful observation side effect.

Acquisition and validity

The descriptor declares 21 inputs and 13 derived channels, with a requested default of 100 Hz per input. Unsupported/unsafe rows remain unavailable. The achieved poll rate depends on the probe and selected inputs.

Global guard: (RCC_S.RCC_AHB5ENR & 0x02000000) = 0x02000000. ETH1 clock disabled (RCC_AHB5ENR.ETH1EN clear): the block is unclocked and reads return zeros, not data

SVD device: STM32N657. Target prefix: STM32N65.

Inputs are sampled separately while firmware runs. DWARF paths require the exact Debug ELF; unresolved or null pointers produce unavailable values. A readable object is not proof that it has finished initialization. Firmware can update or reuse it between reads. Missing observations propagate to dependent fields and checks.

Cards with a capacity reference show value / capacity, not a percentage. Both readings must be available, capacity must be positive, and the value must lie between zero and capacity. Otherwise the card is unavailable. Individual fields retain their raw values in traces. Saved observations describe their acquisition time, not fresh target state.

Cards and tables

Traffic

MAC counter observations and derived rates. Host polling can miss brief state transitions.

Receive path

Descriptor occupancy and queue/state snapshots describe the instant sampled. A brief stall can occur between observations.

Transmit path

Decoded controller states from the sampled status registers.

Errors and drops

Missed-frame and overflow fields come from consuming counters and describe read intervals. CRC/alignment and stack drops are cumulative.

Network stack

Application-owned lwIP counters. Offsets and widths must match this exact N6 demo ELF and its lwIP configuration.

Raw registers and access limits

Registers, addresses and packed fields are kept out of graphs by default. PHY MDIO access remains unsafe and unavailable; grouping does not authorize a read.

Every sampled input

All paths below come from the downloadable definition. Integer types specify width and signedness. No scaling is applied to a raw read. A field without a declared unit is a code, count, address or raw register; its engineering meaning is explained above or below.

wrapping tells analysis to account for rollover at the declared integer width; a reset can look like a wrap, and multiple wraps between samples cannot be recovered. monotonic uses sampled increases without inventing a reset/wrap delta. clear_on_read reports a consuming read interval, not a lifetime total. A display styled as a counter does not itself establish any of these policies.

Derived fields and rates

Rates need two valid samples at increasing timestamps and are interval averages. Gaps break the calculation. A negative raw delta is clamped to zero by the rate calculation; do not infer an instantaneous event rate from a reset. Unknown map keys pass through numerically; an unmapped code is not a validated physical measurement.

Findings

Application not draining

warning · app-not-draining. lwip.ip_recv does not increase over 250 ms while eth.rx_good advances by at least 50.

Good MAC unicast frames advance while the sampled IP receive counter does not. Check driver scheduling, buffers and the application consumer, but also account for cached statistics and traffic that never reaches IP.

Evidence: lwip.ip_recv, eth.rx_good, eth.rx_ring, eth.rx_dma_state, eth.rx_missed_frames, lwip.mem_used.

RX frames missed by the MAC

error · rx-frames-missed. eth.rx_missed_frames ≥ 1 at a valid sample.

The MTL missed-packet field is positive in a consuming read interval. This establishes reported receive loss, not a unique descriptor-starvation diagnosis. Compare FIFO overflow, queue fill, DMA state and ring ownership.

Evidence: eth.rx_missed_frames, eth.rx_fifo_overflow, eth.rx_ring, eth.rx_dma_state, lwip.ip_recv.

CRC errors on the wire

error · rx-crc-errors. eth.rx_crc_err increases between valid samples.

The CRC counter advanced. Investigate cable/connector, PHY configuration and electrical integrity alongside alignment errors; this observation alone cannot identify a unique cause.

Evidence: eth.rx_crc_err, eth.rx_align_err, eth.mac_config.

RX stopped while TX continues

warning · rx-stopped. eth.rx_good does not increase over 1000 ms while eth.tx_good advances by at least 1.

The MAC keeps transmitting but nothing is being received. Suspect the receive path specifically: RX DMA state, buffer availability, or the peer no longer sending.

Evidence: eth.rx_rate, eth.tx_rate, eth.rx_dma_state, eth.tx_dma_state.

RX FIFO overflowed

error · rx-fifo-overflow. eth.rx_fifo_overflow ≥ 1 at a valid sample.

Frames were lost inside the MAC's receive FIFO: the MTL queue filled faster than the DMA drained it into memory. Unlike missed frames (no descriptor), this points at bus/DMA throughput or a burst above what the queue depth absorbs. Value is frames lost in one poll interval (clear-on-read).

Evidence: eth.rx_fifo_overflow, eth.rxq_fill, eth.rxq_packets, eth.rx_missed_frames, eth.rx_ring.

RX descriptor ring saturated

suspicious · rx-ring-saturated. eth.rx_ring ≥ 3 for 100 ms of observations.

At least three of four descriptors stayed software-owned across 100 ms of sampled evidence. This is a high-backlog threshold, not literally four-of-four fullness; brief saturation can occur between polls.

Evidence: eth.rx_ring, eth.rx_ring_cur, eth.rx_dma_state, eth.rx_missed_frames.

Datagrams dropped by the stack

warning · stack-dropping. lwip.udp_drop increases between valid samples.

The stack received datagrams and threw them away: no PCB is bound for that port, or the receive queue of a socket nobody is reading is full. Loss above the MAC, so the Ethernet counters stay clean.

Evidence: lwip.udp_drop, lwip.udp_recv, lwip.mem_used, eth.rx_good.

Value dictionaries

These are the exact value mappings in this version of the descriptor. Unlisted status codes remain numeric; they are not implicitly success. Decode a value in the context of its field and validity.

Value map 1

Value map 2

Value map 3

Value map 4

Value map 5

Value map 6

Definition and contribution

Checked against the N6 demo main.c, ethernetif.c, lwipopts.h, lwIP stats.h, the STM32N657 CMSIS Ethernet register definitions and the domain rate/counter/finding decoder. Firmware layout and SVD compatibility must be rechecked for any adapted build.

View or propose changes to the canonical JSON. Contribution guide.

Download SHA-256: 5df29bdc78a799741cdb3ad76d7b6555bbc44c84319dea64547d10d2dfa7c170.