main.c

Go to the documentation of this file.

 
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "jof.h"
#include "jof_produce.h"
#include "mg_page_fixture.h"
#include "mg_reader.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_board_ek_ra8d2_touch.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_display_pal.h"
#include "ra8_display_pal_lcd.h"
#include "ra8_err.h"
#include "ra8_gfx.h"
#include "ra8_isr.h"
#include "ra8_mstp.h"
#include "ra8_panel.h"
#include "ra8_panel_timing.h"
#include "ra8_sdramc.h"
#include "ra8_tile_cache.h"
#include "ra8_time.h"
#include "ra8_touch.h"

typedef enum : uint32_t {
  k_mg_uart_baud        = 115200U, 
  k_mg_settle_ms        = 500U,    
  k_mg_frame_ms         = 25U,     
  k_mg_led_every        = 16U,     
  k_mg_touch_max_points = 1U,      
} mg_boot_t;

typedef enum : uint32_t {
  k_mg_tile_edge  = 256U,        
  k_mg_cap_edge   = 2048U,       
  k_mg_cell_bytes = 256U * 256U, 
  /* ::k_mg_view_cols / ::k_mg_view_rows are the tile columns/rows one 1:1
   * viewport frame can straddle: ceil(extent / tile) tiles, plus one for the
   * viewport not being tile-aligned. The content area is the panel minus the
   * status bar (the render clips there). See the derivation note below. */
  k_mg_view_cols =
    (((uint32_t)k_panel_width_px + k_mg_tile_edge - 1U) / k_mg_tile_edge) + 1U, 
  k_mg_view_rows =
    ((((uint32_t)k_panel_height_px - (uint32_t)k_mg_statusbar_h) + k_mg_tile_edge - 1U) /
     k_mg_tile_edge) +
    1U,                                                         
  k_mg_cells   = (k_mg_view_cols + 1U) * (k_mg_view_rows + 1U), 
  k_mg_buckets = 64U,                                           
  k_mg_cell_budget_bytes = 4U * 1024U * 1024U,                  
  k_mg_scratch           = 96U * 1024U,                         
  k_mg_work_bytes        = 3203832U,                            
  k_mg_store_bytes       = 4U * 1024U * 1024U,                  
  k_mg_image_id          = 1U,                                  
  k_mg_hex_nibbles       = 8U,                                  
  k_mg_nibble_bits       = 4U,                                  
  k_mg_nibble_mask       = 0x0FU,                               
  k_mg_dec_ten           = 10U,                                 
} mg_atlas_t;
 
/*
 * ::k_mg_cells is DERIVED from the panel + tile geometry, never hand-picked
 * (#338). The reader pages the atlas one tile at a time (get / blit / put), so
 * the cache does not need every on-screen tile pinned at once -- but it must
 * still be able to *hold* the tiles a frame touches, or a one-tile pan evicts
 * tiles that are still on screen and re-inflates them next frame. That is the
 * thrash: with a sub-frame budget every pan re-decodes ~a full screen of
 * 64 KiB DEFLATE tiles.
 *
 * At 1:1 a 1024x600 panel with a 48 px status bar shows a 1024x552 content
 * window over 256x256 tiles, straddling at most ::k_mg_view_cols x
 * ::k_mg_view_rows = 5 x 4 = 20 tiles. Sizing the cache to that frame plus one
 * tile of margin on each axis (::k_mg_cells = 6 x 5 = 30, ~1.9 MiB of the
 * 64 MB SDRAM) means the union of any single-step pan's before/after frames
 * stays resident, so a pan re-decodes only the newly exposed row/column, never
 * a tile still on screen. `apps/board/stand_alone/ereader/tests/src/test_app_ereader_manga.c`
 * (test_manga_pan_no_thrash) measures the eviction/decode count for a
 * representative pan against the old 4-cell budget and asserts it collapses.
 *
 * Two compile-time tripwires keep the budget honest:
 *   - the first static_assert fails the build if ::k_mg_cells is ever set below
 *     the frame demand (a manual override, or a geometry change that outgrows
 *     it), the condition that reintroduces the thrash;
 *   - the second bounds the resident-tile arena by ::k_mg_cell_budget_bytes so
 *     the derivation cannot silently balloon the SDRAM working set.
 * The 4-cell budget lives on only as the explicit eviction-stress case in the
 * host test, which is what it was always right for.
 */
