Cross-TU surface shared between the device-MSC BOT statemachine (ra8_usb_pmsc.c) and the SCSI command handlers (ra8_usb_pmsc_scsi.c). More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_usb.h"
#include "ra8_usb_pmsc.h"

Include dependency graph for ra8_usb_pmsc_internal.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_usb_pmsc_state_data_t
	Singleton shadow state for the device-MSC driver. More...

Enumerations
enum	ra8_usb_pmsc_state_t : uint8_t { k_ra8_pmsc_state_idle = 0U , k_ra8_pmsc_state_cbw_rx = 1U , k_ra8_pmsc_state_cdb_decode = 2U , k_ra8_pmsc_state_data_tx = 3U , k_ra8_pmsc_state_data_rx = 4U , k_ra8_pmsc_state_csw_tx = 5U }
	BOT state-machine phases. More...
enum	ra8_usb_pmsc_size_t : uint16_t { k_ra8_pmsc_cbw_len = 31U , k_ra8_pmsc_csw_len = 13U , k_ra8_pmsc_cdb_max_len = 16U }
	Standard BOT wrapper sizes. More...
enum	ra8_usb_pmsc_byte_shift_t : uint8_t { k_ra8_pmsc_shift_byte0 = 0U , k_ra8_pmsc_shift_byte1 = 8U , k_ra8_pmsc_shift_byte2 = 16U , k_ra8_pmsc_shift_byte3 = 24U }
	Per-byte left-shift constants for serialisation. More...
enum	ra8_usb_pmsc_byte_mask_t : uint32_t { k_ra8_pmsc_byte_mask = 0xFFU }
	Single-byte extraction mask. More...
enum	ra8_usb_pmsc_cdb_opcode_offset_t : uint8_t { k_ra8_pmsc_cdb_off_opcode = 0U }
	Offset of the SCSI operation code inside the cached CDB. More...

Functions
void	priv_zero_bytes (uint8_t *dst, uint32_t len)
	Zero len bytes at dst byte-by-byte.
ra8_err_t	priv_handle_inquiry (uint8_t data_buf, uint32_t capacity, uint32_t out_len)
	Build the 36-byte SCSI INQUIRY response.
ra8_err_t	priv_handle_read_capacity (uint8_t data_buf, uint32_t capacity, uint32_t out_len)
	Build the 8-byte READ_CAPACITY(10) response.
ra8_err_t	priv_handle_request_sense (uint8_t data_buf, uint32_t capacity, uint32_t out_len)
	Build the 18-byte REQUEST SENSE response.
ra8_err_t	priv_handle_mode_sense (uint8_t data_buf, uint32_t capacity, uint32_t out_len)
	Build the minimal 4-byte MODE SENSE(6) header response.
ra8_err_t	priv_handle_read10 (uint8_t data_buf, uint32_t capacity, uint32_t out_len)
	Run a SCSI READ(10).
ra8_err_t	priv_handle_write10 (const uint8_t data_buf, uint32_t out_len)
	Run a SCSI WRITE(10) – the data buffer holds the host-supplied payload.

Variables
ra8_usb_pmsc_state_data_t	g_usb_pmsc_state
	Singleton shadow state shared by both device-MSC TUs.

Detailed Description

Cross-TU surface shared between the device-MSC BOT state

machine (ra8_usb_pmsc.c) and the SCSI command handlers (ra8_usb_pmsc_scsi.c).

Tag: [Ring 3 / HAL] {World: NS}

The native device-MSC class layer is split across two translation units so each stays under the 1000-line file-size cap. This src/-local header carries the shadow-state singleton, the small shared serialisation helpers, and the SCSI handler declarations that the BOT dispatcher invokes. It is NOT part of the public API: the public contract lives in ra8_usb_pmsc.h.

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

Definition in file ra8_usb_pmsc_internal.h.

Enumeration Type Documentation

◆ ra8_usb_pmsc_byte_mask_t

enum ra8_usb_pmsc_byte_mask_t : uint32_t

Single-byte extraction mask.

Enumerator
k_ra8_pmsc_byte_mask	RA8 pmsc byte mask.

Definition at line 83 of file ra8_usb_pmsc_internal.h.

◆ ra8_usb_pmsc_byte_shift_t

