ThreadX + ra8_fs file-operations demo on the on-board OSPI flash. More...

#include <stdint.h>
#include <string.h>
#include "ra8_board_ek_ra8d2.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_isr.h"
#include "ra8_time.h"
#include "lx_api.h"
#include "lx_fs_backend.h"
#include "lx_nor_driver_ra8_xspi.h"
#include "tx_api.h"

Include dependency graph for main.c:

Enumerations
enum	demo_config_t : uint32_t { k_demo_baud = 115200U , k_demo_thread_stack = 8192U , k_demo_file_chunk = 64U }
	Compile-time settings (console + worker geometry). More...

Functions
static void	demo_panic_halt (void)
	Halt forever in WFI.
static void	demo_setup_or_halt (void)
	Bring CGC + the J-Link OB VCOM console up.
static void	demo_print (const char *s)
	Write a NUL-terminated ASCII string to the console.
static void	demo_fs_lock_acquire (void *ctx)
	ra8_fs lock-seam acquire: block on the ThreadX mutex.
static void	demo_fs_lock_release (void *ctx)
	ra8_fs lock-seam release: hand the ThreadX mutex back.
static bool	demo_lx_open (void)
	Format + open the LevelX NOR partition on the OSPI flash.
static bool	demo_fs_format_mount (ra8_fs_backend_t out_backend, ra8_fs_mount_t *out_mount)
	Bind the backend, lay down + mount a FAT volume on the LevelX partition.
static bool	demo_read_verify (ra8_fs_mount_t mount, const char path, const char *expected)
	Read `path` back and verify its bytes equal `expected`.
static void	demo_list_entry (const char name, uint8_t attr, uint64_t size, void ctx)
	ra8_fs_listdir callback: print one root-directory entry name.
static void	demo_file_ops (ra8_fs_mount_t *mount)
	Run the file-ops sequence; print the pass banner only if all pass.
static void	demo_thread_entry (ULONG thread_input)
	ThreadX worker entry: bring up LevelX + FAT, run the file ops.
void	tx_application_define (void *first_unused_memory)
	ThreadX system-define hook: build the worker + the ra8_fs lock seam.
void	main (void)
	Application entry.

Variables
static const char	s_readme_text [] = "ra8_fs FAT on OSPI flash via LevelX.\r\n"
	Test payload written into both demo files.
static const char	s_readme_path [] = "/readme.txt"
	Path of the file that is read back and verified.
static const char	s_scratch_path [] = "/scratch.txt"
	Path of the file that is deleted and confirmed gone.
