Shared constants + step prototypes for the OSPI USB self-loop app. More...

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

Include dependency graph for usb_selftest_ospi_steps.h:

This graph shows which files directly or indirectly include 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_hex_t : uint8_t { k_selftest_hex_chars_u16 = 4U , k_selftest_hex_chars_u32 = 8U , k_selftest_dec_chars_u32 = 10U , k_selftest_nibble_bits = 4U , k_selftest_hex_digit_split = 10U }
	Hex/decimal text-formatter sizing constants. More...
enum	selftest_mask_t : uint32_t { k_selftest_nibble_mask = 0xFU , k_selftest_dec_radix = 10U }
	Bit-mask constants used by the text formatters. More...
enum	selftest_verify_t : uint32_t { k_selftest_burst_blocks = 8U , k_selftest_burst_bytes = 4096U , k_selftest_target_lun = 0U , k_selftest_wp_probe_lba = 50U , k_selftest_no_mismatch = 0xFFFFFFFFU , k_selftest_ms_per_sec = 1000U , k_selftest_bytes_per_kib = 1024U }
	Content-verification geometry over the device's FAT16 volume. More...
enum	selftest_phase_t : uint32_t { k_selftest_phase_boot = 0U , k_selftest_phase_host_init = 1U , k_selftest_phase_enum = 2U , k_selftest_phase_mount = 3U , k_selftest_phase_verify = 4U , k_selftest_phase_wp = 5U , k_selftest_phase_pass = 6U }
	J-Link probe values marking host-ladder progress. More...
enum	selftest_ospi_t : uint32_t { k_ospi_instance = 0U , k_ospi_test_offset = 0x00100000U , k_ospi_bytes = 0x00100000U , k_ospi_erase_sector = 0x00001000U , k_ospi_erase_count = 256U }
	OSPI flash geometry the device-side volume is backed by. More...
enum	selftest_pattern_t : uint32_t { k_ospi_pat_smul = 31U , k_ospi_pat_imul = 131U , k_ospi_pat_bias = 0xA5U , k_ospi_pat_mask = 0xFFU }
	Deterministic sector-pattern coefficients (device + host agree). 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 }
	SCSI sense triple for an unsupported / out-of-range request. More...
enum	scsi_wp_sense_t : uint8_t { k_scsi_sense_data_protect = 0x07U , k_scsi_asc_write_protected = 0x27U }
	SCSI sense triple for a write to the protected medium. 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_data_clusters = 2048U , k_fat_last_data_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_boot_t : uint32_t { k_boot_jmp0 = 0xEBU , k_boot_jmp1 = 0x3CU , k_boot_jmp2 = 0x90U , k_boot_media = 0xF8U , k_boot_sec_per_trk = 32U , k_boot_num_heads = 16U , k_boot_drive_num = 0x80U , k_boot_ext_sig = 0x29U , k_boot_volume_id = 0x52A8D20AU , k_boot_sig_lo = 0x55U , k_boot_sig_hi = 0xAAU , k_boot_sig_lo_off = 510U , k_boot_sig_hi_off = 511U }
	Boot-sector field values (MS FAT spec 1.03 sec 3.1). 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...
enum	selftest_word_pack_t : uint32_t { k_word_shift = 16U , k_word_mask = 0xFFFFU }
	32-bit little-endian split constants. More...

Functions
void	selftest_pattern_fill (uint32_t win_sector, UCHAR *out)
	Compute the deterministic pattern for one window data sector.
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_print (const char *text)
	Print a NUL-terminated ASCII string over the console.
ra8_err_t	selftest_print_dec (uint32_t value)
	Print a uint32_t as ASCII decimal.
ra8_err_t	selftest_print_hex (uint32_t value, uint8_t digits)
	Print a value as fixed-width uppercase hex.
ra8_err_t	selftest_print_fail (const char *what, ra8_err_t err)
	Print "FAIL <what> err=0xNNNNNNNN" on its own line.
ra8_err_t	selftest_host_pass (void)
	One full host-side pass: enumerate, mount, verify, WP.

Detailed Description

Shared constants + step prototypes for the OSPI USB self-loop app.

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

Self-contained contract surface shared between the app's translation units. main.c owns boot, the ThreadX workers, and tx_application_ define; the FAT16-synthesis / console / Mass-Storage-media callbacks live in usb_selftest_ospi_format.c; the polled host-side pass ladder (enumerate -> mount -> verify -> write-protect) lives in usb_selftest_ospi_host.c. This header carries every app-local enum (volume geometry, OSPI pattern coefficients, SCSI sense triples, console sizing, J-Link phase markers) plus the cross-TU function prototypes so no symbol is defined in one TU and referenced from another without going through this header.

