examples/ek_ra8d2/hw_validated/hil/usb_selftest_microsd/src/usb_selftest_microsd_steps.c More...

#include "usb_selftest_microsd_steps.h"
#include <stdint.h>
#include <string.h>
#include "ra8_board_ek_ra8d2.h"
#include "ra8_err.h"
#include "ra8_usb.h"
#include "ra8_usb_hmsc.h"
#include "tx_api.h"
#include "ux_api.h"
#include "ux_dcd_ra8_usb.h"
#include "ux_device_class_storage.h"
#include "ux_device_stack.h"

Include dependency graph for usb_selftest_microsd_steps.c:

Functions
static UINT	microsd_msc_read (VOID storage, ULONG lun, UCHAR data_pointer, ULONG number_blocks, ULONG lba, ULONG *media_status)
	Storage media-read callback: serve the boot-time SD snapshot.
static UINT	microsd_msc_write (VOID storage, ULONG lun, UCHAR data_pointer, ULONG number_blocks, ULONG lba, ULONG *media_status)
	Storage media-write callback: reject (all LUNs are read-only).
static UINT	microsd_msc_status (VOID storage, ULONG lun, ULONG media_id, ULONG media_status)
	Storage media-status callback.
static UINT	microsd_usbx_stack_up (void)
	Bring USBX system + device stack up with the MSC framework.
static void	microsd_fill_lun (UX_SLAVE_CLASS_STORAGE_PARAMETER *p, uint32_t idx)
	Populate the LUN parameter slot with geometry + callbacks.
static UINT	microsd_class_register (void)
	Register the Mass-Storage class with one read-only LUN.
VOID	microsd_device_worker (ULONG arg)
	Device-side worker: bring the read-only SD FS device up, then park.
static ra8_err_t	microsd_verify_one (uint32_t lun)
	Read + verify the LUN's sectors against the SD snapshot.
static ra8_err_t	microsd_print_lun_ok (uint32_t lun)
	Print "LUN n OK (256 sectors)" for a verified logical unit.
static ra8_err_t	microsd_host_enumerate (ra8_usb_hmsc_device_t *device)
	Enumerate the looped device and print its PID + GET_MAX_LUN.
static ra8_err_t	microsd_host_pass (void)
	One full host-side pass: enumerate, verify the SD snapshot.
VOID	microsd_host_worker (ULONG arg)
	Host-side worker: retry the full pass until it succeeds.

Variables
static UCHAR	s_usbx_pool [k_microsd_usbx_pool_bytes]
	USBX memory pool (USBX uses tx_byte_pool internally).
static UCHAR	s_msc_vendor_id [] = "RA8D2 "
static UCHAR	s_msc_product_id [] = "MICROSD CARD RO "
static UCHAR	s_msc_product_rev [] = "0001"
static volatile uint32_t	s_dbg_phase
	Host-ladder phase marker (microsd_phase_t).
static volatile uint32_t	s_dbg_luns_ok
	Sectors that read back matching the SD snapshot this pass.
static volatile uint32_t	s_dbg_max_lun
	Device-reported GET_MAX_LUN value (expect 0, single LUN).
static volatile uint32_t	s_dbg_mismatch = (uint32_t)k_microsd_no_mismatch
	First mismatching sector, or k_microsd_no_mismatch.
static volatile uint32_t	s_dbg_pass_count
	Completed full passes (sticky success counter).
static volatile uint32_t	s_dbg_read_calls
	Device-side media_read invocations.
static volatile uint32_t	s_dbg_dev_step
	Device worker progress: 1 stack, 2 class, 3 dcd, 4 attach, 5 parked.
static volatile uint32_t	s_dbg_dev_err
	Device worker first failing return code (0 = none).
static UCHAR	s_device_framework_fs []
static UCHAR	s_string_framework []
	USBX string descriptor table (vendor / product / serial).
static UCHAR	s_language_id_framework [] = {k_usb_langid_en_us_lo, k_usb_langid_en_us_hi}
	USBX language-id table – US English.

Detailed Description

examples/ek_ra8d2/hw_validated/hil/usb_selftest_microsd/src/usb_selftest_microsd_steps.c

USBX device worker, read-only MSC media callbacks, and host verify ladder

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

Split out of main.c to keep every translation unit under the line-count cap. Holds the device-side bring-up (USBX system + device stack

single read-only Mass-Storage LUN + DCD attach), the read-only media callbacks that serve the boot-time SD snapshot, and the polled host-side enumerate/READ(10)/verify ladder that byte-checks the looped device against that same snapshot. The two cross-TU probes (s_usb_selftest_microsd_sd_snapshot, s_usb_selftest_microsd_dbg_bootsig) are defined in main.c (stamped at SD bring-up before the kernel starts) and consumed here; everything else this file needs is owned locally.

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

Function Documentation

◆ microsd_class_register()

UINT microsd_class_register ( void )

static

Register the Mass-Storage class with one read-only LUN.

Sets number_lun = 1 and fills the single LUN slot via microsd_fill_lun, so the host's GET_MAX_LUN returns 0. One LUN is the minimal read-only microSD exposure.

