USB mass-storage block-device backend – a hosted device as 512-byte logical blocks. More...

#include "ra8_io_blockdev_usbmsc.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_io_blockdev.h"
#include "ra8_io_blockdev_backend.h"
#include "ra8_usb_hmsc.h"

Include dependency graph for ra8_io_blockdev_usbmsc.c:

Enumerations
enum	ra8_io_usbmsc_const_t : uint32_t { k_ra8_io_usbmsc_erase_unit_blocks = 1 }
	USB-MSC backend layout constants. More...

Functions
static ra8_err_t	internal_usbmsc_read (void ctx, uint32_t lba, uint32_t count, uint8_t buf)
	USB-MSC backend: read count blocks at lba into buf.
static ra8_err_t	internal_usbmsc_write (void ctx, uint32_t lba, uint32_t count, const uint8_t buf)
	USB-MSC backend: write count blocks from buf at lba.
static ra8_err_t	internal_usbmsc_get_caps (const void ctx, ra8_io_blockdev_caps_t out)
	USB-MSC backend: report medium capabilities.
ra8_err_t	ra8_io_blockdev_usbmsc_init (ra8_io_blockdev_t bd, ra8_io_blockdev_usbmsc_state_t state, uint8_t lun)
	Bind a hosted USB mass-storage backend into a caller-owned handle.

Variables
static const char *const	s_tag = "ra8_io_blockdev_usbmsc"
	Module log tag.
static const ra8_io_blockdev_iface_t	s_usbmsc_iface
	USB-MSC backend vtable.

Detailed Description

USB mass-storage block-device backend – a hosted device as 512-byte logical blocks.

Tag: [Ring 4 / PAL] {World: NS}

Implements ra8_io_blockdev_iface by forwarding reads and writes to the ra8_usb_hmsc class layer, which issues SCSI READ(10) / WRITE(10) / READ CAPACITY(10) over Bulk-Only Transport. The class layer owns the attached device, so the only per-device state is the LUN this handle addresses. USB mass storage offers no host erase primitive and the class layer buffers nothing, so both optional vtable slots are NULL. This file touches no raw MMIO – the HUM citations live in the ra8_usb_hmsc driver and the USB HAL beneath it.

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

Definition in file ra8_io_blockdev_usbmsc.c.

Enumeration Type Documentation

◆ ra8_io_usbmsc_const_t

enum ra8_io_usbmsc_const_t : uint32_t

USB-MSC backend layout constants.

A hosted mass-storage device exposes no erase granularity to the host, so the fabric reports the smallest legal unit – one logical block – exactly as the SD backends do.

Since: 0.1.0

Enumerator
k_ra8_io_usbmsc_erase_unit_blocks	One logical block per erase unit.

Definition at line 48 of file ra8_io_blockdev_usbmsc.c.

Function Documentation

◆ internal_usbmsc_get_caps()

ra8_err_t internal_usbmsc_get_caps	(	const void *	ctx,
		ra8_io_blockdev_caps_t *	out )

static

USB-MSC backend: report medium capabilities.

Issues SCSI READ CAPACITY(10) on the bound LUN and fills out for a read-write medium with no erase concept. A device whose native block size is not 512 bytes is refused: the fabric's logical block is fixed at k_ra8_io_block_size_bytes, so reporting its block count would state a capacity in a unit the layers above would read as 512-byte blocks.

Parameters

[in]	ctx	USB-MSC backend state (as a const void cookie).
[out]	out	Capabilities snapshot.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	*out populated.
k_ra8_err_null_ptr	ctx or out was NULL.
k_ra8_err_not_supported	The device's native block size is not 512.
k_ra8_err_invalid_state	The class layer is down or nothing attached.
k_ra8_err_hw_error	The Bulk-Only Transport exchange failed.

Precondition: ctx is a populated USB-MSC state.; out is writable.

Postcondition: On success *out describes a read-write, no-erase USB medium.; No backend state is mutated.

Note: Blocking, polled: every call issues a SCSI command.

Since: 0.1.0

Definition at line 166 of file ra8_io_blockdev_usbmsc.c.

References ra8_io_blockdev_caps_t::block_count, ra8_io_blockdev_caps_t::erase_unit_blocks, ra8_io_blockdev_caps_t::erase_value, k_ra8_err_not_supported, k_ra8_io_block_size_bytes, k_ra8_io_erase_value_zero, k_ra8_io_usbmsc_erase_unit_blocks, k_ra8_ok, ra8_io_blockdev_caps_t::logical_block_bytes, ra8_io_blockdev_usbmsc_state_t::lun, ra8_io_blockdev_caps_t::must_erase_before_write, ra8_io_blockdev_caps_t::program_size_bytes, RA8_CHECK_NULL_PTR, ra8_usb_hmsc_read_capacity(), ra8_io_blockdev_caps_t::read_only, and s_tag.

◆ internal_usbmsc_read()

ra8_err_t internal_usbmsc_read	(	void *	ctx,
		uint32_t	lba,
		uint32_t	count,
		uint8_t *	buf )

static

USB-MSC backend: read count blocks at lba into buf.

Rejects a run longer than one SCSI READ(10) can express, then forwards to ra8_usb_hmsc_read10 on the bound LUN. The class layer enforces attach state, LUN range and device capacity.

Parameters

