Host-side console formatters + ra8_fs backend + pass ladder. More...

#include <stdint.h>
#include <string.h>
#include "usb_selftest_hs_host_steps.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_fs.h"
#include "ra8_io_blockdev.h"
#include "ra8_io_blockdev_usbmsc.h"
#include "ra8_time.h"
#include "ra8_usb_hmsc.h"

Include dependency graph for usb_selftest_hs_host_host.c:

Functions
static uint8_t	selftest_nibble_to_hex (uint32_t nibble)
	Format one nibble (0..15) into an uppercase hex character.
static uint32_t	selftest_str_len (const char *text)
	Bounded ASCII string length (cap k_selftest_print_cap).
static ra8_err_t	selftest_sci_write (const uint8_t *data, uint32_t len)
	Push a literal block over SCI8 polled.
static ra8_err_t	selftest_print (const char *text)
	Print a NUL-terminated ASCII string over the console.
static ra8_err_t	selftest_print_dec (uint32_t value)
	Print a uint32_t as ASCII decimal.
static ra8_err_t	selftest_print_hex (uint32_t value, uint8_t digits)
	Print a value as fixed-width uppercase hex.
static ra8_err_t	selftest_print_fail (const char *what, ra8_err_t err)
	Print "FAIL <what> err=0xNNNNNNNN" on its own line.
static const char *	selftest_fs_type_name (ra8_fs_type_t type)
	Map a detected filesystem type to a printable name.
static ra8_err_t	selftest_mount_volume (ra8_fs_mount_t **out_mount)
	Mount the loop device's volume through the USB-MSC backend.
static ra8_err_t	selftest_verify_mram_raw (void)
	Raw multi-block READ(10) of the MRAM data region vs MRAM.
static ra8_err_t	selftest_print_verify_verdict (void)
	Print the verify verdict line (bytes + duration + rate).
static ra8_err_t	selftest_write_protect_probe (void)
	WRITE(10) into the read-only LUN must be rejected.
static ra8_err_t	selftest_host_enumerate (ra8_usb_hmsc_device_t *out_device)
	Bring the host controller up and enumerate the loop device.
ra8_err_t	selftest_host_pass (void)
	One full host-side pass: enumerate, mount, browse, verify, WP.

Variables
static volatile uint32_t	s_dbg_phase
	Host-ladder phase marker (selftest_phase_t).
static volatile uint32_t	s_dbg_verified_bytes
	Bytes content-verified so far this pass.
static volatile uint32_t	s_dbg_mismatch_off = (uint32_t)k_selftest_no_mismatch
	First mismatching MRAM offset (k_selftest_no_mismatch = none).
static volatile uint32_t	s_dbg_verify_ms
	Milliseconds the 1 MiB verify streamed for.
static volatile uint32_t	s_dbg_pass_count
	Completed full passes (sticky success counter).
static ra8_io_blockdev_t	s_selftest_usb_dev
	Block device fronting the hosted MSC volume for this ladder.
static ra8_io_blockdev_usbmsc_state_t	s_selftest_usb_state
	Caller-owned backend state for s_selftest_usb_dev.

Detailed Description

Host-side console formatters + ra8_fs backend + pass ladder.

Tag: [Ring 6 / APP] {World: S}

The host half of the USB self-loop config A app: the SCI8 -> J-Link OB CDC console formatters, the ra8_fs backend vtable over the polled host-MSC class, the raw multi-block READ(10) integrity sweep against the MRAM window, the write-protect rejection probe, and the full pass ladder (selftest_host_pass). main.c's selftest_host_worker drives selftest_host_pass; the J-Link phase / verify / pass probes that track its progress live in this translation unit.

Split out of main.c verbatim to keep every translation unit under the 1000-line file-size cap; see usb_selftest_hs_host_steps.h for the shared constants and the pass-ladder contract.

Author: Brighton Sikarskie

Date: 2026-06-12

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

Since: 0.1.0

Definition in file usb_selftest_hs_host_host.c.

Function Documentation

◆ selftest_fs_type_name()

const char * selftest_fs_type_name ( ra8_fs_type_t type )

static

Map a detected filesystem type to a printable name.

Total over the enum; unknown maps to "unknown".

Parameters

[in] type Mount-time detection result.

Returns: Static NUL-terminated name string.

Return values

fat16 For k_ra8_fs_type_fat16 (the expected verdict).

Precondition: None – total over the enum.; type came from a populated mount struct.

Postcondition: No state changes.; Returned pointer references static storage.

Note: Pure function.

Since: 0.1.0