enum ra8_usb_pmsc_byte_shift_t : uint8_t

Per-byte left-shift constants for serialisation.

Enumerator
k_ra8_pmsc_shift_byte0	RA8 pmsc shift byte0.
k_ra8_pmsc_shift_byte1	RA8 pmsc shift byte1.
k_ra8_pmsc_shift_byte2	RA8 pmsc shift byte2.
k_ra8_pmsc_shift_byte3	RA8 pmsc shift byte3.

Definition at line 72 of file ra8_usb_pmsc_internal.h.

◆ ra8_usb_pmsc_cdb_opcode_offset_t

enum ra8_usb_pmsc_cdb_opcode_offset_t : uint8_t

Offset of the SCSI operation code inside the cached CDB.

Shared by the BOT dispatcher (ra8_usb_pmsc.c) and the SCSI handler TU (ra8_usb_pmsc_scsi.c). Per SPC-4 the CDB operation code is always byte 0.

Enumerator
k_ra8_pmsc_cdb_off_opcode	Operation Code (CDB byte 0).

Definition at line 95 of file ra8_usb_pmsc_internal.h.

◆ ra8_usb_pmsc_size_t

enum ra8_usb_pmsc_size_t : uint16_t

Standard BOT wrapper sizes.

The CBW / CSW lengths are nailed down by USB MSC BBB rev 1.0 sections 5.1 and 5.2 respectively.

Enumerator
k_ra8_pmsc_cbw_len	CBW length (BBB sec 5.1).
k_ra8_pmsc_csw_len	CSW length (BBB sec 5.2).
k_ra8_pmsc_cdb_max_len	CDB ceiling.

Definition at line 62 of file ra8_usb_pmsc_internal.h.

◆ ra8_usb_pmsc_state_t

enum ra8_usb_pmsc_state_t : uint8_t

BOT state-machine phases.

Mirrors FSP's USB_PMSC_CBWRCV / USB_PMSC_DATARCV / USB_PMSC_DATASND / USB_PMSC_CSWSND values in r_usb_pmsc_driver.c. The starter adds idle and cdb_decode phases so the host-side stepping matches the textbook BBB lifecycle.

Enumerator
k_ra8_pmsc_state_idle	Pre-CBW.
k_ra8_pmsc_state_cbw_rx	CBW arrived on bulk-OUT.
k_ra8_pmsc_state_cdb_decode	Dispatch to a SCSI handler.
k_ra8_pmsc_state_data_tx	Push data on bulk-IN.
k_ra8_pmsc_state_data_rx	Pull data on bulk-OUT.
k_ra8_pmsc_state_csw_tx	Push CSW on bulk-IN.

Definition at line 46 of file ra8_usb_pmsc_internal.h.

Function Documentation

◆ priv_handle_inquiry()

ra8_err_t priv_handle_inquiry	(	uint8_t *	data_buf,
		uint32_t	capacity,
		uint32_t *	out_len )

Build the 36-byte SCSI INQUIRY response.

Asks the storage backend for the three ASCII strings (vendor, product, revision) and bakes them into the response per SBC-4 sec 6.6. SPACE-padding is applied if the backend returns a shorter string.

Parameters

[out]	data_buf	Destination response buffer.
[in]	capacity	Capacity of data_buf in bytes.
[out]	out_len	Receives the response length.

Returns: Result code.

Return values

k_ra8_ok	Operation succeeded.
k_ra8_err_invalid_size	Buffer too small.

Precondition: Module state is consistent.; Storage backend is attached.

Postcondition: Caller-visible state matches the documented contract.; *out_len holds the response length on success.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 202 of file ra8_usb_pmsc_scsi.c.

References g_usb_pmsc_state, internal_pad_space(), k_ra8_err_invalid_size, k_ra8_ok, k_ra8_pmsc_inq_byte_addl_length, k_ra8_pmsc_inq_byte_dev_type, k_ra8_pmsc_inq_byte_removable, k_ra8_pmsc_inq_byte_resp_format, k_ra8_pmsc_inq_byte_version, k_ra8_pmsc_inq_off_addl_length, k_ra8_pmsc_inq_off_dev_type, k_ra8_pmsc_inq_off_product, k_ra8_pmsc_inq_off_removable, k_ra8_pmsc_inq_off_resp_format, k_ra8_pmsc_inq_off_revision, k_ra8_pmsc_inq_off_vendor, k_ra8_pmsc_inq_off_version, k_ra8_pmsc_inq_product_len, k_ra8_pmsc_inq_revision_len, k_ra8_pmsc_inq_vendor_len, k_ra8_pmsc_inquiry_resp_len, and priv_zero_bytes().

