examples/ek_ra8d2/hw_pending/manual/usb_msc_sdcard/inc/usb_msc_sdcard_steps.h More...

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

Include dependency graph for usb_msc_sdcard_steps.h:

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

Enumerations
enum	sdmsc_config_t : uint32_t { k_sdmsc_thread_stack = 4096U , k_sdmsc_usbx_pool_bytes = 32768U , k_sdmsc_idle_ticks = 50U , k_sdmsc_baud = 115200U , k_sdmsc_sd_spi_channel = 0U , k_sdmsc_print_cap = 160U , k_sdmsc_dev_priority = 8U , k_sdmsc_block_size = 512U , k_sdmsc_blocks_per_mib = 2048U }
	Compile-time settings: thread, pool, console, SD bus, cadence. More...
enum	sdmsc_hex_t : uint8_t { k_sdmsc_hex_chars_u32 = 8U , k_sdmsc_dec_chars_u32 = 10U , k_sdmsc_nibble_bits = 4U , k_sdmsc_hex_digit_split = 10U }
	Hex/decimal text-formatter sizing constants. More...
enum	sdmsc_mask_t : uint32_t { k_sdmsc_nibble_mask = 0xFU , k_sdmsc_dec_radix = 10U }
	Bit-mask constants used by the text formatters. More...
enum	sdmsc_dev_step_t : uint32_t { k_sdmsc_dev_step_stack = 1U , k_sdmsc_dev_step_class = 2U , k_sdmsc_dev_step_dcd = 3U , k_sdmsc_dev_step_attach = 4U , k_sdmsc_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_sense_medium_error = 0x03U , k_scsi_asc_unrecovered_read = 0x11U , k_scsi_asc_write_fault = 0x03U , k_scsi_ascq_none = 0x00U }
	SCSI sense triples (key / ASC / ASCQ) the media callbacks report. More...
enum	usb_langid_byte_t : uint8_t { k_usb_langid_en_us_lo = 0x09U , k_usb_langid_en_us_hi = 0x04U }
	USBX LANGID descriptor 0x0409 (English-US), little-endian pair. More...

Functions
ra8_err_t	sdmsc_print (const char *text)
	Print a NUL-terminated ASCII string over the SCI8 console.
ra8_err_t	sdmsc_print_dec (uint32_t value)
	Print a uint32_t as ASCII decimal over the SCI8 console.
ra8_err_t	sdmsc_print_hex (uint32_t value, uint8_t digits)
	Print a value as fixed-width uppercase hex over the SCI8 console.
ra8_err_t	sdmsc_print_fail (const char *what, ra8_err_t err)
	Print "FAIL <what> err=0xNNNNNNNN" on its own console line.
VOID	sdmsc_device_worker (ULONG arg)
	Device worker: bring the live-SD read/write MSC device up, then park.

Variables
volatile uint32_t	s_usb_msc_sdcard_blocks
	Live SD card capacity in 512-byte blocks (0 = no card).

Detailed Description

examples/ek_ra8d2/hw_pending/manual/usb_msc_sdcard/inc/usb_msc_sdcard_steps.h

Shared contract for the live-SD USB MSC device console + worker steps

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

Declares the constants, the cross-translation-unit card-capacity probe, and the function prototypes shared between main.c and the helper siblings usb_msc_sdcard_console.c (SCI8 console formatters) and usb_msc_sdcard_steps.c (USBX device worker plus the read/write MSC media callbacks that drive the live SD card). 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 point is only declared when the firmware (on-target) USB stack is compiled in.

Author: Brighton Sikarskie

Date: 2026-07-08

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

Since: 0.1.0

Definition in file usb_msc_sdcard_steps.h.

Enumeration Type Documentation

◆ scsi_sense_code_t

enum scsi_sense_code_t : uint8_t

SCSI sense triples (key / ASC / ASCQ) the media callbacks report.

