ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
usb_host_file_ops_steps.c File Reference

examples/ek_ra8d2/hw_validated/manual/usb_host_file_ops/src/usb_host_file_ops_steps.c More...

#include "usb_host_file_ops_steps.h"
#include <stdint.h>
#include "ra8_board_ek_ra8d2.h"
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_io_blockdev.h"
#include "ra8_io_blockdev_usbmsc.h"
Include dependency graph for usb_host_file_ops_steps.c:

Go to the source code of this file.

Data Structures

struct  fileops_listdir_ctx_t
 Cookie carried through ra8_fs_listdir for printing + matching. More...

Functions

static uint8_t fileops_nibble_to_hex (uint32_t nibble)
 Format one nibble (0..15) into an uppercase hex character.
static uint32_t fileops_str_len (const char *text)
 Bounded ASCII string length (cap k_fileops_print_cap).
static bool fileops_name_eq (const char *a, const char *b)
 Bounded ASCII string equality (cap k_fileops_name_cap).
static ra8_err_t fileops_sci_write (const uint8_t *data, uint32_t len)
 Push a literal block over SCI8 polled.
ra8_err_t fileops_print (const char *text)
 Print a NUL-terminated ASCII string over the console.
ra8_err_t fileops_print_dec (uint64_t value)
 Print a uint32_t as ASCII decimal.
ra8_err_t fileops_print_hex (uint32_t value, uint8_t digits)
 Print a value as fixed-width uppercase hex.
ra8_err_t fileops_print_fail (const char *what, ra8_err_t err)
 Print "FAIL <what> err=0xNNNNNNNN" on its own line.
static const char * fileops_fs_type_name (ra8_fs_type_t type)
 Map a detected filesystem type to a printable name.
ra8_err_t fileops_mount_volume (ra8_fs_mount_t **out_mount)
 Mount the attached drive through the USB-MSC backend.
static void fileops_listdir_cb (const char *name, uint8_t attr, uint64_t size, void *ctx)
 Listdir callback: print one entry, match the expectation names.
static ra8_err_t fileops_step_listdir (ra8_fs_mount_t *mount, const char *want, const char *avoid)
 List the root directory and check presence/absence expectations.
static ra8_err_t fileops_read_back (ra8_fs_mount_t *mount, const char *path)
 Open path and verify it reads back the known payload.
static ra8_err_t fileops_expect_absent (ra8_fs_mount_t *mount, const char *path)
 Require that path no longer resolves on the volume.
static ra8_err_t fileops_step_write (ra8_fs_mount_t *mount)
 Step 3: print the banner and write the payload file.
ra8_err_t fileops_suite_create (ra8_fs_mount_t *mount)
 Suite steps 1..5: cleanup, baseline listdir, write, verify, list.
ra8_err_t fileops_suite_mutate (ra8_fs_mount_t *mount)
 Suite steps 6..9: rename, old-gone/new-intact, list, delete.
static void fileops_dump_rows (const uint8_t *data, uint32_t offset, uint32_t len)
 Hex-dump len bytes of data starting at offset.
void fileops_probe_layout (void)
 Dump the partition table + LBA1/LBA2 heads after a mount failure.

Variables

static const char k_fileops_name_a [] = "USBTEST.TXT"
 Name the payload file is created under (8.3-safe, <= 15 chars).
static const char k_fileops_name_b [] = "USBDONE.TXT"
 Name the payload file is renamed to (8.3-safe, <= 15 chars).
static const uint8_t k_fileops_payload []
 Known payload written to and read back from the drive.
static ra8_io_blockdev_t s_fileops_usb_dev
 Block device fronting the hosted MSC volume for this ladder.
static ra8_io_blockdev_usbmsc_state_t s_fileops_usb_state
 Caller-owned backend state for s_fileops_usb_dev.

Detailed Description

examples/ek_ra8d2/hw_validated/manual/usb_host_file_ops/src/usb_host_file_ops_steps.c

