examples/ek_ra8d2/hil_needs_revalidation/usb_selftest_wlun/inc/usb_selftest_wlun_steps.h More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_usb_hmsc.h"
#include "ux_api.h"

Include dependency graph for usb_selftest_wlun_steps.h:

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

Enumerations
enum	wlun_config_t : uint32_t { k_wlun_thread_stack = 4096U , k_wlun_host_stack = 8192U , k_wlun_usbx_pool_bytes = 32768U , k_wlun_idle_ticks = 50U , k_wlun_boot_wait_ticks = 500U , k_wlun_retry_ticks = 3000U , k_wlun_baud = 115200U , k_wlun_print_cap = 160U , k_wlun_dev_priority = 8U , k_wlun_host_priority = 24U }
	Compile-time settings: threads, pool, console, cadence. More...
enum	wlun_hex_t : uint8_t { k_wlun_hex_chars_u16 = 4U , k_wlun_hex_chars_u32 = 8U , k_wlun_dec_chars_u32 = 10U , k_wlun_nibble_bits = 4U , k_wlun_hex_digit_split = 10U }
	Hex/decimal text-formatter sizing constants. More...
enum	wlun_mask_t : uint32_t { k_wlun_nibble_mask = 0xFU , k_wlun_dec_radix = 10U }
	Bit-mask constants used by the text formatters. More...
enum	wlun_geom_t : uint32_t { k_wlun_count = 1U , k_wlun_sectors = 64U , k_wlun_block_size = 512U , k_wlun_burst_blocks = 8U , k_wlun_burst_bytes = 4096U , k_wlun_target_lun0 = 0U , k_wlun_no_mismatch = 0xFFFFFFFFU , k_wlun_pat_lun_mul = 97U , k_wlun_pat_lba_mul = 7U , k_wlun_pat_bias = 0x5AU , k_wlun_byte_mask = 0xFFU , k_wlun_mismatch_lun_shift = 24U }
	LUN geometry + verification constants. More...
enum	wlun_phase_t : uint32_t { k_wlun_phase_boot = 0U , k_wlun_phase_init = 1U , k_wlun_phase_enum = 2U , k_wlun_phase_verify = 3U , k_wlun_phase_pass = 4U }
	J-Link probe values marking host-ladder progress. More...

Functions
void	wlun_pattern_fill (uint32_t lun, uint32_t lba, UCHAR *out)
	Fill one 512-byte sector with this LUN/LBA's deterministic bytes.
uint8_t	wlun_nibble_to_hex (uint32_t nibble)
	Format one nibble (0..15) into an uppercase hex character.
uint32_t	wlun_str_len (const char *text)
	Bounded ASCII string length (cap k_wlun_print_cap).
ra8_err_t	wlun_sci_write (const uint8_t *data, uint32_t len)
	Push a literal block over SCI8 polled.
ra8_err_t	wlun_print (const char *text)
	Print a NUL-terminated ASCII string over the console.
ra8_err_t	wlun_print_dec (uint32_t value)
	Print a uint32_t as ASCII decimal.
ra8_err_t	wlun_print_hex (uint32_t value, uint8_t digits)
	Print a value as fixed-width uppercase hex.
ra8_err_t	wlun_print_fail (const char *what, ra8_err_t err)
	Print "FAIL <what> err=0xNNNNNNNN" on its own line.
VOID	wlun_host_worker (ULONG arg)
	Host-side worker: retry the full pass until it succeeds.

Detailed Description

examples/ek_ra8d2/hil_needs_revalidation/usb_selftest_wlun/inc/usb_selftest_wlun_steps.h

Shared seam for the USB writable-LUN self-loop: constants + helpers

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

Splits the writable-LUN self-loop example into cohesive translation units so each one stays under the per-file line cap. This header is the single shared contract between main.c (board bring-up + device side) and the two sibling units:

usb_selftest_wlun_console.c – the deterministic per-(LUN,LBA) pattern generator plus the SCI8 polled console formatters.
usb_selftest_wlun_host.c – the polled host MSC ladder: enumerate, WRITE(10) the pattern across the whole RAM disk, then READ(10) it back and byte-check every sector.

It carries the compile-time tunables, the geometry / pattern constants, the host-ladder phase markers, and the prototypes of every helper that is referenced across translation units. main.c keeps main(), the SysTick override, tx_application_define, the USB descriptors, the device-side media callbacks, and the device-worker bring-up.

