Optional SD-card book source for the hybrid e-reader. More...

#include <string.h>
#include "epub.h"
#include "epub_fs.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_cgc.h"
#include "ra8_check.h"
#include "ra8_fs.h"
#include "ra8_port_constants.h"
#include "ra8_port_utils.h"
#include "ra8_sci_spi.h"
#include "ra8_sdmmc_spi.h"
#include "ra8_spi.h"
#include "sh_app.h"

Include dependency graph for sh_sd.c:

Enumerations
enum	sh_sd_const_t : uint32_t { k_sd_spi_chan = 0U }
	SD bus constants. More...

Functions
static ra8_err_t	sh_sd_set_clock (void *ctx, uint32_t hz)
static ra8_err_t	sh_sd_cs (void *ctx, bool asserted)
	ra8_sdmmc_spi_transport_t::cs over ra8_gpio (CS active-low).
static ra8_err_t	sh_sd_xfer (void ctx, const uint8_t tx, uint8_t *rx, uint32_t len)
	ra8_sdmmc_spi_transport_t::xfer over ra8_sci_spi_xfer.
static ra8_err_t	sh_sd_bus_init (void)
	Route Pmod2 SPI pins + CS GPIO and init SCI0 SPI at the 400 kHz floor.
bool	sh_sd_mount (void)
	Bring up the Pmod2 microSD over ra8_sdmmc_spi and mount its FAT volume.
static void	sh_sd_listdir_cb (const char name, uint8_t attr, uint64_t size, void ctx)
	ra8_fs_listdir callback: append each root book file as an SD entry.
void	sh_sd_scan (void)
	Append every root *.RBK file on the card as an SD shelf entry.
bool	sh_sd_book_open (const char name, uint32_t out_len)
	Open SD file `name` and hold it as the paged book backing.
ra8_err_t	sh_sd_book_read (void ctx, uint64_t offset, uint8_t buf, uint32_t len)
	ra8_vsource_read_fn over the held-open SD book file (seek + read).
size_t	sh_sd_comic_read (void ctx, uint64_t offset, void buf, size_t len)
	comic_read_fn over the held-open SD book file (seek + clamped read).
void	sh_sd_book_close (void)
	Close the held SD book file (idempotent).
bool	sh_sd_open_epub (const char name, void out_book)
	Stream-open SD file `name` as an EPUB via epub_open_streamed_fs.
void	sh_sd_close_epub (void *book)
	Close a streamed EPUB opened by sh_sd_open_epub and its source file.

Variables
static const ra8_port_pin_t	k_sd_pin_sck = (ra8_port_pin_t)k_ra8_board_pmod2_spi_sck
static const ra8_port_pin_t	k_sd_pin_cipo = (ra8_port_pin_t)k_ra8_board_pmod2_spi_cipo
static const ra8_port_pin_t	k_sd_pin_copi = (ra8_port_pin_t)k_ra8_board_pmod2_spi_copi
static const ra8_port_pin_t	k_sd_pin_cs = (ra8_port_pin_t)k_ra8_board_pmod2_spi_cs
static uint32_t	s_pclka_hz
	PCLKA for the SPI clock divider.
static ra8_fs_backend_t	s_backend
	SD block-device backend (mount-lived).
static ra8_fs_mount_t *	s_mount
	Mounted FAT volume, or NULL.
static ra8_fs_file_t *	s_book
	Held-open .RBK backing paged reads.
static const char *	s_sd_tag = "sh_sd"
	Log tag for SD-read diagnostics.
