ra8_doc.h File Reference

Data Operation Circuit (DOC) driver header. More...

#include <stdint.h>
#include "ra8_doc_regs.h"
#include "ra8_err.h"

Include dependency graph for ra8_doc.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	ra8_doc_window_polarity_t : uint8_t {   k_ra8_doc_window_inside = 0U ,   k_ra8_doc_window_outside = 1U }
	Window-comparison polarity for ra8_doc_set_window(). More...

Functions
ra8_err_t	ra8_doc_init (void)
	Reset the DOC control register to its reset state.
ra8_err_t	ra8_doc_add16 (uint16_t a, uint16_t b, uint16_t *out_sum)
	Perform a 16-bit hardware add.
ra8_err_t	ra8_doc_sub16 (uint16_t a, uint16_t b, uint16_t *out_diff)
	Perform a 16-bit hardware subtract.
ra8_err_t	ra8_doc_set_window (uint16_t lower, uint16_t upper, ra8_doc_window_polarity_t polarity)
	Configure the DOC for 16-bit window comparison.
ra8_err_t	ra8_doc_window_compare (uint16_t value, bool *out_flag)
	Trigger a 16-bit window comparison and return the DOPCF flag.

Detailed Description

Data Operation Circuit (DOC) driver header.

Public API for the 16-bit Data Operation Circuit that performs hardware add / subtract / compare operations. Useful for cheap running checksums and threshold compares without burning CPU cycles.

Copyright

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

Definition in file ra8_doc.h.

Enumeration Type Documentation

ra8_doc_window_polarity_t

enum ra8_doc_window_polarity_t : uint8_t

Window-comparison polarity for ra8_doc_set_window().

Selects between inside-band and outside-band detection. The silicon encodes this via DOCR.DCSEL[2:0] (HUM Ch 57.2.1 p 3519):

• k_ra8_doc_window_inside -> DCSEL = 100b (4)
• k_ra8_doc_window_outside -> DCSEL = 101b (5)

Inside-window: DOPCF is set when DODSR0 < DODIR < DODSR1 (strict). Outside-window: DOPCF is set when DODIR < DODSR0 or DODSR1 < DODIR (strict). Boundary values (DODIR == lower or DODIR == upper) do NOT trigger DOPCF in either mode – the comparisons are strictly less-than / greater-than.

Invariant

Only values 0 (inside) and 1 (outside) are valid.

// Configure DOC for inside-band ADC supervision
ra8_doc_set_window(0x0800U, 0x1800U, k_ra8_doc_window_inside);

See also

ra8_doc_set_window() Configure window thresholds and polarity.

ra8_doc_window_compare() Trigger a comparison and read DOPCF.

Since

0.1.0

Enumerator
k_ra8_doc_window_inside	Flag when DODSR0 < DODIR < DODSR1 (strict inequalities).
k_ra8_doc_window_outside	Flag when DODIR < DODSR0 or DODSR1 < DODIR.

Definition at line 93 of file ra8_doc.h.

Function Documentation

ra8_doc_add16()

ra8_err_t ra8_doc_add16 ( uint16_t a, uint16_t b, uint16_t * out_sum )

nodiscard

Perform a 16-bit hardware add.

Parameters

[in]	a	First operand.
[in]	b	Second operand.
[out]	out_sum	Receives a + b (wraps mod 2^16).

Returns

ra8_err_t error code.

Since

0.1.0

Definition at line 127 of file ra8_doc.c.

References internal_ra8_doc_run_16(), internal_ra8_doc_set_mode_16(), k_ra8_doc_mode_add, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_hw_sum().

ra8_doc_init()

ra8_err_t ra8_doc_init ( void )

nodiscard

Reset the DOC control register to its reset state.

Clears DOCR, DODIR, and DODSR0. Leaves the block disabled until the first operation.

Returns

k_ra8_ok on success.

Since

0.1.0

Definition at line 103 of file ra8_doc.c.