static LX_NOR_FLASH	s_nor_flash
static TX_THREAD	s_demo_thread
static UCHAR	s_demo_stack [k_demo_thread_stack]
static TX_MUTEX	s_fs_mutex
	ThreadX mutex the ra8_fs lock seam is bound to (#608).
static char	s_lx_flash_name [] = "ra8_xspi_nor"

Detailed Description

ThreadX + ra8_fs file-operations demo on the on-board OSPI flash.

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

An ra8_fs FAT file-operations exerciser backed by the EK-RA8D2's on-board Octo-SPI NOR flash (via LevelX wear-levelling), NOT an SD card: the board's microSD is on Pmod2 / SCI0 Simple-SPI, and the always-present OSPI flash needs no card at all. It is the file-ops counterpart to threadx_fs_levelx_demo (which proves the LevelX integration); this one drives the ra8_fs FAT API itself, from an RTOS world through the ra8_fs_set_lock() seam bound to a ThreadX mutex (#608).

Brings the chip up like uart_hello (CGC -> SCI8 @ 115200 8N1), then hands control to ThreadX. tx_application_define spawns one worker that:

Formats + opens a LevelX NOR partition on the OSPI flash (lx_nor_driver_ra8_xspi).
Lays down a fresh FAT volume on top via the LevelX<->ra8_fs backend (lx_fs_backend_bind -> ra8_fs_format -> ra8_fs_mount).
Creates two files, lists the root, reads one back and verifies its bytes match, deletes the other and confirms it is gone.
Prints [fs] ospi FAT roundtrip ok on success.

No card, no jumpers – the flash is soldered on the board, so this runs unattended on the HIL bench.

Author: Brighton Sikarskie

Date: 2026-06-15

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

Since: 0.1.0

Definition in file main.c.

Enumeration Type Documentation

◆ demo_config_t

enum demo_config_t : uint32_t

Compile-time settings (console + worker geometry).

Enumerator
k_demo_baud	SCI8 baud (matches uart_hello).
k_demo_thread_stack	Worker-thread stack bytes.
k_demo_file_chunk	Read-back chunk for verification.

Definition at line 62 of file main.c.

Function Documentation

◆ demo_file_ops()

void demo_file_ops ( ra8_fs_mount_t * mount )

static

Run the file-ops sequence; print the pass banner only if all pass.

create two files -> list root -> read+verify readme -> delete scratch -> confirm the delete. Any failure returns without the banner.

Parameters

[in,out] mount Mounted FAT volume.

Precondition: mount is mounted for read/write.

Postcondition: On success [fs] ospi FAT roundtrip ok is queued.

Since: 0.1.0

Definition at line 311 of file main.c.

References demo_list_entry(), demo_print(), demo_read_verify(), k_ra8_err_not_found, k_ra8_ok, ra8_fs_listdir(), ra8_fs_stat(), ra8_fs_unlink(), ra8_fs_write_file(), s_readme_path, s_readme_text, s_scratch_path, and strlen().

Referenced by demo_thread_entry().

◆ demo_fs_format_mount()

bool demo_fs_format_mount	(	ra8_fs_backend_t *	out_backend,
		ra8_fs_mount_t **	out_mount )

static

Bind the backend, lay down + mount a FAT volume on the LevelX partition.

lx_fs_backend_bind wires the three ra8_fs_backend_t callbacks onto s_nor_flash; ra8_fs_format then writes a FAT12 superfloppy (the xSPI driver exposes a 64-block LevelX window – 384 usable 512-byte sectors – so FAT12 is the band that fits, exactly as the retired FileX format auto-selected) and ra8_fs_mount parses it back.

Parameters

[out]	out_backend	Receives the bound backend (must outlive the mount).
[out]	out_mount	Receives the mount handle.

Returns: true on success; false (with a printed reason) on any failure.

Precondition: demo_lx_open returned true.

Postcondition: On true *out_mount is a mounted FAT volume ready for file I/O.

Since: 0.1.0

Definition at line 219 of file main.c.

References demo_print(), k_ra8_fs_type_fat12, k_ra8_ok, ra8_fs_format_opts_t::label, lx_fs_backend_bind(), ra8_fs_format(), ra8_fs_mount(), s_nor_flash, and ra8_fs_format_opts_t::type.

Referenced by demo_thread_entry().

◆ demo_fs_lock_acquire()

void demo_fs_lock_acquire ( void * ctx )

static

ra8_fs lock-seam acquire: block on the ThreadX mutex.

Parameters

[in] ctx The bound TX_MUTEX*.

Precondition: The mutex was created; the seam contract forbids failure, so wait forever.

Postcondition: The calling thread holds the mutex.

Since: 0.1.0

Definition at line 155 of file main.c.

References tx_mutex_get, and TX_WAIT_FOREVER.

Referenced by tx_application_define().

◆ demo_fs_lock_release()

void demo_fs_lock_release ( void * ctx )

static

ra8_fs lock-seam release: hand the ThreadX mutex back.

Parameters

[in] ctx The bound TX_MUTEX*.

Precondition: The calling thread holds the mutex (acquire/release pair up).

Postcondition: The mutex is released.

Since: 0.1.0

Definition at line 168 of file main.c.

References tx_mutex_put.

Referenced by tx_application_define().

◆ demo_list_entry()

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

static

ra8_fs_listdir callback: print one root-directory entry name.

Parameters

[in]	name	Entry name (NUL-terminated UTF-8).
[in]	attr	FAT attribute bits (unused).
[in]	size	Entry size in bytes (unused).
[in]	ctx	Unused cookie.

Precondition: Invoked by ra8_fs_listdir only.

Postcondition: One indented name line is queued on the console.

Since: 0.1.0

Definition at line 290 of file main.c.

References demo_print().

Referenced by demo_file_ops().

◆ demo_lx_open()

bool demo_lx_open ( void )

static

Format + open the LevelX NOR partition on the OSPI flash.

The LevelX NOR driver owns the OCTA bus bring-up (pin routing, the 8D/1S software-reset recovery, ra8_xspi_init, RDID probe) inside lx_nor_driver_ra8_xspi_initialize, so this must NOT also call ra8_xspi_init (a second PFS route is rejected and format then fails). Let the driver own it.

Returns: true on success; false (with a printed reason) on any LevelX error.

Precondition: LevelX has been initialised (::lx_nor_flash_initialize in the define hook).

Postcondition: On true s_nor_flash is open and ready for sector I/O.

Since: 0.1.0

Definition at line 186 of file main.c.

References demo_print(), lx_nor_driver_ra8_xspi_initialize(), s_lx_flash_name, and s_nor_flash.

Referenced by demo_thread_entry().

◆ demo_panic_halt()

void demo_panic_halt ( void )

static

Halt forever in WFI.

Precondition: Called only after a fatal error.

Postcondition: CPU is parked; only a debugger or reset recovers.

Since: 0.1.0

Definition at line 98 of file main.c.

◆ demo_print()

void demo_print ( const char * s )

static

Write a NUL-terminated ASCII string to the console.

Parameters

[in] s NUL-terminated ASCII string (NULL is ignored).

Postcondition: On success the bytes are queued in the BSP console TX FIFO.

Since: 0.1.0

Definition at line 137 of file main.c.

References ra8_board_uart_console_write(), and strlen().

◆ demo_read_verify()

bool demo_read_verify	(	ra8_fs_mount_t *	mount,
		const char *	path,
		const char *	expected )

static

Read path back and verify its bytes equal expected.

Parameters

[in,out]	mount	Mounted FAT volume.
[in]	path	NUL-terminated path at the root.
[in]	expected	NUL-terminated bytes the file must contain.

Returns: true if the readback matched expected exactly.

Precondition: mount is mounted and path exists.

Postcondition: The file is closed again; no volume state is modified.

Since: 0.1.0

Definition at line 250 of file main.c.

References demo_print(), k_demo_file_chunk, k_ra8_fs_mode_read, k_ra8_ok, memcmp(), ra8_fs_close(), ra8_fs_open(), ra8_fs_read(), and strlen().

Referenced by demo_file_ops().

◆ demo_setup_or_halt()

void demo_setup_or_halt ( void )

static

Bring CGC + the J-Link OB VCOM console up.

Panic-halts on any failure.

Precondition: Reset_Handler / SystemInit complete.

Postcondition: On success the BSP console is sending at 115200 8N1.

Since: 0.1.0

Definition at line 112 of file main.c.

References demo_panic_halt(), k_demo_baud, k_ra8_clock_id_cpuclk0, k_ra8_ok, ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), and ra8_time_init().

◆ demo_thread_entry()

void demo_thread_entry ( ULONG thread_input )

static

ThreadX worker entry: bring up LevelX + FAT, run the file ops.

Parameters

[in] thread_input Unused.

Precondition: tx_application_define scheduled this thread.

Postcondition: LevelX + the mount are closed; the verdict has been printed.

Since: 0.1.0

Definition at line 353 of file main.c.

References demo_file_ops(), demo_fs_format_mount(), demo_lx_open(), demo_print(), ra8_fs_unmount(), and s_nor_flash.

◆ main()

void main ( void )

Application entry.

The application entry point Reset_Handler hands control to.

Brings up clocks + UART, then enters ThreadX.

Precondition: Reset_Handler has copied .data and zeroed .bss.

Postcondition: On clean entry the kernel runs the worker thread once.

Since: 0.1.0

Definition at line 426 of file main.c.

References demo_panic_halt(), demo_print(), demo_setup_or_halt(), and ra8_isr_globals_enable().

◆ tx_application_define()

void tx_application_define ( void * first_unused_memory )

ThreadX system-define hook: build the worker + the ra8_fs lock seam.

Creates the mutex first and installs it through ra8_fs_set_lock() before the worker can issue a filesystem call, per the seam's init-time contract (#608). LevelX's core is initialised here too.

Parameters

[in] first_unused_memory Free-RAM sentinel from the port (unused; control blocks are static).

Precondition: ::tx_kernel_enter has been called.

Postcondition: One worker thread is created; LevelX and the lock seam are initialised.

Since: 0.1.0

Definition at line 387 of file main.c.

References demo_fs_lock_acquire(), demo_fs_lock_release(), demo_print(), demo_thread_entry(), k_ra8_ok, ra8_fs_set_lock(), s_demo_stack, s_demo_thread, s_fs_mutex, s_thread_name, TX_AUTO_START, tx_mutex_create, TX_NO_INHERIT, TX_NO_TIME_SLICE, and tx_thread_create.

Variable Documentation

◆ s_demo_stack

UCHAR s_demo_stack[k_demo_thread_stack]

static

Definition at line 82 of file main.c.

◆ s_demo_thread

TX_THREAD s_demo_thread

static

Definition at line 81 of file main.c.

◆ s_fs_mutex

TX_MUTEX s_fs_mutex

static

ThreadX mutex the ra8_fs lock seam is bound to (#608).

Definition at line 85 of file main.c.

Referenced by tx_application_define().

◆ s_lx_flash_name

char s_lx_flash_name[] = "ra8_xspi_nor"

static

Definition at line 88 of file main.c.

Referenced by demo_lx_open(), and demo_lx_open_or_panic().

◆ s_nor_flash

LX_NOR_FLASH s_nor_flash

static

Definition at line 79 of file main.c.

◆ s_readme_path

const char s_readme_path[] = "/readme.txt"

static

Path of the file that is read back and verified.

Definition at line 73 of file main.c.

Referenced by demo_file_ops().

◆ s_readme_text

const char s_readme_text[] = "ra8_fs FAT on OSPI flash via LevelX.\r\n"

static

Test payload written into both demo files.

Definition at line 70 of file main.c.

Referenced by demo_file_ops().

◆ s_scratch_path

const char s_scratch_path[] = "/scratch.txt"

static

Path of the file that is deleted and confirmed gone.

Definition at line 76 of file main.c.

Referenced by demo_file_ops().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ demo_config_t

Function Documentation

◆ demo_file_ops()

◆ demo_fs_format_mount()

◆ demo_fs_lock_acquire()

◆ demo_fs_lock_release()

◆ demo_list_entry()

◆ demo_lx_open()

◆ demo_panic_halt()

◆ demo_print()

◆ demo_read_verify()

◆ demo_setup_or_halt()

◆ demo_thread_entry()

◆ main()

◆ tx_application_define()

Variable Documentation

◆ s_demo_stack

◆ s_demo_thread

◆ s_fs_mutex

◆ s_lx_flash_name

◆ s_nor_flash

◆ s_readme_path

◆ s_readme_text

◆ s_scratch_path