Returns: UINT UX_SUCCESS on success.

Return values

UX_SUCCESS Class registered.

Precondition: microsd_usbx_stack_up has succeeded.; Media callbacks are defined.

Postcondition: MSC class bound to configuration 1, interface 0, with 1 LUN.; GET_MAX_LUN will report 0.

Note: Not re-entrant.

Since: 0.1.0

Definition at line 439 of file usb_selftest_microsd_steps.c.

References k_microsd_count, memset(), microsd_fill_lun(), s_msc_product_id, s_msc_product_rev, and s_msc_vendor_id.

Referenced by microsd_device_worker().

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

void microsd_fill_lun	(	UX_SLAVE_CLASS_STORAGE_PARAMETER *	p,
		uint32_t	idx )

static

Populate the LUN parameter slot with geometry + callbacks.

The single LUN is a read-only FAT-disk-typed, removable, 64-sector microSD-backed volume whose media callbacks serve the boot SD snapshot.

Parameters

[in,out]	p	The class parameter block.
[in]	idx	LUN slot index (0..1).

Precondition: p is zeroed and being filled before class register.; idx is below k_microsd_count.

Postcondition: Slot idx carries the geometry + media callbacks.; No other slot is touched.

Note: Helper to keep the register function within the size cap.

Since: 0.1.0

Definition at line 402 of file usb_selftest_microsd_steps.c.

References k_microsd_block_size, k_microsd_sectors, microsd_msc_read(), microsd_msc_status(), and microsd_msc_write().

Referenced by microsd_class_register().

◆ microsd_host_enumerate()

ra8_err_t microsd_host_enumerate ( ra8_usb_hmsc_device_t * device )

staticnodiscard

Enumerate the looped device and print its PID + GET_MAX_LUN.

Sets the enum phase, runs ra8_usb_hmsc_enumerate, records the reported max-LUN in s_dbg_max_lun, and streams the enumerated pid=... GET_MAX_LUN=... banner. On enumerate failure the host controller is closed so the next retry re-attaches clean.

Parameters

[out] device Receives the enumerated descriptor snapshot.

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

Return values

k_ra8_ok Device enumerated and the banner printed.

Precondition: device is non-null.; ra8_usb_hmsc_init has succeeded on this pass.

Postcondition: s_dbg_max_lun mirrors the device's GET_MAX_LUN.; On failure the host controller is deinitialized.

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

Since: 0.1.0

Definition at line 608 of file usb_selftest_microsd_steps.c.

References k_microsd_hex_chars_u16, k_microsd_phase_enum, k_ra8_ok, ra8_usb_hmsc_device_t::max_lun, microsd_print(), microsd_print_dec(), microsd_print_fail(), microsd_print_hex(), ra8_usb_hmsc_device_t::product_id, ra8_usb_hmsc_close(), ra8_usb_hmsc_enumerate(), s_dbg_max_lun, and s_dbg_phase.

Referenced by microsd_host_pass().

◆ microsd_host_pass()

ra8_err_t microsd_host_pass ( void )

staticnodiscard

One full host-side pass: enumerate, verify the SD snapshot.

Phases mirror microsd_phase_t. On any failure the host controller is closed so the next retry starts from a clean attach.

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

Return values

k_ra8_ok The pass printed MICROSD PASS.

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

Postcondition: On success s_dbg_pass_count 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

Definition at line 654 of file usb_selftest_microsd_steps.c.

References k_microsd_count, k_microsd_phase_init, k_microsd_phase_pass, k_microsd_phase_verify, k_ra8_board_led2, k_ra8_ok, k_ra8_usb_speed_hs, microsd_host_enumerate(), microsd_print(), microsd_print_fail(), microsd_print_lun_ok(), microsd_verify_one(), ra8_board_led_on(), ra8_usb_hmsc_close(), ra8_usb_hmsc_init(), s_dbg_luns_ok, s_dbg_pass_count, and s_dbg_phase.

Referenced by microsd_host_worker().

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

UINT microsd_msc_read	(	VOID *	storage,
		ULONG	lun,
		UCHAR *	data_pointer,
		ULONG	number_blocks,
		ULONG	lba,
		ULONG *	media_status )

static

Storage media-read callback: serve the boot-time SD snapshot.

Bound-checks the request against the exposed window, then copies the bytes straight out of s_usb_selftest_microsd_sd_snapshot (the read-only image of SD LBA 0..63 captured at boot). No live card access happens on the class thread. LED1 toggles per call so loop traffic is visible.

Parameters

[in,out]	storage	USBX storage class instance (unused).
[in]	lun	Logical unit number (unused; single LUN).
[out]	data_pointer	USBX-owned destination buffer.
[in]	number_blocks	Number of 512-byte blocks to produce.
[in]	lba	Starting LBA.
[out]	media_status	Filled with sense status word.

Returns: UX_SUCCESS if the request fits the window; else UX_ERROR.

Return values

UX_SUCCESS	Read completed from the snapshot.
UX_ERROR	Out-of-range LBA / count.

Precondition: data_pointer / media_status are non-NULL (USBX guarantee).; s_usb_selftest_microsd_sd_snapshot was populated at boot.