Console helpers + ra8_fs file-op suite for the USB host file-ops app.

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

Implements the polled-console print helpers, the ra8_io USB-MSC block device the ra8_fs mount runs on, the root-directory listing, the nine file-operation steps, and the on-mount-failure disk-layout probe. These routines were split out of main.c so every translation unit stays under the repository file-size cap; the boot/bring-up code and the retry ladder remain in main.c.

Author
Brighton Sikarskie
Date
2026-06-12
Since
0.1.0

Definition in file usb_host_file_ops_steps.c.

Function Documentation

◆ fileops_dump_rows()

void fileops_dump_rows ( const uint8_t * data,
uint32_t offset,
uint32_t len )
static

Hex-dump len bytes of data starting at offset.

Parameters
[in]dataSector buffer.
[in]offsetFirst byte index to print.
[in]lenByte count to print.
Precondition
data holds at least offset + len bytes.
SCI8 init already ran.
Postcondition
The dump rows are queued on the console.
No other state changes.
Note
Print errors are swallowed – diagnostic only.
Since
0.1.0

Definition at line 672 of file usb_host_file_ops_steps.c.

References fileops_print(), fileops_print_hex(), k_fileops_hex_chars_u16, and k_fileops_probe_row.

Referenced by fileops_probe_layout().

◆ fileops_expect_absent()

ra8_err_t fileops_expect_absent ( ra8_fs_mount_t * mount,
const char * path )
staticnodiscard

Require that path no longer resolves on the volume.

Parameters
[in]mountLive mount handle.
[in]pathName that must not exist.
Returns
ra8_err_t verdict.
Return values
k_ra8_err_existsThe name still opened successfully.
Precondition
mount is a live handle from ra8_fs_mount.
path was unlinked or renamed away.
Postcondition
Any accidentally opened handle is closed again.
No filesystem mutation occurs.
Note
A lookup error other than not-found is propagated as-is.
Since
0.1.0

Definition at line 494 of file usb_host_file_ops_steps.c.

References fileops_print_fail(), k_ra8_err_exists, k_ra8_err_not_found, k_ra8_fs_mode_read, k_ra8_ok, ra8_fs_close(), and ra8_fs_open().

Referenced by fileops_suite_mutate().

◆ fileops_fs_type_name()

const char * fileops_fs_type_name ( ra8_fs_type_t type)
static

Map a detected filesystem type to a printable name.

Parameters
[in]typeMount-time detection result.
Returns
Static NUL-terminated name string.
Return values
exfatFor k_ra8_fs_type_exfat.
Precondition
None – total over the enum.
type came from a populated mount struct.
Postcondition
No state changes.
Returned pointer references static storage.
Note
Pure function.
Since
0.1.0

Definition at line 255 of file usb_host_file_ops_steps.c.

References k_ra8_fs_type_exfat, k_ra8_fs_type_fat12, k_ra8_fs_type_fat16, k_ra8_fs_type_fat32, and k_ra8_fs_type_unknown.

Referenced by fileops_mount_volume().

◆ fileops_listdir_cb()

void fileops_listdir_cb ( const char * name,
uint8_t attr,
uint64_t size,
void * ctx )
static

Listdir callback: print one entry, match the expectation names.

Parameters
[in]nameNUL-terminated entry name.
[in]attrFAT attribute byte.
[in]sizeFile size in bytes (0 for directories).
[in,out]ctxfileops_listdir_ctx_t cookie.
Precondition
Invoked only by ra8_fs_listdir with a valid cookie.
SCI8 init already ran.
Postcondition
The entry line is queued; counters/flags are updated.
No other state changes.
Note
Print errors are swallowed – the walk must finish.
Since
0.1.0

Definition at line 342 of file usb_host_file_ops_steps.c.

References fileops_listdir_ctx_t::avoid, fileops_listdir_ctx_t::count, fileops_name_eq(), fileops_print(), fileops_print_dec(), fileops_listdir_ctx_t::found_avoid, fileops_listdir_ctx_t::found_want, k_ra8_fs_attr_directory, and fileops_listdir_ctx_t::want.