static_assert((uint64_t)k_mg_cells >= (uint64_t)k_mg_view_cols * (uint64_t)k_mg_view_rows,
              "tile cache is smaller than the 1:1 viewport tile demand: re-derive k_mg_cells from "
              "the panel + tile geometry so a single-step pan cannot thrash (#338)");
static_assert((uint64_t)k_mg_cells * (uint64_t)k_mg_cell_bytes <= (uint64_t)k_mg_cell_budget_bytes,
              "resident tile arena exceeds its SDRAM budget: the tile-cache derivation grew past "
              "k_mg_cell_budget_bytes");
 
/*
 * ::k_mg_work_bytes is DERIVED, never hand-picked: it is exactly
 * `jof_work_bytes(k_mg_cap_edge, k_mg_cap_edge, k_mg_tile_edge,
 * k_mg_tile_edge)` -- the producer's own worst-case arena requirement for the
 * cap this app advertises, taken at the format's maximum 4 bpp. A round number
 * here is how the advertised cap and the real capability drift apart: a 2 MiB
 * arena backs a cap of only 1016 px, so the app used to advertise 2048 and
 * fail-closed (`k_ra8_err_invalid_size`) on any in-budget source wider than
 * that. Three layers keep the two in agreement:
 *   - the static_assert below is a compile-time tripwire on the band term
 *     (`cap * tile_h * bpp_max`), a strict lower bound on the full
 *     requirement, so raising ::k_mg_cap_edge without re-deriving the arena
 *     fails the build;
 *   - `apps/board/stand_alone/ereader/tests/src/test_app_ereader_manga.c` asserts the arena
 *     against the real
 *     `jof_work_bytes()` return, which is the exact and
 *     authoritative check, and runs in CI;
 *   - `mg_build_atlas()` re-checks the same call at boot, so a mismatch that
 *     somehow reaches silicon reports `FAIL atlas` instead of silently
 *     under-delivering the advertised cap.
 * The band term alone is a lower bound, not the whole requirement, so the
 * static_assert can only catch an under-sized arena, never certify a
 * sufficient one -- that is the test's and the boot check's job.
 */
static_assert((uint64_t)k_mg_work_bytes >=
                ((uint64_t)k_mg_cap_edge * (uint64_t)k_mg_tile_edge * (uint64_t)k_jof_bpp_max),
              "work arena is below the producer band term for the advertised cap: re-derive "
              "k_mg_work_bytes from jof_work_bytes() for k_mg_cap_edge");

typedef enum : uint16_t {
  k_mg_fb_w = k_panel_width_px,  
  k_mg_fb_h = k_panel_height_px, 
} mg_fb_t;

RA8_BOARD_PANEL_FRAMEBUFFER(s_framebuffer);

[[gnu::section(".sdram_data")]] static uint8_t s_work[k_mg_work_bytes];
[[gnu::section(".sdram_data")]] static uint8_t s_store_buf[k_mg_store_bytes];
[[gnu::section(
  ".sdram_data")]] static uint8_t s_cell_mem[(size_t)k_mg_cells * (size_t)k_mg_cell_bytes];
[[gnu::section(".sdram_data")]] static uint8_t s_scratch[k_mg_scratch];

static const display_cfg_t k_mg_display_cfg = {
  .iface             = &k_display_backend_lcd_ra8_glcdc,
  .framebuffer       = s_framebuffer,
  .framebuffer_bytes = sizeof(s_framebuffer),
  .width_px          = (uint16_t)k_mg_fb_w,
  .height_px         = (uint16_t)k_mg_fb_h,
  .pixfmt            = k_display_pixfmt_rgb565,
  .panel_timing      = &s_ra8_panel_ek_ra8d2_timing,
};

static display_handle_t* s_display = nullptr;
static display_fb_t s_fb;

static jof_memstore_t s_store;
static jof_info_t s_info;
static ra8_tile_cache_t s_cache;
static mg_tile_src_t s_tile_src;
static mg_reader_t s_reader;

static ra8_tile_key_t s_keys[k_mg_cells];
static ra8_tile_dims_t s_dims[k_mg_cells];
static ra8_keycache_cell_t s_meta[k_mg_cells];
static int32_t s_buckets[k_mg_buckets];

typedef struct {
  const uint8_t* data; 
  uint32_t       len;  
  uint32_t       pos;  
} mg_png_cursor_t;