Author: Brighton Sikarskie

Date: 2026-06-13

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

Since: 0.1.0

Definition in file usb_selftest_wlun_steps.h.

Enumeration Type Documentation

◆ wlun_config_t

enum wlun_config_t : uint32_t

Compile-time settings: threads, pool, console, cadence.

Enumerator
k_wlun_thread_stack	Device worker stack (bytes).
k_wlun_host_stack	Host worker stack (bytes).
k_wlun_usbx_pool_bytes	USBX memory pool (bytes).
k_wlun_idle_ticks	Parked-loop back-off (ticks).
k_wlun_boot_wait_ticks	Host start delay (1 ms ticks).
k_wlun_retry_ticks	Pause between ladder retries.
k_wlun_baud	J-Link OB CDC log baud.
k_wlun_print_cap	Bound for console-string scans.
k_wlun_dev_priority	Device bring-up worker priority.
k_wlun_host_priority	Host worker priority (below USBX).

Definition at line 53 of file usb_selftest_wlun_steps.h.

◆ wlun_geom_t

enum wlun_geom_t : uint32_t

LUN geometry + verification constants.

Enumerator
k_wlun_count	Logical units exposed (single writable).
k_wlun_sectors	512-byte sectors (RAM disk = 32 KiB).
k_wlun_block_size	SCSI logical block size.
k_wlun_burst_blocks	Blocks per READ(10) burst.
k_wlun_burst_bytes	8 x 512 B burst buffer.
k_wlun_target_lun0	First LUN index.
k_wlun_no_mismatch	Probe: no mismatch.
k_wlun_pat_lun_mul	Per-LUN pattern multiplier.
k_wlun_pat_lba_mul	Per-LBA pattern multiplier.
k_wlun_pat_bias	Pattern constant bias.
k_wlun_byte_mask	Byte mask.
k_wlun_mismatch_lun_shift	s_dbg_mismatch: LUN in bits 31:24.

Definition at line 91 of file usb_selftest_wlun_steps.h.

◆ wlun_hex_t

enum wlun_hex_t : uint8_t

Hex/decimal text-formatter sizing constants.

Enumerator
k_wlun_hex_chars_u16	16-bit value -> "ABCD".
k_wlun_hex_chars_u32	32-bit value -> "ABCDEF01".
k_wlun_dec_chars_u32	Max digits for a 32-bit count.
k_wlun_nibble_bits	Bits per hex nibble.
k_wlun_hex_digit_split	Threshold between '0-9'/'A-F'.

Definition at line 70 of file usb_selftest_wlun_steps.h.

◆ wlun_mask_t

enum wlun_mask_t : uint32_t

Bit-mask constants used by the text formatters.

Enumerator
k_wlun_nibble_mask	4-bit nibble mask.
k_wlun_dec_radix	Base for decimal conversion.

Definition at line 82 of file usb_selftest_wlun_steps.h.

◆ wlun_phase_t

enum wlun_phase_t : uint32_t

J-Link probe values marking host-ladder progress.

Enumerator
k_wlun_phase_boot	Host thread not started.
k_wlun_phase_init	ra8_usb_hmsc_init issued.
k_wlun_phase_enum	Enumerating.
k_wlun_phase_verify	Reading + checking LUNs.
k_wlun_phase_pass	All LUNs verified.

Definition at line 110 of file usb_selftest_wlun_steps.h.

Function Documentation

◆ wlun_host_worker()

VOID wlun_host_worker ( ULONG arg )

Host-side worker: retry the full pass until it succeeds.

Waits for the device side to attach, then loops the full enumerate / WRITE(10) / verify pass with a retry pause until the writable LUN verifies; afterwards parks so the verdict stays on the wire.

Parameters

[in] arg ThreadX entry argument (unused).

Precondition: tx_application_define created this thread.; The HS host pins, expander switch, and PLL are up (main).

Postcondition: On success the pass counter and LED2 are latched.; Retries forever otherwise; each failure prints its step.

Note: Blocking calls; ms timeouts via ra8_time.

Since: 0.1.0

Definition at line 298 of file usb_selftest_wlun_host.c.

References k_ra8_ok, k_wlun_boot_wait_ticks, k_wlun_idle_ticks, k_wlun_retry_ticks, tx_thread_sleep, and wlun_host_pass().

Referenced by tx_application_define().

◆ wlun_nibble_to_hex()