The USBX-typed entry points (UCHAR* / UINT / VOID* / ULONG) are only declared when ThreadX/USBX is in the build, i.e. outside RA8_OFF_TARGET; the plain console helpers are likewise gated since their definitions are.

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

Enumeration Type Documentation

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

Definition at line 152 of file usb_selftest_ospi_steps.h.

◆ scsi_wp_sense_t

enum scsi_wp_sense_t : uint8_t

SCSI sense triple for a write to the protected medium.

Enumerator
k_scsi_sense_data_protect	Sense key: DATA PROTECT.
k_scsi_asc_write_protected	ASC: WRITE PROTECTED.

Definition at line 159 of file usb_selftest_ospi_steps.h.

◆ 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 46 of file usb_selftest_ospi_steps.h.

◆ selftest_fat_boot_t

enum selftest_fat_boot_t : uint32_t

Boot-sector field values (MS FAT spec 1.03 sec 3.1).

Enumerator
k_boot_jmp0	Short JMP opcode.
k_boot_jmp1	JMP displacement.
k_boot_jmp2	NOP.
k_boot_media	Fixed-disk media byte.
k_boot_sec_per_trk	Geometry filler.
k_boot_num_heads	Geometry filler.
k_boot_drive_num	BIOS drive number.
k_boot_ext_sig	Extended boot signature.
k_boot_volume_id	Arbitrary volume serial.
k_boot_sig_lo	Boot signature low byte.
k_boot_sig_hi	Boot signature high byte.
k_boot_sig_lo_off	Signature low-byte offset.
k_boot_sig_hi_off	Signature high-byte offset.

Definition at line 195 of file usb_selftest_ospi_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_data_clusters	Clusters backed by MRAM (1 MiB).
k_fat_last_data_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 172 of file usb_selftest_ospi_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 215 of file usb_selftest_ospi_steps.h.

◆ selftest_hex_t

enum selftest_hex_t : uint8_t

Hex/decimal text-formatter sizing constants.

Enumerator
k_selftest_hex_chars_u16	16-bit value -> "ABCD".
k_selftest_hex_chars_u32	32-bit value -> "ABCDEF01".
k_selftest_dec_chars_u32	Max digits for a 32-bit count.
k_selftest_nibble_bits	Bits per hex nibble.
k_selftest_hex_digit_split	Threshold between '0-9'/'A-F'.

Definition at line 73 of file usb_selftest_ospi_steps.h.

◆ selftest_mask_t

enum selftest_mask_t : uint32_t

Bit-mask constants used by the text formatters.

Enumerator
k_selftest_nibble_mask	4-bit nibble mask.
k_selftest_dec_radix	Base for decimal conversion.

Definition at line 85 of file usb_selftest_ospi_steps.h.

◆ selftest_ospi_t

enum selftest_ospi_t : uint32_t

OSPI flash geometry the device-side volume is backed by.