Referenced by fileops_step_listdir().

◆ fileops_mount_volume()

ra8_err_t fileops_mount_volume ( ra8_fs_mount_t ** out_mount)
nodiscard

Mount the attached drive through the USB-MSC backend.

Parameters
[out]out_mountReceives the mount handle on success.
Returns
ra8_err_t from the block-device bind, the ra8_fs bridge, or ra8_fs_mount.
Return values
k_ra8_okVolume mounted; the type line was printed.
Precondition
ra8_usb_hmsc_enumerate completed on the attached drive.
out_mount is non-NULL.
Postcondition
On k_ra8_ok the mount handle is live and must be unmounted later.
The "mounted fs=" line is queued on success.
Note
Reads the MBR/BPB chain over USB.
Since
0.1.0

Definition at line 272 of file usb_host_file_ops_steps.c.

References fileops_fs_type_name(), fileops_print(), fileops_print_dec(), fileops_print_fail(), k_fileops_target_lun, k_ra8_ok, ra8_fs_mount(), ra8_io_blockdev_as_fs_backend(), ra8_io_blockdev_usbmsc_init(), s_fileops_usb_dev, and s_fileops_usb_state.

Referenced by fileops_run_ladder().

◆ fileops_name_eq()

bool fileops_name_eq ( const char * a,
const char * b )
static

Bounded ASCII string equality (cap k_fileops_name_cap).

Parameters
[in]aFirst NUL-terminated string.
[in]bSecond NUL-terminated string.
Returns
true when both strings match through their terminators.
Return values
falseOn the first differing byte.
Precondition
a and b are non-NULL.
Both strings are NUL-terminated within the cap.
Postcondition
No state changes.
Comparison never walks past k_fileops_name_cap bytes.
Note
Case-sensitive byte compare.
Since
0.1.0

Definition at line 114 of file usb_host_file_ops_steps.c.

References k_fileops_name_cap.

Referenced by fileops_listdir_cb().

◆ fileops_nibble_to_hex()

uint8_t fileops_nibble_to_hex ( uint32_t nibble)
static

Format one nibble (0..15) into an uppercase hex character.

Parameters
[in]nibble4-bit value.
Returns
ASCII '0'..'9' or 'A'..'F'.
Return values
'0'For a zero nibble.
Precondition
Caller has already masked the value to 4 bits.
None beyond the mask contract.
Postcondition
Returned byte is in the printable hex range.
No state changes.
Note
Pure function.
Since
0.1.0

Definition at line 67 of file usb_host_file_ops_steps.c.

References k_fileops_hex_digit_split.

Referenced by fileops_print_hex().

◆ fileops_print()

ra8_err_t fileops_print ( const char * text)
nodiscard

Print a NUL-terminated ASCII string over the console.

Parameters
[in]textString to print (CR/LF included by the caller).
Returns
ra8_err_t propagated from the SCI helper.
Return values
k_ra8_okAll bytes queued.
Precondition
SCI8 init already ran; text is non-NULL.
text is NUL-terminated within k_fileops_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 146 of file usb_host_file_ops_steps.c.

References fileops_sci_write(), and fileops_str_len().

Referenced by fileops_dump_rows(), fileops_listdir_cb(), fileops_mount_volume(), fileops_print_attach(), fileops_print_fail(), fileops_probe_layout(), fileops_run_ladder(), fileops_step_listdir(), fileops_step_write(), fileops_suite_create(), fileops_suite_mutate(), and main().

◆ fileops_print_dec()

ra8_err_t fileops_print_dec ( uint64_t value)
nodiscard

Print a uint32_t as ASCII decimal.

Parameters
[in]valueValue to print.
Returns
ra8_err_t propagated from the SCI helper.
Return values
k_ra8_okAll 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 151 of file usb_host_file_ops_steps.c.

