main.c File Reference

Data Operation Circuit (DOC) hardware vs software check. More...

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

Include dependency graph for main.c:

Go to the source code of this file.

Enumerations
enum	doc_demo_const_t : uint32_t { k_doc_demo_period_ms = 1000U }
	Demo tunables. More...
enum	doc_demo_layout_t : uint8_t { k_doc_demo_table_len = 8U }
	Operand-table layout. More...

Functions
static void	internal_panic_halt (void)
	Park the core after an unrecoverable DOC demo failure.
static uint16_t	internal_sw_sum (void)
	Software reference: sum every operand modulo 2^16.
static ra8_err_t	internal_hw_sum (uint16_t *out_sum)
	Hardware DOC sum: chain seven add16 calls into the accumulator.
static void	internal_setup_or_halt (void)
	Bring CGC, SysTick, both LEDs, and DOC up or halt.
static ra8_err_t	internal_one_iter (uint8_t *out_match)
	One iteration: HW sum + SW sum + compare.
void	main (void)
	Compare DOC and software sums continuously for HIL observation.

Variables
static const uint16_t	s_doc_demo_operands [k_doc_demo_table_len]
	Eight 16-bit operands chained through DOC.add.
volatile uint32_t	g_doc_match = 0U
	HIL liveness counter – incremented on every iteration where the hardware DOC sum matched the software reference sum.
volatile uint32_t	g_doc_mismatch = 0U
	HIL failure counter – incremented every time the hardware DOC sum disagreed with the software reference, or the DOC accumulator call returned a non-ok status.

Detailed Description

Data Operation Circuit (DOC) hardware vs software check.

Tag

[Ring 6 / APP] {World: S}

The on-chip Data Operation Circuit accepts 16-bit add / subtract / compare operations and stores the result in DODSR (HUM Ch "DOC"). This app sums an 8-entry constant table both via the hardware ra8_doc_add16 API (chained accumulator) and via a portable software reference, then compares the two checksums every second. LED1 toggles on a match; LED2 latches if the two ever diverge.

The HAL only exposes 16-bit add and sub (no XOR), so we exercise the add path – it is sufficient to prove DOC bring-up + register access + result readback. Bare EK-RA8D2; no expansion board.

Copyright

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

Since

0.1.0

Definition in file main.c.

Enumeration Type Documentation

doc_demo_const_t

enum doc_demo_const_t : uint32_t

Demo tunables.

Enumerator
k_doc_demo_period_ms	Doc demo period ms.

Definition at line 37 of file main.c.

doc_demo_layout_t

enum doc_demo_layout_t : uint8_t

Operand-table layout.

Enumerator
k_doc_demo_table_len	Doc demo table length.

Definition at line 42 of file main.c.

Function Documentation

internal_hw_sum()

ra8_err_t internal_hw_sum ( uint16_t * out_sum )

staticnodiscard

Hardware DOC sum: chain seven add16 calls into the accumulator.

Seeds the accumulator from the first table item, applies each remaining operand through DOC add16, and publishes only the final complete result.

MC/DC:

Compound decision: ra8_doc_add16 != ok. One atomic condition x 2 vectors; covered by test_app_doc_demo.c (success path + bad pointer rejection).

Parameters

[out]

out_sum

Receives the chained DOC sum.

Returns

Status of the chained hardware calculation.

Return values

k_ra8_ok	Every DOC addition succeeded and *out_sum was written.
(other)	The first DOC operation error, returned without publishing.

Precondition

out_sum non-NULL.

ra8_doc_init completed successfully.

Postcondition

On success *out_sum == internal_sw_sum().

On failure no later table operand is processed.

Note

Not thread-safe with concurrent access to the DOC accumulator.

Since

0.1.0

Definition at line 163 of file main.c.

References k_doc_demo_table_len, k_ra8_ok, ra8_doc_add16(), RA8_INTERNAL, and s_doc_demo_operands.

Referenced by internal_one_iter().

internal_one_iter()

ra8_err_t internal_one_iter ( uint8_t * out_match )

staticnodiscard

One iteration: HW sum + SW sum + compare.

Runs the hardware calculation first, computes the immutable software reference only after hardware success, and normalizes equality to a one-byte boolean result.

MC/DC:

Compound decision: hw_err != ok || hw_sum != sw_sum. Two atomic conditions x N+1 = 3 vectors – match path (steady state), hw_err branch (driver-failure mock), mismatch branch (mock seeds a wrong DODSR value).

Parameters

[out]

out_match

Receives 1 if hw == sw, 0 otherwise.

Returns

Status from internal_hw_sum.

Return values

k_ra8_ok	*out_match contains the normalized comparison result.
(other)	Hardware calculation failed and comparison was skipped.

Precondition

out_match non-NULL.

The DOC peripheral was initialized by internal_setup_or_halt.

Postcondition

On success *out_match is 0 or 1.

On failure the hardware error is returned unchanged.

Note

Not thread-safe with concurrent DOC access.

Since

0.1.0