References r_doc_regs_t::DOCR, r_doc_regs_t::DODIR, r_doc_regs_t::DODSR0, r_doc_regs_t::DODSR1, r_doc_regs_t::DOSCR, k_ra8_doc_mask_dopcfcl, k_ra8_mstp_doc, k_ra8_ok, ra8_doc(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_setup_or_halt().

ra8_doc_set_window()

ra8_err_t ra8_doc_set_window ( uint16_t lower, uint16_t upper, ra8_doc_window_polarity_t polarity )

nodiscard

Configure the DOC for 16-bit window comparison.

Programmes DOCR (OMS=00, DOBW=0, DCSEL=inside or outside), DODSR0 (lower threshold), and DODSR1 (upper threshold) to set up a 16-bit window comparison. After this call, each write to DODIR via ra8_doc_window_compare() triggers a hardware comparison; DOSR.DOPCF is set when the input satisfies the selected condition:

• k_ra8_doc_window_inside: DODSR0 < DODIR < DODSR1 (strict).
• k_ra8_doc_window_outside: DODIR < DODSR0 or DODSR1 < DODIR (strict).

Boundary values (DODIR == lower or DODIR == upper) do NOT trigger DOPCF in either mode (HUM Ch 57.2.1 p 3519: all comparisons are strict).

The HUM constraint DODSR1 > DODSR0 (Ch 57.2.5 p 3521, Ch 57.2.6 p 3522) is enforced: lower >= upper is rejected. Any stale DOPCF flag is cleared before returning so the first ra8_doc_window_compare() call reflects a fresh comparison only.

Parameters

[in]	lower	Lower window threshold [0..65534]; written to DODSR0. Must be strictly less than upper.
[in]	upper	Upper window threshold [1..65535]; written to DODSR1. Must be strictly greater than lower.
[in]	polarity	Detection polarity (k_ra8_doc_window_inside or k_ra8_doc_window_outside).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Window programmed and stale DOPCF cleared.
k_ra8_err_invalid_arg	lower >= upper, or polarity is out of range.

Precondition

ra8_doc_init() has been called successfully.

lower < upper (strictly; the hardware requires DODSR1 > DODSR0).

Postcondition

DOCR holds OMS=00, DOBW=0, DCSEL encoding polarity.

DODSR0 == lower and DODSR1 == upper and DOSR.DOPCF == 0.

Note

Not thread-safe; caller must serialize with other DOC operations.

See also

ra8_doc_window_compare() Trigger a comparison and read DOPCF.

ra8_doc_init() Must be called before this function.

Since

0.1.0

HUM:

Ch 57.2.1 "DOCR : DOC Control Register" p 3519 – DCSEL[2:0] inside (100b) and outside (101b) window modes. Ch 57.2.5 "DODSR0 : DOC Data Setting Register 0" p 3521 – lower bound. Ch 57.2.6 "DODSR1 : DOC Data Setting Register 1" p 3522 – upper bound.

Configure the DOC for 16-bit window comparison.

Definition at line 152 of file ra8_doc.c.

References r_doc_regs_t::DOCR, r_doc_regs_t::DODSR0, r_doc_regs_t::DODSR1, r_doc_regs_t::DOSCR, k_ra8_doc_bit_dcsel, k_ra8_doc_dcsel_inside, k_ra8_doc_dcsel_outside, k_ra8_doc_mask_dcsel, k_ra8_doc_mask_dopcfcl, k_ra8_doc_window_outside, k_ra8_err_invalid_arg, k_ra8_ok, ra8_doc(), ra8_log_error, ra8_log_info, and s_tag.

ra8_doc_sub16()

ra8_err_t ra8_doc_sub16 ( uint16_t a, uint16_t b, uint16_t * out_diff )

nodiscard

Perform a 16-bit hardware subtract.

Parameters

[in]	a	Minuend.
[in]	b	Subtrahend.
[out]	out_diff	Receives a - b (wraps mod 2^16).

Returns

ra8_err_t error code.

Since

0.1.0

Definition at line 136 of file ra8_doc.c.

References internal_ra8_doc_run_16(), internal_ra8_doc_set_mode_16(), k_ra8_doc_mode_subtract, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

ra8_doc_window_compare()

ra8_err_t ra8_doc_window_compare ( uint16_t value, bool * out_flag )

nodiscard

Trigger a 16-bit window comparison and return the DOPCF flag.

Verifies the DOC is in compare mode (DOCR.OMS == 00), then writes value to DODIR which triggers the hardware comparison against the thresholds programmed by ra8_doc_set_window(). DOSR.DOPCF is read back and returned via out_flag. The flag is cleared before and after the comparison so each call reflects only the single DODIR write.

The window decision itself is made by the silicon comparator. The RAM-backed host register file has no comparator engine, so host unit tests stage DOSR.DOPCF before the call to drive both flag legs; the inside/outside/boundary semantics are proven on silicon.

Parameters

[in]	value	16-bit data value to compare against the window. Range: 0..65535.
[out]	out_flag	Set to true if the comparison condition was met (DOSR.DOPCF == 1 after the comparison), false otherwise. Must not be nullptr.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Comparison complete; *out_flag updated.
k_ra8_err_null_ptr	out_flag is nullptr.
k_ra8_err_invalid_state	DOCR.OMS != 0 (not in compare mode; call ra8_doc_set_window() first).

Precondition

ra8_doc_set_window() has been called to configure the window.

out_flag points to writable storage (non-NULL).

Postcondition

*out_flag reflects the DOSR.DOPCF result of the comparison.

DOSR.DOPCF is cleared on exit (DOSCR.DOPCFCL written).

Note

Not thread-safe; caller must serialize.

See also

ra8_doc_set_window() Configure the window thresholds first.

Since

0.1.0

HUM:

Ch 57.2.4 "DODIR : DOC Data Input Register" p 3521 – write triggers op. Ch 57.2.2 "DOSR : DOC Flag Status Register" p 3520 – DOPCF read. Ch 57.2.3 "DOSCR : DOC Status Clear Register" p 3521 – DOPCFCL clear.

Trigger a 16-bit window comparison and return the DOPCF flag.

Definition at line 193 of file ra8_doc.c.

References r_doc_regs_t::DOCR, r_doc_regs_t::DODIR, r_doc_regs_t::DOSCR, r_doc_regs_t::DOSR, k_ra8_doc_mask_dopcf, k_ra8_doc_mask_dopcfcl, k_ra8_doc_mask_oms, k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_doc(), ra8_log_error, and s_tag.