References fileops_sci_write(), k_fileops_dec_chars_u64, and k_fileops_dec_radix.

Referenced by fileops_listdir_cb(), fileops_mount_volume(), fileops_probe_layout(), fileops_step_listdir(), and fileops_step_write().

◆ fileops_print_fail()

ra8_err_t fileops_print_fail ( const char * what,
ra8_err_t err )
nodiscard

Print "FAIL <what> err=0xNNNNNNNN" on its own line.

Parameters
[in]whatShort description of the failed step.
[in]errError code returned by the step.
Returns
ra8_err_t propagated from the SCI helpers.
Return values
k_ra8_okThe 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 186 of file usb_host_file_ops_steps.c.

References fileops_print(), fileops_print_hex(), k_fileops_hex_chars_u32, and k_ra8_ok.

Referenced by fileops_expect_absent(), fileops_mount_volume(), fileops_read_back(), fileops_run_ladder(), fileops_step_listdir(), fileops_step_write(), fileops_suite_mutate(), and main().

◆ fileops_print_hex()

ra8_err_t fileops_print_hex ( uint32_t value,
uint8_t digits )
nodiscard

Print a value as fixed-width uppercase hex.

Parameters
[in]valueValue to print.
[in]digitsHex digit count (4 for u16, 8 for u32).
Returns
ra8_err_t propagated from the SCI helper.
Return values
k_ra8_okAll bytes queued.
Precondition
SCI8 init already ran.
digits is at most k_fileops_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 172 of file usb_host_file_ops_steps.c.

References fileops_nibble_to_hex(), fileops_sci_write(), k_fileops_hex_chars_u32, k_fileops_nibble_bits, and k_fileops_nibble_mask.

Referenced by fileops_dump_rows(), fileops_print_attach(), and fileops_print_fail().

◆ fileops_probe_layout()

void fileops_probe_layout ( void )

Dump the partition table + LBA1/LBA2 heads after a mount failure.

Reads LBA 0 (MBR partition entries at 0x1BE), LBA 1, and LBA 2 straight through the USB backend and prints hex excerpts, so an unrecognized disk layout (e.g. GPT) can be identified from the log.

Precondition
ra8_usb_hmsc_enumerate completed on the attached drive.
SCI8 init already ran.
Postcondition
Three dump blocks are queued on the console.
No filesystem state changes.
Note
Print/read errors are swallowed – diagnostic only.
Since
0.1.0

Definition at line 688 of file usb_host_file_ops_steps.c.

References fileops_dump_rows(), fileops_print(), fileops_print_dec(), k_fileops_probe_head_len, k_fileops_probe_lba_max, k_fileops_probe_tbl_len, k_fileops_probe_tbl_off, k_fileops_sector_bytes, k_ra8_ok, ra8_io_blockdev_read(), and s_fileops_usb_dev.

Referenced by fileops_run_ladder().

◆ fileops_read_back()

ra8_err_t fileops_read_back ( ra8_fs_mount_t * mount,
const char * path )
staticnodiscard

Open path and verify it reads back the known payload.

Parameters
[in]mountLive mount handle.
[in]pathFile expected to hold k_fileops_payload.
Returns
ra8_err_t verdict.
Return values
k_ra8_err_invalid_sizeRead length differs from the payload.
k_ra8_err_invalid_stateA payload byte differs.
Precondition
mount is a live handle from ra8_fs_mount.
path names a file written with the payload.
Postcondition
The file is closed again in every path.
No filesystem mutation occurs.
Note
Reads the file content over USB.
Since
0.1.0

Definition at line 449 of file usb_host_file_ops_steps.c.

References fileops_print_fail(), k_fileops_payload, k_fileops_sector_bytes, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_fs_mode_read, k_ra8_ok, ra8_fs_close(), ra8_fs_open(), and ra8_fs_read().

Referenced by fileops_suite_create(), and fileops_suite_mutate().

◆ fileops_sci_write()

