examples/ek_ra8d2/hw_validated/hil/usb_selftest_microsd/inc/usb_selftest_microsd_steps.h More...

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

Include dependency graph for usb_selftest_microsd_steps.h:

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

Enumerations
enum	microsd_config_t : uint32_t { k_microsd_thread_stack = 4096U , k_microsd_host_stack = 8192U , k_microsd_usbx_pool_bytes = 32768U , k_microsd_idle_ticks = 50U , k_microsd_boot_wait_ticks = 500U , k_microsd_retry_ticks = 3000U , k_microsd_baud = 115200U , k_microsd_sd_spi_channel = 0U , k_microsd_print_cap = 160U , k_microsd_dev_priority = 8U , k_microsd_host_priority = 24U }
	Compile-time settings: threads, pool, console, cadence. More...
enum	microsd_hex_t : uint8_t { k_microsd_hex_chars_u16 = 4U , k_microsd_hex_chars_u32 = 8U , k_microsd_dec_chars_u32 = 10U , k_microsd_nibble_bits = 4U , k_microsd_hex_digit_split = 10U }
	Hex/decimal text-formatter sizing constants. More...
enum	microsd_mask_t : uint32_t { k_microsd_nibble_mask = 0xFU , k_microsd_dec_radix = 10U }
	Bit-mask constants used by the text formatters. More...
enum	microsd_geom_t : uint32_t { k_microsd_count = 1U , k_microsd_sectors = 64U , k_microsd_block_size = 512U , k_microsd_burst_blocks = 8U , k_microsd_burst_bytes = 4096U , k_microsd_target_lun0 = 0U , k_microsd_no_mismatch = 0xFFFFFFFFU , k_microsd_snap_bytes = 64U * 512U , k_microsd_bootsig_off = 510U , k_microsd_bootsig_lo = 0x55U , k_microsd_bootsig_hi = 0xAAU }
	LUN geometry + verification constants. More...
enum	microsd_phase_t : uint32_t { k_microsd_phase_boot = 0U , k_microsd_phase_init = 1U , k_microsd_phase_enum = 2U , k_microsd_phase_verify = 3U , k_microsd_phase_pass = 4U }
	J-Link probe values marking host-ladder progress. More...
enum	microsd_dev_step_t : uint32_t { k_microsd_dev_step_stack = 1U , k_microsd_dev_step_class = 2U , k_microsd_dev_step_dcd = 3U , k_microsd_dev_step_attach = 4U , k_microsd_dev_step_parked = 5U }
	J-Link probe values marking device-worker bring-up progress. More...
enum	scsi_sense_code_t : uint8_t { k_scsi_sense_illegal_request = 0x05U , k_scsi_asc_lba_out_of_range = 0x21U , k_scsi_ascq_none = 0x00U , k_scsi_sense_data_protect = 0x07U , k_scsi_asc_write_protected = 0x27U }
	SCSI sense triple for an unsupported / out-of-range request. More...
enum	usb_langid_byte_t : uint8_t { k_usb_langid_en_us_lo = 0x09U , k_usb_langid_en_us_hi = 0x04U }

Functions
ra8_err_t	microsd_print (const char *text)
	Print a NUL-terminated ASCII string over the SCI8 console.
ra8_err_t	microsd_print_dec (uint32_t value)
	Print a uint32_t as ASCII decimal over the SCI8 console.
ra8_err_t	microsd_print_hex (uint32_t value, uint8_t digits)
	Print a value as fixed-width uppercase hex over the SCI8 console.
ra8_err_t	microsd_print_fail (const char *what, ra8_err_t err)
	Print "FAIL <what> err=0xNNNNNNNN" on its own console line.
VOID	microsd_device_worker (ULONG arg)
	Device-side worker: bring the read-only SD FS device up, then park.
VOID	microsd_host_worker (ULONG arg)
	Host-side worker: retry the full pass until it succeeds.

Variables
unsigned char	s_usb_selftest_microsd_sd_snapshot [(uint32_t) k_microsd_snap_bytes]
	Read-only RAM snapshot of SD LBA 0..63, taken once at boot.
volatile uint32_t	s_usb_selftest_microsd_dbg_bootsig
	1 = LBA0 carries the 0x55AA FAT/exFAT boot signature.

Detailed Description

examples/ek_ra8d2/hw_validated/hil/usb_selftest_microsd/inc/usb_selftest_microsd_steps.h

Shared contract for the USB-microSD self-test console + worker steps

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

Declares the constants, the two cross-translation-unit J-Link probes, and the function prototypes shared between main.c and the helper siblings usb_selftest_microsd_console.c (SCI8 console formatters) and usb_selftest_microsd_steps.c (USBX device worker, read-only MSC media callbacks, and the polled host enumerate/verify ladder). The header is self-contained: it pulls in <stdint.h> for the typed-enum underlying types and ra8_err.h for ra8_err_t. The ThreadX worker entry points are only declared when the firmware (on-target) USB stack is compiled in.

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_microsd_steps.h.

Enumeration Type Documentation

◆ microsd_config_t

enum microsd_config_t : uint32_t

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

