Middleware queue example

Structured pointers, occupancy/capacity cards and consumer-progress checks.

Download example JSON · GitHub source · Authoring examples

Authoring example · Descriptor com.example.middleware-queue · version 1.0.0 · domain API 1.

Purpose and prerequisites

An authoring sample for adapting to your own firmware or instrument. Implement or map active_queue, queue_slots, queue_enqueued and queue_drained. 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 6 inputs and 2 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

Queue

CARD OR ROW	READING AND SIGNIFICANCE	UNIT
Occupancy · `queue.used`	Current used-message count through active_queue; paired with capacity in the Occupancy card. Reference: `queue.capacity`. Message capacity through active_queue. Must be positive and no smaller than used for a valid capacity card.	messages
Status / State · `queue.state`	Firmware state code: 0 idle, 1 active, 2 fault. Define the actual producer before using this rule. Values.	Raw value / decoded state
Performance / Drain rate · `queue.drain_rate`	Interval average of drain-counter changes in messages/s.	messages/s
Performance / Expected rate · `queue.expected_rate`	Mode mapping: 0 → 0, 1 → 50, 2 → 100 messages/s. Other codes pass through and are not validated physical rates.	messages/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
`queue.used`	`(*active_queue).used`	u32	See its card/table above.
`queue.capacity`	`(*active_queue).capacity`	u32	See its card/table above.
`queue.state`	`(*active_queue).state`	u32	See its card/table above.
`queue.mode`	`queue_slots[1].mode`	u32	Mode in queue_slots[1], selecting the expected-drain-rate mapping.
`queue.enqueued`	`queue_enqueued`	u32	Wrapping enqueue counter supplied by firmware; reference for detecting a non-progressing consumer. Counter policy: `wrapping`.
`queue.drained`	`queue_drained`	u32	Wrapping drain counter supplied by firmware; counts application-defined completed drains. 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
`queue.drain_rate`	max(0, change in `queue.drained` / elapsed seconds)	Interval average of drain-counter changes in messages/s.	messages/s
`queue.expected_rate`	Map `queue.mode`	Mode mapping: 0 → 0, 1 → 50, 2 → 100 messages/s. Other codes pass through and are not validated physical rates. Values.	messages/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

Consumer stopped progressing

warning · drain-stalled. queue.drained does not increase over 1000 ms while queue.enqueued advances by at least 10.

Evaluate this condition with the evidence and expected application behavior; it does not uniquely identify a root cause.

Evidence: queue.used, queue.capacity.

Firmware reports a fault

error · fault-state. queue.state is one of: 2.

Inspect the firmware fault reason before restarting this queue.

Drain rate below expectation

warning · slow-drain. queue.drain_rate < 0.8 × queue.expected_rate for 2000 ms of observations.

Evaluate this condition with the evidence and expected application behavior; it does not uniquely identify a root cause.

Evidence: queue.mode.

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`	Idle
`1`	Active
`2`	Fault

Value map 2

RAW VALUE	DECODED LABEL / MAPPED VALUE
`0`	0
`1`	50
`2`	100

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: aeb03c5b620de9df9e852af88734fe1e7a7cdc182229dffac6515480469122e2.

TRACE DOMAINS OVERVIEW ALL GUIDES EMAIL SUPPORT