Debugging & Verification Exercise

Lesson 1

1. Understand the exercise boundary

The fictional controller begins in IDLE, enters STARTING after a start command and should reach RUNNING only after a valid sensor observation. An output is enabled in RUNNING. A 100 ms starting deadline, sensor updates from an interrupt, watchdog supervision and restart behaviour make the example small enough to inspect while preserving the kinds of interactions that create real firmware defects.

The downloadable project is intentionally incomplete and incorrect. Two nominal tests pass. Four targeted checks are marked pending, so the initial runner exits with a failure status. That is the expected starting condition: the work is to define the missing claims, implement tests that expose the defects and then repair the design. The numbers are teaching inputs and do not establish suitable limits for a real product.

This exercise stays inside the controller boundary. It asks what the firmware does with time, shared state, reset and progress. The complementary Embedded Academy exercise asks whether sensors, links, host software and recovery behaviour work together across the complete system.

Lesson 2

2. Complete the requirements before repairing code

The starter includes four incomplete statements. Rewrite each with a trigger, state, time origin, boundary, required response and observable acceptance criterion. “Starting shall time out after 100 ms” does not say whether the fault occurs at 100 ms or after it, which clock is authoritative, what output is required or how rollover is handled.

These are suitable exercise requirements, not product requirements. A real design would justify the deadline, define physical output timing, name the actual synchronisation mechanism and specify the watchdog interval and reset sequence. Preserve that distinction in your test report.

Lesson 3

3. Draw behaviour and execution contexts

Draw the state transitions separately from the execution-context diagram. The state model contains IDLE, STARTING, RUNNING and FAULT. The context model contains the timer interrupt, sensor interrupt, main loop, watchdog peripheral and output driver. Combining them into one crowded drawing often hides the fact that an interrupt can run while the main loop is stalled.

Mark every shared object. The sensor interrupt writes temperature, timestamp and validity. Main processing reads the same fields. The timer interrupt changes the clock and services the watchdog in the starter. Ask which operations are atomic on the assumed target, which ordering rules apply and what observation proves useful progress.

Write a short fault hypothesis for each planted defect before opening the code. This prevents line-by-line debugging from becoming the only method and gives each test a specific claim to challenge.

Lesson 4

4. Inspect the deliberately flawed implementation

The complete flawed implementation is shown below and included in the download. Read it once for intent and again for execution order. Annotate the four places where a requirement can be defeated.

#include "firmware.h"

#define START_TIMEOUT_MS UINT32_C(100)

volatile uint32_t g_tick_ms;
volatile uint32_t g_watchdog_kicks;
volatile struct sensor_sample g_sensor_sample;

static void watchdog_kick(void)
{
    ++g_watchdog_kicks;
}

void timer_interrupt(void)
{
    ++g_tick_ms;

    /* Deliberate defect: an interrupt proves only that the interrupt ran. */
    watchdog_kick();
}

void sensor_interrupt(int16_t centi_c, bool valid)
{
    /* Deliberate defect: main can observe fields from different acquisitions. */
    g_sensor_sample.centi_c = centi_c;
    g_sensor_sample.captured_ms = g_tick_ms;
    g_sensor_sample.valid = valid;
}

void controller_boot(struct controller *c, enum reset_reason reason,
                     bool retained_running)
{
    c->mode = MODE_IDLE;
    c->output_on = false;
    c->state_entered_ms = g_tick_ms;
    c->last_sample_ms = 0;
    c->progress_count = 0;

    /* Deliberate defect: a watchdog reset can resume an active output. */
    if (reason == RESET_WATCHDOG && retained_running) {
        c->mode = MODE_RUNNING;
        c->output_on = true;
    }
}

void controller_start(struct controller *c)
{
    if (c->mode == MODE_IDLE) {
        c->mode = MODE_STARTING;
        c->state_entered_ms = g_tick_ms;
    }
}

void controller_step(struct controller *c)
{
    /* Deliberate defect: this is not a coherent interrupt-to-main snapshot. */
    const struct sensor_sample sample = g_sensor_sample;
    const bool new_sample = sample.captured_ms != c->last_sample_ms;

    ++c->progress_count;

    if (c->mode == MODE_STARTING && new_sample) {
        c->last_sample_ms = sample.captured_ms;
        if (sample.valid && sample.centi_c >= 3000) {
            c->mode = MODE_RUNNING;
            c->output_on = true;
            return;
        }

        /* Deliberate defect: no new sample means the timeout is never checked. */
        if ((uint32_t)(g_tick_ms - c->state_entered_ms) > START_TIMEOUT_MS) {
            c->mode = MODE_FAULT;
            c->output_on = false;
        }
    }
}

Do not correct everything at once. A large rewrite can make the symptoms disappear without proving which change addressed which defect. Establish one failing test per claim, retain the original observation, make the smallest coherent design correction and rerun the relevant regression set.

Lesson 5

5. Design tests that force the critical condition

EX-003 should enter STARTING, provide no new sample, execute at 99 ms and then exactly 100 ms, and require FAULT with output off at the boundary. EX-004 should force or emulate an update in progress so the reader cannot accept a mixture of fields. EX-005 should boot after a watchdog reset with retained active information and require IDLE with output off. EX-006 should advance timer interrupts without calling main processing and require that watchdog service does not continue.

Each test needs a precondition, stimulus, observation and verdict. Avoid a long scenario that fails for several possible reasons. A focused failure message should tell you which boundary or invariant was violated. After the repair, add nearby negative cases: 99 ms must not time out, a completed sensor update must be accepted, a normal power-on must remain inhibited and one completed main iteration may refresh supervision.

Lesson 6

6. Correct design ownership, not only symptoms

The timeout belongs to state supervision and must be evaluated independently of sensor arrival. The sensor handoff needs a supported coherent-snapshot mechanism, not merely volatile. Restart policy belongs to controlled initialisation, not a convenience rule based on retained state. Watchdog authority belongs to evidence of required progress, not the highest-frequency interrupt.

Your target may use a bounded critical section, interrupt masking, double buffering, a sequence counter or a platform-supported queue. Select one using the target's atomicity, latency and memory rules. The starter does not prescribe a universal mechanism. Record the chosen contract: which context publishes, how completion is indicated, what the reader does during an update and the maximum time for which access can be deferred.

Lesson 7

7. Plan the verification ladder and closure record

Host tests can demonstrate state transitions, arithmetic boundaries and logic around a simulated handoff. They cannot prove atomic access on the target, interrupt latency, watchdog configuration, reset-pin behaviour or physical output de-energisation. Allocate those claims to target integration and, where relevant, HIL.

Close each defect with the original failing observation, requirement correction, design change, review, passing regression and impact on other tests. Record remaining limitations rather than turning “all host tests pass” into a claim about the product.

Decision guide

Where should each defect be exposed?

Engineering evidence

What should the work produce?

Practical check

Questions for your next design review

• Does timeout supervision run even when the awaited event never arrives?
• Can the reader prove all sample fields belong to one acquisition?
• Is every reset reason mapped to a safe, deliberate initial state?
• Does watchdog service represent the progress that matters?
• Does the evidence state which target behaviours remain unverified?