Definition at line 332 of file usb_selftest_hs_host_host.c.

References k_ra8_fs_type_exfat, k_ra8_fs_type_fat12, k_ra8_fs_type_fat16, k_ra8_fs_type_fat32, and k_ra8_fs_type_unknown.

Referenced by selftest_mount_volume().

◆ selftest_host_enumerate()

ra8_err_t selftest_host_enumerate ( ra8_usb_hmsc_device_t * out_device )

staticnodiscard

Bring the host controller up and enumerate the loop device.

Initializes the USBHS host, enumerates the downstream FS device over the cable, and prints its VID/PID. On any failure the host controller is closed so the caller's retry starts clean.

Parameters

[out] out_device Receives the enumerated device snapshot.

Returns: First failing step's error, or k_ra8_ok.

Return values

k_ra8_ok Host up and device enumerated; identity printed.

Precondition: Device-side class is registered and attached (other thread).; out_device is non-NULL.

Postcondition: On k_ra8_ok the host controller is live and out_device filled.; On failure the host controller has been closed again.

Note: Blocking; runs on the low-priority host thread.

Since: 0.1.0

Definition at line 590 of file usb_selftest_hs_host_host.c.

References k_ra8_ok, k_ra8_usb_speed_hs, k_selftest_hex_chars_u16, k_selftest_phase_enum, k_selftest_phase_host_init, ra8_usb_hmsc_device_t::product_id, ra8_usb_hmsc_close(), ra8_usb_hmsc_enumerate(), ra8_usb_hmsc_init(), s_dbg_phase, selftest_print(), selftest_print_fail(), selftest_print_hex(), and ra8_usb_hmsc_device_t::vendor_id.

Referenced by selftest_host_pass().

◆ selftest_host_pass()

ra8_err_t selftest_host_pass ( void )

nodiscard

One full host-side pass: enumerate, mount, browse, verify, WP.

Run one full soak pass and print the verdict.

One full host-side pass: enumerate, mount, verify, WP.

Drives the host-side ladder over the self-loop cable: brings the USBHS host up and enumerates the FS device, mounts and parses the FAT16 volume, browses the root directory, raw-verifies the 1 MiB MRAM data region with multi-block READ(10) bursts, then probes the write-protect rejection. Phases are mirrored into the J-Link progress probe for readout. On any failure the host controller is closed so the next retry starts from a clean attach. The host worker thread (in main.c) loops this until it returns k_ra8_ok.

Returns: First failing step's error, or k_ra8_ok.

Return values

k_ra8_ok The pass printed the BROWSE PASS banner.

Precondition: Device-side class is registered and attached (other thread).; The self-loop cable connects J7 to J11.

Postcondition: On success the pass counter advanced and LED2 is on.; On failure the host controller is deinitialized again.

Note: Blocking; runs on the low-priority host thread.

Since: 0.1.0

One full host-side pass: enumerate, mount, browse, verify, WP.

Definition at line 628 of file usb_selftest_hs_host_host.c.

References k_ra8_board_led2, k_ra8_ok, k_selftest_phase_mount, k_selftest_phase_pass, k_selftest_phase_verify, k_selftest_phase_wp, ra8_board_led_on(), ra8_fs_unmount(), ra8_usb_hmsc_close(), s_dbg_pass_count, s_dbg_phase, selftest_host_enumerate(), selftest_mount_volume(), selftest_print(), selftest_print_verify_verdict(), selftest_verify_mram_raw(), and selftest_write_protect_probe().

◆ selftest_mount_volume()

ra8_err_t selftest_mount_volume ( ra8_fs_mount_t ** out_mount )

staticnodiscard

Mount the loop device's volume through the USB-MSC backend.

Binds the ra8_io USB-MSC block device over the polled host class, bridges it to an ra8_fs backend, and prints the detected filesystem type (must be fat16 for this device).

Parameters

[out] out_mount Receives the mount handle on success.

Returns: ra8_err_t from the block-device bind, the ra8_fs bridge, or ra8_fs_mount.

Return values

k_ra8_ok Volume mounted; the type line was printed.

Precondition: ra8_usb_hmsc_enumerate completed on the loop device.; out_mount is non-NULL.

Postcondition: On k_ra8_ok the mount handle is live and must be unmounted later.; The "mounted fs=" line is queued on success.

Note: Reads the BPB chain over the self-loop cable.

Since: 0.1.0

Definition at line 370 of file usb_selftest_hs_host_host.c.

