Data Operation Circuit (DOC) peripheral-block model for ra8_emulator. More...

#include <stdint.h>
#include <stdio.h>
#include "board_periph_block.h"
#include "emu_host_io_internal.h"

Include dependency graph for board_periph_doc.c:

Data Structures
struct	doc_state_t
	DOC register state. More...

Enumerations
enum	doc_lit_t : uint32_t { k_u32_all = 0xFFFFFFFFU , k_u16_full = 0x0000FFFFU }
	Result-width masks for the DOC unit (32-bit vs 16-bit mode). More...
enum	doc_map_t : uint64_t { k_doc_base = 0x40311000UL , k_doc_span = 0x20UL , k_doc_off_docr = 0x00UL , k_doc_off_dosr = 0x04UL , k_doc_off_doscr = 0x08UL , k_doc_off_dodir = 0x0CUL , k_doc_off_dodsr0 = 0x10UL , k_doc_off_dodsr1 = 0x14UL }
	DOC block geometry (ra8_doc_regs.h). More...
enum	doc_field_t : uint32_t { k_doc_oms_mask = 0x03U , k_doc_dobw_mask = 0x08U , k_doc_dcsel_mask = 0x70U , k_doc_dcsel_shift = 4U , k_doc_dopcf = 0x01U }
	DOCR / DOSR field masks (ra8_doc_regs.h). More...
enum	doc_mode_t : uint32_t { k_doc_mode_compare = 0U , k_doc_mode_add = 1U , k_doc_mode_subtract = 2U }
	DOCR.OMS operation modes. More...
enum	doc_order_t : uint32_t { k_doc_block_order = 141U }
	Per-tick order slot for the DOC block (relative order only). More...

Functions
static RA8_INTERNAL uint32_t	internal_doc_width_mask (void)
	Width mask selected by DOCR.DOBW (0 = 16-bit, 1 = 32-bit).
static RA8_INTERNAL void	internal_doc_apply (uint32_t dodir)
	Apply one DODIR operand to DODSR0 per the current DOCR.OMS mode.
static RA8_INTERNAL void	internal_doc_reset (void)
	Reset the DOC unit to power-on state.
static RA8_INTERNAL uint64_t	internal_doc_read (uc_engine *uc, uint64_t addr, unsigned size)
	MMIO read inside the DOC window.
static RA8_INTERNAL void	internal_doc_write (uc_engine *uc, uint64_t addr, unsigned size, uint64_t value)
	MMIO write inside the DOC window.
static RA8_INTERNAL void	internal_doc_report (void)
	End-of-run DOC section: mode, last result, op count.
static RA8_INTERNAL void	internal_doc_block_register (void)
	Register the DOC block before main (host constructor).

Variables
static doc_state_t	s_doc
static const board_periph_block_t	s_k_doc_block
	DOC block descriptor (self-registered with the core).

Detailed Description

Data Operation Circuit (DOC) peripheral-block model for ra8_emulator.

Models the RA8D2 DOC (ra8_doc_regs.h, ra8_doc.c) at 0x40311000 so doc_demo's hardware result matches its software reference. The demo chains an 8-entry add through the DOC and compares the hardware sum to a portable software sum, lighting LED1 on a match and latching LED2 on any divergence; against the sparse fallback DODSR0 read back garbage, so LED2 latched. (The RA8_OFF_TARGET shortcut in ra8_doc.c that stores the result in software is compiled out of the real cross-target .elf ra8_emulator runs, so the genuine "write DODIR, read DODSR0" hardware path must work.)

The unit is one accumulator DODSR0 updated by each DODIR write per DOCR.OMS:

Add (OMS=1): DODSR0 += DODIR, masked to the DOCR.DOBW width (16 / 32); DOPCF latches on a carry out of the width.
Subtract (OMS=2): DODSR0 -= DODIR, masked; DOPCF latches on a borrow.
Compare (OMS=0): DOPCF latches when the DODIR-vs-DODSR0 relation the DCSEL field selects holds (match / mismatch implemented; the rest default to mismatch).

