ra8_sdfont.h File Reference

Load a TTF/OTF font off a Pmod SD card, self-provisioning if absent. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_port_constants.h"

Include dependency graph for ra8_sdfont.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ra8_sdfont_cfg_t
	SD-card font-store bus description + provisioning policy. More...

Enumerations
enum	ra8_sdfont_source_t : uint8_t {   k_ra8_sdfont_source_card = 0 ,   k_ra8_sdfont_source_provisioned = 1 }
	Provenance of the font bytes returned by ra8_sdfont_load. More...

Functions
ra8_err_t	ra8_sdfont_load (const ra8_sdfont_cfg_t *cfg, uint8_t *buf, uint32_t cap, uint32_t *out_len, ra8_sdfont_source_t *out_source)
	Mount the Pmod SD card and load a font, provisioning it if absent.

Detailed Description

Load a TTF/OTF font off a Pmod SD card, self-provisioning if absent.

Tag

[Ring 4 / SDFont] {World: NS}

One reusable helper for the e-reader font-storage path shared by the sd_font_render and ereader_ui example apps. It brings up an SD card on an SCI Simple-SPI bus (Pmod2 / J25 on the EK-RA8D2), mounts the FAT volume through ra8_fs, and loads a named font file into a caller-owned buffer.

The distinguishing feature is self-provisioning: when the named file is absent from the card, the helper writes a caller-supplied fallback blob (a font baked into flash) to the card, then reads it back – so a freshly formatted "random" card boots straight into a working render with no host-side image prep. Provisioning is opt-in: pass provision_blob == NULL to keep the load strictly read-only (the historical ereader_ui behaviour).

The helper is transport-thin: it owns the ra8_sdmmc_spi <-> ra8_sci_spi chip-select / clock / transfer shim internally, so callers only describe the bus (channel + four pins + PCLKA rate) instead of re-implementing those three callbacks in every app.

Example:

const ra8_sdfont_cfg_t cfg = {
  .spi_channel    = 0U,                                   // Pmod2 = SCI0
  .sck            = (ra8_port_pin_t)k_ra8_board_pmod2_spi_sck,
  .cipo           = (ra8_port_pin_t)k_ra8_board_pmod2_spi_cipo,
  .copi           = (ra8_port_pin_t)k_ra8_board_pmod2_spi_copi,
  .cs             = (ra8_port_pin_t)k_ra8_board_pmod2_spi_cs,
  .pclka_hz       = pclka_hz,
  .filename       = "FONT.OTF",
  .provision_blob = g_ra8_font_literata_latin1,            // baked fallback
  .provision_len  = g_ra8_font_literata_latin1_len,
};
uint32_t           len = 0U;
ra8_sdfont_source_t src = k_ra8_sdfont_source_card;
if (ra8_sdfont_load(&cfg, font_buf, sizeof(font_buf), &len, &src) == k_ra8_ok) {
  ra8_reflow_init(w, h, font_buf, len, px, ink, link, &engine);
}

Copyright

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

Since

0.1.0

Definition in file ra8_sdfont.h.

Enumeration Type Documentation

ra8_sdfont_source_t

enum ra8_sdfont_source_t : uint8_t

Provenance of the font bytes returned by ra8_sdfont_load.

Lets the caller distinguish a card that already carried the font from one that was empty and got provisioned on this boot – useful for diagnostics, HIL banners, and deciding whether to surface a "first run" message.

See also

ra8_sdfont_load

Since

0.1.0

Enumerator
k_ra8_sdfont_source_card	File already on the card; read as-is.
k_ra8_sdfont_source_provisioned	File was absent; written from the blob, then read back from the card.

Definition at line 70 of file ra8_sdfont.h.

Function Documentation

ra8_sdfont_load()

ra8_err_t ra8_sdfont_load ( const ra8_sdfont_cfg_t * cfg, uint8_t * buf, uint32_t cap, uint32_t * out_len, ra8_sdfont_source_t * out_source )

nodiscard

Mount the Pmod SD card and load a font, provisioning it if absent.

Routes the configured SPI pins to SCI Simple-SPI, claims chip-select as a GPIO output, brings up the card through ra8_sdmmc_spi, mounts the FAT volume through ra8_fs, and opens ra8_sdfont_cfg_t::filename for reading. If the file is absent and ra8_sdfont_cfg_t::provision_blob is non-NULL, the blob is written to the card with ra8_fs_write_file, then re-opened and read back – so the returned bytes are always the on-card copy, byte-for-byte identical to what a later boot will read. The font is copied into buf and the FAT volume is unmounted before return.

Parameters

[in]	cfg	Non-NULL bus + provisioning descriptor.
[out]	buf	Non-NULL destination buffer for the font bytes.
[in]	cap	Capacity of buf in bytes; must be > 0.
[out]	out_len	Non-NULL; receives the number of bytes loaded.
[out]	out_source	Optional (may be NULL); receives whether the font came from the card or was provisioned this boot.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Font loaded; *out_len holds its length.
k_ra8_err_null_ptr	cfg, buf, or out_len is NULL.
k_ra8_err_invalid_arg	cap is 0.
k_ra8_err_not_found	File absent and provisioning disabled (NULL blob).
k_ra8_err_no_data	File present but shorter than a usable font header.
other	Propagated from ra8_sci_spi, ra8_sdmmc_spi, or ra8_fs (no card, mount failure, write failure...).

Precondition

ra8_cgc_init has run and ra8_sdfont_cfg_t::pclka_hz is the live PCLKA rate.

buf points to at least cap writable bytes (SDRAM-backed for big fonts).

Postcondition

On success *out_len is in [16, cap] and buf holds the font.

On any return the FAT volume opened here is unmounted.

Note

Not thread-safe and not ISR-safe: blocking, polled SPI; single-shot module state backs the transport shim. Call once from init context.

See also

ra8_sdfont_source_t

Since

0.1.0

Definition at line 392 of file ra8_sdfont.c.

References ra8_sdfont_cfg_t::filename, internal_bringup_spi(), internal_mount(), internal_open_or_provision(), internal_read_font(), internal_validate(), k_ra8_ok, k_ra8_sdfont_source_card, ra8_fs_unmount(), and s_default_name.

Referenced by er_try_load_font(), and sfr_load_font_or_halt().