JTAG / IEEE-1149.1 Boundary Scan TAP HAL implementation. More...

#include "ra8_bscan.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_bscan_regs.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"

Include dependency graph for ra8_bscan.c:

Data Structures
struct	ra8_bscan_state_t
	Firmware-side TAP bookkeeping object. More...

Enumerations
enum	ra8_bscan_clear_arg_t : uint32_t { k_ra8_bscan_clear_mask_none = 0U }
	Allowed values for the mask argument of ra8_bscan_clear_status. More...

Functions
static bool	internal_is_known_instruction (ra8_bscan_instr_t instr)
	Validate that an instruction code is one of the named opcodes.
ra8_err_t	ra8_bscan_init (void)
	Initialise the firmware-side TAP bookkeeping object.
ra8_err_t	ra8_bscan_deinit (void)
	Tear down the bookkeeping object.
ra8_err_t	ra8_bscan_get_idcode (uint32_t *out)
	Get the chip's hardwired JTIDR device ID code.
ra8_err_t	ra8_bscan_get_status (ra8_bscan_status_t *out)
	Get a snapshot of the driver's TAP bookkeeping state.
ra8_err_t	ra8_bscan_clear_status (uint32_t mask)
	Clear the recorded last-instruction state (no hardware effect).
ra8_err_t	ra8_bscan_set_instruction (ra8_bscan_instr_t instr)
	Record the JTIR opcode the external fixture is currently driving.

Variables
static const char *	s_tag = "BSCAN"
	Log tag used by every ra8_log_* call in this driver.
static ra8_bscan_state_t	s_bscan_state
	Singleton bookkeeping state.

Detailed Description

JTAG / IEEE-1149.1 Boundary Scan TAP HAL implementation.

Tag: [Ring 3 / HAL] {World: NS}

Tracks the firmware-side view of the RA8D2 boundary-scan Test Access Port. The four TAP registers (JTIR, JTIDR, JTBPR, JTBSR) described in HUM Ch 50.2 (p 3258-3259) are not memory-mapped – they live behind the JTAG pin interface and are accessible only to an external manufacturing-test fixture. This driver therefore carries no register accesses; it only maintains a small cached status object that other firmware modules can query.

Citation strategy: every public API includes at least one HUM Ch 50 citation in a comment to anchor the design intent in the spec, even though no register write actually happens.

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

Definition in file ra8_bscan.c.

Enumeration Type Documentation

◆ ra8_bscan_clear_arg_t

enum ra8_bscan_clear_arg_t : uint32_t

Allowed values for the mask argument of ra8_bscan_clear_status.

Sibling drivers (ACMPHS, GLCDC, ...) accept a 32-bit bitmask of status flags to clear. This driver has no hardware flags so the only legal value is zero. The enum makes that contract explicit.

Enumerator
k_ra8_bscan_clear_mask_none	No-op mask – the only legal value.

Definition at line 51 of file ra8_bscan.c.

Function Documentation

◆ internal_is_known_instruction()

bool internal_is_known_instruction ( ra8_bscan_instr_t instr )

static

Validate that an instruction code is one of the named opcodes.

Parameters

[in] instr Candidate opcode.

Returns: true if instr matches one of the values in HUM Ch 50.2.1 Table (p 3258); false for any reserved code.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 94 of file ra8_bscan.c.

References k_ra8_bscan_instr_bypass, k_ra8_bscan_instr_clamp, k_ra8_bscan_instr_extest, k_ra8_bscan_instr_highz, k_ra8_bscan_instr_idcode, k_ra8_bscan_instr_sample_preload, and RA8_INTERNAL.

Referenced by ra8_bscan_set_instruction().

◆ ra8_bscan_clear_status()

ra8_err_t ra8_bscan_clear_status ( uint32_t mask )

nodiscard

Clear the recorded last-instruction state (no hardware effect).