Enumerator
k_microsd_thread_stack	Device worker stack (bytes).
k_microsd_host_stack	Host worker stack (bytes).
k_microsd_usbx_pool_bytes	USBX memory pool (bytes).
k_microsd_idle_ticks	Parked-loop back-off (ticks).
k_microsd_boot_wait_ticks	Host start delay (1 ms ticks).
k_microsd_retry_ticks	Pause between ladder retries.
k_microsd_baud	J-Link OB CDC log baud.
k_microsd_sd_spi_channel	SCI0 Simple-SPI -> Pmod2 microSD.
k_microsd_print_cap	Bound for console-string scans.
k_microsd_dev_priority	Device bring-up worker priority.
k_microsd_host_priority	Host worker priority (below USBX).

Definition at line 36 of file usb_selftest_microsd_steps.h.

◆ microsd_dev_step_t

enum microsd_dev_step_t : uint32_t

J-Link probe values marking device-worker bring-up progress.

Enumerator
k_microsd_dev_step_stack	USBX system + device stack up.
k_microsd_dev_step_class	MSC class registered.
k_microsd_dev_step_dcd	DCD bridge initialized.
k_microsd_dev_step_attach	Device attached (DPRPU).
k_microsd_dev_step_parked	Bring-up done; worker parked.

Definition at line 105 of file usb_selftest_microsd_steps.h.

◆ microsd_geom_t

enum microsd_geom_t : uint32_t

LUN geometry + verification constants.

Enumerator
k_microsd_count	Single read-only logical unit.
k_microsd_sectors	Exposed sectors (LBA 0..63).
k_microsd_block_size	SCSI logical block size.
k_microsd_burst_blocks	Blocks per READ(10) burst.
k_microsd_burst_bytes	8 x 512 B burst buffer.
k_microsd_target_lun0	First LUN index.
k_microsd_no_mismatch	Probe: no mismatch.
k_microsd_snap_bytes	RAM snapshot of LBA 0..63.
k_microsd_bootsig_off	FAT/exFAT 0x55AA at byte 510.
k_microsd_bootsig_lo	Boot-signature byte 510.
k_microsd_bootsig_hi	Boot-signature byte 511.

Definition at line 75 of file usb_selftest_microsd_steps.h.

◆ microsd_hex_t

enum microsd_hex_t : uint8_t

Hex/decimal text-formatter sizing constants.

Enumerator
k_microsd_hex_chars_u16	16-bit value -> "ABCD".
k_microsd_hex_chars_u32	32-bit value -> "ABCDEF01".
k_microsd_dec_chars_u32	Max digits for a 32-bit count.
k_microsd_nibble_bits	Bits per hex nibble.
k_microsd_hex_digit_split	Threshold between '0-9'/'A-F'.

Definition at line 54 of file usb_selftest_microsd_steps.h.

◆ microsd_mask_t

enum microsd_mask_t : uint32_t

Bit-mask constants used by the text formatters.

Enumerator
k_microsd_nibble_mask	4-bit nibble mask.
k_microsd_dec_radix	Base for decimal conversion.

Definition at line 66 of file usb_selftest_microsd_steps.h.

◆ microsd_phase_t

enum microsd_phase_t : uint32_t

J-Link probe values marking host-ladder progress.

Enumerator
k_microsd_phase_boot	Host thread not started.
k_microsd_phase_init	ra8_usb_hmsc_init issued.
k_microsd_phase_enum	Enumerating.
k_microsd_phase_verify	Reading + checking LUNs.
k_microsd_phase_pass	All LUNs verified.

Definition at line 93 of file usb_selftest_microsd_steps.h.

◆ scsi_sense_code_t

enum scsi_sense_code_t : uint8_t

SCSI sense triple for an unsupported / out-of-range request.

Enumerator
k_scsi_sense_illegal_request	Sense key: ILLEGAL REQUEST.
k_scsi_asc_lba_out_of_range	ASC: LBA out of range.
k_scsi_ascq_none	ASCQ: none.
k_scsi_sense_data_protect	Sense key: DATA PROTECT.
k_scsi_asc_write_protected	ASC: WRITE PROTECTED.

Definition at line 114 of file usb_selftest_microsd_steps.h.

◆ usb_langid_byte_t

enum usb_langid_byte_t : uint8_t

Enumerator
k_usb_langid_en_us_lo	LANGID 0x0409 low byte.
k_usb_langid_en_us_hi	LANGID 0x0409 high byte.

Definition at line 123 of file usb_selftest_microsd_steps.h.

Function Documentation

◆ microsd_device_worker()

VOID microsd_device_worker ( ULONG arg )

Device-side worker: bring the read-only SD FS device up, then park.

USBX system + device stack + MSC class (1 LUN) + DCD bridge on the USBFS controller, then DPRPU attach. USBX runs the SCSI/BBB state machine on its own class threads after this.

Parameters

[in] arg ThreadX entry argument (unused).

Precondition: tx_application_define created this thread.; USB-FS pins + 48 MHz clock are up (main did both).

Postcondition: The FS device is attached and serviceable on its single LUN.; On any bring-up failure the thread exits.

Note: Runs once; loops forever on success.

