Skip to content

System Health ​

Runtime/health and reset reporting.

Boot-time counters held in the .cw_reboot_safe RAM section (survives soft-reset, lost on cold-boot or sub-retention brown-out) plus a latched reset-cause from the HAL reset driver. Intended for cloud-reportable device-health metrics.

Types ​

Name
structosFaultRecord_t
CPU state at the last crash.
structosOomRecord_t
Evidence of one failed heap allocation.
structosWatchdogRecord_t
Evidence of one watchdog bite.
enumosFaultKind_t
What ended the run. Every kind is reported as cwResetCrash.

Functions Overview ​

Name
uint32_tosGetFreeHeapSize(void )
Current free heap (bytes) — thin wrapper for xPortGetFreeHeapSize().
uint32_tosGetMinimumEverFreeHeapSize(void )
Lowest free-heap watermark since boot (bytes).
uint32_tosGetRebootCount(void )
Number of boots since the last cold-start. Increments once per boot in cw_health_init_early(). Resets to 1 on power-on / sub-retention brown-out (when the .cw_reboot_safe blob fails magic+checksum check).
uint32_tosGetCrashCount(void )
Number of crashes (HardFault / UsageFault / MemManage / BusFault) since the last cold-start.
uint8_tosGetResetCause(void )
Latched reset cause for the current boot. SW-intent (set by the crash handlers / watchdog / osReboot before the actual reset) takes precedence over the HW cause. Values mirror libcoldwave CW_RESET_* constants.
voidcw_stack_telemetry_dump(void )
intosGetFaultRecord(osFaultRecord_t * out)
Copies the record of the last crash since the last cold start.
uint32_tosGetOomCount(void )
Number of failed heap allocations since the last cold start.
intosGetOomRecord(osOomRecord_t * out)
Copies the pending OOM record, i.e. the first failure since the last cold start or since osClearOomRecord(). Later failures only increment the counter: the first one is the informative one, the rest are usually its consequences.
voidosClearOomRecord(void )
Acknowledges the pending record so the next failure is captured again. The counter is unaffected.
intosGetWatchdogRecord(osWatchdogRecord_t * out)
Copies the unacknowledged record.
voidosClearWatchdogRecord(void )
Acknowledges the record.

Defines ​

Name
OS_HAS_FAULT_RECORDDefined when osGetFaultRecord is available.
OS_FAULT_THREAD_NAME_LENSize of osFaultRecord_t::thread, including the terminating NUL.
OS_OOM_THREAD_NAME_LENSize of osOomRecord_t::thread, including the terminating NUL.
OS_WDOG_THREAD_NAME_LENSize of osWatchdogRecord_t::thread, including the terminating NUL.

Types Documentation ​

enum osFaultKind_t ​

EnumeratorDescription
osFaultNone
osFaultHard
osFaultMemManage
osFaultBus
osFaultUsage
osFaultStackOverflow
osFaultAssert
osFaultPureVirtual
osFaultOomdetails in osOomRecord_t

What ended the run. Every kind is reported as cwResetCrash.

Function Details ​

function osGetFreeHeapSize ​

cpp
uint32_t osGetFreeHeapSize(
    void 
)

Current free heap (bytes) — thin wrapper for xPortGetFreeHeapSize().

function osGetMinimumEverFreeHeapSize ​

cpp
uint32_t osGetMinimumEverFreeHeapSize(
    void 
)

Lowest free-heap watermark since boot (bytes).

function osGetRebootCount ​

cpp
uint32_t osGetRebootCount(
    void 
)

Number of boots since the last cold-start. Increments once per boot in cw_health_init_early(). Resets to 1 on power-on / sub-retention brown-out (when the .cw_reboot_safe blob fails magic+checksum check).

function osGetCrashCount ​

cpp
uint32_t osGetCrashCount(
    void 
)

Number of crashes (HardFault / UsageFault / MemManage / BusFault) since the last cold-start.

function osGetResetCause ​

cpp
uint8_t osGetResetCause(
    void 
)

Latched reset cause for the current boot. SW-intent (set by the crash handlers / watchdog / osReboot before the actual reset) takes precedence over the HW cause. Values mirror libcoldwave CW_RESET_* constants.

Return: uint8_t value in the CW_RESET_* domain.

function cw_stack_telemetry_dump ​

cpp
void cw_stack_telemetry_dump(
    void 
)

Logs one line per thread with its stack high-watermark (minimum ever remaining headroom in bytes). Useful from shells / support dumps to right-size stacks empirically.

function osGetFaultRecord ​

cpp
int osGetFaultRecord(
    osFaultRecord_t * out
)

Copies the record of the last crash since the last cold start.

Parameters:

  • out destination; may be NULL to only query whether one exists.

Return: 1 if a record exists, 0 otherwise.

function osGetOomCount ​

cpp
uint32_t osGetOomCount(
    void 
)

Number of failed heap allocations since the last cold start.

function osGetOomRecord ​

cpp
int osGetOomRecord(
    osOomRecord_t * out
)

Copies the pending OOM record, i.e. the first failure since the last cold start or since osClearOomRecord(). Later failures only increment the counter: the first one is the informative one, the rest are usually its consequences.

Parameters:

  • out destination; may be NULL to only query whether a record is pending.

Return: 1 if a record is pending, 0 otherwise.

function osClearOomRecord ​

cpp
void osClearOomRecord(
    void 
)

Acknowledges the pending record so the next failure is captured again. The counter is unaffected.

function osGetWatchdogRecord ​

cpp
int osGetWatchdogRecord(
    osWatchdogRecord_t * out
)

Copies the unacknowledged record.

Parameters:

  • out destination; may be NULL to only query whether one is pending.

Return: 1 if a record is pending, 0 otherwise.

function osClearWatchdogRecord ​

cpp
void osClearWatchdogRecord(
    void 
)

Acknowledges the record.

Macros Documentation ​

define OS_HAS_FAULT_RECORD ​

cpp
#define OS_HAS_FAULT_RECORD (1)

Defined when osGetFaultRecord is available.

define OS_FAULT_THREAD_NAME_LEN ​

cpp
#define OS_FAULT_THREAD_NAME_LEN (12)

Size of osFaultRecord_t::thread, including the terminating NUL.

define OS_OOM_THREAD_NAME_LEN ​

cpp
#define OS_OOM_THREAD_NAME_LEN (16)

Size of osOomRecord_t::thread, including the terminating NUL.

define OS_WDOG_THREAD_NAME_LEN ​

cpp
#define OS_WDOG_THREAD_NAME_LEN (12)

Size of osWatchdogRecord_t::thread, including the terminating NUL.