On-silicon FIPS 180-4 known-answer test for the RSIP HASH engine. More...

#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_err.h"
#include "ra8_isr.h"
#include "ra8_rsip_core.h"
#include "ra8_time.h"

Include dependency graph for main.c:

Enumerations
enum	kat_const_t : uint32_t { k_kat_baud = 115200U , k_kat_period_ms = 1000U }
	Demo tunables. More...
enum	kat_msg_len_t : uint8_t { k_kat_msg2_len = 56U }
	Length of the 56-byte NIST two-block message (excludes the NUL). More...

Functions
static void	internal_kat_panic_halt (void)
	Park the processor after fatal setup or KAT control-flow failure.
static void	internal_kat_setup_or_halt (void)
	Initialize clocks, timing, console, and status LEDs for the KAT.
static bool	internal_kat_one (const uint8_t msg, uint32_t len, const uint8_t expect)
	Hash one message on the RSIP engine and compare to a known answer.
void	main (void)
	The application entry point Reset_Handler hands control to.

Variables
static const uint8_t	s_msg_abc [] = {'a', 'b', 'c'}
	NIST vector 2 input: "abc".
static const uint8_t	s_msg_two_block [] = "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"
	NIST vector 3 input: the 448-bit two-block message.
static const uint8_t	s_exp_empty [k_ra8_rsip_sha256_digest_bytes]
	Expected SHA-256("") – FIPS 180-4.
static const uint8_t	s_exp_abc [k_ra8_rsip_sha256_digest_bytes]
	Expected SHA-256("abc") – FIPS 180-4.
static const uint8_t	s_exp_two_block [k_ra8_rsip_sha256_digest_bytes]
	Expected SHA-256(56-byte two-block message) – FIPS 180-4.
static const uint8_t	s_kat_msg_ok [] = "rsip sha256: KAT OK\r\n"
	HIL verdict emitted after all SHA-256 vectors pass.
static const uint8_t	s_kat_msg_fail [] = "rsip sha256: KAT FAIL\r\n"
	HIL verdict emitted after one or more SHA-256 vectors fail.

Detailed Description

On-silicon FIPS 180-4 known-answer test for the RSIP HASH engine.

Tag: [Ring 6 / APP] {World: S}

Validates ra8_rsip_sha256 – the exact primitive ra8_rot uses to re-compute an image digest on silicon – against the published FIPS 180-4 NIST vectors, running on the real EK-RA8D2 hardware. ra8_rsip_sha256 is backed by the in-tree software SHA-256: the RSIP-E50D HASH hardware has no usable register interface (HUM Ch 52 documents none) and is non-functional on silicon – this app first proved that, then the driver was fixed to route the digest through software (see libs/ra8_hal/src/ra8_rsip.c). The software backend is the working implementation until the FSP procedural RSIP driver is ported.

Vectors (FIPS 180-4):

"" -> e3b0c442...7852b855
"abc" -> ba7816bf...f20015ad
56-byte two-block message -> 248d6a61...19db06c1

Reporting:

LED1 toggles on every all-vectors-pass cycle; LED2 latches on any failure.
"rsip sha256: KAT OK" / "rsip sha256: KAT FAIL" over SCI8 (115200 8N1, J-Link OB CDC), scraped by the HIL rig (hil.conf).

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file main.c.

Enumeration Type Documentation

◆ kat_const_t

enum kat_const_t : uint32_t

Demo tunables.

Enumerator
k_kat_baud	Kat baud.
k_kat_period_ms	Kat period ms.

Definition at line 46 of file main.c.

◆ kat_msg_len_t

enum kat_msg_len_t : uint8_t

Length of the 56-byte NIST two-block message (excludes the NUL).

Enumerator
k_kat_msg2_len	Kat msg2 length.

Definition at line 52 of file main.c.

Function Documentation

◆ internal_kat_one()

bool internal_kat_one	(	const uint8_t *	msg,
		uint32_t	len,
		const uint8_t *	expect )

staticnodiscard

Hash one message on the RSIP engine and compare to a known answer.