static mg_png_cursor_t s_png_cursor;

/* Console banner fragments. */
static const uint8_t k_msg_boot[]  = "ereader-manga: boot\r\n";
static const uint8_t k_msg_fail[]  = "ereader-manga: FAIL init\r\n";
static const uint8_t k_msg_atl[]   = "ereader-manga: FAIL atlas\r\n";
static const uint8_t k_msg_rend[]  = "ereader-manga: FAIL render\r\n";
static const uint8_t k_msg_pre[]   = "ereader-manga: page ";
static const uint8_t k_msg_x[]     = "x";
static const uint8_t k_msg_tiles[] = " tiles=";
static const uint8_t k_msg_atlas[] = " atlas=";
static const uint8_t k_msg_view[]  = " view=0,0 zoom=1:1 crc=";
static const uint8_t k_msg_ok[]    = " ok\r\n";

static void mg_print(const uint8_t* msg, uint32_t len)
{
  (void)ra8_board_uart_console_write(msg, (size_t)len);
}

static void mg_panic_halt(const uint8_t* msg, uint32_t len)
{
  mg_print(msg, len);
  (void)ra8_board_led_on(k_ra8_board_led_red);
  __asm__ volatile("bkpt #0");
  while (1) {
    __asm__ volatile("wfi");
  }
}

static void mg_print_hex(uint32_t value)
{
  uint8_t buf[k_mg_hex_nibbles];
  for (uint32_t i = 0U; i < (uint32_t)k_mg_hex_nibbles; ++i) {
    const uint32_t shift = ((uint32_t)k_mg_hex_nibbles - 1U - i) * (uint32_t)k_mg_nibble_bits;
    const uint32_t nib   = (value >> shift) & (uint32_t)k_mg_nibble_mask;
    buf[i] = (uint8_t)((nib < (uint32_t)k_mg_dec_ten) ? ('0' + nib) : ('A' + (nib - k_mg_dec_ten)));
  }
  mg_print(buf, (uint32_t)k_mg_hex_nibbles);
}

static void mg_print_uint(uint32_t value)
{
  uint8_t  buf[k_mg_dec_ten];
  uint32_t n = 0U;
  if (value == 0U) {
    buf[n] = '0';
    n++;
  }
  while ((value > 0U) && (n < (uint32_t)k_mg_dec_ten)) {
    buf[n] = (uint8_t)('0' + (value % (uint32_t)k_mg_dec_ten));
    n++;
    value /= (uint32_t)k_mg_dec_ten;
  }
  for (uint32_t i = 0U; i < n; ++i) {
    mg_print(&buf[n - 1U - i], 1U);
  }
}
 
/* ===========================================================================
 * Boot helpers
 * =========================================================================== */

static void mg_bringup_clocks(void)
{
  uint32_t cpuclk0_hz = 0U;
  if ((ra8_cgc_init() != k_ra8_ok) || (ra8_mstp_init() != k_ra8_ok)) {
    mg_panic_halt(k_msg_fail, (uint32_t)sizeof(k_msg_fail) - 1U);
  }
  if (ra8_cgc_get_clock_hz(k_ra8_clock_id_cpuclk0, &cpuclk0_hz) != k_ra8_ok) {
    mg_panic_halt(k_msg_fail, (uint32_t)sizeof(k_msg_fail) - 1U);
  }
  if (ra8_time_init(cpuclk0_hz) != k_ra8_ok) {
    mg_panic_halt(k_msg_fail, (uint32_t)sizeof(k_msg_fail) - 1U);
  }
  if ((ra8_board_led_init(k_ra8_board_led_blue) != k_ra8_ok) ||
      (ra8_board_led_init(k_ra8_board_led_red) != k_ra8_ok)) {
    mg_panic_halt(k_msg_fail, (uint32_t)sizeof(k_msg_fail) - 1U);
  }
  if (ra8_board_uart_console_init((uint32_t)k_mg_uart_baud) != k_ra8_ok) {
    mg_panic_halt(k_msg_fail, (uint32_t)sizeof(k_msg_fail) - 1U);
  }
  ra8_isr_globals_enable();
}

