rte_watchdog.c

Go to the documentation of this file.

#include "rte/redundancy/watchdog/rte_watchdog.h"
 
#include "rte/utils/lifecycle/rte_lifecycle.h"
#include "rte/oal/log/rte_log.h"
#include "rte/utils/safestate/rte_safestate.h"
#include "rte/oal/timer/rte_timer.h"
 
#include <stdbool.h>
#include <string.h>
 
#ifndef RTE_WATCHDOG_MAX_COUNT
#define RTE_WATCHDOG_MAX_COUNT 8U
#endif

typedef struct rte_watchdog_s
{
    uint8_t                in_use;       
    uint8_t                active;       
    uint8_t                fired;      
    rte_watchdog_config_t config;        
    rte_timestamp_ms_t    deadline_ms;   
    rte_timestamp_ms_t    last_kick_ms;  
    uint32_t               kicks;         
    uint32_t               fires;         
    uint32_t               recoveries;    
} rte_watchdog_s;

static rte_watchdog_s g_watchdog_pool[RTE_WATCHDOG_MAX_COUNT];
static uint8_t          g_manager_initialized = 0U;
 
/* ============================================================================
 * Internal helpers
 * ========================================================================== */

static bool is_valid_handle(rte_watchdog_t watchdog)
{
    const rte_watchdog_s *slot = (const rte_watchdog_s *)watchdog;
 
    return (slot != NULL) && (slot >= &g_watchdog_pool[0]) && (slot < &g_watchdog_pool[RTE_WATCHDOG_MAX_COUNT])
           && (slot->in_use != 0U);
}

static bool is_valid_action(rte_watchdog_action_t action)
{
    bool valid;
 
    switch (action)
    {
        case RTE_WATCHDOG_ACTION_LOG:
        case RTE_WATCHDOG_ACTION_SAFESTATE:
        case RTE_WATCHDOG_ACTION_REBOOT:
        case RTE_WATCHDOG_ACTION_FAILOVER:
        case RTE_WATCHDOG_ACTION_CUSTOM:
            valid = true;
            break;
        default:
            valid = false;
            break;
    }
    return valid;
}

static bool is_supervising(const rte_watchdog_s *slot)
{
    return (slot->in_use != 0U) && (slot->active != 0U) && (slot->fired == 0U);
}

static uint32_t first_supervising_index(void)
{
    uint32_t found = (uint32_t)RTE_WATCHDOG_MAX_COUNT;
    uint32_t i;
 
    for (i = 0U; (i < (uint32_t)RTE_WATCHDOG_MAX_COUNT) && (found == (uint32_t)RTE_WATCHDOG_MAX_COUNT); i++)
    {
        if (is_supervising(&g_watchdog_pool[i]))
        {
            found = i;
        }
    }
    return found;
}
 
/* ============================================================================
 * API: Watchdog Manager
 * ========================================================================== */
 
rte_status_t rte_watchdog_manager_initialize(void)
{
    if (g_manager_initialized == 0U)
    {
        (void)memset(g_watchdog_pool, 0, sizeof(g_watchdog_pool));
        g_manager_initialized = 1U;
        rte_log_write(RTE_LOG_LEVEL_INFO, "watchdog", "manager initialized");
    }
    return RTE_STATUS_OK;
}
 
rte_status_t rte_watchdog_manager_shutdown(void)
{
    size_t i;
 
    for (i = 0U; i < (size_t)RTE_WATCHDOG_MAX_COUNT; i++)
    {
        g_watchdog_pool[i].active = 0U;
    }
    g_manager_initialized = 0U;
    rte_log_write(RTE_LOG_LEVEL_INFO, "watchdog", "manager shut down");
    return RTE_STATUS_OK;
}
 
/* ============================================================================
 * API: Core Watchdog Operations
 * ========================================================================== */
 