Computes a bounded SHA-256 digest into local storage and compares all digest bytes with the supplied FIPS 180-4 known answer.

Parameters

[in]	msg	Message bytes; may be NULL only when `len` is 0.
[in]	len	Message length in bytes.
[in]	expect	k_ra8_rsip_sha256_digest_bytes expected digest; non-NULL.

Returns: true iff the engine digest matches expect exactly.

Return values

true	Hashing succeeded and every digest byte matched `expect`.
false	Hashing failed or at least one digest byte differed.

Precondition: expect addresses k_ra8_rsip_sha256_digest_bytes readable bytes.; The RSIP engine is initialised (ra8_rsip_init returned success).

Postcondition: No global state is mutated.; The transient digest buffer leaves scope on return.

Note: Single condition – no compound decision, so no MC/DC obligation.

Since: 0.1.0

Definition at line 170 of file main.c.

References k_ra8_ok, k_ra8_rsip_sha256_digest_bytes, memcmp(), and ra8_rsip_sha256().

Referenced by main().

◆ internal_kat_panic_halt()

void internal_kat_panic_halt ( void )

static

Park the processor after fatal setup or KAT control-flow failure.

Executes wait-for-interrupt indefinitely, preventing any failed diagnostic state from returning into normal application execution.

Precondition: The caller has determined that the application cannot continue safely.; No remaining foreground recovery operation can restore valid state.

Postcondition: This function does not return.; The processor remains in a low-activity wait loop.

Note: This terminal path preserves the diagnostic failure state for probing.

Since: 0.1.0

Definition at line 102 of file main.c.

References RA8_INTERNAL.

Referenced by internal_kat_setup_or_halt(), and main().

◆ internal_kat_setup_or_halt()

void internal_kat_setup_or_halt ( void )

static

Initialize clocks, timing, console, and status LEDs for the KAT.

Brings each prerequisite up in dependency order and transfers to internal_kat_panic_halt if any required operation fails.

Precondition: The function runs during single-threaded application startup.; EK-RA8D2 board registers are accessible through the platform mapping.

Postcondition: On return, timing, console output, and both status LEDs are ready.; Any prerequisite failure prevents a return to the caller.

Note: SHA-256 uses the software backend, so no RSIP engine bring-up is needed.

Since: 0.1.0

Definition at line 122 of file main.c.

References internal_kat_panic_halt(), k_kat_baud, k_ra8_board_led1, k_ra8_board_led2, k_ra8_clock_id_cpuclk0, k_ra8_ok, ra8_board_led_init(), ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), RA8_INTERNAL, and ra8_time_init().

Referenced by main().

◆ main()

void main ( void )

The application entry point Reset_Handler hands control to.

Returns void, not int. This is a freestanding image: there is no hosted C environment, no process and nothing to report an exit status to. ISO C fixes main at int only for a hosted implementation; for a freestanding one (C23 5.1.2.1) the startup function's name and type are implementation-defined, and this is that definition. Reset_Handler discards no value because there is none to discard, and if main ever does return, startup halts the CPU rather than resuming anything.

The firmware lane is compiled -ffreestanding (see cmake/ra8_add_app.cmake) and the flag and this signature travel together: without it both GCC and clang reject a non-int main (-Wmain / -Wmain-return-type). Do not remove one without the other.

That coupling is why the declaration sits behind __STDC_HOSTED__ == 0, which -ffreestanding sets and a hosted build does not. The guard is not defensive dressing: this header is reachable from host builds (the unit tests compile ra8_core natively), and an unguarded void main(void); makes every hosted translation unit that includes it fail with conflicting types for 'main' against its own ISO int main. The declaration therefore exists exactly where its contract does.

