usb_host_msc_browse_steps.h File Reference

Shared constants + device-side FAT16/MSC step declarations. More...

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

Include dependency graph for usb_host_msc_browse_steps.h:

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

Go to the source code of this file.

Enumerations
enum	selftest_config_t : uint32_t {   k_selftest_thread_stack = 4096U ,   k_selftest_host_stack = 8192U ,   k_selftest_usbx_pool_bytes = 32768U ,   k_selftest_block_size = 512U ,   k_selftest_idle_ticks = 50U ,   k_selftest_boot_wait_ticks = 500U ,   k_selftest_retry_ticks = 5000U ,   k_selftest_baud = 115200U ,   k_selftest_print_cap = 160U ,   k_selftest_dev_priority = 8U ,   k_selftest_host_priority = 24U }
	Compile-time settings: threads, pool, console, retry cadence. More...
enum	selftest_mram_t : uint32_t {   k_mram_base_addr = 0x02000000U ,   k_mram_bytes = 0x00100000U }
	The MRAM window the device-side volume exposes. More...
enum	selftest_fat_geom_t : uint32_t {   k_fat_reserved_sectors = 1U ,   k_fat_num_fats = 1U ,   k_fat_fat_sectors = 17U ,   k_fat_root_entries = 512U ,   k_fat_root_sectors = 32U ,   k_fat_data_sectors = 4096U ,   k_fat_fat_lba = 1U ,   k_fat_root_lba = 18U ,   k_fat_data_lba = 50U ,   k_fat_total_sectors = 4146U ,   k_fat_first_cluster = 2U ,   k_fat_mram_clusters = 2048U ,   k_fat_last_mram_clus = 2049U ,   k_fat_entries_per_sec = 256U ,   k_fat_eoc = 0xFFFFU ,   k_fat_entry0 = 0xFFF8U }
	Synthesized FAT16 volume geometry (MS FAT spec 1.03). More...
enum	selftest_fat_off_t : uint8_t {   k_bpb_off_jmp = 0U ,   k_bpb_off_oem = 3U ,   k_bpb_off_bps = 11U ,   k_bpb_off_spc = 13U ,   k_bpb_off_rsvd = 14U ,   k_bpb_off_nfats = 16U ,   k_bpb_off_rootent = 17U ,   k_bpb_off_totsec16 = 19U ,   k_bpb_off_media = 21U ,   k_bpb_off_fatsz16 = 22U ,   k_bpb_off_spt = 24U ,   k_bpb_off_heads = 26U ,   k_bpb_off_drvnum = 36U ,   k_bpb_off_bootsig = 38U ,   k_bpb_off_volid = 39U ,   k_bpb_off_label = 43U ,   k_bpb_off_fstype = 54U ,   k_dir_entry_bytes = 32U ,   k_dir_off_attr = 11U ,   k_dir_off_cluster_lo = 26U ,   k_dir_off_size = 28U ,   k_dir_attr_volume = 0x08U ,   k_dir_attr_read_only = 0x01U ,   k_dir_name_bytes = 11U ,   k_byte_shift = 8U ,   k_byte_mask = 0xFFU }
	Byte offsets inside the boot sector and directory entries. More...

Functions
UINT	selftest_msc_read (VOID *storage, ULONG lun, UCHAR *data_pointer, ULONG number_blocks, ULONG lba, ULONG *media_status)
	Storage media-read callback: synthesize sectors over MRAM.
UINT	selftest_msc_write (VOID *storage, ULONG lun, UCHAR *data_pointer, ULONG number_blocks, ULONG lba, ULONG *media_status)
	Storage media-write callback: always rejects (write-protected).
UINT	selftest_msc_status (VOID *storage, ULONG lun, ULONG media_id, ULONG *media_status)
	Storage media-status callback.
ra8_err_t	selftest_host_pass (void)
	One full host-side pass: enumerate, mount, browse, verify, WP.

Detailed Description

Shared constants + device-side FAT16/MSC step declarations.

Tag

[Ring 6 / APP] {World: S}

Companion header for the usb_host_msc_browse self-loop app. It carries the volume-geometry and field-offset enums that BOTH main.c and the device-side step translation unit (usb_host_msc_browse_steps.c) reference, plus the prototypes for the three USBX storage media callbacks that the step TU defines but main.c's class-register helper still wires into the LUN.

