rabook_import_compiler.c

Go to the documentation of this file.

 
#include "rabook_import_compiler.h"
 
#include <stddef.h>
#include <stdint.h>
 
#include "book.h"
#include "epub.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_rabook_pipeline.h"
#include "ra8_vmem.h"
#include "ra8_vmem_stream.h"
#include "ra8_vsource.h"

static const char* const s_tag = "rabook_import_compiler";

typedef struct {
  ra8_fs_file_t*    file; 
  ra8_vsource_obj_t obj;  
  ra8_vsource_t     vsrc; 
  ra8_vmem_stream_t st;   
} import_stream_t;

RA8_INTERNAL static ra8_err_t
internal_source_read(void* ctx, uint64_t offset, uint8_t* buf, uint32_t len)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "source_read: ctx");
  RA8_CHECK_NULL_PTR(buf, s_tag, "source_read: buf");
  if (offset > (uint64_t)UINT32_MAX) {
    return k_ra8_err_out_of_range; /* GCOVR_EXCL_LINE -- ra8_fs_size is 32-bit, so offsets fit */
  }
  ra8_fs_file_t* file = (ra8_fs_file_t*)ctx;
  ra8_err_t      err  = ra8_fs_seek(file, (uint32_t)offset);
  if (err != k_ra8_ok) {
    return err; /* GCOVR_EXCL_LINE -- seek clamps to size and cannot fail on a live handle */
  }
  uint32_t got = 0U;
  err          = ra8_fs_read(file, buf, len, &got);
  if (err != k_ra8_ok) {
    return err; /* corrupt FAT chain / backend fault mid-stream */
  }
  if (got != len) {
    return k_ra8_err_hw_error; /* GCOVR_EXCL_LINE -- ra8_vsource_loader clamps len to o->size */
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t
internal_cache_bind(const rabook_import_compiler_ctx_t* ctx, import_stream_t* ss, uint32_t size)
{
  RA8_CHECK_NULL_PTR(ctx->cache, s_tag, "cache");
  RA8_CHECK_NULL_PTR(ss->file, s_tag, "file");
  ra8_err_t err = ra8_vsource_init(&ss->vsrc, &ss->obj, 1U);
  if (err != k_ra8_ok) {
    return err; /* GCOVR_EXCL_LINE -- registry storage is the frame's own struct, never NULL/zero */
  }
  uint32_t oid = 0U;
  err = ra8_vsource_add_paged(&ss->vsrc, internal_source_read, ss->file, 0U, (uint64_t)size, &oid);
  if (err != k_ra8_ok) {
    return err;
  }
  const ra8_vmem_cfg_t cfg = {
    .frame_mem    = ctx->cache_frames,
    .frame_bytes  = ctx->cache_frame_bytes,
    .frame_count  = ctx->cache_frame_count,
    .meta         = ctx->cache_meta,
    .keys         = ctx->cache_keys,
    .buckets      = ctx->cache_buckets,
    .bucket_count = ctx->cache_bucket_count,
    .loader       = ra8_vsource_loader,
    .loader_ctx   = &ss->vsrc,
  };
  *ctx->cache = (ra8_vmem_t){};
  err         = ra8_vmem_init(ctx->cache, &cfg);
  if (err != k_ra8_ok) {
    return err; /* a NULL / zero-sized cookie cache dimension */
  }
  return ra8_vmem_stream_init(&ss->st, ctx->cache, oid, (uint64_t)size);
}

RA8_INTERNAL static ra8_err_t internal_stream_open(const rabook_import_compiler_ctx_t* ctx,
                                                   ra8_fs_mount_t*                     mount,
                                                   const char*                         epub_path,
                                                   import_stream_t*                    ss)
{
  RA8_CHECK_NULL_PTR(ctx->epub, s_tag, "epub");
  RA8_CHECK_NULL_PTR(ss, s_tag, "stream state");
  ra8_err_t err = ra8_fs_open(mount, epub_path, k_ra8_fs_mode_read, &ss->file);
  if (err != k_ra8_ok) {
    return err;
  }
  /* ra8_fs_size cannot fail on the handle ra8_fs_open just returned (in_use
   * set, both out-params non-NULL); on any future contract change `size`
   * stays 0 and internal_cache_bind rejects it as invalid_size. */
  uint64_t size64 = 0U;
  (void)ra8_fs_size(ss->file, &size64);
  /* Import sources are sized in 32 bits; an over-4-GiB source is clamped to
   * the reject path (0 -> invalid_size in the bind below). */
  const uint32_t size = (size64 <= (uint64_t)UINT32_MAX) ? (uint32_t)size64 : 0U;
  err                 = internal_cache_bind(ctx, ss, size);
  if (err == k_ra8_ok) {
    const epub_stream_media_t media = {
      .read = ra8_vmem_stream_read,
      .ctx  = &ss->st,
      .size = (uint64_t)size,
    };
    err = epub_open_streamed(&media, epub_path, ctx->epub);
  }
  if (err != k_ra8_ok) {
    (void)ra8_fs_close(ss->file);
    ss->file = nullptr;
  }
  return err;
}
 
ra8_err_t rabook_import_compile_adapter(void*           compile_ctx,
                                        ra8_fs_mount_t* mount,
                                        const char*     epub_path,
                                        const char*     out_path)
{
  RA8_CHECK_NULL_PTR(compile_ctx, s_tag, "compile_ctx");
  RA8_CHECK_NULL_PTR(mount, s_tag, "mount");
  RA8_CHECK_NULL_PTR(epub_path, s_tag, "epub_path");
  RA8_CHECK_NULL_PTR(out_path, s_tag, "out_path");
 
  /* The cookie's epub/cache fields are validated by the stream-open helpers and
   * the bufs/scr by `rabook_compile_from_epub`, so a NULL cookie field still
   * yields k_ra8_err_null_ptr without restating those guards here. */
  const rabook_import_compiler_ctx_t* ctx = (const rabook_import_compiler_ctx_t*)compile_ctx;
 
  /* The book streams through `ss` for the whole compile, so it lives in this
   * frame, spanning open -> compile -> close. */
  import_stream_t ss  = {};
  ra8_err_t       err = internal_stream_open(ctx, mount, epub_path, &ss);
  if (err != k_ra8_ok) {
    return err;
  }
 
  err            = rabook_compile_from_epub(ctx->epub, ctx->bufs, ctx->scr, mount, out_path);
  ra8_err_t cerr = epub_close(ctx->epub);
  (void)ra8_fs_close(ss.file); /* always release the source handle */
  if (err != k_ra8_ok) {
    return err;
  }
  return cerr;
}

RA8_INTERNAL static ra8_err_t internal_read_whole_file(ra8_fs_mount_t* mount,
                                                       const char*     path,
                                                       uint8_t*        buf,
                                                       uint32_t        cap,
                                                       uint32_t*       out_len)
{
  ra8_fs_file_t* file = nullptr;
  ra8_err_t      err  = ra8_fs_open(mount, path, k_ra8_fs_mode_read, &file);
  if (err != k_ra8_ok) {
    return err;
  }
  /* ra8_fs_size cannot fail on a just-opened handle; a lying 0 simply reads 0
   * bytes below and the dispatch rejects the empty source. */
  uint64_t size64 = 0U;
  (void)ra8_fs_size(file, &size64);
  const uint32_t size = (size64 <= (uint64_t)UINT32_MAX) ? (uint32_t)size64 : UINT32_MAX;
  if (size > cap) {
    /* Transport overflow: the source cannot fit the cross-core buffer. Report
     * no_mem (an offload-failure class) so the streamed in-core fallback --
     * which has no size ceiling (#230) -- can still import the book. */
    (void)ra8_fs_close(file);
    return k_ra8_err_no_mem;
  }
  err            = ra8_fs_read(file, buf, cap, out_len);
  ra8_err_t cerr = ra8_fs_close(file);
  if (err != k_ra8_ok) {
    return err;
  }
  return cerr;
}

RA8_INTERNAL static ra8_err_t
internal_dispatch_and_cache(const rabook_import_compiler_m33_ctx_t* ctx,
                            uint32_t                                epub_len,
                            ra8_fs_mount_t*                         mount,
                            const char*                             out_path)
{
  uint32_t  blob_len = 0U;
  ra8_err_t err      = ctx->dispatch(ctx->dispatch_ctx,
                                     ctx->epub_load_buf,
                                     epub_len,
                                     ctx->blob_buf,
                                     ctx->blob_cap,
                                     &blob_len);
  if (err != k_ra8_ok) {
    return err;
  }
  /* Validate the worker-produced blob before caching -- a cross-core transfer
   * slip or a worker fault could yield a structurally-broken blob. */
  err = book_validate(ctx->blob_buf, (size_t)blob_len);
  if (err != k_ra8_ok) {
    return err;
  }
  return ra8_fs_write_file(mount, out_path, ctx->blob_buf, blob_len);
}

RA8_INTERNAL static bool internal_is_dispatch_failure(ra8_err_t err)
{
  return (err == k_ra8_err_hw_error) || (err == k_ra8_err_no_mem);
}

RA8_INTERNAL static ra8_err_t
internal_fallback_or_propagate(const rabook_import_compiler_m33_ctx_t* ctx,
                               ra8_err_t                               err,
                               ra8_fs_mount_t*                         mount,
                               const char*                             epub_path,
                               const char*                             out_path)
{
  if (!internal_is_dispatch_failure(err)) {
    return err;
  }
  if (ctx->fallback == nullptr) {
    return err;
  }
  ra8_log_warn(s_tag, "M33 offload failed; compiling in-core instead");
  return rabook_import_compile_adapter(ctx->fallback, mount, epub_path, out_path);
}

RA8_INTERNAL static ra8_err_t
internal_offload_or_fallback(const rabook_import_compiler_m33_ctx_t* ctx,
                             uint32_t                                epub_len,
                             ra8_fs_mount_t*                         mount,
                             const char*                             epub_path,
                             const char*                             out_path)
{
  ra8_err_t err = internal_dispatch_and_cache(ctx, epub_len, mount, out_path);
  if (err == k_ra8_ok) {
    return k_ra8_ok;
  }
  return internal_fallback_or_propagate(ctx, err, mount, epub_path, out_path);
}
 
ra8_err_t rabook_import_compile_adapter_m33(void*           compile_ctx,
                                            ra8_fs_mount_t* mount,
                                            const char*     epub_path,
                                            const char*     out_path)
{
  RA8_CHECK_NULL_PTR(compile_ctx, s_tag, "compile_ctx");
  RA8_CHECK_NULL_PTR(mount, s_tag, "mount");
  RA8_CHECK_NULL_PTR(epub_path, s_tag, "epub_path");
  RA8_CHECK_NULL_PTR(out_path, s_tag, "out_path");
 
  rabook_import_compiler_m33_ctx_t* ctx = (rabook_import_compiler_m33_ctx_t*)compile_ctx;
  RA8_CHECK_NULL_PTR(ctx->dispatch, s_tag, "dispatch");
 
  /* ctx->epub_load_buf / ctx->blob_buf are caller-owned per the cookie invariant
   * and reached through ra8_fs_read / the dispatch, so a NULL there is a caller
   * bug -- matching how the in-core adapter leans on its downstream guards. */
 
  /* Read the source .epub off the mount (the M85 owns the FS), then offload. A
   * read-stage transport overflow (source larger than the load buffer, #230)
   * is an offload failure like any other: the streamed in-core fallback still
   * imports the book. */
  uint32_t  epub_len = 0U;
  ra8_err_t err =
    internal_read_whole_file(mount, epub_path, ctx->epub_load_buf, ctx->epub_load_cap, &epub_len);
  if (err != k_ra8_ok) {
    return internal_fallback_or_propagate(ctx, err, mount, epub_path, out_path);
  }
  return internal_offload_or_fallback(ctx, epub_len, mount, epub_path, out_path);
}