DOCS/TRACE DOMAINS/PACKET COUNTER EXAMPLE
BKPT DEBUG & VIEWALYZER RS
Packet counter example
Wrapping counters, a derived rate and an error-count finding.
Download example JSON · GitHub source · Authoring examples
Authoring example · Descriptor com.example.packet-counter · version 1.0.0 · domain API 1.
Purpose and prerequisites
An authoring sample for adapting to your own firmware or instrument. Firmware must supply packets_completed and packet_errors. 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 2 inputs and 1 derived channels, with a requested default of 20 Hz per input. Unsupported/unsafe rows remain unavailable. The achieved poll rate depends on the probe and selected inputs.
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
Packets
| CARD OR ROW | READING AND SIGNIFICANCE | UNIT |
|---|---|---|
Completed · packets.completed | Firmware-owned completed-packet counter, wrapping at 32 bits. The example supplies no producer; define precisely what completed means in your firmware. | packets |
Errors · packets.errors | Firmware-owned packet-error counter. Choose which failures increment it; the template cannot identify their cause. | packets |
Throughput · packets.rate | Interval average of completed-counter changes in packets/s, not wire throughput. | packets/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 |
|---|---|---|---|
packets.completed | packets_completed | u32 | See its card/table above. Counter policy: wrapping. |
packets.errors | packet_errors | u32 | See its card/table above. Counter policy: wrapping. |
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 |
|---|---|---|---|
packets.rate | max(0, change in packets.completed / elapsed seconds) | Interval average of completed-counter changes in packets/s, not wire throughput. | packets/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
Packet errors increased
warning · packet-errors. packets.errors increases between valid samples.
The firmware error counter advanced. Inspect the driver's error reason and compare with traffic load.
Evidence: packets.errors, packets.rate.
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: a23d2495696bb651f5118c14bc87e2498184307b8c91a2ccd3f85e77b082208b.