Resets the bookkeeping last_instruction field back to BYPASS (which is the TAP's reset-state instruction per HUM Ch 50.2.1, p 3258 – the JTIR reset value 0xE selects the BYPASS path). Used by the host-side fixture when it has finished a scan run and wants the firmware-side log to stop reporting the previous opcode.

Parameters

[in] mask Reserved – must be 0. Present to match the ra8_<short>_clear_status(uint32_t) shape used by sibling HAL drivers.

Returns: ra8_err_t

Return values

k_ra8_ok	Success.
k_ra8_err_invalid_arg	mask is non-zero.
k_ra8_err_not_initialized	ra8_bscan_init not called.

Precondition: ra8_bscan_init has been called.; mask is 0.

Postcondition: Recorded instruction == BYPASS.; Initialized flag unchanged.

Note: Not thread-safe.

See also: ra8_bscan_set_instruction

Since: 0.1.0

Definition at line 159 of file ra8_bscan.c.

References k_ra8_bscan_clear_mask_none, k_ra8_bscan_instr_bypass, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ok, and s_bscan_state.

Referenced by bs_run_checks().

◆ ra8_bscan_deinit()

ra8_err_t ra8_bscan_deinit ( void )

nodiscard

Tear down the bookkeeping object.

Clears the recorded instruction and idcode and marks the driver as uninitialized. Touches no hardware.

Returns: ra8_err_t

Return values

k_ra8_ok Always succeeds.

Precondition: Driver may be in any state (deinit is idempotent).; Single-threaded shutdown context.

Postcondition: ra8_bscan_get_status->initialized == false.; ra8_bscan_get_status->last_instruction == BYPASS.

Note: Not thread-safe.

See also: ra8_bscan_init

Since: 0.1.0

Definition at line 122 of file ra8_bscan.c.

References k_ra8_bscan_instr_bypass, k_ra8_ok, and s_bscan_state.

◆ ra8_bscan_get_idcode()

ra8_err_t ra8_bscan_get_idcode ( uint32_t * out )

nodiscard

Get the chip's hardwired JTIDR device ID code.

Returns the constant value the external fixture should observe when it shifts JTIDR out over TDO after issuing the IDCODE instruction (per HUM Ch 50.3.2 (4) IDCODE description, p 3261). The value is sourced from the regs header and does NOT require hardware access.

Parameters

[out] out Receives the 32-bit JTIDR value.

Returns: ra8_err_t

Return values

k_ra8_ok	Success, *out is valid.
k_ra8_err_null_ptr	out is NULL.
k_ra8_err_not_initialized	ra8_bscan_init has not been called.

Precondition: ra8_bscan_init has been called.; out is a writable uint32_t.

Postcondition: On success *out == 0x085DA447.; Driver state unchanged.

Note: Thread safety: re-entrant (read-only access to a constant).

See also: ra8_bscan_init; k_ra8_bscan_jtidr_reset

Since: 0.1.0

Definition at line 134 of file ra8_bscan.c.

References k_ra8_err_not_initialized, k_ra8_ok, RA8_CHECK_NULL_PTR, s_bscan_state, and s_tag.

Referenced by bs_run_checks().

◆ ra8_bscan_get_status()

ra8_err_t ra8_bscan_get_status ( ra8_bscan_status_t * out )

nodiscard

Get a snapshot of the driver's TAP bookkeeping state.

Returns the firmware-side view (initialized flag, last reported JTIR opcode, expected JTIDR). Does not query hardware – the four TAP registers (JTIR / JTIDR / JTBPR / JTBSR) are not CPU-readable (HUM Ch 50.2.3 explicit note, p 3259).

Parameters

[out] out Receives the status snapshot.

Returns: ra8_err_t

Return values

k_ra8_ok	Success.
k_ra8_err_null_ptr	out is NULL.

Precondition: out is a writable ra8_bscan_status_t object.; Single-threaded read or caller serialises access.

Postcondition: Driver state unchanged.; *out reflects the most recent calls to ra8_bscan_init, ra8_bscan_deinit, and ra8_bscan_set_instruction.

Note: Thread safety: not thread-safe relative to set_instruction.

See also: ra8_bscan_set_instruction

Since: 0.1.0

Definition at line 147 of file ra8_bscan.c.

References ra8_bscan_status_t::expected_idcode, ra8_bscan_status_t::initialized, k_ra8_ok, ra8_bscan_status_t::last_instruction, RA8_CHECK_NULL_PTR, s_bscan_state, and s_tag.

Referenced by bs_run_checks().

◆ ra8_bscan_init()

ra8_err_t ra8_bscan_init ( void )

nodiscard

Initialise the firmware-side TAP bookkeeping object.

Marks the driver as initialized and seeds the expected JTIDR with the chip's hardwired device ID code (0x085D_A447, HUM Ch 50.2.2 Table 50.3 entry, p 3258). Touches no hardware: the boundary-scan TAP is reachable only over the external JTAG pins.

Returns: ra8_err_t

Return values

k_ra8_ok Always succeeds.

Precondition: Single-threaded init context.; Caller has not already called ra8_bscan_init since the last ra8_bscan_deinit (re-init is allowed and is a no-op).

Postcondition: ra8_bscan_get_status->initialized == true.; ra8_bscan_get_status->expected_idcode == 0x085DA447.

Note: Not thread-safe.

See also: ra8_bscan_deinit; ra8_bscan_get_idcode

Since: 0.1.0

Definition at line 110 of file ra8_bscan.c.

References k_ra8_bscan_instr_bypass, k_ra8_bscan_jtidr_reset, k_ra8_ok, ra8_log_info, s_bscan_state, and s_tag.

Referenced by bs_run_checks().

◆ ra8_bscan_set_instruction()

ra8_err_t ra8_bscan_set_instruction ( ra8_bscan_instr_t instr )

nodiscard

Record the JTIR opcode the external fixture is currently driving.

Pure firmware-side bookkeeping. The opcode is validated against the named instruction set in HUM Ch 50.2.1 Table (p 3258); reserved 4-bit codes are rejected. The TAP itself does not see this call – the actual JTIR load happens via Shift-IR on the JTAG pins from the external fixture.

Parameters

[in] instr One of the named opcodes in ra8_bscan_instr_t.

Returns: ra8_err_t

Return values

k_ra8_ok	Recorded.
k_ra8_err_invalid_arg	instr is a reserved opcode.
k_ra8_err_not_initialized	ra8_bscan_init not called.

Precondition: ra8_bscan_init has been called.; instr is one of EXTEST / SAMPLE_PRELOAD / IDCODE / CLAMP / HIGHZ / BYPASS.

Postcondition: ra8_bscan_get_status->last_instruction == instr.; Initialized flag unchanged.

Note: Not thread-safe.

Warning: EXTEST / CLAMP / HIGHZ disconnect every general-purpose I/O from its normal peripheral function. Recording one of these opcodes here does not cause that effect, but the fixture loading the same opcode over TDI will.

See also: ra8_bscan_get_status; ra8_bscan_clear_status

Since: 0.1.0

Definition at line 174 of file ra8_bscan.c.

References internal_is_known_instruction(), k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ok, ra8_log_info_val, s_bscan_state, and s_tag.

Referenced by bs_run_checks().

Variable Documentation

◆ s_bscan_state

ra8_bscan_state_t s_bscan_state

static

Initial value:

                                       = {
  .initialized      = false,
  .last_instruction = k_ra8_bscan_instr_bypass,
  .expected_idcode  = 0U,
}

Singleton bookkeeping state.

Updated only by this file.

Note: Not thread-safe; callers must serialise access from a single init / shutdown context.

Definition at line 72 of file ra8_bscan.c.

Referenced by ra8_bscan_clear_status(), ra8_bscan_deinit(), ra8_bscan_get_idcode(), ra8_bscan_get_status(), ra8_bscan_init(), and ra8_bscan_set_instruction().

◆ s_tag

const char* s_tag = "BSCAN"

static

Log tag used by every ra8_log_* call in this driver.

Definition at line 39 of file ra8_bscan.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_bscan_clear_arg_t

Function Documentation

◆ internal_is_known_instruction()

◆ ra8_bscan_clear_status()

◆ ra8_bscan_deinit()

◆ ra8_bscan_get_idcode()

◆ ra8_bscan_get_status()

◆ ra8_bscan_init()

◆ ra8_bscan_set_instruction()

Variable Documentation

◆ s_bscan_state

◆ s_tag