rte_status_t rte_watchdog_create(rte_watchdog_t *handle_out, const rte_watchdog_config_t *config)
{
    size_t i;
 
    if ((handle_out == NULL) || (config == NULL) || (config->timeout_ms == 0U) || !is_valid_action(config->action))
    {
        return RTE_STATUS_INVALID_PARAM;
    }
    if (((config->action == RTE_WATCHDOG_ACTION_CUSTOM) || (config->action == RTE_WATCHDOG_ACTION_FAILOVER))
        && (config->custom_action == NULL))
    {
        /* FAILOVER requires a real handler just like CUSTOM does (see
         * rte_watchdog_timeout_handler()'s own doc) - a FAILOVER watchdog
         * with no handler wired up can only ever log, which is what
         * ACTION_LOG is already for; requiring custom_action here catches
         * that misconfiguration at create() time instead of silently
         * degrading to a log line the first time it actually fires. */
        return RTE_STATUS_INVALID_PARAM;
    }
    if (g_manager_initialized == 0U)
    {
        return RTE_STATUS_NOT_INITIALIZED;
    }
    {
        /* REQ-LIFECYCLE-001 (ADR-026): a watchdog is a setup-only resource - refuse once the
         * application's setup phase has been locked. */
        rte_status_t lifecycle_status = rte_lifecycle_check_setup_allowed();
 
        if (lifecycle_status != RTE_STATUS_OK)
        {
            return lifecycle_status;
        }
    }
 
    for (i = 0U; i < (size_t)RTE_WATCHDOG_MAX_COUNT; i++)
    {
        if (g_watchdog_pool[i].in_use == 0U)
        {
            (void)memset(&g_watchdog_pool[i], 0, sizeof(g_watchdog_pool[i]));
            g_watchdog_pool[i].in_use = 1U;
            g_watchdog_pool[i].config = *config;
            *handle_out = (rte_watchdog_t)&g_watchdog_pool[i];
            rte_log_write(RTE_LOG_LEVEL_INFO, config->name, "watchdog created");
            return RTE_STATUS_OK;
        }
    }
    return RTE_STATUS_RESOURCE_EXHAUSTED;
}
 
rte_status_t rte_watchdog_start(rte_watchdog_t watchdog)
{
    rte_watchdog_s *slot = (rte_watchdog_s *)watchdog;
    rte_timestamp_ms_t now_ms = 0U;
    rte_status_t status;
 
    if (!is_valid_handle(watchdog))
    {
        status = RTE_STATUS_INVALID_PARAM;
    }
    else
    {
        /* REQ-WATCHDOG-003: a failed clock read is returned as-is and the
         * watchdog is not armed - arming against a deadline computed from a
         * made-up "now" (0) would create a watchdog that either fires at
         * once or never, neither of which the caller asked for. */
        status = rte_timer_now(&now_ms);
        if (status == RTE_STATUS_OK)
        {
            slot->active = 1U;
            slot->fired = 0U;
            slot->deadline_ms = now_ms + slot->config.timeout_ms;
            slot->last_kick_ms = now_ms;
        }
    }
    return status;
}
 
rte_status_t rte_watchdog_stop(rte_watchdog_t watchdog)
{
    rte_watchdog_s *slot = (rte_watchdog_s *)watchdog;
 
    if (!is_valid_handle(watchdog))
    {
        return RTE_STATUS_INVALID_PARAM;
    }
    slot->active = 0U;
    return RTE_STATUS_OK;
}
 
rte_status_t rte_watchdog_kick(rte_watchdog_t watchdog)
{
    rte_watchdog_s *slot = (rte_watchdog_s *)watchdog;
    rte_timestamp_ms_t now_ms = 0U;
    rte_status_t status;
 
    if (!is_valid_handle(watchdog))
    {
        status = RTE_STATUS_INVALID_PARAM;
    }
    else if ((slot->active == 0U) || (slot->fired != 0U))
    {
        /* Not running, or already fired and awaiting an explicit
         * start() before it can be kicked again - this codebase's real
         * status enum has no generic RTE_STATUS_ERROR (see
         * rte_status.h); RTE_STATUS_INTERNAL_ERROR is the closest
         * "kick while not in a kickable state" signal available. */
        status = RTE_STATUS_INTERNAL_ERROR;
    }
    else
    {
        /* REQ-WATCHDOG-003: a failed clock read is returned as-is; the
         * deadline stays where the last good read put it and the kick is
         * not counted, so a clock fault cannot be mistaken for liveness. */
        status = rte_timer_now(&now_ms);
        if (status == RTE_STATUS_OK)
        {
            slot->deadline_ms = now_ms + slot->config.timeout_ms;
            slot->last_kick_ms = now_ms;
            slot->kicks++;
        }
    }
    return status;
}
 