[in]	ctx	USB-MSC backend state (as a void cookie).
[in]	lba	First logical block address.
[in]	count	Number of blocks to read.
[out]	buf	Destination buffer (>= count * 512 bytes).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Blocks read into buf.
k_ra8_err_null_ptr	ctx or buf was NULL.
k_ra8_err_out_of_range	count exceeds the READ(10) transfer bound.
k_ra8_err_invalid_state	The class layer is down or nothing attached.
k_ra8_err_invalid_arg	count was zero, or the LUN is out of range.
k_ra8_err_hw_error	The Bulk-Only Transport exchange failed.

Precondition: ctx is a populated USB-MSC state.; buf is writable for count * 512 bytes.

Postcondition: On success buf holds the requested device data.; On failure buf is left as the class layer leaves it.

Note: Blocking, polled; not safe to call from an ISR.

Since: 0.1.0

Definition at line 83 of file ra8_io_blockdev_usbmsc.c.

References k_ra8_err_out_of_range, k_ra8_io_usbmsc_max_transfer_blocks, ra8_io_blockdev_usbmsc_state_t::lun, RA8_CHECK_NULL_PTR, ra8_usb_hmsc_read10(), and s_tag.

◆ internal_usbmsc_write()

ra8_err_t internal_usbmsc_write	(	void *	ctx,
		uint32_t	lba,
		uint32_t	count,
		const uint8_t *	buf )

static

USB-MSC backend: write count blocks from buf at lba.

Rejects a run longer than one SCSI WRITE(10) can express, then forwards to ra8_usb_hmsc_write10 on the bound LUN. A write-protected medium is reported by the device, not predicted here.

Parameters

[in]	ctx	USB-MSC backend state (as a void cookie).
[in]	lba	First logical block address.
[in]	count	Number of blocks to write.
[in]	buf	Source buffer (>= count * 512 bytes).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Blocks written to the device.
k_ra8_err_null_ptr	ctx or buf was NULL.
k_ra8_err_out_of_range	count exceeds the WRITE(10) transfer bound.
k_ra8_err_invalid_state	The class layer is down or nothing attached.
k_ra8_err_invalid_arg	count was zero, or the LUN is out of range.
k_ra8_err_hw_error	The Bulk-Only Transport exchange failed.

Precondition: ctx is a populated USB-MSC state.; buf is readable for count * 512 bytes.

Postcondition: On success the device blocks [lba, lba+count) equal buf.; On failure the device is left as the class layer leaves it.

Note: Blocking, polled; not safe to call from an ISR.

Since: 0.1.0

Definition at line 125 of file ra8_io_blockdev_usbmsc.c.

References k_ra8_err_out_of_range, k_ra8_io_usbmsc_max_transfer_blocks, ra8_io_blockdev_usbmsc_state_t::lun, RA8_CHECK_NULL_PTR, ra8_usb_hmsc_write10(), and s_tag.

◆ ra8_io_blockdev_usbmsc_init()

ra8_err_t ra8_io_blockdev_usbmsc_init	(	ra8_io_blockdev_t *	bd,
		ra8_io_blockdev_usbmsc_state_t *	state,
		uint8_t	lun )

nodiscard

Bind a hosted USB mass-storage backend into a caller-owned handle.

Records lun in state and points bd at the USB-MSC vtable with state as its context. No allocation and no bus traffic occur; the caller owns both bd and state. The device itself must already be enumerated – the application calls ra8_usb_hmsc_init and waits for the attach callback – before any I/O is issued through the bound handle.

Parameters

[out]	bd	Handle to bind (zero-initialised by the caller).
[out]	state	Caller-owned backend state to populate.
[in]	lun	Logical unit to address, within k_ra8_hmsc_max_lun.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Backend bound; bd is usable once attached.
k_ra8_err_null_ptr	bd or state was NULL.
k_ra8_err_out_of_range	lun exceeds the class layer's LUN ceiling.

Precondition: bd and state out-live every call made through the device.; The application enumerates the device before issuing I/O through bd.

Postcondition: On success bd dispatches to the USB-MSC backend for lun.; On any non-ok return bd and state are left unbound/untouched.

Note: Not thread-safe with respect to the same device or the class layer.

Since: 0.1.0

Definition at line 205 of file ra8_io_blockdev_usbmsc.c.

References ra8_io_blockdev_t::ctx, ra8_io_blockdev_t::iface, k_ra8_err_out_of_range, k_ra8_hmsc_max_lun, k_ra8_ok, ra8_io_blockdev_usbmsc_state_t::lun, RA8_CHECK_NULL_PTR, s_tag, and s_usbmsc_iface.

Referenced by fileops_mount_volume(), selftest_mount_volume(), selftest_mount_volume(), selftest_mount_volume(), selftest_mount_volume(), and selftest_mount_volume().

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_io_blockdev_usbmsc"

static

Module log tag.

Definition at line 35 of file ra8_io_blockdev_usbmsc.c.

◆ s_usbmsc_iface

const ra8_io_blockdev_iface_t s_usbmsc_iface

static

Initial value:

                                                    = {
  .read     = internal_usbmsc_read,
  .write    = internal_usbmsc_write,
  .erase    = nullptr,
  .get_caps = internal_usbmsc_get_caps,
  .sync     = nullptr,
}

USB-MSC backend vtable.

erase/sync are NULL (no host erase, no buffering).

Definition at line 197 of file ra8_io_blockdev_usbmsc.c.

Referenced by ra8_io_blockdev_usbmsc_init().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_io_usbmsc_const_t

Function Documentation

◆ internal_usbmsc_get_caps()

◆ internal_usbmsc_read()

◆ internal_usbmsc_write()

◆ ra8_io_blockdev_usbmsc_init()

Variable Documentation

◆ s_tag

◆ s_usbmsc_iface