1. Home
2. Academy
3. Embedded C from Zero
4. Volume 11

11.1 Polling vs interrupts

Polling means asking, over and over, whether anything has happened. An interrupt means being told the moment it does.

Every program in this course so far has polled. The main loop goes round, checks a pin, does some work, and goes round again. That is a perfectly good design, and a great deal of shipped firmware works exactly that way.

for (;;) {
    if (gpio_read(BUTTON)) {
        handle_button();
    }
    update_display();
    check_temperature();
}

It has two problems, and both come from the same place: nothing is looked at until the loop gets round to it.

The first is speed of response. If one pass of the loop takes 20 ms, a button press might sit there for 20 ms before anyone notices. The second is worse. If an event is shorter than one pass, the loop can miss it completely.

When polling is still the right answer

Interrupts are not automatically better. Polling wins when the timing is easy to reason about, because nothing surprises you, and stack use and worst-case timing can be worked out on paper.

11.2 The vector table and the NVIC

The chip already knows where your handler is. Volume 09's vector table holds the address of every one of them.

Volume 09 looked at the first two entries: the initial stack pointer and the reset handler. The table does not stop there. Entry after entry follows, one per interrupt source, each holding the address of the function to run.

void *const vector_table[] = {
    (void *)&_estack,          /*  0  where the stack starts          */
    Reset_Handler,             /*  1  out of reset                    */
    NMI_Handler,               /*  2                                  */
    HardFault_Handler,         /*  3                                  */
    /* ... more core exceptions ... */
    TIM2_IRQHandler,           /* 44  the timer 2 interrupt           */
    USART1_IRQHandler,         /* 53  the serial port                 */
};

When timer 2 fires, the hardware reads entry 44 and jumps there. Nothing in your code is consulted. This is why an interrupt handler is never called by anything you can see: the caller is the silicon.

The controller in between

Between the peripherals and the core sits the interrupt controller. On Arm Cortex-M chips it is called the NVIC, and it holds three things for every interrupt source.

Enabling one is usually two steps, and forgetting either is the classic first-day bug.

TIM2->DIER |= DIER_UIE;        /* 1. the peripheral: tell me when you overflow */
NVIC_EnableIRQ(TIM2_IRQn);     /* 2. the controller: let that reach the core   */

11.3 Writing an interrupt handler

A handler is an ordinary C function with an extraordinary caller. The rules that matter are about what it must not do.

There is nothing special about the code. The name has to match the one in the vector table, it takes no arguments and returns nothing, and that is the whole of the syntax.

volatile uint32_t tick_count;

void TIM2_IRQHandler(void)
{
    if (TIM2->SR & SR_UIF) {       /* did this interrupt really come from here? */
        TIM2->SR = ~SR_UIF;        /* tell the peripheral we have dealt with it */
        tick_count++;
    }
}

Two lines in that function matter more than the rest.

Checking the status register first is not optional on peripherals that raise one interrupt for several reasons. A UART interrupt might mean a byte arrived, or a byte finished sending, or an error happened. You have to ask which.

Clearing the flag is what stops the interrupt firing again immediately. Forget it and the handler runs forever, the main loop never gets a single instruction, and the board looks frozen.

The things a handler must not do

• Do not wait for anything. A delay loop, or polling a peripheral until it is ready, may be waiting for an interrupt that cannot run
• Do not call printf. It is slow, it may allocate, and it is often not reentrant
• Do not call malloc or free, for the same reasons
• Do not do long work. Take the byte, set a flag, push to a queue, and get out
• Do not assume it will not be interrupted. Something more urgent may be waiting

11.4 Priorities and nesting

When two interrupts want to run, priority decides. When a more urgent one arrives mid-handler, it interrupts the handler - that is preemption.

Every source gets a priority number. On Arm chips a lower number means more urgent, which is the opposite of what most people guess, and is worth saying out loud once.

The rules are short:

1. If nothing is running, the most urgent pending interrupt runs
2. If a handler is running, a more urgent interrupt interrupts it
3. An equally urgent or less urgent one waits until the handler finishes
4. A disabled one does not run at all, but stays pending until it is enabled

Rather than take that on trust, here is a model of a controller obeying exactly those rules, with handlers that print as they start and finish. TIMER is priority 1, UART and ADC are both 2, BUTTON is 3.

1. a more urgent interrupt arrives while a handler is running
   .. UART fires
   -> UART starts (priority 2)
      reading the received byte
      -> TIMER starts (priority 1)
         bumping the tick counter
      <- TIMER done
      storing the byte - this line runs after TIMER finished
   <- UART done

The UART handler was half way through when the timer fired. TIMER is more urgent, so it ran to completion first, and then UART carried on from exactly where it stopped. That is nesting, and it is the reason a handler must never assume it runs undisturbed.

Now the other direction:

2. a less urgent interrupt arrives while a handler is running
   .. TIMER fires
   -> TIMER starts (priority 1)
      bumping the tick counter
      .. BUTTON fires
      still inside TIMER - BUTTON has to wait
   <- TIMER done
   -> BUTTON starts (priority 3)
      starting the debounce timer
   <- BUTTON done

BUTTON fired in the middle of TIMER and got nowhere. It stayed pending until TIMER finished, and then ran. Equal priorities behave the same way: the running one finishes first.

Choosing the numbers

Priority is a budget for lateness. Ask what happens if a handler is late, not how important the device feels.

11.5 Sharing data with a handler safely

The handler and the main loop share variables, and they can interrupt each other between any two instructions. That is where the hardest bugs in embedded C live.

Volume 10 showed one of them already. Here are all three, each provoked at the exact instant that breaks it, so they happen every run instead of once a fortnight.

One: the lost update

Both sides do count++. That is three steps each, so one increment can overwrite the other.

1. both main and the handler do count++
   two increments happened, count is 1
   volatile did not help: it is still a read, a change and a write

volatile guarantees the reads and writes really happen. It does not glue them together.

Two: the torn read

A 64-bit microsecond clock, kept by the timer handler, read by the main loop. A 32-bit chip must read it in two halves, and the interrupt can land in between.

uint32_t hi = micros_hi;
/* the timer interrupt lands here, the low half wraps and the high half grows */
uint32_t lo = micros_lo;
return ((uint64_t)hi << 32) | lo;

before:   hi=5 lo=0xFFFFFFFF, so the true value is 25769803775
read_torn returned 21474836480
the real value now is 25769803776
the answer is 4294967296 too low, and that value never existed

The high half came from before the wrap, the low half from after it. The result is not merely stale, it is a number the clock never held. A timeout built on it fires four billion microseconds early.

The fix does not need a critical section. Read the high half, the low half, then the high half again. If the high half changed, something wrapped in between, so throw it away and go round again.

for (;;) {
    uint32_t first_hi = micros_hi;
    uint32_t lo       = micros_lo;
    uint32_t again_hi = micros_hi;
    if (first_hi == again_hi) {
        return ((uint64_t)first_hi << 32) | lo;   /* no wrap happened */
    }
}

high half changed while reading - trying again
read_safe returned 25769803777, which is a value the counter really held
a consistent answer, even though the counter moved underneath it

Three: the lost event

A flag can say that something happened. It cannot say that two things happened.

3. a flag versus a count
   2 events arrived, and 1 got handled - a flag only says yes or no
   2 events arrived, and 2 got handled - a counter remembers them all

What is actually safe

11.6 Critical sections and atomic access

When an update cannot be made indivisible, make it uninterruptible. That is a critical section, and it is the last resort rather than the first.

uint32_t state = save_and_disable_irq();

shared_total += reading;            /* the three steps, undisturbed */

restore_irq(state);

Saving and restoring matters. If you end with a blind "enable interrupts" and the caller had already disabled them, you have switched them on underneath somebody else, and the bug appears far from here.

Better: design the sharing away