Referenced by internal_dispatch_scsi().

◆ priv_handle_mode_sense()

ra8_err_t priv_handle_mode_sense	(	uint8_t *	data_buf,
		uint32_t	capacity,
		uint32_t *	out_len )

Build the minimal 4-byte MODE SENSE(6) header response.

Per SPC-4 sec 6.11 a header-only response is legal when no descriptors / pages are present. Byte 0 = mode data length (3). Byte 1 = medium type (0). Byte 2 = device-specific parameter (0). Byte 3 = block descriptor length (0).

Parameters

[out]	data_buf	Destination response buffer.
[in]	capacity	Capacity of data_buf in bytes.
[out]	out_len	Receives the response length.

Returns: Result code.

Return values

k_ra8_ok	Operation succeeded.
k_ra8_err_invalid_size	Buffer too small.

Precondition: Module state is consistent.; Storage backend is attached.

Postcondition: Caller-visible state matches the documented contract.; *out_len holds the response length on success.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 268 of file ra8_usb_pmsc_scsi.c.

References k_ra8_err_invalid_size, k_ra8_ok, k_ra8_pmsc_mode_data_length_value, k_ra8_pmsc_mode_sense_resp_len, and priv_zero_bytes().

Referenced by internal_dispatch_scsi().

◆ priv_handle_read10()

ra8_err_t priv_handle_read10	(	uint8_t *	data_buf,
		uint32_t	capacity,
		uint32_t *	out_len )

Run a SCSI READ(10).

Decodes the cached READ(10) CDB, asks the backend for the geometry, and reads the requested blocks into data_buf.

Parameters

[out]	data_buf	Destination data buffer.
[in]	capacity	Capacity of data_buf in bytes.
[out]	out_len	Receives the transferred byte count.

Returns: Result code.

Return values

k_ra8_ok	Operation succeeded.
k_ra8_err_invalid_size	Buffer too small for the read.

Precondition: Module state is consistent.; Storage backend is attached.

Postcondition: Caller-visible state matches the documented contract.; *out_len holds the transferred byte count on success.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 280 of file ra8_usb_pmsc_scsi.c.

References g_usb_pmsc_state, internal_decode_rw10(), k_ra8_err_invalid_size, k_ra8_ok, and k_ra8_pmsc_block_size_default.

Referenced by internal_dispatch_scsi().

◆ priv_handle_read_capacity()

ra8_err_t priv_handle_read_capacity	(	uint8_t *	data_buf,
		uint32_t	capacity,
		uint32_t *	out_len )

Build the 8-byte READ_CAPACITY(10) response.

Per SBC-4 sec 5.10 the response is the LAST valid LBA (block_count - 1, big-endian) followed by the block size (big-endian).

Parameters

[out]	data_buf	Destination response buffer.
[in]	capacity	Capacity of data_buf in bytes.
[out]	out_len	Receives the response length.

Returns: Result code.

Return values

k_ra8_ok	Operation succeeded.
k_ra8_err_invalid_size	Buffer too small.

Precondition: Module state is consistent.; Storage backend is attached.

Postcondition: Caller-visible state matches the documented contract.; *out_len holds the response length on success.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 233 of file ra8_usb_pmsc_scsi.c.

References g_usb_pmsc_state, internal_pack_u32_be(), k_ra8_err_invalid_size, k_ra8_ok, k_ra8_pmsc_cap_off_blk_size, k_ra8_pmsc_cap_off_last_lba, k_ra8_pmsc_read_capacity_resp_len, and priv_zero_bytes().

Referenced by internal_dispatch_scsi().

◆ priv_handle_request_sense()

ra8_err_t priv_handle_request_sense	(	uint8_t *	data_buf,
		uint32_t	capacity,
		uint32_t *	out_len )

Build the 18-byte REQUEST SENSE response.