DODSR0 is read/write (the driver seeds operand A there); DOSR exposes DOPCF and DOSCR clears it. Only the add path is exercised by an in-tree example (doc_demo); subtract and compare use their documented semantics.

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

Since: 0.1.0

Definition in file board_periph_doc.c.

Enumeration Type Documentation

◆ doc_field_t

enum doc_field_t : uint32_t

DOCR / DOSR field masks (ra8_doc_regs.h).

Enumerator
k_doc_oms_mask	OMS[1:0] mode select.
k_doc_dobw_mask	DOBW: 0 = 16-bit, 1 = 32-bit.
k_doc_dcsel_mask	DCSEL[2:0] compare condition.
k_doc_dcsel_shift	DCSEL field position.
k_doc_dopcf	DOSR DOPCF flag / DOSCR clear.

Definition at line 57 of file board_periph_doc.c.

◆ doc_lit_t

enum doc_lit_t : uint32_t

Result-width masks for the DOC unit (32-bit vs 16-bit mode).

Enumerator
k_u32_all	32-bit all-ones result mask.
k_u16_full	16-bit result mask.

Definition at line 39 of file board_periph_doc.c.

◆ doc_map_t

enum doc_map_t : uint64_t

DOC block geometry (ra8_doc_regs.h).

Enumerator
k_doc_base	DOC base (HUM Ch 57.2).
k_doc_span	Register window.
k_doc_off_docr	DOCR control (OMS/DOBW/DCSEL), 8b.
k_doc_off_dosr	DOSR status (DOPCF), 8b.
k_doc_off_doscr	DOSCR status clear, 8b.
k_doc_off_dodir	DODIR data input.
k_doc_off_dodsr0	DODSR0 reference / result.
k_doc_off_dodsr1	DODSR1 upper threshold.

Definition at line 45 of file board_periph_doc.c.

◆ doc_mode_t

enum doc_mode_t : uint32_t

DOCR.OMS operation modes.

Enumerator
k_doc_mode_compare	Compare (set DOPCF on DCSEL hit).
k_doc_mode_add	DODSR0 += DODIR.
k_doc_mode_subtract	DODSR0 -= DODIR.

Definition at line 66 of file board_periph_doc.c.

◆ doc_order_t

enum doc_order_t : uint32_t

Per-tick order slot for the DOC block (relative order only).

Enumerator
k_doc_block_order	After the CRC block; report order.

Definition at line 73 of file board_periph_doc.c.

Function Documentation

◆ internal_doc_apply()

RA8_INTERNAL void internal_doc_apply ( uint32_t dodir )

static

Apply one DODIR operand to DODSR0 per the current DOCR.OMS mode.

Apply one dodir operand to dodsr0 per the current docr.oms mode; this step is contained within the board periph doc model and uses bounded caller or module-owned storage.

Parameters

[in] dodir Dodir input used by the operation.

Precondition: Arguments satisfy the ranges documented for doc apply.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph doc model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 113 of file board_periph_doc.c.

References internal_doc_width_mask(), k_doc_dcsel_mask, k_doc_dcsel_shift, k_doc_dopcf, k_doc_mode_add, k_doc_mode_subtract, k_doc_oms_mask, RA8_INTERNAL, and s_doc.

Referenced by internal_doc_write().

◆ internal_doc_block_register()

RA8_INTERNAL void internal_doc_block_register ( void )

static

Register the DOC block before main (host constructor).

Definition at line 257 of file board_periph_doc.c.

References board_periph_register_block(), RA8_INTERNAL, and s_k_doc_block.

◆ internal_doc_read()

RA8_INTERNAL uint64_t internal_doc_read	(	uc_engine *	uc,
		uint64_t	addr,
		unsigned	size )

static

MMIO read inside the DOC window.

MMIO read inside the doc window; this step is contained within the board periph doc model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	addr	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.

Returns: The doc read result produced by the board periph doc model.

Return values

value The operation-specific doc read value.