Since: 0.1.0

Definition at line 459 of file usb_selftest_microsd_steps.c.

References k_microsd_dev_step_attach, k_microsd_dev_step_class, k_microsd_dev_step_dcd, k_microsd_dev_step_parked, k_microsd_dev_step_stack, k_microsd_idle_ticks, k_ra8_ok, k_ra8_usb_speed_fs, microsd_class_register(), microsd_usbx_stack_up(), ra8_usb_device_attach(), s_dbg_dev_err, s_dbg_dev_step, tx_thread_sleep, and ux_dcd_ra8_usb_initialize().

Referenced by tx_application_define().

◆ microsd_host_worker()

VOID microsd_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/verify pass with a retry pause until the SD 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 698 of file usb_selftest_microsd_steps.c.

References k_microsd_boot_wait_ticks, k_microsd_idle_ticks, k_microsd_retry_ticks, k_ra8_ok, microsd_host_pass(), and tx_thread_sleep.

Referenced by tx_application_define().

◆ microsd_print()

ra8_err_t microsd_print ( const char * text )

nodiscard

Print a NUL-terminated ASCII string over the SCI8 console.

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_microsd_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 119 of file usb_selftest_microsd_console.c.

References microsd_sci_write(), and microsd_str_len().

Referenced by microsd_host_enumerate(), microsd_host_pass(), microsd_print_fail(), and microsd_print_lun_ok().

◆ microsd_print_dec()

ra8_err_t microsd_print_dec ( uint32_t value )

nodiscard

Print a uint32_t as ASCII decimal over the SCI8 console.

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

Print a uint32_t as ASCII decimal over the SCI8 console.

Definition at line 125 of file usb_selftest_microsd_console.c.

References k_microsd_dec_chars_u32, k_microsd_dec_radix, and microsd_sci_write().

Referenced by microsd_host_enumerate(), and microsd_print_lun_ok().

◆ microsd_print_fail()

ra8_err_t microsd_print_fail	(	const char *	what,
		ra8_err_t	err )

nodiscard

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

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 164 of file usb_selftest_microsd_console.c.

References k_microsd_hex_chars_u32, k_ra8_ok, microsd_print(), and microsd_print_hex().

Referenced by microsd_host_enumerate(), microsd_host_pass(), and microsd_verify_one().

◆ microsd_print_hex()

ra8_err_t microsd_print_hex	(	uint32_t	value,
		uint8_t	digits )

nodiscard

Print a value as fixed-width uppercase hex over the SCI8 console.

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_microsd_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

Print a value as fixed-width uppercase hex over the SCI8 console.

Definition at line 150 of file usb_selftest_microsd_console.c.

References k_microsd_hex_chars_u32, k_microsd_nibble_bits, k_microsd_nibble_mask, microsd_nibble_to_hex(), and microsd_sci_write().

Referenced by microsd_host_enumerate(), and microsd_print_fail().

Variable Documentation

◆ s_usb_selftest_microsd_dbg_bootsig

volatile uint32_t s_usb_selftest_microsd_dbg_bootsig

extern

1 = LBA0 carries the 0x55AA FAT/exFAT boot signature.

Defined and stamped in main.c during SD bring-up; read by the host-side verify ladder to confirm the snapshot is a valid boot region before the READ(10) sweep.

Note: Single-writer at boot; read-only afterwards.

Since: 0.1.0

Stamped here at SD bring-up and read by the host-side verify ladder in "usb_selftest_microsd_steps.c".

Note: Single-writer at boot; read-only afterwards.

Since: 0.1.0

Definition at line 201 of file main.c.

Referenced by microsd_sd_snapshot(), and microsd_verify_one().

◆ s_usb_selftest_microsd_sd_snapshot

unsigned char s_usb_selftest_microsd_sd_snapshot[(uint32_t) k_microsd_snap_bytes]

extern

Read-only RAM snapshot of SD LBA 0..63, taken once at boot.

Defined in main.c (populated before the kernel starts by the SD bring-up step) and read by both the device-side media-read callback and the host-side verify ladder in usb_selftest_microsd_steps.c.

Note: Single-writer at boot; read-only afterwards.

Since: 0.1.0

Populated here before the kernel starts; consumed by both the device-side media-read callback and the host-side verify ladder in "usb_selftest_microsd_steps.c".

Note: Single-writer at boot; read-only afterwards.

Since: 0.1.0

Definition at line 215 of file main.c.

Referenced by microsd_msc_read(), microsd_sd_snapshot(), and microsd_verify_one().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ microsd_config_t

◆ microsd_dev_step_t

◆ microsd_geom_t

◆ microsd_hex_t

◆ microsd_mask_t

◆ microsd_phase_t

◆ scsi_sense_code_t

◆ usb_langid_byte_t

Function Documentation

◆ microsd_device_worker()

◆ microsd_host_worker()

◆ microsd_print()

◆ microsd_print_dec()

◆ microsd_print_fail()

◆ microsd_print_hex()

Variable Documentation

◆ s_usb_selftest_microsd_dbg_bootsig

◆ s_usb_selftest_microsd_sd_snapshot