Chapter 6: Memory Protection#

What this chapter answers: why does the OS survive when an app crashes?

On a PC, when one app crashes, the OS and the other apps keep running. The OS ends only the program that misbehaved.

In this chapter the OS catches the exceptions (faults) the CPU raises on a division by zero or a write to an address that does not exist, and stops only the task that caused it. The other tasks carry on as if nothing happened.

Sample code#

Directory: docs/os-on-arduino/code/06_memory_protection

uv run pio run -d 06_memory_protection -t upload
uv run pio device monitor -b 115200

Source code#

The sketch for this chapter. Click a file name to expand. The code is mirrored automatically from the manuscript repository, so what you see here is always current.

src/main.cpp — 141 lines

Open on GitHub

/**
 * Chapter 6: Memory Protection Demo
 *
 * Demonstrates HardFault handling:
 * - Divide by zero detection
 * - Invalid memory access detection
 * - Crashed task termination (other tasks continue)
 */

#include <Arduino.h>
#include "os_kernel.h"
#include "os_fault.h"

// Arduino UNO R4 WiFi は基板上に "L" と印字された LED を持っています。
// 追加部品なしで動かせるよう、これを主 LED として使います。
#define LED_PIN LED_BUILTIN

// Normal task: blinks LED
void task_led(void)
{
    pinMode(LED_PIN, OUTPUT);
    while (1) {
        digitalWrite(LED_PIN, HIGH);
        os_sleep(500);
        digitalWrite(LED_PIN, LOW);
        os_sleep(500);
    }
}

// Normal task: periodic output
void task_heartbeat(void)
{
    int count = 0;
    while (1) {
        Serial.print("[Heartbeat] ");
        Serial.println(count++);
        os_sleep(2000);
    }
}

// Crash task: divide by zero
void task_crash_divzero(void)
{
    Serial.println("[Crash] Dividing by zero in 3 seconds...");
    Serial.flush();
    os_sleep(3000);

    // Ensure Serial is idle before crashing
    Serial.flush();
    os_sleep(100);

    volatile int a = 100;
    volatile int b = 0;
    volatile int c = a / b;  // This will trigger HardFault!
    (void)c;
}

// Crash task: invalid memory access
void task_crash_memory(void)
{
    Serial.println("[Crash] Invalid memory access in 5 seconds...");
    os_sleep(5000);

    volatile uint32_t *bad_ptr = (uint32_t *)0xFFFFFFFF;
    *bad_ptr = 0x12345678;  // This will trigger HardFault!
}

// Shell-like task for control
void task_shell(void)
{
    Serial.println();
    Serial.println("Commands: 'd' = div by zero, 'm' = bad memory, 'p' = ps");

    while (1) {
        // Print any pending fault messages (deferred from ISR context)
        fault_print_pending();

        if (Serial.available()) {
            char c = Serial.read();

            if (c == 'd') {
                Serial.println("Creating div-by-zero crash task...");
                os_create_task(task_crash_divzero, "Crash_Div", 512);
            } else if (c == 'm') {
                Serial.println("Creating bad-memory crash task...");
                os_create_task(task_crash_memory, "Crash_Mem", 512);
            } else if (c == 'p') {
                Serial.println();
                Serial.println("ID  NAME           STATE");
                for (int i = 0; i < os_get_task_count(); i++) {
                    Serial.print(i);
                    Serial.print("   ");
                    Serial.print(os_get_task_name(i));
                    Serial.print("     ");
                    TaskState s = os_get_task_state(i);
                    Serial.println(s == TASK_READY ? "READY" :
                                   s == TASK_RUNNING ? "RUNNING" :
                                   s == TASK_BLOCKED ? "BLOCKED" :
                                   s == TASK_TERMINATED ? "TERMINATED" : "?");
                }
            }
        }
        os_sleep(100);
    }
}

void setup()
{
    Serial.begin(115200);
    while (!Serial) { }

    Serial.println("=== Memory Protection Demo ===");
    Serial.println();
    Serial.println("This demo shows fault handling.");
    Serial.println("When a task crashes, only that task is terminated.");
    Serial.println("Other tasks continue running.");
    Serial.println();

    // Initialize fault handling
    fault_init();

    // Initialize OS
    os_init();

    // Create tasks
    os_create_task(task_led, "LED", 512);
    os_create_task(task_heartbeat, "Heartbeat", 512);
    os_create_task(task_shell, "Shell", 1024);

    Serial.println("Press 'd' for divide-by-zero crash");
    Serial.println("Press 'm' for bad memory access crash");
    Serial.println("Press 'p' to show task list");
    Serial.println();

    os_start();
}

