DOCS/TRACE DOMAINS/ETHERNET AUTHORING EXAMPLE
BKPT DEBUG & VIEWALYZER RS
Ethernet authoring example
Guarded registers, descriptor ownership and backlog checks for a placeholder MAC.
Download example JSON · GitHub source · Authoring examples
Authoring example · Descriptor com.example.mac-monitor · version 1.0.0 · domain API 1.
Purpose and prerequisites
An authoring sample for adapting to your own firmware or instrument. Replace ExampleMCU registers and ring layout with verified target definitions. It is not a tested board-support domain.
Engineering interpretation
The fields and thresholds below are the exact example contract. Replace placeholder sources and document the actual producer, units, safe-access conditions and acceptable states before enabling this on a target. Parsing success establishes format validity, not hardware compatibility.
Acquisition and validity
The descriptor declares 4 inputs and 2 derived channels, with a requested default of 10 Hz per input. Unsupported/unsafe rows remain unavailable. The achieved poll rate depends on the probe and selected inputs.
Global guard: (CLOCK.ENABLE & 0x1) = 0x1. The Ethernet clock must be enabled.
SVD device: ExampleMCU. Target prefix: ExampleMCU.
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
Receive path
| CARD OR ROW | READING AND SIGNIFICANCE | UNIT |
|---|---|---|
DMA state · eth.state | Two-bit sample state code from the placeholder status register. These example names are not STM32N6 hardware meanings. Values. | Raw value / decoded state |
Pending descriptors · eth.rx_pending | Number of four descriptors with OWN clear, using the declared stride/offset. Adapt the ownership convention to the driver. | descriptors |
Receive rate · eth.rx_rate | Interval average of good-frame counter changes, in frames/s. | frames/s |
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.
| INPUT | SOURCE / ADDRESS PATH | TYPE | INTERPRETATION / ACCESS |
|---|---|---|---|
eth.rx_good | ETH.RX_GOOD | u32 | Placeholder good-frame register; requires verified non-consuming counter behavior after its reset-on-read guard passes. Counter policy: wrapping. Guard: (ETH.COUNTER_CONTROL & 0x4) = 0. Disable reset-on-read before observing this counter. |
eth.status | ETH.STATUS | u32 | Placeholder status word assumed read-safe. Verify the real target before use. |
eth.rx_pending | rx_descriptors: 4 entries, 24-byte stride; 32-bit ownership word at +12, mask 0x80000000; count clear ownership bits. | u32 | See its card/table above. |
eth.payload | Payload contents are outside this monitor's observation contract. | u32 | Intentionally unsupported; payload inspection is outside this example. Payload contents are outside this monitor's observation contract. |
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
| CHANNEL | CALCULATION | MEANING | UNIT |
|---|---|---|---|
eth.state | (eth.status >> 1) & 0x3 | Two-bit sample state code from the placeholder status register. These example names are not STM32N6 hardware meanings. Values. | Code / state |
eth.rx_rate | max(0, change in eth.rx_good / elapsed seconds) | Interval average of good-frame counter changes, in frames/s. | frames/s |
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
Receive backlog
warning · rx-backlog. eth.rx_pending ≥ 3 for 500 ms of observations.
At least three receive descriptors stayed pending across the observed window. Check whether the receive task is reclaiming descriptors.
Evidence: eth.rx_pending, eth.rx_rate, eth.state.
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
| RAW VALUE | DECODED LABEL / MAPPED VALUE |
|---|---|
0 | Stopped |
1 | Running |
2 | Suspended |
3 | Error |
Definition and contribution
Verified against the complete authoring descriptor and the native validation, structured-source, derived-field, finding and action contracts. No real producer is supplied for this sample.
View or propose changes to the canonical JSON. Contribution guide.
Download SHA-256: 17162587dbb852dde89fa2e61bb275c00576cd6e62608e52b420628e06bb79b3.