Postcondition: Either the blocks were copied or media_status is non-zero.; s_dbg_read_calls advanced.

Note: Called from the USBX storage class thread.

Since: 0.1.0

Definition at line 251 of file usb_selftest_microsd_steps.c.

References k_microsd_block_size, k_microsd_sectors, k_ra8_board_led1, k_scsi_asc_lba_out_of_range, k_scsi_ascq_none, k_scsi_sense_illegal_request, memcpy(), ra8_board_led_toggle(), s_dbg_read_calls, and s_usb_selftest_microsd_sd_snapshot.

Referenced by microsd_fill_lun().

◆ microsd_msc_status()

UINT microsd_msc_status	(	VOID *	storage,
		ULONG	lun,
		ULONG	media_id,
		ULONG *	media_status )

static

Storage media-status callback.

Always reports media-present.

Synthesized LUNs never go absent; status is constant 0.

Parameters

[in,out]	storage	USBX storage class instance (unused).
[in]	lun	Logical unit number (unused).
[in]	media_id	Media id (unused).
[out]	media_status	Filled with 0 (no fault).

Returns: Always UX_SUCCESS.

Return values

UX_SUCCESS Media is present and ready.

Precondition: media_status is non-NULL (USBX guarantee).; The class instance is live.

Postcondition: *media_status is 0.; No other state changes.

Note: Synthesized volumes; never report media-not-present.

Since: 0.1.0

Definition at line 339 of file usb_selftest_microsd_steps.c.

Referenced by microsd_fill_lun().

◆ microsd_msc_write()

UINT microsd_msc_write	(	VOID *	storage,
		ULONG	lun,
		UCHAR *	data_pointer,
		ULONG	number_blocks,
		ULONG	lba,
		ULONG *	media_status )

static

Storage media-write callback: reject (all LUNs are read-only).

The single microSD-backed volume is read-only; any WRITE(10) is refused with DATA PROTECT. Hosts honouring the MODE SENSE WP bit never call this.

Parameters

[in,out]	storage	USBX storage class instance (unused).
[in]	lun	Logical unit number (unused).
[in]	data_pointer	USBX-owned source buffer (unused).
[in]	number_blocks	Number of blocks the host tried (unused).
[in]	lba	Starting LBA (unused).
[out]	media_status	Filled with DATA PROTECT sense.

Returns: Always UX_ERROR.

Return values

UX_ERROR The medium is write-protected.

Precondition: media_status is non-NULL (USBX guarantee).; The LUN reports write-protected via MODE SENSE.

Postcondition: *media_status carries the DATA PROTECT sense triple.; No synthesized content changes.

Note: Hosts honouring the MODE SENSE WP bit never call this.

Since: 0.1.0

Definition at line 300 of file usb_selftest_microsd_steps.c.

References k_scsi_asc_write_protected, k_scsi_ascq_none, and k_scsi_sense_data_protect.

Referenced by microsd_fill_lun().

◆ microsd_print_lun_ok()

ra8_err_t microsd_print_lun_ok ( uint32_t lun )

staticnodiscard

Print "LUN n OK (256 sectors)" for a verified logical unit.

Parameters

[in] lun The LUN that just verified.

Returns: ra8_err_t propagated from the SCI helpers.

Return values

k_ra8_ok The line is queued.

Precondition: microsd_verify_one returned k_ra8_ok for lun.; SCI8 init already ran.

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

Note: Blocking polled TX.

Since: 0.1.0

Definition at line 574 of file usb_selftest_microsd_steps.c.

References k_ra8_ok, microsd_print(), and microsd_print_dec().

Referenced by microsd_host_pass().

◆ microsd_usbx_stack_up()

UINT microsd_usbx_stack_up ( void )

static

Bring USBX system + device stack up with the MSC framework.

One-shot USBX pool + device-stack init (FS-only framework).

Returns: UINT UX_SUCCESS on success.

Return values

UX_SUCCESS Stack ready.

Precondition: File-scope pool reserved.; Thread context.

Postcondition: Device stack accepts class registrations.; On failure USBX state is undefined.

Note: Single-call; not idempotent.

Since: 0.1.0

Definition at line 368 of file usb_selftest_microsd_steps.c.

References k_microsd_usbx_pool_bytes, s_device_framework_fs, s_language_id_framework, s_string_framework, and s_usbx_pool.

Referenced by microsd_device_worker().

◆ microsd_verify_one()

ra8_err_t microsd_verify_one ( uint32_t lun )

staticnodiscard

Read + verify the LUN's sectors against the SD snapshot.

READ_CAPACITY (must report k_microsd_sectors), confirm the SD boot signature, then a raw multi-block READ(10) sweep in 8-block against the boot-time SD snapshot (s_usb_selftest_microsd_sd_snapshot).

Parameters

[in] lun Logical unit to verify (0..1).

Returns: ra8_err_t verdict.

Return values

k_ra8_ok	Every sector matched the SD snapshot.
k_ra8_err_invalid_size	READ_CAPACITY reported wrong geometry.
k_ra8_err_invalid_state	A byte differed from the snapshot.