void loop()
{
    // Never reached
}

src/os_fault.cpp — 170 lines

Open on GitHub

/**
 * os_fault.cpp - Fault Handler Implementation
 * Chapter 6: Memory Protection
 */

#include "os_fault.h"
#include "os_kernel.h"
#include <Arduino.h>

static volatile int g_fault_occurred = 0;
static volatile const char* g_fault_reason = "";
static volatile int g_faulted_task = -1;

// Forward declarations for vector table override
extern "C" __attribute__((naked)) void HardFault_Handler(void);
extern "C" void PendSV_Handler(void);
extern "C" void SysTick_Handler(void);

void fault_init(void)
{
    // Enable divide by zero trap
    SCB->CCR |= SCB_CCR_DIV_0_TRP_Msk;

    // Do NOT enable separate UsageFault/BusFault/MemFault handlers.
    // By leaving them disabled, all faults escalate to HardFault,
    // which we handle via the VTOR override below.

    // The Arduino framework copies the vector table to RAM (VTOR points to RAM).
    // We must overwrite the HardFault entry in the RAM vector table directly.
    // Also override PendSV and SysTick entries for the OS scheduler.
    uint32_t *vtor = (uint32_t *)SCB->VTOR;
    vtor[3] = (uint32_t)HardFault_Handler;   // Vector #3 = HardFault
    vtor[14] = (uint32_t)PendSV_Handler;     // Vector #14 = PendSV
    vtor[15] = (uint32_t)SysTick_Handler;    // Vector #15 = SysTick

    g_fault_occurred = 0;
    g_fault_reason = "";
}

const char* fault_get_reason(void)
{
    return (const char*)g_fault_reason;
}

int fault_occurred(void)
{
    return g_fault_occurred;
}

void fault_clear(void)
{
    g_fault_occurred = 0;
    g_fault_reason = "";
}

static void analyze_fault(void)
{
    uint32_t cfsr = SCB->CFSR;

    // Check Usage Fault Status Register (UFSR)
    if (cfsr & SCB_CFSR_DIVBYZERO_Msk) {
        g_fault_reason = "Divide by zero";
    } else if (cfsr & SCB_CFSR_UNALIGNED_Msk) {
        g_fault_reason = "Unaligned access";
    } else if (cfsr & SCB_CFSR_UNDEFINSTR_Msk) {
        g_fault_reason = "Undefined instruction";
    } else if (cfsr & SCB_CFSR_INVSTATE_Msk) {
        g_fault_reason = "Invalid state (Thumb bit)";
    } else if (cfsr & SCB_CFSR_INVPC_Msk) {
        g_fault_reason = "Invalid PC";
    }
    // Check Bus Fault Status Register (BFSR)
    else if (cfsr & SCB_CFSR_PRECISERR_Msk) {
        g_fault_reason = "Precise data bus error";
    } else if (cfsr & SCB_CFSR_IMPRECISERR_Msk) {
        g_fault_reason = "Imprecise data bus error";
    } else if (cfsr & SCB_CFSR_IBUSERR_Msk) {
        g_fault_reason = "Instruction bus error";
    }
    // Check Memory Management Fault Status Register (MMFSR)
    else if (cfsr & SCB_CFSR_DACCVIOL_Msk) {
        g_fault_reason = "Data access violation";
    } else if (cfsr & SCB_CFSR_IACCVIOL_Msk) {
        g_fault_reason = "Instruction access violation";
    }
    else {
        g_fault_reason = "Unknown fault";
    }

    // Clear fault flags
    SCB->CFSR = cfsr;
}

// Safe landing pad for terminated tasks after fault recovery
extern "C" void _fault_task_sink(void)
{
    while (1) {
        __WFI();
    }
}

// Flag to defer fault message printing to a safe context
static volatile int g_fault_pending_print = 0;
static volatile uint32_t g_fault_pc = 0;