Definition at line 237 of file main.c.

References internal_hw_sum(), internal_sw_sum(), k_ra8_ok, and RA8_INTERNAL.

Referenced by main().

internal_panic_halt()

void internal_panic_halt ( void )

static

Park the core after an unrecoverable DOC demo failure.

Repeatedly executes WFI, retaining DOC and clock state for debugging.

Precondition

Called only from a fatal boot or terminal foreground path.

The caller does not require recovery without reset.

Postcondition

The core stays in the WFI loop until external intervention.

Neither HIL result counter changes after entry.

Note

Not thread-safe; this is the terminal single-threaded path.

Since

0.1.0

Definition at line 68 of file main.c.

References RA8_INTERNAL.

internal_setup_or_halt()

void internal_setup_or_halt ( void )

static

Bring CGC, SysTick, both LEDs, and DOC up or halt.

Initializes dependencies in order and transfers to the panic helper on the first failed HAL operation.

Precondition

Reset startup initialized static storage and the vector table.

Called once before global interrupt enable.

Postcondition

On return, DOC and both status LEDs are ready for the compare loop.

The delay service uses the measured CPU clock.

Note

Not thread-safe; it mutates global peripheral state.

Since

0.1.0

Definition at line 189 of file main.c.

References internal_panic_halt(), k_ra8_board_led1, k_ra8_board_led2, k_ra8_clock_id_cpuclk0, k_ra8_ok, ra8_board_led_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), ra8_doc_init(), RA8_INTERNAL, and ra8_time_init().

internal_sw_sum()

uint16_t internal_sw_sum ( void )

static

Software reference: sum every operand modulo 2^16.

Walks the immutable operand table in order with explicit 16-bit wraparound, providing the reference for the DOC accumulator.

MC/DC:

Loop bound is statically known; no compound boolean decisions in this helper. (MC/DC vector pattern: trivial; covered by any call.)

Returns

Wrap-around sum.

Return values

0..UINT16_MAX

Deterministic modulo-2^16 table sum.

Precondition

None.

The file-scope operand table is fully initialized.

Postcondition

Return value is reproducible for the fixed operand table.

Neither the table nor any peripheral state is modified.

Note

Pure and reentrant.

Since

0.1.0

Definition at line 130 of file main.c.

References k_doc_demo_table_len, RA8_INTERNAL, and s_doc_demo_operands.

Referenced by internal_one_iter().

main()

void main

(

void

)

Compare DOC and software sums continuously for HIL observation.

The application entry point Reset_Handler hands control to.

Initializes the demo, executes one comparison per period, increments the exported match or mismatch counter, and toggles the matching LED.

Precondition

Reset startup and SystemInit completed successfully.

DOC and the status LEDs are not owned by another context.

Postcondition

Every iteration increments exactly one HIL result counter.

LED1 represents matches and LED2 represents failures or mismatches.

Note

Does not return during normal operation.

Since

0.1.0

Definition at line 260 of file main.c.

References g_doc_match, g_doc_mismatch, internal_one_iter(), internal_panic_halt(), internal_setup_or_halt(), k_doc_demo_period_ms, k_ra8_board_led1, k_ra8_board_led2, k_ra8_ok, ra8_board_led_toggle(), ra8_delay_ms(), and ra8_isr_globals_enable().

Variable Documentation

g_doc_match

volatile uint32_t g_doc_match = 0U

HIL liveness counter – incremented on every iteration where the hardware DOC sum matched the software reference sum.

Read externally by scripts/hil/jlink_memprobe.sh via SWD. The probe asserts this counter advances by >= HIL_PROBE_MIN_ADVANCE over the sample window, proving the DOC peripheral actually computed the same chained-add result as the portable software reference (the alive-mode check could only prove the chip didn't crash, not that DOC arithmetic was correct).

Note

Read externally by J-Link only; firmware never reads back.

Since

0.1.0

Definition at line 91 of file main.c.

Referenced by main().

g_doc_mismatch

volatile uint32_t g_doc_mismatch = 0U

HIL failure counter – incremented every time the hardware DOC sum disagreed with the software reference, or the DOC accumulator call returned a non-ok status.

The memprobe asserts this stays at 0 (or below HIL_PROBE_MAX_FAILURE). Catches silent failure modes where DOC reports success but produces a wrong DODSR result, or where the driver returns an error code – both previously invisible because the chip kept iterating the main loop.

Note

Read externally by J-Link only; firmware never reads back.

Since

0.1.0

Definition at line 108 of file main.c.

Referenced by main().

s_doc_demo_operands

const uint16_t s_doc_demo_operands[k_doc_demo_table_len]

static

Initial value:

                                          = {
  0x1111U,
  0x2222U,
  0x3333U,
  0x0F0FU,
  0xF0F0U,
  0x00FFU,
  0xFF00U,
  0xDEADU,
}

Eight 16-bit operands chained through DOC.add.

Definition at line 47 of file main.c.

Referenced by internal_hw_sum(), and internal_sw_sum().