static epub_stream_fs_ctx_t	s_epub_io
	Held-open streamed .epub source (#230); valid while an EPUB is open.

Detailed Description

Optional SD-card book source for the hybrid e-reader.

Brings up the Pmod2 microSD over SCI0 Simple-SPI -> ra8_sdmmc_spi -> ra8_fs (mirroring the pagecache / epub_open path), scans the FAT root for book files (sh_classify.h), and serves demand-paged byte-range reads out of the selected file. Each .rabook is the same compressed RBKC container the baked books use, so the rest of the app is source-agnostic. The opened book's file handle stays held (sh_sd_book_open) and sh_sd_book_read seeks + reads single compressed chunks on demand – the whole container is never resident. .epub books use the same discipline (#230): sh_sd_open_epub holds the source file open and epub seeks + reads each ZIP entry on demand, so no whole-file buffer exists for EPUBs either. Mounting is best-effort: with no card (ra8_emulator run without --sd) ra8_sdmmc_spi_init() times out and the shelf stays baked-only.

[Ring 6 / App] {World: NS}

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

Since: 0.1.0

Definition in file sh_sd.c.

Enumeration Type Documentation

◆ sh_sd_const_t

enum sh_sd_const_t : uint32_t

SD bus constants.

Enumerator
k_sd_spi_chan	Pmod2 / J25 SCI0 Simple-SPI channel.

Definition at line 42 of file sh_sd.c.

Function Documentation

◆ sh_sd_book_close()

void sh_sd_book_close ( void )

Close the held SD book file (idempotent).

Definition at line 225 of file sh_sd.c.

References ra8_fs_close(), and s_book.

Referenced by sh_comic_close(), sh_comic_open(), sh_paged_close(), and sh_sd_book_open().

◆ sh_sd_book_open()

bool sh_sd_book_open	(	const char *	name,
		uint32_t *	out_len )

Open SD file name and hold it as the paged book backing.

Closes any previously held book file first. The handle stays open until sh_sd_book_close (or the next open), so sh_sd_book_read can serve chunk reads on demand – the file is never slurped whole.

Parameters

[in]	name	Root file name (e.g. "Meditations.rabook").
[out]	out_len	Receives the file size in bytes.

Returns: true if the file is open and non-empty.

Since: 0.1.0

Definition at line 150 of file sh_sd.c.

References k_ra8_fs_mode_read, k_ra8_ok, ra8_fs_open(), ra8_fs_size(), s_book, s_mount, and sh_sd_book_close().

Referenced by sh_book_open_rabook(), and sh_comic_open().

◆ sh_sd_book_read()

ra8_err_t sh_sd_book_read	(	void *	ctx,
		uint64_t	offset,
		uint8_t *	buf,
		uint32_t	len )

ra8_vsource_read_fn over the held-open SD book file (seek + read).

Parameters

[in]	ctx	Unused (the held file handle is module state).
[in]	offset	Absolute byte offset within the file.
[out]	buf	Destination for exactly `len` bytes.
[in]	len	Bytes to read; a read past EOF is rejected.

Returns: k_ra8_ok, or the ra8_fs error / k_ra8_err_out_of_range on a short read.

Precondition: A book file is held open via sh_sd_book_open.

Postcondition: On k_ra8_ok exactly len bytes were copied to buf.

Since: 0.1.0

Definition at line 176 of file sh_sd.c.

References k_ra8_err_invalid_state, k_ra8_err_out_of_range, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_fs_read(), ra8_fs_seek(), s_book, and s_sd_tag.

Referenced by sh_book_open_rabook().

◆ sh_sd_bus_init()

ra8_err_t sh_sd_bus_init ( void )

staticnodiscard

Route Pmod2 SPI pins + CS GPIO and init SCI0 SPI at the 400 kHz floor.

Definition at line 82 of file sh_sd.c.

References k_ra8_err_invalid_arg, k_ra8_level_high, k_ra8_ok, k_ra8_psel_sci_async, k_ra8_sdmmc_spi_clock_init_hz, k_ra8_spi_mode_0, k_sd_pin_cipo, k_sd_pin_copi, k_sd_pin_cs, k_sd_pin_sck, k_sd_spi_chan, ra8_gpio_output_init(), ra8_pfs_route_peripheral(), ra8_sci_spi_init(), and s_pclka_hz.

Referenced by sh_sd_mount().

◆ sh_sd_close_epub()

void sh_sd_close_epub ( void * book )

Close a streamed EPUB opened by sh_sd_open_epub and its source file.

Parameters

[in,out] book The epub_book_t* passed to sh_sd_open_epub.

Since: 0.1.0

Definition at line 244 of file sh_sd.c.

References epub_close_streamed_fs(), and s_epub_io.

Referenced by sh_book_open().

◆ sh_sd_comic_read()

size_t sh_sd_comic_read	(	void *	ctx,
		uint64_t	offset,
		void *	buf,
		size_t	len )

comic_read_fn over the held-open SD book file (seek + clamped read).

Shares the held file handle with sh_sd_book_read but matches the comic reader's seam shape (returns the byte count, not an error) and serves a short read at EOF instead of rejecting it – comic's miniz/RAR backends probe the archive tail and treat a short read as end-of-file.

Parameters

[in]	ctx	Unused (the held file handle is module state).
[in]	offset	Absolute byte offset within the file.
[out]	buf	Destination buffer (`len` writable bytes).
[in]	len	Bytes requested.

Returns: Bytes actually copied (0 at/after EOF or on any error).

Precondition: A comic file is held open via sh_sd_book_open.; buf holds len writable bytes.

Postcondition: At most len bytes were copied to buf; the return is that count.

Since: 0.1.0

Definition at line 203 of file sh_sd.c.

References k_ra8_ok, ra8_fs_read(), ra8_fs_seek(), and s_book.

Referenced by sh_comic_open().

◆ sh_sd_cs()

ra8_err_t sh_sd_cs	(	void *	ctx,
		bool	asserted )

static

ra8_sdmmc_spi_transport_t::cs over ra8_gpio (CS active-low).

Definition at line 68 of file sh_sd.c.

References k_ra8_level_high, k_ra8_level_low, k_sd_pin_cs, and ra8_gpio_write().

Referenced by sh_sd_mount().

◆ sh_sd_listdir_cb()

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

static

ra8_fs_listdir callback: append each root book file as an SD entry.

Definition at line 119 of file sh_sd.c.

References sh_entry_t::author, sh_entry_t::blob_len, sh_entry_t::fmt, sh_entry_t::from_sd, g_sh, k_ra8_fs_attr_directory, k_ra8_fs_attr_volume_id, k_sh_fmt_rabook, k_sh_max_books, k_sh_name_cap, sh_entry_t::sd_name, sh_book_classify(), strlen(), strncpy(), and sh_entry_t::title.

Referenced by sh_sd_scan().

◆ sh_sd_mount()

bool sh_sd_mount ( void )

Bring up the Pmod2 microSD over ra8_sdmmc_spi and mount its FAT volume.

Returns: true if a card mounted; false (the common no-card case) leaves the shelf baked-only.

Precondition: Clocks (ra8_cgc) are initialised.

Postcondition: On true, ::sh_sd_read / sh_sd_scan are usable.

Since: 0.1.0

Definition at line 97 of file sh_sd.c.

References k_ra8_clock_id_pclka, k_ra8_ok, ra8_cgc_get_clock_hz(), ra8_fs_mount(), ra8_sdmmc_spi_bind_fs_backend(), ra8_sdmmc_spi_init(), s_backend, s_mount, s_pclka_hz, sh_sd_bus_init(), sh_sd_cs(), sh_sd_set_clock(), and sh_sd_xfer().

Referenced by main().

◆ sh_sd_open_epub()

bool sh_sd_open_epub	(	const char *	name,
		void *	out_book )

Stream-open SD file name as an EPUB via epub_open_streamed_fs.

No whole-file residency (#230): the source file stays held open by this module and every ZIP entry (chapter, cover, resource) is seek+read on demand, so there is no book-size ceiling below the ra8_fs 4 GiB offset limit. Release with sh_sd_close_epub.

Parameters