extern "C" void HardFault_Handler_C(FaultFrame *frame)
{
    g_fault_occurred = 1;
    g_faulted_task = g_current_task;
    g_fault_pc = frame->pc;

    analyze_fault();

    // Terminate the faulted task and redirect PC to safe sink
    if (g_faulted_task > 0) {
        os_terminate_task(g_faulted_task);

        // Rewrite the stacked PC to a safe infinite loop so that
        // returning from the fault doesn't re-execute the faulting
        // instruction. The SysTick scheduler will switch away from
        // this terminated task on the next tick.
        frame->pc = (uint32_t)_fault_task_sink;
        frame->xpsr = 0x01000000;  // Thumb bit set

        // Defer printing to next safe context
        g_fault_pending_print = 1;
        return;
    }

    // If idle task or no task crashed, halt
    while (1) { }
}

// Call this from a task (e.g., shell) to print deferred fault info
void fault_print_pending(void)
{
    if (!g_fault_pending_print) return;
    g_fault_pending_print = 0;

    Serial.println();
    Serial.println("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!");
    Serial.println("!!!       FAULT DETECTED      !!!");
    Serial.println("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!");
    Serial.println();
    Serial.print("Task ");
    Serial.print(g_faulted_task);
    Serial.print(" (");
    Serial.print(os_get_task_name(g_faulted_task));
    Serial.println(") crashed!");
    Serial.print("Reason: ");
    Serial.println((const char*)g_fault_reason);
    Serial.print("PC at fault: 0x");
    Serial.println(g_fault_pc, HEX);
    Serial.println("Task terminated. Other tasks continue.");
    Serial.println();
}

extern "C" __attribute__((naked)) void HardFault_Handler(void)
{
    __asm volatile (
        "   TST     LR, #4              \n"  // Check which stack was used
        "   ITE     EQ                  \n"
        "   MRSEQ   R0, MSP             \n"  // MSP if LR bit 2 is 0
        "   MRSNE   R0, PSP             \n"  // PSP if LR bit 2 is 1
        "   PUSH    {LR}                \n"  // Save EXC_RETURN
        "   BL      HardFault_Handler_C \n"  // Call C handler (preserves LR on stack)
        "   POP     {LR}                \n"  // Restore EXC_RETURN
        "   BX      LR                  \n"  // Return from exception properly
    );
}

src/os_kernel.cpp — 219 lines

Open on GitHub

/**
 * os_kernel.cpp - Mini OS Kernel Implementation
 * Chapter 6: Memory Protection
 */

#include "os_kernel.h"
#include <Arduino.h>
#include <string.h>

TCB g_tasks[MAX_TASKS];
volatile int g_task_count = 0;
volatile int g_current_task = -1;
volatile int g_next_task = -1;
volatile uint32_t g_system_ticks = 0;

const uint32_t g_tcb_size = sizeof(TCB);

static uint32_t g_stack_pool[STACK_POOL_SIZE / 4];
static uint32_t g_stack_used;   // 切り出し済みのワード数

static void idle_task(void) { while (1) __WFI(); }

// タスク関数が return したときの受け皿。例外フレームの LR スロットは
// ここを指す (第3章 3.4)。EXC_RETURN を置く場所ではない。
static void task_exit(void)
{
    g_tasks[g_current_task].state = TASK_TERMINATED;
    os_yield();
    while (1) { }  // ここには到達しない
}

static uint32_t* init_task_stack(uint32_t *stack_top, void (*entry)(void))
{
    uint32_t *sp = stack_top;
    *(--sp) = 0x01000000;
    *(--sp) = (uint32_t)entry;
    *(--sp) = (uint32_t)task_exit;  // LR: タスクが return したときの戻り先
    *(--sp) = 0; *(--sp) = 0; *(--sp) = 0; *(--sp) = 0; *(--sp) = 0;
    *(--sp) = 0; *(--sp) = 0; *(--sp) = 0; *(--sp) = 0;
    *(--sp) = 0; *(--sp) = 0; *(--sp) = 0; *(--sp) = 0;
    return sp;
}

void os_init(void)
{
    memset(g_tasks, 0, sizeof(g_tasks));
    g_task_count = 0;
    g_current_task = -1;
    g_next_task = -1;
    g_system_ticks = 0;
    os_create_task(idle_task, "idle", IDLE_STACK_SIZE);
}