References k_ra8_ok, k_selftest_target_lun, ra8_fs_mount(), ra8_io_blockdev_as_fs_backend(), ra8_io_blockdev_usbmsc_init(), s_selftest_usb_dev, s_selftest_usb_state, selftest_fs_type_name(), selftest_print(), and selftest_print_fail().

Referenced by selftest_host_pass().

◆ selftest_nibble_to_hex()

uint8_t selftest_nibble_to_hex ( uint32_t nibble )

static

Format one nibble (0..15) into an uppercase hex character.

Standard '0'-'9' then 'A'-'F' mapping.

Parameters

[in] nibble 4-bit value.

Returns: ASCII '0'..'9' or 'A'..'F'.

Return values

'0'	For a zero nibble.

Precondition: Caller has already masked the value to 4 bits.; None beyond the mask contract.

Postcondition: Returned byte is in the printable hex range.; No state changes.

Note: Pure function.

Since: 0.1.0

Definition at line 79 of file usb_selftest_hs_host_host.c.

References k_selftest_hex_digit_split.

Referenced by selftest_print_hex().

◆ selftest_print()

ra8_err_t selftest_print ( const char * text )

staticnodiscard

Print a NUL-terminated ASCII string over the console.

Length-bounded by selftest_str_len.

Parameters

[in] text String to print (CR/LF included by the caller).

Returns: ra8_err_t propagated from the SCI helper.

Return values

k_ra8_ok All bytes queued.

Precondition: SCI8 init already ran; text is non-NULL.; text is NUL-terminated within k_selftest_print_cap bytes.

Postcondition: The string bytes are in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 159 of file usb_selftest_hs_host_host.c.

References selftest_sci_write(), and selftest_str_len().

Referenced by selftest_host_enumerate(), selftest_host_pass(), selftest_mount_volume(), selftest_print_fail(), selftest_print_verify_verdict(), and selftest_write_protect_probe().

◆ selftest_print_dec()

ra8_err_t selftest_print_dec ( uint32_t value )

staticnodiscard

Print a uint32_t as ASCII decimal.

Digit-reversal into a bounded scratch buffer.

Parameters

[in] value Value to print.

Returns: ra8_err_t propagated from the SCI helper.

Return values

k_ra8_ok All bytes queued.

Precondition: SCI8 init already ran.; None beyond console readiness.

Postcondition: One ASCII decimal token is in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 182 of file usb_selftest_hs_host_host.c.

References k_selftest_dec_chars_u32, k_selftest_dec_radix, and selftest_sci_write().

Referenced by selftest_print_verify_verdict().

◆ selftest_print_fail()

ra8_err_t selftest_print_fail	(	const char *	what,
		ra8_err_t	err )

staticnodiscard

Print "FAIL <what> err=0xNNNNNNNN" on its own line.

One-line diagnostic; print errors inside are not recoverable anyway, so the first failing chunk's code is returned.

Parameters

[in]	what	Short description of the failed step.
[in]	err	Error code returned by the step.

Returns: ra8_err_t propagated from the SCI helpers.

Return values

k_ra8_ok The diagnostic line is queued.

Precondition: SCI8 init already ran.; what is NUL-terminated within the print cap.

Postcondition: One diagnostic line is in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 259 of file usb_selftest_hs_host_host.c.

References k_ra8_ok, k_selftest_hex_chars_u32, selftest_print(), and selftest_print_hex().

Referenced by selftest_host_enumerate(), selftest_mount_volume(), selftest_verify_mram_raw(), and selftest_write_protect_probe().

◆ selftest_print_hex()

ra8_err_t selftest_print_hex	(	uint32_t	value,
		uint8_t	digits )

staticnodiscard

Print a value as fixed-width uppercase hex.

Width is clamped to 8 hex digits.

Parameters

[in]	value	Value to print.
[in]	digits	Hex digit count (4 for u16, 8 for u32).

Returns: ra8_err_t propagated from the SCI helper.

Return values

k_ra8_ok All bytes queued.

Precondition: SCI8 init already ran.; digits is at most k_selftest_hex_chars_u32.

Postcondition: One fixed-width hex token is in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 225 of file usb_selftest_hs_host_host.c.

References k_selftest_hex_chars_u32, k_selftest_nibble_bits, k_selftest_nibble_mask, selftest_nibble_to_hex(), and selftest_sci_write().

Referenced by selftest_host_enumerate(), selftest_print_fail(), and selftest_write_protect_probe().

◆ selftest_print_verify_verdict()

ra8_err_t selftest_print_verify_verdict ( void )

staticnodiscard

Print the verify verdict line (bytes + duration + rate).

"verified 1048576 bytes in N ms (M KiB/s)".