Hosted first-party code – everything under tests/ and tools/ – uses the ISO int main(...) contract instead, because it genuinely does run under an OS that reads the exit status. scripts/checks/check_entry_points.py holds each domain to its own contract (#707).

Declared here, once, for the same reason SystemInit is: every vector_table.c used to restate it as a local extern int32_t main(void);, sixteen copies that no compiler ever compared against the definition – and roughly thirty of them had silently drifted out of agreement with the main they called.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has configured the clock tree and VTOR.

Postcondition: Control does not return; the image runs until reset or halt.; Any value the application wanted to report has been logged, not returned.

Note: Not thread-safe; single-threaded startup context only.

Warning: Only valid while the translation unit is compiled -ffreestanding. A hosted build rejects this signature.

See also: SystemInit()

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up CGC + BSP audio then plays blocks.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the playback loop forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up CGC + GPT triple, runs sweep.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the sweep loop forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up clocks + UART + RMII pins, then ThreadX.

Precondition: Reset_Handler has copied .data and zeroed .bss.

Postcondition: On clean entry the kernel runs the worker thread once.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up clocks + UART, then enters ThreadX.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the kernel runs the worker thread forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up LED, console, SDHI pins, then ThreadX.

Precondition: Reset_Handler has copied .data + zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: CPUCLK0 is raised to the PLL1 target before the kernel starts.; On clean entry the SD card thread runs forever.; On any HAL init failure the function halts in __WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up CGC + USB-FS + UAC1, then enters the iso-IN feed loop forever.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the iso-IN feed loop forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: SystemInit set VTOR / FPU / priority grouping.

The application entry point Reset_Handler hands control to.

See file header.

Precondition: Boot init has completed.; The secure-boot library's BLXNS into NS image either failed or was skipped (the call site in ra8_trustzone_init is a no-op on host builds).

Postcondition: Diagnostic counter latched, CPU parked in a halt loop.; Function never returns.

Note: Single-threaded entry.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: On success g_eoh_chapters / g_eoh_crc hold the parsed results, the banner is emitted, and g_eoh_heartbeat advances once per frame.; On any failure g_eoh_err is non-zero and the CPU parks (no heartbeat).

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: The chapters/ch0-CRC banner is emitted; the CPU then loops in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: On success the g_etoc_* result globals hold the parsed TOC values, the banner is emitted, and g_etoc_heartbeat advances once per frame.; On any failure g_etoc_err is non-zero and the CPU parks (no heartbeat).

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss; SystemInit set VTOR/FPU.

Postcondition: The shelf scans on the panel; taps open books, browse, and read.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: The slab/arena/tile/vmem banner is emitted; the CPU then loops in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: On success the cache globals are latched and g_pc_heartbeat advances.; On any failure g_pc_err is non-zero and the CPU parks (no heartbeat).

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Profiles power modes once a second.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the profile + blink loop.; On any HAL hard error LED2 latches ON.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler has copied .data and zeroed .bss.; The shared board boot files installed the vector table.

Postcondition: The demo has run once and its verdict banner is streaming steadily.; The CPU idles re-emitting the banner (or halts after a fatal init error).

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up the clocks, console, SPI, and SD card, then runs the shared ra8_io VFS round-trip over the SD-over-SPI block device. On success it prints the exact PASS banner the HIL runner and ra8_emulator smoke gate scrape for; on any failure it prints FAIL and parks the core.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On a clean run the CPU loops forever after the PASS banner.; On any failure the function prints FAIL and halts in WFI.

Note: Not thread-safe; this is the single-threaded app entry.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Initialises logging and the console, brings up the OSPI NOR volume, runs the erase-before-write round-trip, and prints a single PASS/FAIL verdict line over SCI8 before parking in an infinite loop.

Precondition: SystemInit configured VTOR / FPU / priority grouping.; The OSPI NOR array is present (modelled in ra8_emulator, real on silicon).

Postcondition: Exactly one PASS or FAIL verdict line has been queued on SCI8.; Control parks in an infinite loop; the function never returns.

Note: Single-threaded; runs to the park loop on the main stack.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: The page-count + render-hash banner is emitted; the CPU loops in WFI.

Since: 0.1.0

Definition at line 179 of file main.c.

References internal_kat_one(), internal_kat_panic_halt(), internal_kat_setup_or_halt(), k_kat_msg2_len, k_kat_period_ms, k_ra8_board_led1, k_ra8_board_led2, ra8_board_led_toggle(), ra8_board_uart_console_write(), ra8_delay_ms(), ra8_isr_globals_enable(), s_exp_abc, s_exp_empty, s_exp_two_block, s_kat_msg_fail, s_kat_msg_ok, s_msg_abc, and s_msg_two_block.

Variable Documentation

◆ s_exp_abc

const uint8_t s_exp_abc[k_ra8_rsip_sha256_digest_bytes]

static

Initial value:

                               = {
  0xBAU, 0x78U, 0x16U, 0xBFU, 0x8FU, 0x01U, 0xCFU, 0xEAU, 0x41U, 0x41U, 0x40U,
  0xDEU, 0x5DU, 0xAEU, 0x22U, 0x23U, 0xB0U, 0x03U, 0x61U, 0xA3U, 0x96U, 0x17U,
  0x7AU, 0x9CU, 0xB4U, 0x10U, 0xFFU, 0x61U, 0xF2U, 0x00U, 0x15U, 0xADU,
}

Expected SHA-256("abc") – FIPS 180-4.

Definition at line 70 of file main.c.

Referenced by main().

◆ s_exp_empty

const uint8_t s_exp_empty[k_ra8_rsip_sha256_digest_bytes]

static

Initial value:

                                 = {
  0xE3U, 0xB0U, 0xC4U, 0x42U, 0x98U, 0xFCU, 0x1CU, 0x14U, 0x9AU, 0xFBU, 0xF4U,
  0xC8U, 0x99U, 0x6FU, 0xB9U, 0x24U, 0x27U, 0xAEU, 0x41U, 0xE4U, 0x64U, 0x9BU,
  0x93U, 0x4CU, 0xA4U, 0x95U, 0x99U, 0x1BU, 0x78U, 0x52U, 0xB8U, 0x55U,
}

Expected SHA-256("") – FIPS 180-4.

Definition at line 63 of file main.c.

Referenced by main().

◆ s_exp_two_block

const uint8_t s_exp_two_block[k_ra8_rsip_sha256_digest_bytes]

static

Initial value:

                                     = {
  0x24U, 0x8DU, 0x6AU, 0x61U, 0xD2U, 0x06U, 0x38U, 0xB8U, 0xE5U, 0xC0U, 0x26U,
  0x93U, 0x0CU, 0x3EU, 0x60U, 0x39U, 0xA3U, 0x3CU, 0xE4U, 0x59U, 0x64U, 0xFFU,
  0x21U, 0x67U, 0xF6U, 0xECU, 0xEDU, 0xD4U, 0x19U, 0xDBU, 0x06U, 0xC1U,
}

Expected SHA-256(56-byte two-block message) – FIPS 180-4.

Definition at line 77 of file main.c.

Referenced by main().

◆ s_kat_msg_fail

const uint8_t s_kat_msg_fail[] = "rsip sha256: KAT FAIL\r\n"

static

HIL verdict emitted after one or more SHA-256 vectors fail.

Definition at line 87 of file main.c.

Referenced by main().

◆ s_kat_msg_ok

const uint8_t s_kat_msg_ok[] = "rsip sha256: KAT OK\r\n"

static

HIL verdict emitted after all SHA-256 vectors pass.

Definition at line 84 of file main.c.

Referenced by main().

◆ s_msg_abc

const uint8_t s_msg_abc[] = {'a', 'b', 'c'}

static

NIST vector 2 input: "abc".

Definition at line 57 of file main.c.

Referenced by main().

◆ s_msg_two_block

const uint8_t s_msg_two_block[] = "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq"

static

NIST vector 3 input: the 448-bit two-block message.

Definition at line 60 of file main.c.

Referenced by main().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ kat_const_t

◆ kat_msg_len_t

Function Documentation

◆ internal_kat_one()

◆ internal_kat_panic_halt()

◆ internal_kat_setup_or_halt()

◆ main()

Variable Documentation

◆ s_exp_abc

◆ s_exp_empty

◆ s_exp_two_block

◆ s_kat_msg_fail

◆ s_kat_msg_ok

◆ s_msg_abc

◆ s_msg_two_block