int os_create_task(void (*entry)(void), const char *name, uint32_t stack_size)
{
    if (g_task_count >= MAX_TASKS) return -1;
    int id = g_task_count;
    TCB *task = &g_tasks[id];
    task->id = id;
    task->state = TASK_READY;
    task->priority = id;
    task->entry = entry;
    task->wake_tick = 0;
    task->cpu_ticks = 0;
    strncpy(task->name, name, sizeof(task->name) - 1);
    if (stack_size == 0) {
        stack_size = DEFAULT_STACK_SIZE;
    }
    uint32_t words = (stack_size + 3) / 4;
    if (g_stack_used + words > STACK_POOL_SIZE / 4) {
        return -1;          // プールが尽きた。黙って縮めず、失敗として返す
    }
    g_stack_used += words;
    task->stack_size = stack_size;
    task->stack_base = &g_stack_pool[g_stack_used];   // スタックは上端から下へ伸びる
    task->sp = init_task_stack(task->stack_base, entry);
    g_task_count++;
    return id;
}

void os_schedule(void)
{
    for (int i = 0; i < g_task_count; i++) {
        if (g_tasks[i].state == TASK_BLOCKED && g_system_ticks >= g_tasks[i].wake_tick) {
            g_tasks[i].state = TASK_READY;
        }
    }

    int next = g_current_task;
    do {
        next = (next + 1) % g_task_count;
        if (g_tasks[next].state == TASK_READY || g_tasks[next].state == TASK_RUNNING) break;
    } while (next != g_current_task);

    if (next != g_current_task || g_current_task < 0) {
        if (g_current_task >= 0 && g_tasks[g_current_task].state == TASK_RUNNING) {
            g_tasks[g_current_task].state = TASK_READY;
        }
        g_tasks[next].state = TASK_RUNNING;
        g_next_task = next;
        SCB->ICSR |= SCB_ICSR_PENDSVSET_Msk;
    }
}

void os_yield(void) { os_schedule(); }
void os_sleep(uint32_t ms) {
    if (g_current_task > 0) {
        g_tasks[g_current_task].state = TASK_BLOCKED;
        g_tasks[g_current_task].wake_tick = g_system_ticks + ms;
        os_schedule();
    }
}
void os_suspend_task(int id) {
    if (id > 0 && id < g_task_count) {
        g_tasks[id].state = TASK_SUSPENDED;
        if (id == g_current_task) os_schedule();
    }
}
void os_resume_task(int id) {
    if (id > 0 && id < g_task_count && g_tasks[id].state == TASK_SUSPENDED) {
        g_tasks[id].state = TASK_READY;
    }
}
void os_terminate_task(int id) {
    if (id > 0 && id < g_task_count) {
        g_tasks[id].state = TASK_TERMINATED;
        if (id == g_current_task) os_schedule();
    }
}

uint32_t os_get_tick(void) { return g_system_ticks; }
int os_get_task_count(void) { return g_task_count; }
const char* os_get_task_name(int id) { return (id >= 0 && id < g_task_count) ? g_tasks[id].name : ""; }
TaskState os_get_task_state(int id) { return (id >= 0 && id < g_task_count) ? g_tasks[id].state : TASK_TERMINATED; }
int os_get_current_task(void) { return g_current_task; }

void os_start(void)
{
    NVIC_SetPriority(PendSV_IRQn, 0xFF);
    SysTick_Config(SystemCoreClock / 1000 * TIME_SLICE_MS);
    g_current_task = -1;
    g_next_task = 0;
    // Do NOT switch CONTROL to PSP here — PSP is not yet initialized.
    // PendSV returns with EXC_RETURN=0xFFFFFFFD, which automatically
    // switches thread mode to PSP after loading the first task's context.
    SCB->ICSR |= SCB_ICSR_PENDSVSET_Msk;
    while (1) { }
}

extern "C" void SysTick_Handler(void) {
    // 実際に経過した時間を、いま走っていたタスクの取り分として計上する。
    // os_schedule() 側で数えると os_yield() の回数まで混ざってしまう。
    if (g_current_task >= 0) {
        g_tasks[g_current_task].cpu_ticks += TIME_SLICE_MS;
    }
    g_system_ticks += TIME_SLICE_MS;
    os_schedule();
}