Per SPC-4 / SBC-3: an out-of-range LBA is ILLEGAL REQUEST with "LOGICAL BLOCK ADDRESS OUT OF RANGE"; a failed card read is MEDIUM ERROR with "UNRECOVERED READ ERROR"; a failed card write is MEDIUM ERROR with "PERIPHERAL DEVICE WRITE FAULT". The class stores the triple into the LUN's REQUEST SENSE data, so the host sees the true failure cause.

Enumerator
k_scsi_sense_illegal_request	Sense key: ILLEGAL REQUEST.
k_scsi_asc_lba_out_of_range	ASC: LBA out of range.
k_scsi_sense_medium_error	Sense key: MEDIUM ERROR.
k_scsi_asc_unrecovered_read	ASC: unrecovered read error.
k_scsi_asc_write_fault	ASC: peripheral dev write fault.
k_scsi_ascq_none	ASCQ: none.

Definition at line 90 of file usb_msc_sdcard_steps.h.

◆ sdmsc_config_t

enum sdmsc_config_t : uint32_t

Compile-time settings: thread, pool, console, SD bus, cadence.

Enumerator
k_sdmsc_thread_stack	Device worker stack (bytes).
k_sdmsc_usbx_pool_bytes	USBX memory pool (bytes).
k_sdmsc_idle_ticks	Parked-loop back-off (ticks).
k_sdmsc_baud	J-Link OB CDC log baud.
k_sdmsc_sd_spi_channel	SCI0 Simple-SPI -> Pmod2 microSD.
k_sdmsc_print_cap	Bound for console-string scans.
k_sdmsc_dev_priority	Device bring-up worker priority.
k_sdmsc_block_size	SCSI logical block size (bytes).
k_sdmsc_blocks_per_mib	512-B blocks per MiB.

Definition at line 36 of file usb_msc_sdcard_steps.h.

◆ sdmsc_dev_step_t

enum sdmsc_dev_step_t : uint32_t

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

Enumerator
k_sdmsc_dev_step_stack	USBX system + device stack up.
k_sdmsc_dev_step_class	MSC class registered.
k_sdmsc_dev_step_dcd	DCD bridge initialized.
k_sdmsc_dev_step_attach	Device attached (DPRPU).
k_sdmsc_dev_step_parked	Bring-up done; worker parked.

Definition at line 72 of file usb_msc_sdcard_steps.h.

◆ sdmsc_hex_t

enum sdmsc_hex_t : uint8_t

Hex/decimal text-formatter sizing constants.

Enumerator
k_sdmsc_hex_chars_u32	32-bit value -> "ABCDEF01".
k_sdmsc_dec_chars_u32	Max digits for a 32-bit count.
k_sdmsc_nibble_bits	Bits per hex nibble.
k_sdmsc_hex_digit_split	Threshold between '0-9'/'A-F'.

Definition at line 52 of file usb_msc_sdcard_steps.h.

◆ sdmsc_mask_t

enum sdmsc_mask_t : uint32_t

Bit-mask constants used by the text formatters.

Enumerator
k_sdmsc_nibble_mask	4-bit nibble mask.
k_sdmsc_dec_radix	Base for decimal conversion.

Definition at line 63 of file usb_msc_sdcard_steps.h.

◆ usb_langid_byte_t

enum usb_langid_byte_t : uint8_t

USBX LANGID descriptor 0x0409 (English-US), little-endian pair.

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

Definition at line 103 of file usb_msc_sdcard_steps.h.

Function Documentation

◆ sdmsc_device_worker()

VOID sdmsc_device_worker ( ULONG arg )

Device worker: bring the live-SD read/write MSC device up, then park.

USBX system + device stack + MSC class (1 writable LUN sized from s_usb_msc_sdcard_blocks) + DCD bridge on the USBFS controller, then DPRPU attach and the READY banner. USBX runs the SCSI/BBB state machine on its own class threads after this; the media callbacks stream the live card via ra8_sdmmc_spi_read_blocks / ra8_sdmmc_spi_write_blocks.

Parameters

