ICARUS OS — Background Checksum integrity monitor. More...

#include <stdint.h>
#include <stdbool.h>

Data Structures
struct	cs_region_t
	Descriptor for a monitored memory region. More...

Macros
#define	CS_MAX_REGIONS 8
	Maximum number of monitored memory regions.

Typedefs
typedef void(*	cs_mismatch_fn) (uint8_t region_idx, uint16_t expected, uint16_t actual)
	Mismatch callback signature.

Functions
void	cs_init (void)
	Initialize the checksum monitor.

void	cs_set_callback (cs_mismatch_fn fn)
	Register the mismatch callback.

bool	cs_add_region (uint8_t idx, const uint8_t *addr, uint32_t size)
	Add a memory region to the monitor.

bool	cs_enable (uint8_t idx, bool enabled)
	Enable or disable scanning of a region.

bool	cs_rebaseline (uint8_t idx)
	Re-compute and store the baseline CRC for a region.

uint8_t	cs_check_all (void)
	Scan all enabled regions and invoke the mismatch callback for any CRC failures.

bool	cs_get_region (uint8_t idx, cs_region_t *out)
	Read back a region's configuration.

uint8_t	cs_region_count (void)
	Return the number of registered (non-empty) regions.

void	__cs_init (void)
	Privileged implementation of cs_init().

void	__cs_set_callback (cs_mismatch_fn fn)
	Privileged implementation of cs_set_callback().

bool	__cs_add_region (uint8_t idx, const uint8_t *addr, uint32_t size)
	Privileged implementation of cs_add_region().

bool	__cs_enable (uint8_t idx, bool enabled)
	Privileged implementation of cs_enable().

bool	__cs_rebaseline (uint8_t idx)
	Privileged implementation of cs_rebaseline().

uint8_t	__cs_check_all (void)
	Privileged implementation of cs_check_all().

bool	__cs_get_region (uint8_t idx, cs_region_t *out)
	Privileged implementation of cs_get_region().

uint8_t	__cs_region_count (void)
	Privileged implementation of cs_region_count().

Detailed Description

ICARUS OS — Background Checksum integrity monitor.

Version: 0.1.0

Periodically computes CRC16-CCITT over registered memory regions and compares against baseline values captured at startup (or set by the application). Mismatches are reported through a user-supplied callback.

Typical use: monitor flash code segments, critical data tables, and SRAM guard patterns to detect bit-flips from radiation (SEU) or software corruption.

Memory placement:

Region table: DTCM_DATA_PRIV (privileged-only, zero wait-state)
Functions: ITCM_FUNC (zero wait-state instruction fetch)

Thread safety:: All public functions use enter_critical() / exit_critical(). cs_check_all() is designed to be called from a periodic task (e.g. 1 Hz from the FDIR monitor loop).

See also: icarus/crc.h for the underlying CRC16-CCITT implementation

Author: Souham Biswas

Date: 2026

Copyright: Copyright 2025-2026 Souham Biswas https://github.com/ironhide23586/icarus-os-core Licensed under the Apache License, Version 2.0

Definition in file cs.h.

Typedef Documentation

◆ cs_mismatch_fn

typedef void(* cs_mismatch_fn) (uint8_t region_idx, uint16_t expected, uint16_t actual)

Mismatch callback signature.

Parameters

[in]	region_idx	Index of the region that failed (0-based).
[in]	expected	Baseline CRC that was stored at registration.
[in]	actual	CRC computed during the latest scan.

The callback runs inside the critical section of cs_check_all(). Keep it short — typically just a fault injection call.

Definition at line 79 of file cs.h.

Function Documentation

◆ __cs_add_region()

bool __cs_add_region	(	uint8_t	idx,
		const uint8_t *	addr,
		uint32_t	size
	)

Privileged implementation of cs_add_region().

Parameters

[in]	idx	Region index.
[in]	addr	Start address.
[in]	size	Size in bytes.

Return values

true	Region registered and baseline CRC computed.
false	Invalid parameters.

Computes the baseline CRC immediately from the current memory contents using crc16_ccitt() (HW-accelerated on target, software fallback under HOST_TEST).

Definition at line 118 of file cs.c.

References cs_entry_t::addr, cs_entry_t::baseline, crc16_ccitt(), CS_MAX_REGIONS, cs_entry_t::enabled, regions, cs_entry_t::registered, and cs_entry_t::size.

Referenced by cs_add_region(), and SVC_Handler_C().

◆ __cs_check_all()

uint8_t __cs_check_all ( void )

Privileged implementation of cs_check_all().

Returns: Number of regions that failed the CRC check.

First checks cs_hw_ok; if the CRC engine itself is suspect, invokes the callback with region_idx = 0xFF (sentinel) and returns 1 without scanning any regions.

Otherwise iterates all enabled regions, recomputes CRC, and invokes the callback for each mismatch.

Definition at line 172 of file cs.c.

References crc16_ccitt(), cs_hw_ok, CS_MAX_REGIONS, cs_entry_t::enabled, mismatch_cb, and regions.

Referenced by cs_check_all(), and SVC_Handler_C().

◆ __cs_enable()

bool __cs_enable	(	uint8_t	idx,
		bool	enabled
	)

Privileged implementation of cs_enable().

Parameters

[in]	idx	Region index.
[in]	enabled	Enable/disable flag.

Definition at line 137 of file cs.c.

References CS_MAX_REGIONS, cs_entry_t::enabled, and regions.

Referenced by cs_enable(), and SVC_Handler_C().

◆ __cs_get_region()

bool __cs_get_region	(	uint8_t	idx,
		cs_region_t *	out
	)