Returns: ra8_err_t propagated from the SCI helpers.

Return values

k_ra8_ok The verdict line is queued.

Precondition: ::selftest_verify_mram_file returned k_ra8_ok this pass.; SCI8 init already ran.

Postcondition: One verdict line is in the SCI8 TX FIFO.; No other state changes.

Note: Rate math guards the divide against a zero duration.

Since: 0.1.0

Definition at line 478 of file usb_selftest_hs_host_host.c.

References k_ra8_ok, k_selftest_bytes_per_kib, k_selftest_ms_per_sec, s_dbg_verified_bytes, s_dbg_verify_ms, selftest_print(), and selftest_print_dec().

Referenced by selftest_host_pass().

◆ selftest_sci_write()

ra8_err_t selftest_sci_write	(	const uint8_t *	data,
		uint32_t	len )

staticnodiscard

Push a literal block over SCI8 polled.

Thin wrapper fixing the console channel.

Parameters

[in]	data	Buffer to send.
[in]	len	Byte count.

Returns: ra8_err_t passthrough from ra8_board_uart_console_write.

Return values

k_ra8_ok All bytes queued.

Precondition: data is non-NULL; the BSP console init already ran.; len excludes any NUL terminator.

Postcondition: Bytes have been pushed out the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 136 of file usb_selftest_hs_host_host.c.

References ra8_board_uart_console_write().

Referenced by selftest_print(), selftest_print_dec(), and selftest_print_hex().

◆ selftest_str_len()

uint32_t selftest_str_len ( const char * text )

static

Bounded ASCII string length (cap k_selftest_print_cap).

Linear scan with a hard upper bound.

Parameters

[in] text NUL-terminated string.

Returns: Number of bytes before the NUL, capped.

Return values

0	For an empty string.

Precondition: text is non-NULL.; text points to readable storage of at least the returned length.

Postcondition: No state changes.; Return value never exceeds k_selftest_print_cap.

Note: Bounded scan – never walks past the cap on a missing NUL.

Since: 0.1.0

Definition at line 105 of file usb_selftest_hs_host_host.c.

References k_selftest_print_cap.

Referenced by selftest_print().

◆ selftest_verify_mram_raw()

ra8_err_t selftest_verify_mram_raw ( void )

staticnodiscard

Raw multi-block READ(10) of the MRAM data region vs MRAM.

Streams the 1 MiB data region straight through the SCSI READ(10) entry point in 8-block (4 KiB) bursts – one CBW per burst, not per sector – and memcmp's each burst against the same offset of the real MRAM window at 0x02000000. This deliberately bypasses ra8_fs: the filesystem walk re-reads FAT/metadata sectors per cluster (a ~250x device-read amplification that throttled the loop to under 1 sector/s), whereas the raw path is the direct integrity proof – "the SCSI transport returns the chip's flash byte for byte" – and runs at the cable's real rate. The mount step (separate phase) already proved the host can PARSE the FAT16 volume over the loop.

Data region: FAT16 LBA k_fat_data_lba is cluster 2 = MRAM offset 0, so LBA (data_lba + b) holds MRAM[b * 512].

Returns: ra8_err_t verdict.

Return values

k_ra8_ok	All 1 MiB matched byte for byte.
k_ra8_err_invalid_state	A byte differed from MRAM.

Precondition: ra8_usb_hmsc_enumerate completed on the loop device.; The device side exposes the synthesized MRAM volume.

Postcondition: s_dbg_verified_bytes / s_dbg_verify_ms / s_dbg_mismatch_off reflect the outcome.; No filesystem handle is held (raw SCSI path).

Note: Blocking; 256 four-KiB READ(10) bursts over the self-loop.

Since: 0.1.0

Definition at line 431 of file usb_selftest_hs_host_host.c.

References k_fat_data_lba, k_fat_mram_clusters, k_mram_base_addr, k_ra8_err_invalid_state, k_ra8_ok, k_selftest_block_size, k_selftest_burst_blocks, k_selftest_burst_bytes, k_selftest_no_mismatch, k_selftest_target_lun, memcmp(), ra8_time_ms(), ra8_usb_hmsc_read10(), s_dbg_mismatch_off, s_dbg_verified_bytes, s_dbg_verify_ms, and selftest_print_fail().

Referenced by selftest_host_pass().

◆ selftest_write_protect_probe()

ra8_err_t selftest_write_protect_probe ( void )

staticnodiscard

WRITE(10) into the read-only LUN must be rejected.