extern "C" __attribute__((naked)) void PendSV_Handler(void)
{
    __asm volatile (
        "   MRS     R0, PSP              \n"
        "   LDR     R1, =g_current_task  \n"
        "   LDR     R2, [R1]             \n"
        "   CMP     R2, #0               \n"
        "   BLT     _skip_save           \n"
        // Save R4-R11 only when there is a valid current task
        "   STMDB   R0!, {R4-R11}        \n"
        "   LDR     R3, =g_tasks         \n"
        "   LDR     R4, =g_tcb_size      \n"
        "   LDR     R4, [R4]             \n"
        "   MUL     R2, R2, R4           \n"
        "   ADD     R3, R3, R2           \n"
        "   STR     R0, [R3]             \n"
        "_skip_save:                     \n"
        "   LDR     R1, =g_next_task     \n"
        "   LDR     R2, [R1]             \n"
        "   LDR     R1, =g_current_task  \n"
        "   STR     R2, [R1]             \n"
        "   LDR     R3, =g_tasks         \n"
        "   LDR     R4, =g_tcb_size      \n"
        "   LDR     R4, [R4]             \n"
        "   MUL     R2, R2, R4           \n"
        "   ADD     R3, R3, R2           \n"
        "   LDR     R0, [R3]             \n"
        "   LDMIA   R0!, {R4-R11}        \n"
        "   MSR     PSP, R0              \n"
        "   LDR     LR, =0xFFFFFFFD      \n"
        "   BX      LR                   \n"
    );
}

// CPU使用率を取得（パーセント）
// 直前にこの関数を呼んだ時点からの差分で計算する。
// ps のようにタスクごとにループで呼ぶため、基準時刻もタスクごとに持つ。
int os_get_cpu_usage(int task_id)
{
    if (task_id < 0 || task_id >= g_task_count) {
        return -1;
    }

    static uint32_t last_total[MAX_TASKS] = {0};
    static uint32_t last_task_ticks[MAX_TASKS] = {0};

    uint32_t total = g_system_ticks;
    uint32_t delta_total = total - last_total[task_id];

    if (delta_total == 0) {
        return 0;
    }

    uint32_t delta_task = g_tasks[task_id].cpu_ticks - last_task_ticks[task_id];

    last_total[task_id] = total;
    last_task_ticks[task_id] = g_tasks[task_id].cpu_ticks;

    return (delta_task * 100) / delta_total;
}

On the board#

../_images/ch06_fault.gif — Commands are single letters: `p` lists the tasks, `d` creates `Crash_Div` (a division by zero), and `m` creates `Crash_Mem`, which writes to an invalid address (`0xFFFFFFFF`) after 5 s. Here `p` lists the tasks and `d` triggers a division by zero. After the fault `Heartbeat` keeps going, and only `Crash_Div` becomes `TERMINATED`.#

In the simulator#

Without the board, the same firmware running in the simulator looks like this.

../_images/sim_ch06_fault.gif — Sending `d` makes the `Crash_Div` task fault on a division by zero, and `FAULT DETECTED` with the cause is printed. L (Heartbeat) and the `[Heartbeat]` lines keep going. (Recorded in the simulator.)#

Break it#

Predict before you open each answer. The first one needs no code change: try it directly in Chapter 6 in the browser version. For the second, change the code, build it, and drop firmware.elf into the browser version.

Note

The outputs in the answers were captured by actually running the code in QEMU, the same emulator the browser version uses. They have not been checked on the real board yet.

1. Crash five times in a row#

Send d five times in a row, wait a little, then list the tasks with p.

Predict: how many times does FAULT DETECTED appear?

2. Turn off the divide-by-zero trap#

In fault_init() in src/os_fault.cpp, comment out the setting that makes a division by zero raise an exception.

-    SCB->CCR |= SCB_CCR_DIV_0_TRP_Msk;
+    // SCB->CCR |= SCB_CCR_DIV_0_TRP_Msk;

Predict: when you send d, what does 100 / 0 do?

Pitfalls#

(Collected from reader questions — ask via GitHub Issues.)