Privileged implementation of cs_get_region().

Parameters

[in]	idx	Region index.
[out]	out	Destination descriptor.

Definition at line 204 of file cs.c.

References cs_region_t::addr, cs_entry_t::addr, cs_region_t::baseline, cs_entry_t::baseline, CS_MAX_REGIONS, cs_region_t::enabled, cs_entry_t::enabled, regions, cs_region_t::size, and cs_entry_t::size.

Referenced by cs_get_region(), and SVC_Handler_C().

◆ __cs_init()

void __cs_init ( void )

Privileged implementation of cs_init().

Clears all regions, runs the CRC self-test, and stores the result in cs_hw_ok.

Definition at line 91 of file cs.c.

References cs_hw_ok, cs_selftest(), mismatch_cb, and regions.

Referenced by cs_init(), and SVC_Handler_C().

◆ __cs_rebaseline()

bool __cs_rebaseline ( uint8_t idx )

Privileged implementation of cs_rebaseline().

Parameters

[in] idx Region index.

Recomputes the CRC from current memory and stores it as the new baseline. Call after a legitimate write to a monitored region.

Definition at line 152 of file cs.c.

References cs_entry_t::baseline, crc16_ccitt(), CS_MAX_REGIONS, and regions.

Referenced by cs_rebaseline(), and SVC_Handler_C().

◆ __cs_region_count()

uint8_t __cs_region_count ( void )

Privileged implementation of cs_region_count().

Returns: Number of registered (non-empty) region slots.

Definition at line 222 of file cs.c.

References CS_MAX_REGIONS, and regions.

Referenced by cs_region_count(), and SVC_Handler_C().

◆ __cs_set_callback()

void __cs_set_callback ( cs_mismatch_fn fn )

Privileged implementation of cs_set_callback().

Parameters

[in] fn Mismatch callback, or NULL to disable.

Definition at line 101 of file cs.c.

References mismatch_cb.

Referenced by cs_set_callback(), and SVC_Handler_C().

◆ cs_add_region()

bool cs_add_region	(	uint8_t	idx,
		const uint8_t *	addr,
		uint32_t	size
	)

Add a memory region to the monitor.

Parameters

[in]	idx	Region index (0 .. CS_MAX_REGIONS-1).
[in]	addr	Start address of the region.
[in]	size	Size in bytes (must be > 0).

Return values

true	Region registered; baseline CRC computed and stored.
false	Invalid index, NULL addr, or zero size.

Note: The baseline CRC is computed immediately from the current memory contents. Call this after the region is fully initialized (e.g. after flash boot or table activation).

Definition at line 1625 of file svc.c.

References __cs_add_region(), and SVC_CS_ADD_REGION.

◆ cs_check_all()

uint8_t cs_check_all ( void )

Scan all enabled regions and invoke the mismatch callback for any CRC failures.

Returns: Number of regions that failed the CRC check.

Note: Designed to be called periodically from a low-priority task (e.g. 1 Hz from the FDIR monitor loop).

Definition at line 1681 of file svc.c.

References __cs_check_all(), and SVC_CS_CHECK_ALL.

◆ cs_enable()

bool cs_enable	(	uint8_t	idx,
		bool	enabled
	)

Enable or disable scanning of a region.

Parameters

[in]	idx	Region index.
[in]	enabled	True to enable, false to disable.

Return values

true	Success.
false	Invalid index.

Definition at line 1645 of file svc.c.

References __cs_enable(), and SVC_CS_ENABLE.

◆ cs_get_region()

bool cs_get_region	(	uint8_t	idx,
		cs_region_t *	out
	)

Read back a region's configuration.

Parameters

[in]	idx	Region index.
[out]	out	Destination for the region descriptor.

Return values

true	Success.
false	Invalid index or out is NULL.

Definition at line 1697 of file svc.c.

References __cs_get_region(), and SVC_CS_GET_REGION.

◆ cs_init()

void cs_init ( void )

Initialize the checksum monitor.

Clears all regions and sets the mismatch callback to NULL.

Definition at line 1603 of file svc.c.

References __cs_init(), and SVC_CS_INIT.

◆ cs_rebaseline()

bool cs_rebaseline ( uint8_t idx )

Re-compute and store the baseline CRC for a region.

Parameters

[in] idx Region index.

Return values

true	Baseline updated.
false	Invalid index or region not registered.

Note: Call after a legitimate write to a monitored region (e.g. table activation) to prevent false mismatch reports.

Definition at line 1664 of file svc.c.

References __cs_rebaseline(), and SVC_CS_REBASELINE.

◆ cs_region_count()

uint8_t cs_region_count ( void )

Return the number of registered (non-empty) regions.

Definition at line 1716 of file svc.c.

References __cs_region_count(), and SVC_CS_REGION_COUNT.

◆ cs_set_callback()

void cs_set_callback ( cs_mismatch_fn fn )

Register the mismatch callback.

Parameters

[in] fn Function to call when a CRC mismatch is detected. Pass NULL to disable mismatch reporting.

Definition at line 1611 of file svc.c.

References __cs_set_callback(), and SVC_CS_SET_CALLBACK.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ cs_mismatch_fn

Function Documentation

◆ __cs_add_region()

◆ __cs_check_all()

◆ __cs_enable()

◆ __cs_get_region()

◆ __cs_init()

◆ __cs_rebaseline()

◆ __cs_region_count()

◆ __cs_set_callback()

◆ cs_add_region()

◆ cs_check_all()

◆ cs_enable()

◆ cs_get_region()

◆ cs_init()

◆ cs_rebaseline()

◆ cs_region_count()

◆ cs_set_callback()