rte_status_t rte_watchdog_get_status(rte_watchdog_t watchdog, rte_watchdog_status_t *status_out)
{
    const rte_watchdog_s *slot = (const rte_watchdog_s *)watchdog;
    rte_timestamp_ms_t now_ms = 0U;
    rte_status_t status;
 
    if (!is_valid_handle(watchdog) || (status_out == NULL))
    {
        status = RTE_STATUS_INVALID_PARAM;
    }
    else
    {
        /* REQ-WATCHDOG-003: no partial read-out - the two time fields need
         * the clock, so a failed read returns its status and leaves
         * *status_out exactly as the caller passed it. */
        status = rte_timer_now(&now_ms);
        if (status == RTE_STATUS_OK)
        {
            status_out->active = slot->active;
            status_out->kicks = slot->kicks;
            status_out->fires = slot->fires;
            status_out->recoveries = slot->recoveries;
            status_out->time_since_last_kick =
                (rte_duration_ms_t)((now_ms >= slot->last_kick_ms) ? (now_ms - slot->last_kick_ms) : 0U);
            status_out->time_until_fire =
                (rte_duration_ms_t)((slot->deadline_ms > now_ms) ? (slot->deadline_ms - now_ms) : 0U);
        }
    }
    return status;
}
 
rte_status_t rte_watchdog_destroy(rte_watchdog_t watchdog)
{
    rte_watchdog_s *slot = (rte_watchdog_s *)watchdog;
 
    if (!is_valid_handle(watchdog))
    {
        return RTE_STATUS_INVALID_PARAM;
    }
    slot->active = 0U;
    slot->in_use = 0U;
    return RTE_STATUS_OK;
}
 
/* ============================================================================
 * Internal: Timeout Dispatch
 * ========================================================================== */
 
void rte_watchdog_timeout_handler(uint32_t watchdog_id)
{
    rte_watchdog_s *slot;
 
    if (watchdog_id >= (uint32_t)RTE_WATCHDOG_MAX_COUNT)
    {
        return;
    }
    slot = &g_watchdog_pool[watchdog_id];
    if ((slot->in_use == 0U) || (slot->active == 0U) || (slot->fired != 0U))
    {
        return;
    }
 
    slot->fired = 1U;
    slot->fires++;
 
    switch (slot->config.action)
    {
        case RTE_WATCHDOG_ACTION_LOG:
            rte_log_write(RTE_LOG_LEVEL_ERROR, slot->config.name, "watchdog timeout");
            break;
        case RTE_WATCHDOG_ACTION_SAFESTATE:
            slot->recoveries++;
            rte_log_write(RTE_LOG_LEVEL_ERROR, slot->config.name, "watchdog timeout - entering SAFE state");
            rte_safestate_enter(RTE_SAFESTATE_LEVEL_SAFE, RTE_SAFESTATE_REASON_UNSPECIFIED, __FILE__,
                                  (int32_t)__LINE__, slot->config.name);
            break; /* Not statically unreachable: rte_safestate_enter() has no
                    * [[noreturn]]/_Noreturn attribute, so the compiler cannot
                    * prove this dead - kept for switch-statement completeness. */
        case RTE_WATCHDOG_ACTION_REBOOT:
            slot->recoveries++;
            rte_log_write(RTE_LOG_LEVEL_ERROR, slot->config.name, "watchdog timeout - requesting reboot");
            rte_safestate_enter(RTE_SAFESTATE_LEVEL_REBOOT, RTE_SAFESTATE_REASON_UNSPECIFIED, __FILE__,
                                  (int32_t)__LINE__, slot->config.name);
            break; /* Same non-return note as SAFESTATE above. */
        case RTE_WATCHDOG_ACTION_FAILOVER:
            slot->recoveries++;
            rte_log_write(RTE_LOG_LEVEL_ERROR, slot->config.name, "watchdog timeout - failover requested");
            /* rte_watchdog_create() requires config.custom_action != NULL
             * for this action (see its own doc) - dispatched exactly like
             * ACTION_CUSTOM, just under a name that documents *why* the
             * integrator registered this watchdog (loss of a redundant
             * peer/channel) rather than *how* it reacts, which is
             * identical to CUSTOM's own mechanism. This used to be a dead
             * stub ("no generic failover primitive in this framework;
             * caller must poll rte_watchdog_get_status()") - replaced
             * once a real integrator (safeAPIRBC2oo2's dual-channel A/B
             * link) needed exactly this reaction and found nothing to
             * call. */
            if (slot->config.custom_action != NULL)
            {
                slot->config.custom_action(slot->config.context);
            }
            break;
        case RTE_WATCHDOG_ACTION_CUSTOM:
            slot->recoveries++;
            if (slot->config.custom_action != NULL)
            {
                slot->config.custom_action(slot->config.context);
            }
            break;
        default: /* GCOVR_EXCL_LINE - see rationale below */
            /* Defense-in-depth, not a reachable API path:
             * rte_watchdog_create() rejects any config.action that fails
             * is_valid_action() before a slot is ever populated, so a live
             * slot's action is always one of the 5 named cases above.
             * There is no public way to mutate an already-created slot's
             * action, so this default cannot be reached by any caller -
             * kept for switch-statement completeness against a future
             * rte_watchdog_action_t value, not because it is exercised
             * today. See docs/COVERAGE_REPORT.md for the accepted-
             * exception rationale (this is one of the project's two
             * documented gaps against the 100% branch coverage target). */
            rte_log_write(RTE_LOG_LEVEL_ERROR, slot->config.name, "watchdog timeout - unrecognized action"); /* GCOVR_EXCL_LINE */
            break; /* GCOVR_EXCL_LINE */
    }
}
 