uint8_t wlun_nibble_to_hex ( uint32_t nibble )

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 masked the value to 4 bits.; None beyond the mask contract.

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

Note: Pure function.

Since: 0.1.0

Definition at line 50 of file usb_selftest_wlun_console.c.

References k_wlun_hex_digit_split.

Referenced by wlun_print_hex().

◆ wlun_pattern_fill()

void wlun_pattern_fill	(	uint32_t	lun,
		uint32_t	lba,
		UCHAR *	out )

Fill one 512-byte sector with this LUN/LBA's deterministic bytes.

Byte i = (lun*97 + lba*7 + i + 0x5A) & 0xFF. Distinct per LUN and per LBA so the host can prove it addressed the right logical unit and sector. The device media-read and the host verifier compute it identically.

Parameters

[in]	lun	The logical unit (0..1).
[in]	lba	The logical block address within the LUN.
[out]	out	512-byte destination buffer.

Precondition: out has k_wlun_block_size writable bytes.; lun and lba are within the exposed geometry.

Postcondition: out holds the sector's pattern bytes.; No global state changes.

Note: Pure function.

Since: 0.1.0

Definition at line 37 of file usb_selftest_wlun_console.c.

References k_wlun_block_size, k_wlun_byte_mask, k_wlun_pat_bias, k_wlun_pat_lba_mul, and k_wlun_pat_lun_mul.

Referenced by wlun_verify_one(), and wlun_write_disk().

◆ wlun_print()

ra8_err_t wlun_print ( const char * text )

nodiscard

Print a NUL-terminated ASCII string over the console.

Length-bounded by wlun_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_wlun_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 75 of file usb_selftest_wlun_console.c.

References wlun_sci_write(), and wlun_str_len().

Referenced by wlun_host_enumerate(), wlun_host_pass(), wlun_print_fail(), and wlun_print_lun_ok().

◆ wlun_print_dec()

ra8_err_t wlun_print_dec ( uint32_t value )

nodiscard

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 80 of file usb_selftest_wlun_console.c.

References k_wlun_dec_chars_u32, k_wlun_dec_radix, and wlun_sci_write().

Referenced by wlun_host_enumerate(), and wlun_print_lun_ok().

◆ wlun_print_fail()

ra8_err_t wlun_print_fail	(	const char *	what,
		ra8_err_t	err )

nodiscard

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

One-line diagnostic; first failing chunk's code 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 118 of file usb_selftest_wlun_console.c.

References k_ra8_ok, k_wlun_hex_chars_u32, wlun_print(), and wlun_print_hex().

Referenced by wlun_host_enumerate(), wlun_host_pass(), wlun_verify_one(), and wlun_write_disk().

◆ wlun_print_hex()

ra8_err_t wlun_print_hex	(	uint32_t	value,
		uint8_t	digits )

nodiscard

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_wlun_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 104 of file usb_selftest_wlun_console.c.

References k_wlun_hex_chars_u32, k_wlun_nibble_bits, k_wlun_nibble_mask, wlun_nibble_to_hex(), and wlun_sci_write().

Referenced by wlun_host_enumerate(), and wlun_print_fail().

◆ wlun_sci_write()

ra8_err_t wlun_sci_write	(	const uint8_t *	data,
		uint32_t	len )

nodiscard

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; SCI8 init already ran.; len excludes any NUL terminator.

Postcondition: Bytes are in the SCI8 TX FIFO.; No other state changes.

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 70 of file usb_selftest_wlun_console.c.

References ra8_board_uart_console_write().

Referenced by wlun_print(), wlun_print_dec(), and wlun_print_hex().

◆ wlun_str_len()

uint32_t wlun_str_len ( const char * text )

Bounded ASCII string length (cap k_wlun_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 length.

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

Note: Bounded scan.

Since: 0.1.0

Definition at line 58 of file usb_selftest_wlun_console.c.

References k_wlun_print_cap.

Referenced by wlun_print().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ wlun_config_t

◆ wlun_geom_t

◆ wlun_hex_t

◆ wlun_mask_t

◆ wlun_phase_t

Function Documentation

◆ wlun_host_worker()

◆ wlun_nibble_to_hex()

◆ wlun_pattern_fill()

◆ wlun_print()

◆ wlun_print_dec()

◆ wlun_print_fail()

◆ wlun_print_hex()

◆ wlun_sci_write()

◆ wlun_str_len()