The header is self-contained: it pulls in <stdint.h> for the typed-enum underlying types and, only in the on-target firmware build, ux_api.h for the USBX UINT/VOID/UCHAR/ULONG types used by the callback signatures.

Author

Brighton Sikarskie

Date

2026-06-25

Copyright

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

Since

0.1.0

Definition in file usb_host_msc_browse_steps.h.

Enumeration Type Documentation

selftest_config_t

enum selftest_config_t : uint32_t

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

Enumerator
k_selftest_thread_stack	Device worker stack (bytes).
k_selftest_host_stack	Host worker stack (bytes).
k_selftest_usbx_pool_bytes	USBX memory pool (bytes).
k_selftest_block_size	SCSI logical block size (bytes).
k_selftest_idle_ticks	Parked-loop back-off (ticks).
k_selftest_boot_wait_ticks	Host start delay (1 ms ticks).
k_selftest_retry_ticks	Pause between ladder retries.
k_selftest_baud	J-Link OB CDC log baud.
k_selftest_print_cap	Bound for console-string scans.
k_selftest_dev_priority	Device bring-up worker priority.
k_selftest_host_priority	Host worker: BELOW the USBX storage class thread (UX_THREAD_PRIORITY_CLASS = 20). The polled host loop busy-waits for device data; if it outranked the class thread, that thread could never run selftest_msc_read and every bulk read would time out (enumeration still works – device SETUP is ISR-driven).

Definition at line 41 of file usb_host_msc_browse_steps.h.

selftest_fat_geom_t

enum selftest_fat_geom_t : uint32_t

Synthesized FAT16 volume geometry (MS FAT spec 1.03).

Identical to usb_msc_mram: one 512-byte sector per cluster, data region padded to 4096 clusters to cross the FAT16 threshold, MRAM.BIN occupying clusters 2..2049.

Enumerator
k_fat_reserved_sectors	Boot sector only.
k_fat_num_fats	Single FAT copy.
k_fat_fat_sectors	FAT16 size for 4098 entries.
k_fat_root_entries	Root directory entries.
k_fat_root_sectors	512 entries x 32 B / 512 B.
k_fat_data_sectors	Padded data region (>= 4085).
k_fat_fat_lba	First FAT sector.
k_fat_root_lba	First root-directory sector.
k_fat_data_lba	First data sector (cluster 2).
k_fat_total_sectors	1 + 17 + 32 + 4096.
k_fat_first_cluster	FAT data area starts at cluster 2.
k_fat_mram_clusters	Clusters backed by MRAM (1 MiB).
k_fat_last_mram_clus	Last cluster of MRAM.BIN.
k_fat_entries_per_sec	FAT16 entries per 512-byte sector.
k_fat_eoc	End-of-chain marker.
k_fat_entry0	FAT[0]: media F8 + filler.

Definition at line 81 of file usb_host_msc_browse_steps.h.

selftest_fat_off_t

enum selftest_fat_off_t : uint8_t

Byte offsets inside the boot sector and directory entries.

Enumerator
k_bpb_off_jmp	Jump instruction.
k_bpb_off_oem	OEM name (8 bytes).
k_bpb_off_bps	Bytes per sector.
k_bpb_off_spc	Sectors per cluster.
k_bpb_off_rsvd	Reserved sector count.
k_bpb_off_nfats	Number of FATs.
k_bpb_off_rootent	Root entry count.
k_bpb_off_totsec16	Total sectors (16-bit).
k_bpb_off_media	Media descriptor.
k_bpb_off_fatsz16	Sectors per FAT.
k_bpb_off_spt	Sectors per track.
k_bpb_off_heads	Head count.
k_bpb_off_drvnum	Drive number.
k_bpb_off_bootsig	Extended boot signature.
k_bpb_off_volid	Volume serial (4 bytes).
k_bpb_off_label	Volume label (11 bytes).
k_bpb_off_fstype	Filesystem type (8 bytes).
k_dir_entry_bytes	Directory entry size.
k_dir_off_attr	Attribute byte.
k_dir_off_cluster_lo	First cluster (low word).
k_dir_off_size	File size (32-bit LE).
k_dir_attr_volume	Volume-label attribute.
k_dir_attr_read_only	Read-only attribute.
k_dir_name_bytes	8.3 name field length.
k_byte_shift	Bits per byte for LE packing.
k_byte_mask	Low-byte mask.

Definition at line 104 of file usb_host_msc_browse_steps.h.

selftest_mram_t