static void mg_bringup_panel(void)
{
  ra8_delay_ms((uint32_t)k_mg_settle_ms);
  if (ra8_sdramc_init() != k_ra8_ok) {
    mg_panic_halt(k_msg_fail, (uint32_t)sizeof(k_msg_fail) - 1U);
  }
  if (display_init(&k_mg_display_cfg, &s_display) != k_ra8_ok) {
    mg_panic_halt(k_msg_fail, (uint32_t)sizeof(k_msg_fail) - 1U);
  }
  if (display_get_framebuffer(s_display, &s_fb) != k_ra8_ok) {
    mg_panic_halt(k_msg_fail, (uint32_t)sizeof(k_msg_fail) - 1U);
  }
  if (ra8_gfx_init(s_fb.pixels, s_fb.width_px, s_fb.height_px, k_ra8_gfx_format_rgb565) !=
      k_ra8_ok) {
    mg_panic_halt(k_msg_fail, (uint32_t)sizeof(k_msg_fail) - 1U);
  }
}

static void mg_bringup_touch(void)
{
  const ra8_board_touch_cfg_t cfg = {.max_points = (uint8_t)k_mg_touch_max_points,
                                     .irq_pin    = (uint8_t)k_ra8_touch_irq_pin_unset};
  (void)ra8_board_touch_open(&cfg);
}
 
/* ===========================================================================
 * Atlas produce + cache + reader setup
 * =========================================================================== */

static ra8_err_t mg_png_pull(void* ctx, uint8_t* buf, size_t cap, size_t* got)
{
  mg_png_cursor_t* c     = (mg_png_cursor_t*)ctx;
  const uint32_t   avail = c->len - c->pos;
  size_t           take  = ((uint32_t)cap < avail) ? cap : (size_t)avail;
  (void)memcpy(buf, &c->data[c->pos], take);
  c->pos += (uint32_t)take;
  *got = take;
  return k_ra8_ok;
}

static bool mg_build_atlas(void)
{
  /* The advertised cap must be one this arena can actually serve. The producer
   * carves from the *decoded* geometry, so an under-sized arena would not show
   * up until some in-budget source happened to be wide enough or deep enough in
   * bpp to exhaust it; asking the producer for its own requirement up front
   * turns that latent capability lie into a deterministic boot failure. */
  const uint32_t need = jof_work_bytes((uint16_t)k_mg_cap_edge,
                                       (uint16_t)k_mg_cap_edge,
                                       (uint16_t)k_mg_tile_edge,
                                       (uint16_t)k_mg_tile_edge);
  if ((need == 0U) || (need > (uint32_t)sizeof(s_work))) {
    return false;
  }
  s_png_cursor = (mg_png_cursor_t){.data = k_mg_png, .len = k_mg_png_len, .pos = 0U};
  s_store      = (jof_memstore_t){.buf = s_store_buf, .cap = sizeof(s_store_buf), .len = 0U};
  const jof_produce_cfg_t cfg = {
    .pull     = mg_png_pull,
    .pull_ctx = &s_png_cursor,
    .sink     = jof_memstore_sink,
    .sink_ctx = &s_store,
    .tile_w   = (uint16_t)k_mg_tile_edge,
    .tile_h   = (uint16_t)k_mg_tile_edge,
    /* Deflate tiles (codec 1): each tile is an intra-coded raw-DEFLATE stream,
     * so the 3 MiB page normalizes to a ~20 KiB atlas and every cache miss does
     * real decode-on-demand work (one bounded inflate into the pinned cell) --
     * the streaming-larger-than-RAM property the tile cache exists for. On the
     * 1 GHz M85 a 64 KiB-tile inflate is microseconds; the cost only shows under
     * the ra8_emulator CPU emulator, where boot still completes well inside budget. */
    .codec      = (uint8_t)k_jof_codec_deflate,
    .max_width  = (uint16_t)k_mg_cap_edge,
    .max_height = (uint16_t)k_mg_cap_edge,
    .work       = s_work,
    .work_cap   = sizeof(s_work),
    .webp_work  = nullptr,
  };
  if (jof_produce(&cfg, &s_info) != k_ra8_ok) {
    return false;
  }
  return jof_parse(jof_memstore_pread, &s_store, s_store.len, &s_info) == k_ra8_ok;
}