/* ============================================================================
 * Timer Integration
 * ========================================================================== */
 
void rte_watchdog_timer_tick(void)
{
    /* Polling design, not an ISR/hardware-timer callback: this framework's
     * only portable time source is rte_timer_now() (a plain "read the
     * clock" query, not a way to register a recurring OS-level interrupt
     * across every target this framework claims to support - POSIX,
     * QNX, bare-metal SysTick, etc.). Giving this module its own
     * platform-specific interrupt setup would duplicate what
     * rte::timer already exists to abstract, and would break the
     * "OSAdapters are integrator-supplied" philosophy (ADR-005) for a
     * module whose own header was never given an OSAdapter vtable. Instead:
     * whatever already runs periodically in the integrating application
     * (its own rte_timer periodic callback, or just its own main loop)
     * is expected to call this function regularly - each call is an O(N)
     * scan (N = RTE_WATCHDOG_MAX_COUNT, a small fixed pool) comparing
     * each active watchdog's deadline against the current time. */
    rte_timestamp_ms_t now_ms = 0U;
 
    if (g_manager_initialized != 0U)
    {
        if (rte_timer_now(&now_ms) != RTE_STATUS_OK)
        {
            /* REQ-WATCHDOG-004: the clock this whole module measures with
             * has failed. If any watchdog is supervising right now, its
             * deadline can no longer be checked - and a watchdog that can
             * never expire is exactly the silent failure watchdogs exist to
             * prevent - so the failed time base is itself treated as a
             * fired SAFE-level watchdog (logged under the first supervising
             * slot's name). With nothing supervising there is nothing being
             * silently defeated, and the tick stays a no-op. */
            const uint32_t supervising = first_supervising_index();
 
            if (supervising < (uint32_t)RTE_WATCHDOG_MAX_COUNT)
            {
                /* A NULL name (never validated by create()) only changes
                 * the log text; the decision above does not depend on it. */
                const char *name = g_watchdog_pool[supervising].config.name;
 
                if (name == NULL)
                {
                    name = "(unnamed)";
                }
                rte_log_write(RTE_LOG_LEVEL_ERROR, name, "watchdog clock failed - entering SAFE state");
                rte_safestate_enter(RTE_SAFESTATE_LEVEL_SAFE, RTE_SAFESTATE_REASON_CLOCK_FAILED, __FILE__,
                                      (int32_t)__LINE__, name);
            }
        }
        else
        {
            uint32_t i;
 
            for (i = 0U; i < (uint32_t)RTE_WATCHDOG_MAX_COUNT; i++)
            {
                if (is_supervising(&g_watchdog_pool[i]) && (now_ms >= g_watchdog_pool[i].deadline_ms))
                {
                    rte_watchdog_timeout_handler(i);
                }
            }
        }
    }
}