enum selftest_mram_t : uint32_t

The MRAM window the device-side volume exposes.

Enumerator
k_mram_base_addr	MRAM code window base address.
k_mram_bytes	1 MiB window size.

Definition at line 68 of file usb_host_msc_browse_steps.h.

Function Documentation

selftest_host_pass()

ra8_err_t selftest_host_pass ( void )

nodiscard

One full host-side pass: enumerate, mount, browse, 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.

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

Enumerates and mounts to prove FAT parse, then runs selftest_verify_mram_raw k_selftest_soak_iters times back to back – every burst is still memcmp'd vs MRAM, so a single corrupted transfer anywhere in the soak fails the run. Aggregates volume + time for a stable throughput benchmark, then confirms the RO write rejection once. s_dbg_pass_count mirrors the completed-iteration count for J-Link.

Returns

First failing step's error, or k_ra8_ok.

Return values

k_ra8_ok

All iterations matched; SOAK PASS printed.

Precondition

Device-side class is registered and attached (other thread).

The self-loop cable connects J7 to J11.

Postcondition

On success LED2 is on and the aggregate + PASS lines are queued.

On failure the host controller is closed for a clean retry.

Note

Blocking; ~k_selftest_soak_iters MiB over the loop.

Since

0.1.0

Definition at line 738 of file usb_host_msc_browse_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_browse_root(), selftest_host_enumerate(), selftest_mount_volume(), selftest_print(), selftest_print_verify_verdict(), selftest_verify_mram_raw(), and selftest_write_protect_probe().

Referenced by selftest_host_worker().

selftest_msc_read()

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

Storage media-read callback: synthesize sectors over MRAM.

Bound checks the request against the volume, then fills each block via the FAT16 synthesizer. LED1 toggles per call so the self-loop traffic is visible on the board.

Parameters

[in,out]	storage	USBX storage class instance (unused).
[in]	lun	Logical unit number (must be 0).
[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 volume; otherwise UX_ERROR with media_status set to ILLEGAL REQUEST.

Return values

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

Precondition

data_pointer and media_status are non-NULL (USBX guarantee).

lun is 0 (single-LUN device).

Postcondition

Either number_blocks * 512 bytes were synthesized or media_status is non-zero.

The device-side read-call probe advanced.

Note

Called from the USBX storage class thread.

Since

0.1.0

Bound checks the request against the volume, then fills each block via selftest_fat_fill_sector. LED1 toggles per call so the self-loop traffic is visible on the board.

Parameters

[in,out]	storage	USBX storage class instance (unused).
[in]	lun	Logical unit number (must be 0).
[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 volume; otherwise UX_ERROR with media_status set to ILLEGAL REQUEST.

Return values

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

Precondition

data_pointer and media_status are non-NULL (USBX guarantee).

lun is 0 (single-LUN device).

Postcondition

Either number_blocks * 512 bytes were synthesized 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 304 of file usb_host_msc_browse_steps.c.

References k_fat_total_sectors, k_ra8_board_led1, k_scsi_asc_lba_out_of_range, k_scsi_ascq_none, k_scsi_sense_illegal_request, k_selftest_block_size, ra8_board_led_toggle(), s_dbg_read_calls, and selftest_fat_fill_sector().

Referenced by selftest_msc_class_register(), selftest_msc_class_register(), and selftest_msc_class_register().

selftest_msc_status()

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

Storage media-status callback.

Always reports media-present.

The synthesized volume cannot go away; 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 volume; never reports media-not-present.

Since

0.1.0

Definition at line 347 of file usb_host_msc_browse_steps.c.

Referenced by selftest_msc_class_register(), selftest_msc_class_register(), and selftest_msc_class_register().

selftest_msc_write()

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

Storage media-write callback: always rejects (write-protected).

The host side of this very app probes exactly this rejection (WRITE(10) must fail with DATA PROTECT and the transport must keep working afterwards).

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 also reports write-protected via MODE SENSE.

Postcondition

*media_status carries the DATA PROTECT sense triple.

The MRAM window is untouched.

Note

Hosts honouring the MODE SENSE WP bit never call this.

Since

0.1.0

Definition at line 328 of file usb_host_msc_browse_steps.c.

References k_scsi_asc_write_protected, k_scsi_ascq_none, and k_scsi_sense_data_protect.

Referenced by selftest_msc_class_register(), selftest_msc_class_register(), and selftest_msc_class_register().