ThreadX + ra8_fs-on-LevelX-on-OSPI wear-levelled FAT demo for EK-RA8D2. 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 for the ra8_fs-on-LevelX FAT demo. More...

Functions
static void	demo_panic_halt (void)
	Halt forever in WFI, after draining the SCI8 TX shift register.
static void	demo_setup_or_halt (void)
	Bring CGC + SCI8 up.
static void	demo_print (const char *s)
	Convenience wrapper to write a NUL-terminated string to SCI8.
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 void	demo_lx_open_or_panic (void)
	Format + open the LevelX partition.
static void	demo_fs_format_or_panic (void)
	Bind the backend, format + mount the FAT volume on top of LevelX.
static void	demo_write_test_file (void)
	Create + write /levelx_test.txt with the demo test message.
static void	demo_read_test_file (void)
	Open + read /levelx_test.txt back to SCI8.
static void	demo_thread_entry (ULONG thread_input)
	ThreadX worker entry: bring up LevelX + ra8_fs, exercise the file.
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_demo_test_message [] = "Hello from wear-leveled FAT!"
	Test message written into /levelx_test.txt.
static const char	s_demo_file_path [] = "/levelx_test.txt"
	Path under the FAT root that holds the demo payload.
static LX_NOR_FLASH	s_nor_flash
static ra8_fs_backend_t	s_fs_backend
static ra8_fs_mount_t *	s_fs_mount
static TX_MUTEX	s_fs_mutex
	ThreadX mutex the ra8_fs lock seam is bound to (#608).
static TX_THREAD	s_demo_thread
static UCHAR	s_demo_stack [k_demo_thread_stack]
static char	s_lx_flash_name [] = "ra8_xspi_nor"
	LevelX flash name (mutable so ThreadX/LevelX can take CHAR*).
static char	s_demo_thread_name [] = "fslx_demo"
	Worker-thread name (mutable so ThreadX can take CHAR*).

Detailed Description

ThreadX + ra8_fs-on-LevelX-on-OSPI wear-levelled FAT demo for EK-RA8D2.

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

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

Initialises ra8_xspi against the on-board EK-RA8D2 ISSI IS25LX512M octal-SPI flash chip (via the LevelX NOR driver).
Calls lx_nor_flash_format once to lay down a fresh LevelX partition and lx_nor_flash_open to mount it.
Binds the LevelX flash to the ra8_fs block-device backend (lx_fs_backend_bind) and installs the ra8_fs_set_lock() seam over a ThreadX mutex (#608).
Calls ra8_fs_format followed by ra8_fs_mount to lay down a FAT volume on top of the wear-levelled blocks.
Writes /levelx_test.txt with a known message, then reopens it for read, reads it back and prints the message to SCI8.
Unmounts + closes LevelX cleanly and idles.

Recipe (see also the README.md alongside this main.c):

Connect a USB cable to the J-Link OB CDC port on the EK-RA8D2.
Open a 115200 8N1 terminal.
Flash this firmware (just apps::hardware::flash threadx_fs_levelx_demo).
Watch the [fslx] log lines stream out, ending with [fslx] readback: Hello from wear-leveled FAT! on success.

Author: Brighton Sikarskie

Date: 2026-04-29

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 for the ra8_fs-on-LevelX FAT demo.

Enumerator
k_demo_baud	SCI8 baud (matches uart_hello / threadx_fs_demo).
k_demo_thread_stack	Worker-thread stack size in bytes.
k_demo_file_chunk	Read-back chunk size used when dumping the file to SCI8.

Definition at line 68 of file main.c.

Function Documentation

◆ demo_fs_format_or_panic()

void demo_fs_format_or_panic ( void )

static

Bind the backend, format + mount the FAT volume on top of LevelX.

Calls lx_fs_backend_bind first so ra8_fs has a block device to dispatch into, then ra8_fs_format to lay down a fresh FAT12 superblock (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), then ra8_fs_mount to parse it back.

Precondition: s_nor_flash was successfully opened.

Postcondition: On success s_fs_mount is a mounted FAT volume ready for file I/O.

Since: 0.1.0

Definition at line 245 of file main.c.

References demo_panic_halt(), 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_fs_backend, s_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 187 of file main.c.

References tx_mutex_get, and TX_WAIT_FOREVER.

◆ 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 200 of file main.c.

References tx_mutex_put.

◆ demo_lx_open_or_panic()

void demo_lx_open_or_panic ( void )

static

Format + open the LevelX partition.

Panics on any failure.

Precondition: ra8_xspi_init succeeded for instance 0 (the driver owns it).

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

Since: 0.1.0

Definition at line 213 of file main.c.

References demo_panic_halt(), 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, after draining the SCI8 TX shift register.

Calls ra8_board_uart_console_flush so any panic message previously queued via ra8_board_uart_console_write finishes clocking onto the wire before WFI gates the SCI clock. Without the flush, only the first 1-3 bytes of the failure log reach the host UART because WFI silences the peripheral mid-frame. Return code is intentionally discarded – if the flush times out we still want to halt rather than spin.

Precondition: Called only after a fatal error.

Postcondition: Pending SCI8 TX has drained (or the flush budget expired) and the CPU is parked.

Since: 0.1.0

Definition at line 125 of file main.c.

References ra8_board_uart_console_flush().

◆ demo_print()

void demo_print ( const char * s )

static

Convenience wrapper to write a NUL-terminated string to SCI8.

Parameters

[in] s NUL-terminated ASCII string. Must not be NULL.

Precondition: s != NULL.

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

Since: 0.1.0

Definition at line 169 of file main.c.

References ra8_board_uart_console_write(), and strlen().

◆ demo_read_test_file()

void demo_read_test_file ( void )

static

Open + read /levelx_test.txt back to SCI8.

Precondition: s_fs_mount is mounted FAT and the file exists.

Postcondition: The file's contents have been streamed to SCI8.

Since: 0.1.0

Definition at line 298 of file main.c.

References demo_print(), k_demo_file_chunk, k_ra8_fs_mode_read, k_ra8_ok, ra8_board_uart_console_write(), ra8_fs_close(), ra8_fs_open(), ra8_fs_read(), s_demo_file_path, and s_fs_mount.

Referenced by demo_thread_entry().

◆ demo_setup_or_halt()

void demo_setup_or_halt ( void )

static

Bring CGC + SCI8 up.

Panic-halts on any failure.

Precondition: Reset_Handler / SystemInit complete.

Postcondition: On success SCI8 is sending at 115200 8N1.

Since: 0.1.0

Definition at line 141 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 + ra8_fs, exercise the file.

Parameters

[in] thread_input Unused.

Precondition: tx_application_define has scheduled this thread.

Postcondition: On success the test file has been written + read back.

Since: 0.1.0

Definition at line 331 of file main.c.

References demo_fs_format_or_panic(), demo_lx_open_or_panic(), demo_print(), demo_read_test_file(), demo_write_test_file(), ra8_fs_unmount(), s_fs_mount, and s_nor_flash.

◆ demo_write_test_file()

void demo_write_test_file ( void )

static

Create + write /levelx_test.txt with the demo test message.

Precondition: s_fs_mount is mounted FAT.

Postcondition: On success the file exists on the FAT volume containing exactly s_demo_test_message bytes.

Since: 0.1.0

Definition at line 274 of file main.c.

References demo_print(), k_ra8_ok, ra8_fs_write_file(), s_demo_file_path, s_demo_test_message, s_fs_mount, and strlen().

Referenced by demo_thread_entry().

◆ 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 413 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 Pointer to the start of free RAM provided by the ThreadX port; unused – we statically allocate.

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 374 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_demo_thread_name, s_fs_mutex, TX_AUTO_START, tx_mutex_create, TX_NO_INHERIT, TX_NO_TIME_SLICE, and tx_thread_create.

Variable Documentation

◆ s_demo_file_path

const char s_demo_file_path[] = "/levelx_test.txt"

static

Path under the FAT root that holds the demo payload.

Definition at line 83 of file main.c.

Referenced by demo_read_test_file(), and demo_write_test_file().

◆ s_demo_stack

UCHAR s_demo_stack[k_demo_thread_stack]

static

Definition at line 99 of file main.c.

◆ s_demo_test_message

const char s_demo_test_message[] = "Hello from wear-leveled FAT!"

static

Test message written into /levelx_test.txt.

Definition at line 80 of file main.c.

Referenced by demo_write_test_file().

◆ s_demo_thread

TX_THREAD s_demo_thread

static

Definition at line 98 of file main.c.

◆ s_demo_thread_name

char s_demo_thread_name[] = "fslx_demo"

static

Worker-thread name (mutable so ThreadX can take CHAR*).

Definition at line 105 of file main.c.

◆ s_fs_backend

ra8_fs_backend_t s_fs_backend

static

Definition at line 91 of file main.c.

◆ s_fs_mount

ra8_fs_mount_t* s_fs_mount

static

Definition at line 92 of file main.c.

Referenced by demo_fs_format_or_panic(), demo_read_test_file(), demo_thread_entry(), and demo_write_test_file().

◆ s_fs_mutex

TX_MUTEX s_fs_mutex

static

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

Definition at line 95 of file main.c.

◆ s_lx_flash_name

char s_lx_flash_name[] = "ra8_xspi_nor"

static

LevelX flash name (mutable so ThreadX/LevelX can take CHAR*).

Definition at line 102 of file main.c.

◆ s_nor_flash

LX_NOR_FLASH s_nor_flash

static

Definition at line 88 of file main.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ demo_config_t

Function Documentation

◆ demo_fs_format_or_panic()

◆ demo_fs_lock_acquire()

◆ demo_fs_lock_release()

◆ demo_lx_open_or_panic()

◆ demo_panic_halt()

◆ demo_print()

◆ demo_read_test_file()

◆ demo_setup_or_halt()

◆ demo_thread_entry()

◆ demo_write_test_file()

◆ main()

◆ tx_application_define()

Variable Documentation

◆ s_demo_file_path

◆ s_demo_stack

◆ s_demo_test_message

◆ s_demo_thread

◆ s_demo_thread_name

◆ s_fs_backend

◆ s_fs_mount

◆ s_fs_mutex

◆ s_lx_flash_name

◆ s_nor_flash