Per SPC-4 sec 6.30 the device returns "no sense" (0x00) once the CHECK CONDITION has been cleared. The starter does not track sense state; it always answers "no sense" so subsequent commands proceed.

Parameters

[out]	data_buf	Destination response buffer.
[in]	capacity	Capacity of data_buf in bytes.
[out]	out_len	Receives the response length.

Returns: Result code.

Return values

k_ra8_ok	Operation succeeded.
k_ra8_err_invalid_size	Buffer too small.

Precondition: Module state is consistent.; Storage backend is attached.

Postcondition: Caller-visible state matches the documented contract.; *out_len holds the response length on success.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 254 of file ra8_usb_pmsc_scsi.c.

References k_ra8_err_invalid_size, k_ra8_ok, k_ra8_pmsc_request_sense_resp_len, k_ra8_pmsc_sense_addl_length_byte, k_ra8_pmsc_sense_addl_length_value, k_ra8_pmsc_sense_resp_code, and priv_zero_bytes().

Referenced by internal_dispatch_scsi().

◆ priv_handle_write10()

ra8_err_t priv_handle_write10	(	const uint8_t *	data_buf,
		uint32_t *	out_len )

Run a SCSI WRITE(10) – the data buffer holds the host-supplied payload.

Decodes the cached WRITE(10) CDB, asks the backend for the geometry, and writes the supplied blocks through the backend.

Parameters

[in]	data_buf	Host-supplied payload buffer.
[out]	out_len	Receives the transferred byte count.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Storage backend is attached.

Postcondition: Caller-visible state matches the documented contract.; *out_len holds the transferred byte count on success.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 313 of file ra8_usb_pmsc_scsi.c.

References g_usb_pmsc_state, internal_decode_rw10(), k_ra8_ok, and k_ra8_pmsc_block_size_default.

Referenced by internal_dispatch_scsi().

◆ priv_zero_bytes()

void priv_zero_bytes	(	uint8_t *	dst,
		uint32_t	len )

Zero len bytes at dst byte-by-byte.

Avoids memset so the project's clang-tidy clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling gate stays clean. Defined in ra8_usb_pmsc.c, shared with the SCSI handler TU.

Parameters

[out]	dst	Destination buffer (non-null, at least len bytes).
[in]	len	Byte count to clear.

Precondition: dst is non-null and spans at least len bytes.; Module state is consistent.

Postcondition: All len bytes at dst are zero.; No other state mutated.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 250 of file ra8_usb_pmsc.c.

Referenced by priv_handle_inquiry(), priv_handle_mode_sense(), priv_handle_read_capacity(), priv_handle_request_sense(), ra8_usb_pmsc_build_csw(), and ra8_usb_pmsc_init().

Variable Documentation

◆ g_usb_pmsc_state

ra8_usb_pmsc_state_data_t g_usb_pmsc_state

extern

Singleton shadow state shared by both device-MSC TUs.

Defined in ra8_usb_pmsc.c; the SCSI handler TU reads the cached CDB and storage backend through this extern declaration.

Note: Single-instance, single-LUN; not thread-safe.

Warning: Direct modification outside the driver TUs is forbidden.

Since: 0.1.0

Definition at line 139 of file ra8_usb_pmsc.c.

Referenced by internal_configure_pipes(), internal_dispatch_advance_state(), internal_dispatch_preconditions(), internal_dispatch_scsi(), priv_handle_inquiry(), priv_handle_read10(), priv_handle_read_capacity(), priv_handle_write10(), ra8_usb_pmsc_attach_storage(), ra8_usb_pmsc_build_csw(), ra8_usb_pmsc_close(), ra8_usb_pmsc_feed_cbw(), ra8_usb_pmsc_init(), and ra8_usb_pmsc_step().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_usb_pmsc_byte_mask_t

◆ ra8_usb_pmsc_byte_shift_t

◆ ra8_usb_pmsc_cdb_opcode_offset_t

◆ ra8_usb_pmsc_size_t

◆ ra8_usb_pmsc_state_t

Function Documentation

◆ priv_handle_inquiry()

◆ priv_handle_mode_sense()

◆ priv_handle_read10()

◆ priv_handle_read_capacity()

◆ priv_handle_request_sense()

◆ priv_handle_write10()

◆ priv_zero_bytes()

Variable Documentation

◆ g_usb_pmsc_state