The 1 MiB window the device programs + exposes lives at offset 0x100000 in the IS25LX512M (clear of flash_journal's offset-0 record). ra8_xspi addresses the chip 0-based. Erase granularity is the IS25LX512M 4 KiB sector.

Enumerator
k_ospi_instance	xSPI controller instance.
k_ospi_test_offset	1 MiB into the chip (scratch).
k_ospi_bytes	1 MiB exposed window size.
k_ospi_erase_sector	IS25LX512M 4 KiB erase sector.
k_ospi_erase_count	1 MiB / 4 KiB = 256 erases.

Definition at line 127 of file usb_selftest_ospi_steps.h.

◆ selftest_pattern_t

enum selftest_pattern_t : uint32_t

Deterministic sector-pattern coefficients (device + host agree).

Sector s, byte i holds (s * smul + i * imul + bias) & 0xFF. Both the boot programmer and the host verifier compute this identically, so the host never has to read the OSPI (single-controller contention-free).

Enumerator
k_ospi_pat_smul	Per-sector multiplier.
k_ospi_pat_imul	Per-byte multiplier.
k_ospi_pat_bias	Constant bias.
k_ospi_pat_mask	Byte mask.

Definition at line 144 of file usb_selftest_ospi_steps.h.

◆ selftest_phase_t

enum selftest_phase_t : uint32_t

J-Link probe values marking host-ladder progress.

Enumerator
k_selftest_phase_boot	Host thread not yet started.
k_selftest_phase_host_init	ra8_usb_hmsc_init issued.
k_selftest_phase_enum	Enumerating the FS device.
k_selftest_phase_mount	Mounting the FAT16 volume.
k_selftest_phase_verify	Streaming + checking OSPI.BIN.
k_selftest_phase_wp	Write-protect rejection test.
k_selftest_phase_pass	Full OSPI self-loop pass.

Definition at line 108 of file usb_selftest_ospi_steps.h.

◆ selftest_verify_t

enum selftest_verify_t : uint32_t

Content-verification geometry over the device's FAT16 volume.

Enumerator
k_selftest_burst_blocks	Blocks per READ(10) burst.
k_selftest_burst_bytes	8 x 512 B burst buffer size.
k_selftest_target_lun	Single-LUN device.
k_selftest_wp_probe_lba	Data-region LBA for WP test.
k_selftest_no_mismatch	Probe: no mismatch found.
k_selftest_ms_per_sec	Milliseconds per second.
k_selftest_bytes_per_kib	Bytes per KiB (rate math).

Definition at line 94 of file usb_selftest_ospi_steps.h.

◆ selftest_word_pack_t

enum selftest_word_pack_t : uint32_t

32-bit little-endian split constants.

Enumerator
k_word_shift	Bits per half-word.
k_word_mask	Low half-word mask.

Definition at line 248 of file usb_selftest_ospi_steps.h.

Function Documentation

◆ selftest_host_pass()

ra8_err_t selftest_host_pass ( void )

nodiscard

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

Phases mirror selftest_phase_t and are mirrored into the J-Link phase probe for readout. 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 OSPI PASS.

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, verify, WP.

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

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.

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

◆ 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 sector 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 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 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

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, selftest_fat_fill_sector(), selftest_fat_fill_sector(), and selftest_fat_fill_sector().

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

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

◆ selftest_pattern_fill()

void selftest_pattern_fill	(	uint32_t	win_sector,
		UCHAR *	out )

Compute the deterministic pattern for one window data sector.

Fills out with (win_sector * smul + i * imul + bias) per byte (see selftest_pattern_t). This is the single source of truth: the boot programmer writes it into OSPI and the host verifier recomputes it – so the host never reads the flash and there is no single-controller contention.

Parameters

[in]	win_sector	0-based sector index within the OSPI window.
[out]	out	512-byte destination buffer.

Precondition: out has 512 writable bytes.

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

Note: Pure function.

Since: 0.1.0

Definition at line 227 of file usb_selftest_ospi_format.c.

References k_ospi_pat_bias, k_ospi_pat_imul, k_ospi_pat_mask, k_ospi_pat_smul, and k_selftest_block_size.

Referenced by selftest_ospi_write_pattern(), and selftest_verify_ospi_raw().

◆ selftest_print()

ra8_err_t selftest_print ( const char * text )

nodiscard

Print a NUL-terminated ASCII string over the console.

Length-bounded by the bounded string-length scan.

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

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 423 of file usb_selftest_ospi_format.c.

References selftest_sci_write(), and selftest_str_len().

◆ selftest_print_dec()

ra8_err_t selftest_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 428 of file usb_selftest_ospi_format.c.

References k_selftest_dec_chars_u32, k_selftest_dec_radix, and selftest_sci_write().

◆ selftest_print_fail()

ra8_err_t selftest_print_fail	(	const char *	what,
		ra8_err_t	err )

nodiscard

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 466 of file usb_selftest_ospi_format.c.

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

◆ selftest_print_hex()

ra8_err_t selftest_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_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 452 of file usb_selftest_ospi_format.c.

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

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ scsi_sense_code_t

◆ scsi_wp_sense_t

◆ selftest_config_t

◆ selftest_fat_boot_t

◆ selftest_fat_geom_t

◆ selftest_fat_off_t

◆ selftest_hex_t

◆ selftest_mask_t

◆ selftest_ospi_t

◆ selftest_pattern_t

◆ selftest_phase_t

◆ selftest_verify_t

◆ selftest_word_pack_t

Function Documentation

◆ selftest_host_pass()

◆ selftest_msc_read()

◆ selftest_msc_status()

◆ selftest_msc_write()

◆ selftest_pattern_fill()

◆ selftest_print()

◆ selftest_print_dec()

◆ selftest_print_fail()

◆ selftest_print_hex()