[in] arg ThreadX entry argument (unused).

Precondition: tx_application_define created this thread.; USB-FS pins + 48 MHz clock + the SD card are up (main did all three).

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

Note: Runs once; loops forever on success.

Since: 0.1.0

Definition at line 516 of file usb_msc_sdcard_steps.c.

References k_ra8_err_invalid_state, k_ra8_ok, k_ra8_usb_speed_fs, k_sdmsc_dev_step_attach, k_sdmsc_dev_step_class, k_sdmsc_dev_step_dcd, k_sdmsc_dev_step_parked, k_sdmsc_dev_step_stack, k_sdmsc_idle_ticks, ra8_usb_device_attach(), s_dbg_dev_err, s_dbg_dev_step, s_usb_msc_sdcard_blocks, sdmsc_class_register(), sdmsc_print_fail(), sdmsc_print_ready(), sdmsc_usbx_stack_up(), tx_thread_sleep, and ux_dcd_ra8_usb_initialize().

Referenced by tx_application_define().

◆ sdmsc_print()

ra8_err_t sdmsc_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_sdmsc_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 117 of file usb_msc_sdcard_console.c.

References sdmsc_sci_write(), and sdmsc_str_len().

Referenced by sdmsc_print_card_banner(), sdmsc_print_fail(), and sdmsc_print_ready().

◆ sdmsc_print_dec()

ra8_err_t sdmsc_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 123 of file usb_msc_sdcard_console.c.

References k_sdmsc_dec_chars_u32, k_sdmsc_dec_radix, and sdmsc_sci_write().

Referenced by sdmsc_print_card_banner(), and sdmsc_print_ready().

◆ sdmsc_print_fail()

ra8_err_t sdmsc_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 162 of file usb_msc_sdcard_console.c.

References k_ra8_ok, k_sdmsc_hex_chars_u32, sdmsc_print(), and sdmsc_print_hex().

Referenced by sdmsc_card_up(), and sdmsc_device_worker().

◆ sdmsc_print_hex()

ra8_err_t sdmsc_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 (up to 8).

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_sdmsc_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 148 of file usb_msc_sdcard_console.c.

References k_sdmsc_hex_chars_u32, k_sdmsc_nibble_bits, k_sdmsc_nibble_mask, sdmsc_nibble_to_hex(), and sdmsc_sci_write().

Referenced by sdmsc_print_fail().

Variable Documentation

◆ s_usb_msc_sdcard_blocks

volatile uint32_t s_usb_msc_sdcard_blocks

extern

Live SD card capacity in 512-byte blocks (0 = no card).

Defined in main.c and stamped once during the pre-kernel SD bring-up from ra8_sdmmc_spi_get_capacity (CSD-derived). Read by the worker in usb_msc_sdcard_steps.c to size the MSC LUN and by the media callbacks to bounds-check every SCSI request.

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

Warning: Do not modify after the USBX class registers – the LUN geometry is latched from this value.

Since: 0.1.0

Stamped here once during the pre-kernel SD bring-up from ra8_sdmmc_spi_get_capacity (CSD-derived) and consumed by the worker + media callbacks in usb_msc_sdcard_steps.c.

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

Warning: Do not modify after the USBX class registers – the LUN geometry is latched from this value.

Since: 0.1.0

Definition at line 136 of file main.c.

Referenced by sdmsc_card_up(), sdmsc_class_register(), sdmsc_device_worker(), sdmsc_msc_read(), sdmsc_msc_write(), and sdmsc_print_ready().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ scsi_sense_code_t

◆ sdmsc_config_t

◆ sdmsc_dev_step_t

◆ sdmsc_hex_t

◆ sdmsc_mask_t

◆ usb_langid_byte_t

Function Documentation

◆ sdmsc_device_worker()

◆ sdmsc_print()

◆ sdmsc_print_dec()

◆ sdmsc_print_fail()

◆ sdmsc_print_hex()

Variable Documentation

◆ s_usb_msc_sdcard_blocks