Issues a 1-block WRITE(10) into the data region. The device LUN is write-protected (MODE SENSE WP bit + media_write returns DATA PROTECT), so the host's write entry point must surface an error rather than k_ra8_ok – the MRAM is never modified. This is the write-protection proof.

It deliberately stops there: terminating a data-out phase against a write-protected device STALLs the bulk-OUT endpoint, and recovering the BOT transport afterwards (Bulk-Only Mass Storage Reset + Clear Feature ENDPOINT_HALT on both bulk pipes) is not yet implemented in the host class. That STALL/ClearFeature recovery path is tracked as GitHub issue #92's robustness sweep; this pass parks on success, so the post-STALL desync does not affect the verdict.

Returns: ra8_err_t verdict.

Return values

k_ra8_ok	The write was rejected (protection works).
k_ra8_err_invalid_state	The write was unexpectedly accepted.

Precondition: ra8_usb_hmsc_enumerate completed on the loop device.; The device LUN reports write-protected.

Postcondition: The device volume is untouched (the write never lands).; One verdict line is queued on the console.

Note: Leaves the bulk-OUT pipe halted (see details); pass parks next.

Since: 0.1.0

Definition at line 543 of file usb_selftest_hs_host_host.c.

References k_ra8_err_invalid_state, k_ra8_ok, k_selftest_block_size, k_selftest_hex_chars_u32, k_selftest_target_lun, k_selftest_wp_probe_lba, ra8_usb_hmsc_write10(), selftest_print(), selftest_print_fail(), and selftest_print_hex().

Referenced by selftest_host_pass().

Variable Documentation

◆ s_dbg_mismatch_off

volatile uint32_t s_dbg_mismatch_off = (uint32_t)k_selftest_no_mismatch

static

First mismatching MRAM offset (k_selftest_no_mismatch = none).

Definition at line 51 of file usb_selftest_hs_host_host.c.

◆ s_dbg_pass_count

volatile uint32_t s_dbg_pass_count

static

Completed full passes (sticky success counter).

Definition at line 55 of file usb_selftest_hs_host_host.c.

◆ s_dbg_phase

volatile uint32_t s_dbg_phase

static

Host-ladder phase marker (selftest_phase_t).

Definition at line 47 of file usb_selftest_hs_host_host.c.

◆ s_dbg_verified_bytes

volatile uint32_t s_dbg_verified_bytes

static

Bytes content-verified so far this pass.

Definition at line 49 of file usb_selftest_hs_host_host.c.

◆ s_dbg_verify_ms

volatile uint32_t s_dbg_verify_ms

static

Milliseconds the 1 MiB verify streamed for.

Definition at line 53 of file usb_selftest_hs_host_host.c.

◆ s_selftest_usb_dev

ra8_io_blockdev_t s_selftest_usb_dev

static

Block device fronting the hosted MSC volume for this ladder.

Bound once in selftest_mount_volume by ra8_io_blockdev_usbmsc_init, which wires the ra8_io USB-MSC backend over the polled host-MSC class. File scope because ra8_io_blockdev_as_fs_backend keeps a pointer to this handle for the whole life of the mount.

Note: Single-threaded ladder; no locking.

Warning: Do not rebind while a mount is live.

Since: 0.1.0

Definition at line 298 of file usb_selftest_hs_host_host.c.

◆ s_selftest_usb_state

ra8_io_blockdev_usbmsc_state_t s_selftest_usb_state

static

Caller-owned backend state for s_selftest_usb_dev.

Records the logical unit the backend addresses. Private to the ra8_io USB-MSC backend and must out-live every call made through the device.

Note: Single-threaded ladder; no locking.

Warning: Treat the contents as private to ra8_io.

Since: 0.1.0

Definition at line 312 of file usb_selftest_hs_host_host.c.

Functions

Variables

Detailed Description

Function Documentation

◆ selftest_fs_type_name()

◆ selftest_host_enumerate()

◆ selftest_host_pass()

◆ selftest_mount_volume()

◆ selftest_nibble_to_hex()

◆ selftest_print()

◆ selftest_print_dec()

◆ selftest_print_fail()

◆ selftest_print_hex()

◆ selftest_print_verify_verdict()

◆ selftest_sci_write()

◆ selftest_str_len()

◆ selftest_verify_mram_raw()

◆ selftest_write_protect_probe()

Variable Documentation

◆ s_dbg_mismatch_off

◆ s_dbg_pass_count

◆ s_dbg_phase

◆ s_dbg_verified_bytes

◆ s_dbg_verify_ms

◆ s_selftest_usb_dev

◆ s_selftest_usb_state