The best critical section is the one you did not need. For a stream of data there is a structure that needs no locking at all: the ring buffer.

One producer, one consumer. The handler writes head and only reads tail. The main loop writes tail and only reads head. Each index has exactly one writer, so there is nothing to race over.

#define RING_SIZE 8u                    /* a power of two, so the mask works */
#define RING_MASK (RING_SIZE - 1u)

static volatile uint8_t  buf[RING_SIZE];
static volatile uint32_t head;          /* the producer writes this */
static volatile uint32_t tail;          /* the consumer writes this */

bool ring_put(uint8_t byte)             /* called from the handler */
{
    uint32_t next = (head + 1u) & RING_MASK;

    if (next == tail) {
        dropped++;
        return false;                   /* full: say so, do not overwrite */
    }
    buf[head] = byte;
    head = next;                        /* publish only after the byte is in */
    return true;
}

bool ring_get(uint8_t *out)             /* called from the main loop */
{
    if (tail == head) {
        return false;                   /* empty */
    }
    *out = buf[tail];
    tail = (tail + 1u) & RING_MASK;     /* release the slot after reading it */
    return true;
}

The order of the last two lines in each function is the whole trick. The producer writes the byte first and moves head afterwards, so the consumer never sees an index pointing at a slot that has not been filled. The consumer reads the byte first and moves tail afterwards, so the producer never reuses a slot that has not been read.

2. interrupts arriving while the main loop is reading
  two waiting                  head=5 tail=3  holding 2  [...DE...]
  main loop got 'D'
  one taken, one arrived       head=6 tail=4  holding 2  [....EF..]
  main loop got 'E'
  main loop got 'F'
  drained again                head=6 tail=6  holding 0  [........]

Nothing was lost and nothing was locked. And when it does fill up, it says so rather than corrupting itself:

3. filling it up: the eighth byte has nowhere to go
  ring_put('7') refused - the ring is full
  full                         head=5 tail=6  holding 7  [23456.01]
  1 byte was dropped, and the handler knows it

Look at that last picture. head is 5 and tail is 6, so the data has wrapped round the end of the array. The one empty slot sits at index 5.

What you learned

• Polling is simple and predictable, and it loses events shorter than one pass of the loop
• The vector table holds one address per interrupt source, and the silicon is the caller
• An interrupt needs enabling twice: in the peripheral and in the controller
• The pending bit remembers that an interrupt fired, not how many times
• A handler checks why it was called, clears the flag, and gets out fast
• Never wait, printf or malloc inside a handler
• Lower priority numbers are more urgent on Arm; more urgent interrupts preempt running handlers
• Equal or lower priority waits, and every nested handler costs another stack frame
• count++ shared with a handler can lose an increment, and volatile does not prevent it
• A value read in two halves can come back as a number that never existed; read, check, retry
• A flag cannot count; use a counter or a queue when events can arrive in bursts
• A critical section must save and restore the previous state, and must be short
• A single-producer, single-consumer ring buffer needs no locking, and publishing order is the trick

Practice

void TIM2_IRQHandler(void)
{
    if (TIM2->SR & SR_UIF) {
        TIM2->SR = ~SR_UIF;        /* acknowledge it first */
        tick_count++;
    }
}

void USART1_IRQHandler(void)
{
    if (USART1->SR & SR_RXNE) {
        (void)ring_put((uint8_t)USART1->DR);   /* read it, stash it, leave */
    }
}

/* in the main loop */
uint8_t b;
while (ring_get(&b)) {
    parse_command(b);
    if (command_ready) {
        execute_command();
    }
}

Interview corner

Next, Volume 12 puts interrupts to work on the thing they are best at. Timers: measuring time without a delay loop, generating a steady tick, and making a pin wave up and down on its own with PWM.

Key words from this volume

Every word below has a plain-English entry in the glossary.

• Polling
• Interrupt
• Vector table
• NVIC
• Pending bit
• Reentrant
• Preemption
• Critical section
• Interrupt latency
• Ring buffer