ra8_err_t fileops_sci_write ( const uint8_t * data,
uint32_t len )
staticnodiscard

Push a literal block over SCI8 polled.

Parameters
[in]dataBuffer to send.
[in]lenByte count.
Returns
ra8_err_t passthrough from ra8_board_uart_console_write.
Return values
k_ra8_okAll bytes queued.
Precondition
data is non-NULL; SCI8 init already ran.
len excludes any NUL terminator.
Postcondition
Bytes have been pushed out the SCI8 TX FIFO.
No other state changes.
Note
Blocking polled TX.
Since
0.1.0

Definition at line 141 of file usb_host_file_ops_steps.c.

References ra8_board_uart_console_write().

Referenced by fileops_print(), fileops_print_dec(), and fileops_print_hex().

◆ fileops_step_listdir()

ra8_err_t fileops_step_listdir ( ra8_fs_mount_t * mount,
const char * want,
const char * avoid )
staticnodiscard

List the root directory and check presence/absence expectations.

Parameters
[in]mountLive mount handle.
[in]wantName that must appear (nullptr = no check).
[in]avoidName that must not appear (nullptr = no check).
Returns
ra8_err_t verdict.
Return values
k_ra8_err_not_foundwant was not listed.
k_ra8_err_existsavoid was listed.
Precondition
mount is a live handle from ra8_fs_mount.
SCI8 init already ran.
Postcondition
Every root entry plus the count line is queued.
No filesystem mutation occurs.
Note
Walks the root directory over USB.
Since
0.1.0

Definition at line 384 of file usb_host_file_ops_steps.c.

References fileops_listdir_ctx_t::count, fileops_listdir_cb(), fileops_print(), fileops_print_dec(), fileops_print_fail(), fileops_listdir_ctx_t::found_avoid, fileops_listdir_ctx_t::found_want, k_ra8_err_exists, k_ra8_err_not_found, k_ra8_ok, and ra8_fs_listdir().

Referenced by fileops_suite_create(), and fileops_suite_mutate().

◆ fileops_step_write()

ra8_err_t fileops_step_write ( ra8_fs_mount_t * mount)
staticnodiscard

Step 3: print the banner and write the payload file.

Parameters
[in]mountLive mount handle.
Returns
First failing print/write error, or k_ra8_ok.
Return values
k_ra8_okk_fileops_name_a holds the payload.
Precondition
mount is a live handle from ra8_fs_mount.
Leftover test files were already unlinked.
Postcondition
On k_ra8_ok the volume holds k_fileops_name_a with the payload.
The step banner is queued on the console.
Note
Mutates the volume (creates the test file).
Since
0.1.0

Definition at line 523 of file usb_host_file_ops_steps.c.

References fileops_print(), fileops_print_dec(), fileops_print_fail(), k_fileops_name_a, k_fileops_payload, k_ra8_ok, and ra8_fs_write_file().

Referenced by fileops_suite_create().

◆ fileops_str_len()

uint32_t fileops_str_len ( const char * text)
static

Bounded ASCII string length (cap k_fileops_print_cap).

Parameters
[in]textNUL-terminated string.
Returns
Number of bytes before the NUL, capped.
Return values
0For an empty string.
Precondition
text is non-NULL.
text points to readable storage of at least the returned length.
Postcondition
No state changes.
Return value never exceeds k_fileops_print_cap.
Note
Bounded scan – never walks past the cap on a missing NUL.
Since
0.1.0

Definition at line 88 of file usb_host_file_ops_steps.c.

References k_fileops_print_cap.

Referenced by fileops_print().

◆ fileops_suite_create()

ra8_err_t fileops_suite_create ( ra8_fs_mount_t * mount)
nodiscard

Suite steps 1..5: cleanup, baseline listdir, write, verify, list.