static bool mg_setup_cache(void)
{
  s_tile_src = (mg_tile_src_t){.info        = &s_info,
                               .pread       = jof_memstore_pread,
                               .pread_ctx   = &s_store,
                               .scratch     = s_scratch,
                               .scratch_cap = (uint32_t)sizeof(s_scratch)};
  const ra8_tile_cache_cfg_t cache_cfg = {.cell_mem     = s_cell_mem,
                                          .cell_bytes   = (uint32_t)k_mg_cell_bytes,
                                          .cell_count   = (uint32_t)k_mg_cells,
                                          .meta         = s_meta,
                                          .keys         = s_keys,
                                          .dims         = s_dims,
                                          .buckets      = s_buckets,
                                          .bucket_count = (uint32_t)k_mg_buckets,
                                          .decode       = mg_tile_decode,
                                          .decode_ctx   = &s_tile_src};
  return ra8_tile_cache_init(&s_cache, &cache_cfg) == k_ra8_ok;
}

static void mg_present(void)
{
  (void)display_flush(s_display, display_full_rect(s_display), k_display_refresh_quality);
}

static void mg_print_banner(void)
{
  mg_print(k_msg_pre, (uint32_t)sizeof(k_msg_pre) - 1U);
  mg_print_uint((uint32_t)s_info.width);
  mg_print(k_msg_x, (uint32_t)sizeof(k_msg_x) - 1U);
  mg_print_uint((uint32_t)s_info.height);
  mg_print(k_msg_tiles, (uint32_t)sizeof(k_msg_tiles) - 1U);
  mg_print_uint(s_info.tile_count);
  mg_print(k_msg_atlas, (uint32_t)sizeof(k_msg_atlas) - 1U);
  mg_print_uint(s_info.total_size);
  mg_print(k_msg_view, (uint32_t)sizeof(k_msg_view) - 1U);
  mg_print_hex(mg_fnv1a(s_framebuffer, (uint32_t)sizeof(s_framebuffer)));
  mg_print(k_msg_ok, (uint32_t)sizeof(k_msg_ok) - 1U);
}

static void mg_poll_touch(bool* was_touching)
{
  ra8_touch_point_t pt  = {};
  uint8_t           got = 0U;
  if (ra8_touch_read(&pt, 1U, &got) != k_ra8_ok) {
    return;
  }
  const bool touching = (got > 0U);
  if (touching && !(*was_touching)) {
    if (mg_reader_tap(&s_reader, (int32_t)pt.x, (int32_t)pt.y)) {
      if (mg_reader_render(&s_reader) == k_ra8_ok) {
        mg_present();
        /* Idle-window read-ahead: warm the next pan step's tiles so a follow-on
         * pan finds them resident instead of stalling on a cold decode (#341). */
        (void)mg_reader_prefetch(&s_reader);
      }
    }
  }
  *was_touching = touching;
}

void main(void)
{
  mg_bringup_clocks();
  mg_print(k_msg_boot, (uint32_t)sizeof(k_msg_boot) - 1U);
  mg_bringup_panel();
  mg_bringup_touch();
 
  if (!mg_build_atlas()) {
    mg_panic_halt(k_msg_atl, (uint32_t)sizeof(k_msg_atl) - 1U);
  }
  if (!mg_setup_cache()) {
    mg_panic_halt(k_msg_atl, (uint32_t)sizeof(k_msg_atl) - 1U);
  }
  const mg_reader_cfg_t rcfg = {.fb       = s_framebuffer,
                                .fb_w     = (int32_t)k_mg_fb_w,
                                .fb_h     = (int32_t)k_mg_fb_h,
                                .cache    = &s_cache,
                                .info     = &s_info,
                                .image_id = (uint32_t)k_mg_image_id};
  if (mg_reader_init(&s_reader, &rcfg) != k_ra8_ok) {
    mg_panic_halt(k_msg_atl, (uint32_t)sizeof(k_msg_atl) - 1U);
  }
  if (mg_reader_render(&s_reader) != k_ra8_ok) {
    mg_panic_halt(k_msg_rend, (uint32_t)sizeof(k_msg_rend) - 1U);
  }
  mg_present();
  mg_print_banner();
 
  bool     was_touching = false;
  uint32_t ticks        = 0U;
  while (1) {
    mg_poll_touch(&was_touching);
    if ((ticks % (uint32_t)k_mg_led_every) == 0U) {
      (void)ra8_board_led_toggle(k_ra8_board_led_blue);
    }
    ticks++;
    ra8_delay_ms((uint32_t)k_mg_frame_ms);
  }
}