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

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

Include dependency graph for ra8_bscan.h:

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

Data Structures
struct	ra8_bscan_status_t
	Snapshot of the firmware-side TAP bookkeeping object. More...

Functions
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.

Detailed Description

JTAG / IEEE-1149.1 Boundary Scan TAP HAL surface.

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

Thin software wrapper over the RA8D2 boundary-scan TAP described in HUM Ch 50 "Boundary Scan", p 3257-3262. The actual scan vectors (EXTEST / SAMPLE-PRELOAD / CLAMP / HIGHZ / BYPASS / IDCODE) are driven over the four JTAG pins (TCK / TMS / TDI / TDO) by an external manufacturing-test fixture while the device is held in reset. None of the four TAP registers (JTIR, JTIDR, JTBPR, JTBSR) is reachable through the AHB / system bus, so the firmware-side "driver" is a small bookkeeping object rather than a normal register-poking peripheral.

What this module does:

ra8_bscan_init() – record the expected JTIDR value and mark the TAP-state object as initialized so the host-side test rig has a place to stash its "current instruction" hint.
ra8_bscan_deinit() – forget all state.
ra8_bscan_get_idcode() – return the manufacturer ID code (0x085D_A447 per HUM Ch 50.2.2, p 3258) so a host-side sanity check can confirm it matches what was scanned out over TDO. This is read from a constant; there is no hardware register to fetch.
ra8_bscan_get_status() – report the recorded TAP instruction plus initialisation state.
ra8_bscan_set_instruction() – record (NOT actually load) the JTIR opcode the external fixture is currently driving so other firmware modules (e.g. a logging task) can reflect it.

Warning: Boundary scan can only be exercised while the RES pin is held low (HUM Ch 50.1 Table 50.1, p 3257). Issuing the EXTEST / CLAMP / HIGHZ instructions on a live system disconnects every general-purpose I/O pin from its normal peripheral function and drives it from the JTBSR shift register. Do not call this driver from a running application path – it is intended for power-on self-test / production-test contexts only.; HUM Ch 50.1 (p 3257) also notes the device does not implement the optional TRST pin, so the TAP can only be reset by holding TMS=1 for at least 5 TCK clocks. The firmware cannot do this itself; the external test fixture must.

Not yet implemented

Loading or reading the JTBSR scan chain (cannot be done from the CPU; HUM Ch 50.2 p 3258).
Driving the TAP state machine (Test-Logic-Reset -> Run-Test/Idle -> Select-DR -> ... per HUM Figure 50.2 p 3260) – this is the external fixture's responsibility.
BSDL parsing – handled in host tooling, not on the MCU.

Validation

The CPU-side contract (IDCODE constant cross-check, opcode validation, lifecycle, NULL guards) is exercised by the host unit tests in tests/misc/src/test_ra8_bscan.c and by the on-silicon self-test example examples/.../hil/bscan_selftest (prints bscan: idcode=085DA447 checks=17 PASS). The actual boundary-scan vectors are validated externally by an IEEE-1149.1 JTAG fixture using the device's BSDL file – there is no firmware example for the scan chain itself because it is not CPU-reachable (HUM Ch 50.2.3 p 3259).

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

Definition in file ra8_bscan.h.

Function Documentation

◆ 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().

Data Structures

Functions

Detailed Description

Not yet implemented

Validation

Function Documentation

◆ ra8_bscan_clear_status()

◆ ra8_bscan_deinit()

◆ ra8_bscan_get_idcode()

◆ ra8_bscan_get_status()

◆ ra8_bscan_init()

◆ ra8_bscan_set_instruction()