Parameters
[in]mountLive mount handle.
Returns
First failing step's error, or k_ra8_ok.
Return values
k_ra8_okSteps 1-5 all passed and printed their verdicts.
Precondition
mount is a live handle from ra8_fs_mount.
SCI8 init already ran.
Postcondition
On k_ra8_ok the volume holds k_fileops_name_a with the payload.
Each completed step toggled LED2 and queued its verdict line.
Note
Mutates the volume (creates the test file).
Since
0.1.0

Definition at line 548 of file usb_host_file_ops_steps.c.

References fileops_print(), fileops_read_back(), fileops_step_listdir(), fileops_step_write(), k_fileops_name_a, k_fileops_name_b, k_ra8_board_led2, k_ra8_ok, ra8_board_led_toggle(), and ra8_fs_unlink().

Referenced by fileops_run_ladder().

◆ fileops_suite_mutate()

ra8_err_t fileops_suite_mutate ( ra8_fs_mount_t * mount)
nodiscard

Suite steps 6..9: rename, old-gone/new-intact, list, delete.

Parameters
[in]mountLive mount handle.
Returns
First failing step's error, or k_ra8_ok.
Return values
k_ra8_okSteps 6-9 all passed and printed their verdicts.
Precondition
fileops_suite_create completed on this mount.
SCI8 init already ran.
Postcondition
On k_ra8_ok the volume no longer holds either test name.
Each completed step toggled LED2 and queued its verdict line.
Note
Mutates the volume (rename + unlink).
Since
0.1.0

Definition at line 596 of file usb_host_file_ops_steps.c.

References fileops_expect_absent(), fileops_print(), fileops_print_fail(), fileops_read_back(), fileops_step_listdir(), k_fileops_name_a, k_fileops_name_b, k_ra8_board_led2, k_ra8_ok, ra8_board_led_toggle(), ra8_fs_rename(), and ra8_fs_unlink().

Referenced by fileops_run_ladder().

Variable Documentation

◆ k_fileops_name_a

const char k_fileops_name_a[] = "USBTEST.TXT"
static

Name the payload file is created under (8.3-safe, <= 15 chars).

Definition at line 40 of file usb_host_file_ops_steps.c.

Referenced by fileops_step_write(), fileops_suite_create(), and fileops_suite_mutate().

◆ k_fileops_name_b

const char k_fileops_name_b[] = "USBDONE.TXT"
static

Name the payload file is renamed to (8.3-safe, <= 15 chars).

Definition at line 43 of file usb_host_file_ops_steps.c.

Referenced by fileops_suite_create(), and fileops_suite_mutate().

◆ k_fileops_payload

const uint8_t k_fileops_payload[]
static
Initial value:
=
"ra8d2 usb-hs host file-ops payload 0123456789 the quick brown fox\r\n"

Known payload written to and read back from the drive.

Definition at line 46 of file usb_host_file_ops_steps.c.

Referenced by fileops_read_back(), and fileops_step_write().

◆ s_fileops_usb_dev

ra8_io_blockdev_t s_fileops_usb_dev
static

Block device fronting the hosted MSC volume for this ladder.

Bound once in fileops_mount_volume by ra8_io_blockdev_usbmsc_init, which wires the ra8_io USB-MSC backend over the polled host-MSC class. File scope because ra8_io_blockdev_as_fs_backend keeps a pointer to this handle for the whole life of the mount.

Note
Single-threaded ladder; no locking.
Warning
Do not rebind while a mount is live.
Since
0.1.0

Definition at line 226 of file usb_host_file_ops_steps.c.

Referenced by fileops_mount_volume(), and fileops_probe_layout().

◆ s_fileops_usb_state

ra8_io_blockdev_usbmsc_state_t s_fileops_usb_state
static

Caller-owned backend state for s_fileops_usb_dev.

Records the logical unit the backend addresses. Private to the ra8_io USB-MSC backend and must out-live every call made through the device.

Note
Single-threaded ladder; no locking.
Warning
Treat the contents as private to ra8_io.
Since
0.1.0

Definition at line 240 of file usb_host_file_ops_steps.c.

Referenced by fileops_mount_volume().