Precondition: Arguments satisfy the ranges documented for doc read.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph doc model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 170 of file board_periph_doc.c.

References k_doc_base, k_doc_off_docr, k_doc_off_dodsr0, k_doc_off_dodsr1, k_doc_off_dosr, RA8_INTERNAL, and s_doc.

◆ internal_doc_report()

RA8_INTERNAL void internal_doc_report ( void )

static

End-of-run DOC section: mode, last result, op count.

End-of-run doc section: mode, last result, op count; this step is contained within the board periph doc model and uses bounded caller or module-owned storage.

Precondition: Arguments satisfy the ranges documented for doc report.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph doc model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 231 of file board_periph_doc.c.

References k_doc_oms_mask, priv_emu_io_errf(), RA8_INTERNAL, and s_doc.

◆ internal_doc_reset()

RA8_INTERNAL void internal_doc_reset ( void )

static

Reset the DOC unit to power-on state.

Reset the doc unit to power-on state; this step is contained within the board periph doc model and uses bounded caller or module-owned storage.

Precondition: Arguments satisfy the ranges documented for doc reset.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph doc model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 148 of file board_periph_doc.c.

References RA8_INTERNAL, and s_doc.

◆ internal_doc_width_mask()

RA8_INTERNAL uint32_t internal_doc_width_mask ( void )

static

Width mask selected by DOCR.DOBW (0 = 16-bit, 1 = 32-bit).

Width mask selected by docr.dobw (0 = 16-bit, 1 = 32-bit); this step is contained within the board periph doc model and uses bounded caller or module-owned storage.

Returns: The doc width mask result produced by the board periph doc model.

Return values

value The operation-specific doc width mask value.

Precondition: Arguments satisfy the ranges documented for doc width mask.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph doc model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 98 of file board_periph_doc.c.

References k_doc_dobw_mask, k_u16_full, k_u32_all, RA8_INTERNAL, and s_doc.

Referenced by internal_doc_apply().

◆ internal_doc_write()

RA8_INTERNAL void internal_doc_write	(	uc_engine *	uc,
		uint64_t	addr,
		unsigned	size,
		uint64_t	value )

static

MMIO write inside the DOC window.

MMIO write inside the doc window; this step is contained within the board periph doc model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	addr	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in]	value	Register or payload value involved in the operation.

Precondition: Arguments satisfy the ranges documented for doc write.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph doc model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 203 of file board_periph_doc.c.

References internal_doc_apply(), k_doc_base, k_doc_dopcf, k_doc_off_docr, k_doc_off_dodir, k_doc_off_dodsr0, k_doc_off_dodsr1, k_doc_off_doscr, and s_doc.

Variable Documentation

◆ s_doc

doc_state_t s_doc

static

Definition at line 86 of file board_periph_doc.c.

Referenced by internal_doc_apply(), internal_doc_read(), internal_doc_report(), internal_doc_reset(), internal_doc_width_mask(), and internal_doc_write().

◆ s_k_doc_block

const board_periph_block_t s_k_doc_block

static

Initial value:

                                                = {
  .base   = (uint32_t)k_doc_base,
  .span   = (uint32_t)k_doc_span,
  .order  = (uint32_t)k_doc_block_order,
  .read   = internal_doc_read,
  .write  = internal_doc_write,
  .tick   = nullptr,
  .reset  = internal_doc_reset,
  .report = internal_doc_report,
  .name   = "DOC",
}

DOC block descriptor (self-registered with the core).

Definition at line 244 of file board_periph_doc.c.

Referenced by internal_doc_block_register().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ doc_field_t

◆ doc_lit_t

◆ doc_map_t

◆ doc_mode_t

◆ doc_order_t

Function Documentation

◆ internal_doc_apply()

◆ internal_doc_block_register()

◆ internal_doc_read()

◆ internal_doc_report()

◆ internal_doc_reset()

◆ internal_doc_width_mask()

◆ internal_doc_write()

Variable Documentation

◆ s_doc

◆ s_k_doc_block