Reboot Module - User Guide

What is Reboot?

The Reboot module requests a controlled system restart. It's the mechanism you call when unrecoverable errors require a fresh start. The integrator provides an OSAdapter that actually performs the reset (watchdog, CPU reset, supervisory processor command, etc.).

Key idea: When recovery is impossible, restart cleanly rather than hang.

Quick Start

1. Register OSAdapter at Startup

Integrator supplies platform-specific reboot implementation:

rte_status_t platform_reboot(uint16_t reason_code) {
    // Backend-specific: trigger CPU reset, watchdog, etc.
    // This function must NOT return on success
 
    // Example: use hardware watchdog
    watchdog_enable_without_pet(1ms);  // Timeout in 1ms
    while (1) {}  // Wait for watchdog to reset
 
    return RTE_STATUS_NOT_SUPPORTED;  // Only if watchdog unavailable
}
 
rte_osadapter_reboot_t OSAdapter = {
    .request = platform_reboot
};
 
rte_osadapter_reboot_register(&OSAdapter);

2. Request Reboot on Critical Error

if (unrecoverable_error_detected) {
    rte_status_t rc = rte_reboot_request(APP_REASON_CRITICAL_ERROR);
    // This function typically does not return (CPU resets)
    // If it does return, error code indicates why reboot failed
    if (rc != RTE_STATUS_OK) {
        log_critical("Reboot failed: %s", rte_status_to_string(rc));
    }
}

Integration with Safe-State

Typically called from RTE_REBOOT macro or safe-state handler:

void my_safestate_handler(rte_safestate_level_t level, ...) {
    if (level == RTE_SAFESTATE_LEVEL_REBOOT) {
        log_critical("Initiating controlled restart");
        flush_logs();
        close_resources();
 
        // Request reboot - does not return
        rte_reboot_request(APP_REASON_SAFESTATE_REBOOT);
 
        // If execution reaches here, reboot failed
        // Enter infinite loop as fallback
        while (1) {}
    }
}

Reason Codes

Pass reason code (16-bit) to identify why reboot was requested:

#define APP_REASON_CRITICAL_ERROR 1
#define APP_REASON_WATCHDOG_TIMEOUT 2
#define APP_REASON_MEMORY_CORRUPTION 3
#define APP_REASON_UNRECOVERABLE_FAULT 4
#define APP_REASON_FIRMWARE_UPDATE 5

OSAdapter can persist reason code to NVM for post-reboot diagnostics.

Practical Examples

Example 1: Watchdog-Triggered Reboot

void watchdog_handler(void *context) {
    app_t *app = (app_t *)context;
    log_critical("Watchdog timeout - system hung");
    log_critical("  Cycle count: %u", app->cycle_count);
    log_critical("  Initiating controlled reboot");
 
    rte_reboot_request(APP_REASON_WATCHDOG_TIMEOUT);
    // Does not return (CPU resets)
}

Example 2: Memory Corruption Detection

void check_memory_integrity(void) {
    uint32_t checksum = compute_memory_checksum(&heap_start, heap_size);
    if (checksum != expected_checksum) {
        log_critical("Memory corruption detected!");
        log_critical("  Computed: 0x%x", checksum);
        log_critical("  Expected: 0x%x", expected_checksum);
        log_critical("  Rebooting...");
 
        rte_reboot_request(APP_REASON_MEMORY_CORRUPTION);
        // Does not return
    }
}

Example 3: Reboot with Fallback

void request_reboot_with_timeout(uint32_t timeout_ms) {
    rte_watchdog_t fallback_wd = setup_timeout_watchdog(timeout_ms);
    rte_watchdog_start(fallback_wd);
 
    rte_status_t rc = rte_reboot_request(APP_REASON_SHUTDOWN);
 
    // If reboot failed, watchdog will force reset
    if (rc != RTE_STATUS_OK) {
        log_error("Reboot request failed: %s", rte_status_to_string(rc));
        // Don't kick watchdog - let it timeout and force reset
        while (1) {}
    }
}

Best Practices

1. Register OSAdapter at startup
   • Before any code can request reboot
   • Platform-specific implementation
   • Must handle lack of hardware support gracefully
2. Use specific reason codes
   • Not just 0
   • Aids post-reboot diagnostics
   • OSAdapter can log/persist for analysis
3. Prepare for non-return
   • rte_reboot_request() typically doesn't return
   • Don't rely on execution continuing
   • Any final cleanup should happen before calling
4. Have fallback mechanism
   • Use watchdog timeout as fallback
   • Ensures reset happens even if OSAdapter fails
   • Better than hanging indefinitely
5. Only on unrecoverable errors
   • Not for transient failures
   • Not for user-initiated shutdown (use graceful exit)
   • Only when system state is unsafe to continue

See Also

• Reboot Module - Architecture for internal design
• Safe-State Module - User Guide for RTE_REBOOT macro
• Watchdog Module - User Guide for watchdog-triggered reset