book_paged.c

Go to the documentation of this file.

#include "book_paged.h"
 
#include <string.h>
 
#include "book.h"
#include "book_internal.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_vmem.h"

static const char* const s_tag_paged = "book_paged";

typedef enum : uint32_t {
  k_book_paged_span_pad  = 2U, 
  k_book_paged_min_frame = 2U, 
} book_paged_bound_t;
 
ra8_err_t book_src_resident(book_src_t* out, const void* base, uint32_t size)
{
  RA8_CHECK_NULL_PTR(out, s_tag_paged, "resident: null out");
  RA8_CHECK_NULL_PTR(base, s_tag_paged, "resident: null base");
  if (size == 0U) {
    return k_ra8_err_invalid_size;
  }
  out->base        = (const uint8_t*)base;
  out->vm          = nullptr;
  out->object_id   = 0U;
  out->frame_bytes = 0U;
  out->size        = size;
  (void)memcpy(&out->hdr, base, sizeof(book_header_t));
  return k_ra8_ok;
}
 
ra8_err_t book_src_paged(book_src_t* out,
                         ra8_vmem_t* vm,
                         uint32_t    object_id,
                         uint32_t    frame_bytes,
                         uint32_t    size)
{
  RA8_CHECK_NULL_PTR(out, s_tag_paged, "paged: null out");
  RA8_CHECK_NULL_PTR(vm, s_tag_paged, "paged: null vm");
  /* frame_bytes >= 2 keeps the copy-out loop bound (len/frame_bytes + 2)
   * provably non-overflowing for any uint32_t len. */
  if ((size == 0U) || (frame_bytes < (uint32_t)k_book_paged_min_frame)) {
    return k_ra8_err_invalid_size;
  }
  out->base        = nullptr;
  out->vm          = vm;
  out->object_id   = object_id;
  out->frame_bytes = frame_bytes;
  out->size        = size;
  /* Cache the header so its fields never fault during a walk. */
  return book_src_read(out, 0U, &out->hdr, (uint32_t)sizeof(book_header_t));
}

RA8_INTERNAL
static ra8_err_t
internal_book_src_read_paged(const book_src_t* src, uint32_t off, void* dst, uint32_t len)
{
  uint8_t*       d         = (uint8_t*)dst;
  uint32_t       cur       = off;
  uint32_t       remaining = len;
  const uint32_t max_iter  = (len / src->frame_bytes) + (uint32_t)k_book_paged_span_pad;
  for (uint32_t it = 0U; (it < max_iter) && (remaining > 0U); ++it) {
    void*           page = nullptr;
    const ra8_err_t ge   = ra8_vmem_get(src->vm, src->object_id, (uint64_t)cur, &page);
    if (ge != k_ra8_ok) {
      return ge;
    }
    const uint32_t in_frame = cur % src->frame_bytes;
    const uint32_t avail    = src->frame_bytes - in_frame;
    const uint32_t n        = (remaining < avail) ? remaining : avail;
    (void)memcpy(d, &((const uint8_t*)page)[in_frame], n);
    const ra8_err_t pe = ra8_vmem_put(src->vm, page);
    if (pe != k_ra8_ok) {
      return pe;
    }
    d = &d[n];
    cur += n;
    remaining -= n;
  }
  return (remaining == 0U) ? k_ra8_ok : k_ra8_err_out_of_range;
}
 
ra8_err_t book_src_read(const book_src_t* src, uint32_t off, void* dst, uint32_t len)
{
  RA8_CHECK_NULL_PTR(src, s_tag_paged, "read: null src");
  RA8_CHECK_NULL_PTR(dst, s_tag_paged, "read: null dst");
  if (((uint64_t)off + (uint64_t)len) > (uint64_t)src->size) {
    return k_ra8_err_out_of_range;
  }
  if (len == 0U) {
    return k_ra8_ok;
  }
  if (src->base != nullptr) {
    (void)memcpy(dst, &src->base[off], len);
    return k_ra8_ok;
  }
  if (src->vm == nullptr) {
    return k_ra8_err_invalid_state;
  }
  return internal_book_src_read_paged(src, off, dst, len);
}
 
/* ===========================================================================
 * Image sub-rect reads (#342): the image-pool addressing contract -- descriptor
 * stride, pool base, 4bpp nibble packing, and odd-width parity -- lives here in
 * the library that owns the format, not open-coded in every image renderer. The
 * loupe / tile / thumbnail consumers keep only their geometry and blit and call
 * book_src_image_rect() for "read me this rectangle" as unpacked gray8.
 * =========================================================================== */

typedef enum : uint32_t {
  k_book_gray4_nib_lo   = 0x0FU, 
  k_book_gray4_nib_sh   = 4U,    
  k_book_gray4_ppb      = 2U,    
  k_book_rect_chunk_px  = 512U,  
  k_book_rect_chunk_pad = 2U,    
} book_image_rect_const_t;

RA8_INTERNAL static ra8_err_t internal_book_image_row(const book_src_t*   src,
                                                      const book_image_t* img,
                                                      uint32_t            x,
                                                      uint32_t            ry,
                                                      uint32_t            w,
                                                      uint8_t*            out)
{
  const uint32_t row_flat = (ry * (uint32_t)img->width) + x;
  uint8_t        packed[(k_book_rect_chunk_px / k_book_gray4_ppb) + 1U];
  uint32_t       done     = 0U;
  const uint32_t max_iter = (w / (uint32_t)k_book_rect_chunk_px) + (uint32_t)k_book_rect_chunk_pad;
  for (uint32_t it = 0U; it < max_iter; ++it) {
    if (done >= w) {
      break; /* whole run unpacked; the count bound above is the loop invariant */
    }
    const uint32_t remain = w - done;
    const uint32_t cpx =
      (remain < (uint32_t)k_book_rect_chunk_px) ? remain : (uint32_t)k_book_rect_chunk_px;
    const uint32_t flat0 = row_flat + done;
    const uint32_t first = flat0 >> 1U;
    const uint32_t last  = (flat0 + cpx - 1U) >> 1U;
    const uint32_t n     = (last - first) + 1U;
    const uint64_t off =
      (uint64_t)src->hdr.image_pool_off + (uint64_t)img->data_off + (uint64_t)first;
    if ((off + (uint64_t)n) > (uint64_t)src->size) {
      return k_ra8_err_out_of_range; /* descriptor / geometry points past the blob */
    }
    const ra8_err_t re = book_src_read(src, (uint32_t)off, packed, n);
    if (re != k_ra8_ok) {
      return re;
    }
    for (uint32_t i = 0U; i < cpx; ++i) {
      const uint32_t flat = flat0 + i;
      const uint8_t  byte = packed[(flat >> 1U) - first];
      const uint8_t  nib  = ((flat & 1U) != 0U) ? (uint8_t)(byte & (uint8_t)k_book_gray4_nib_lo)
                                                : (uint8_t)(byte >> (uint8_t)k_book_gray4_nib_sh);
      out[done + i]       = (uint8_t)((nib << (uint8_t)k_book_gray4_nib_sh) | nib);
    }
    done += cpx;
  }
  return (done == w) ? k_ra8_ok : k_ra8_err_out_of_range;
}

RA8_INTERNAL static ra8_err_t internal_book_image_row_gray8(const book_src_t*   src,
                                                            const book_image_t* img,
                                                            uint32_t            x,
                                                            uint32_t            ry,
                                                            uint32_t            w,
                                                            uint8_t*            out)
{
  const uint32_t row_flat = (ry * (uint32_t)img->width) + x;
  const uint64_t off =
    (uint64_t)src->hdr.image_pool_off + (uint64_t)img->data_off + (uint64_t)row_flat;
  /* Single exit (MISRA 15.5): a span leaving the blob is an out-of-range read. */
  ra8_err_t re = k_ra8_err_out_of_range; /* descriptor / geometry points past the blob */
  if ((off + (uint64_t)w) <= (uint64_t)src->size) {
    re = book_src_read(src, (uint32_t)off, out, w);
  }
  return re;
}
 
ra8_err_t book_src_image(const book_src_t* src, uint32_t idx, book_image_t* out_img)
{
  RA8_CHECK_NULL_PTR(src, s_tag_paged, "image: null src");
  RA8_CHECK_NULL_PTR(out_img, s_tag_paged, "image: null out_img");
  if (idx >= src->hdr.image_count) {
    return k_ra8_err_invalid_arg;
  }
  const uint32_t off = src->hdr.image_off + (idx * (uint32_t)sizeof(book_image_t));
  return book_src_read(src, off, out_img, (uint32_t)sizeof(book_image_t));
}
 
ra8_err_t book_src_image_rect(const book_src_t*   src,
                              const book_image_t* img,
                              uint32_t            x,
                              uint32_t            y,
                              uint32_t            w,
                              uint32_t            h,
                              uint8_t*            out,
                              uint32_t            out_stride)
{
  RA8_CHECK_NULL_PTR(src, s_tag_paged, "image_rect: null src");
  RA8_CHECK_NULL_PTR(img, s_tag_paged, "image_rect: null img");
  RA8_CHECK_NULL_PTR(out, s_tag_paged, "image_rect: null out");
  /* Readable raster of a known depth (one decision, single exit -- MISRA 15.5):
   * SVG has no pixel grid, and only the two grayscale depths are unpackable --
   * gray4 nibble-unpacks 2px/byte, gray8 copies 1px/byte verbatim (the retained
   * full-resolution continuous-tone source, #343/#476). book_validate()
   * already refuses any other depth; this also guards a corrupt descriptor. */
  const book_image_pixfmt_t pf = book_image_pixfmt(img);
  if ((img->format != (uint8_t)k_book_image_gray4) ||
      ((pf != k_book_pixfmt_gray4) && (pf != k_book_pixfmt_gray8))) {
    return k_ra8_err_invalid_arg;
  }
  if ((w == 0U) || (h == 0U) || (out_stride < w)) {
    return k_ra8_err_invalid_arg;
  }
  if ((((uint64_t)x + (uint64_t)w) > (uint64_t)img->width) ||
      (((uint64_t)y + (uint64_t)h) > (uint64_t)img->height)) {
    return k_ra8_err_out_of_range; /* sub-rect not fully inside the image */
  }
  const bool is_gray8 = (pf == k_book_pixfmt_gray8);
  for (uint32_t row = 0U; row < h; ++row) {
    uint8_t* const  dst = &out[(size_t)row * (size_t)out_stride];
    const ra8_err_t re  = is_gray8 ? internal_book_image_row_gray8(src, img, x, y + row, w, dst)
                                   : internal_book_image_row(src, img, x, y + row, w, dst);
    if (re != k_ra8_ok) {
      return re;
    }
  }
  return k_ra8_ok;
}
 
/* ===========================================================================
 * Paged plain-text extraction (#163): same output as book_chapter_text but
 * the DOM is read frame-by-frame through an book_src_t / ra8_vmem cache, so a
 * book that exceeds the resident budget is walked with a bounded working set.
 * The resident path above is untouched; these helpers reuse the shared,
 * source-agnostic emit_text / emit_break / is_block leaf helpers on staging
 * buffers, so paged output is byte-for-byte identical to the resident walk.
 * =========================================================================== */

typedef enum : uint32_t {
  k_book_paged_strbuf = 256U, 
  k_book_paged_tagbuf = 64U,  
  k_book_paged_pad    = 2U,   
} book_paged_walk_bound_t;

RA8_INTERNAL static ra8_err_t
internal_paged_node(const book_src_t* src, uint32_t idx, book_node_t* out)
{
  const uint32_t off = src->hdr.node_off + (idx * (uint32_t)sizeof(book_node_t));
  return book_src_read(src, off, out, (uint32_t)sizeof(book_node_t));
}

RA8_INTERNAL
static ra8_err_t
internal_paged_str_short(const book_src_t* src, uint32_t abs_off, char* buf, uint32_t cap)
{
  if (abs_off >= src->size) {
    return k_ra8_err_out_of_range;
  }
  const uint32_t  remain = src->size - abs_off;
  const uint32_t  want   = cap - 1U;
  const uint32_t  chunk  = (remain < want) ? remain : want;
  const ra8_err_t re     = book_src_read(src, abs_off, buf, chunk);
  if (re != k_ra8_ok) {
    return re;
  }
  uint32_t nlen = 0U;
  while ((nlen < chunk) && (buf[nlen] != '\0')) {
    ++nlen;
  }
  buf[nlen] = '\0';
  return k_ra8_ok;
}

RA8_INTERNAL static bool internal_paged_emit_run(const book_src_t* src,
                                                 uint32_t          abs_off,
                                                 char*             out,
                                                 size_t            cap,
                                                 size_t*           pos,
                                                 bool*             at_break,
                                                 ra8_err_t*        io_err)
{
  char           buf[k_book_paged_strbuf];
  uint32_t       off = abs_off;
  const uint32_t max_iter =
    (src->size / (uint32_t)(k_book_paged_strbuf - 1U)) + (uint32_t)k_book_paged_pad;
  for (uint32_t it = 0U; it < max_iter; ++it) {
    if (off >= src->size) {
      return true; /* Ran to blob end without a NUL (degenerate); treat as done. */
    }
    const uint32_t  remain = src->size - off;
    const uint32_t  want   = (uint32_t)(k_book_paged_strbuf - 1U);
    const uint32_t  chunk  = (remain < want) ? remain : want;
    const ra8_err_t re     = book_src_read(src, off, buf, chunk);
    if (re != k_ra8_ok) {
      *io_err = re;
      return false;
    }
    uint32_t nlen = 0U;
    while ((nlen < chunk) && (buf[nlen] != '\0')) {
      ++nlen;
    }
    buf[nlen] = '\0';
    if (!priv_book_emit_text(out, cap, pos, buf, at_break)) {
      return false; /* Output overflow. */
    }
    if (nlen < chunk) {
      return true; /* Hit the real NUL terminator. */
    }
    off += nlen; /* nlen == chunk: advance and read the next chunk. */
  }
  return true;
}

RA8_INTERNAL static bool internal_paged_visit_node(const book_src_t* src,
                                                   uint32_t          n,
                                                   char*             out,
                                                   size_t            cap,
                                                   size_t*           pos,
                                                   bool*             at_break,
                                                   uint32_t*         stack,
                                                   uint32_t*         sp,
                                                   ra8_err_t*        io_err)
{
  book_node_t     node = {};
  const ra8_err_t ne   = internal_paged_node(src, n, &node);
  if (ne != k_ra8_ok) {
    *io_err = ne;
    return false;
  }
  if (*sp >= k_book_xhtml_stack) {
    return false;
  }
  stack[*sp] = node.next_sibling; /* sibling chain after this subtree */
  *sp += 1U;
  if (node.kind == (uint8_t)k_book_node_text) {
    return internal_paged_emit_run(src,
                                   src->hdr.string_off + node.text_off,
                                   out,
                                   cap,
                                   pos,
                                   at_break,
                                   io_err);
  }
  char            tag[k_book_paged_tagbuf] = {};
  const ra8_err_t te = internal_paged_str_short(src,
                                                src->hdr.string_off + node.name_off,
                                                tag,
                                                (uint32_t)k_book_paged_tagbuf);
  if (te != k_ra8_ok) {
    *io_err = te;
    return false;
  }
  bool ok = true;
  if (priv_book_is_block(tag)) {
    ok = priv_book_emit_break(out, cap, pos, at_break);
  }
  if (ok && (*sp < k_book_xhtml_stack)) {
    stack[*sp] = node.first_child; /* descend, pre-order */
    *sp += 1U;
  }
  return ok;
}

RA8_INTERNAL static bool internal_walk_text_paged(const book_src_t* src,
                                                  uint32_t          root,
                                                  uint32_t          node_count,
                                                  char*             out,
                                                  size_t            cap,
                                                  size_t*           pos,
                                                  ra8_err_t*        io_err)
{
  /* Explicit DFS stack (2 KiB) kept in module-static storage so this frame
   * stays within the stack-usage budget; iterative (no recursion) and
   * single-threaded, so the shared buffer never overlaps. */
  static uint32_t s_paged_stack[k_book_xhtml_stack];
  uint32_t*       stack    = s_paged_stack;
  uint32_t        sp       = 0U;
  bool            ok       = true;
  bool            at_break = true;
  stack[sp]                = root;
  sp += 1U;
 
  const uint32_t max_iter = (node_count * k_book_xhtml_iter_x) + k_book_xhtml_stack;
  uint32_t       guard    = 0U;
  while ((sp > 0U) && ok && (guard < max_iter)) {
    ++guard;
    sp -= 1U;
    const uint32_t n = stack[sp];
    if (n == k_book_nil) {
      continue;
    }
    ok = internal_paged_visit_node(src, n, out, cap, pos, &at_break, stack, &sp, io_err);
  }
  return ok && (guard < max_iter);
}
 
ra8_err_t book_chapter_text_src(const book_src_t* src,
                                uint32_t          chapter_idx,
                                char*             out,
                                size_t            cap,
                                size_t*           out_len)
{
  RA8_CHECK_NULL_PTR(src, s_tag_paged, "text_src: null src");
  RA8_CHECK_NULL_PTR(out, s_tag_paged, "text_src: null out");
  RA8_CHECK_NULL_PTR(out_len, s_tag_paged, "text_src: null out_len");
 
  if (chapter_idx >= src->hdr.chapter_count) {
    return k_ra8_err_invalid_arg;
  }
  /* Resident source: delegate to the untouched, byte-identical fast path. */
  if (src->base != nullptr) {
    return book_chapter_text(src->base, chapter_idx, out, cap, out_len);
  }
 
  /* Paged source: read the chapter record, then walk the DOM frame-by-frame. */
  book_chapter_t  chap = {};
  const uint32_t  coff = src->hdr.chapter_off + (chapter_idx * (uint32_t)sizeof(book_chapter_t));
  const ra8_err_t ce   = book_src_read(src, coff, &chap, (uint32_t)sizeof(book_chapter_t));
  if (ce != k_ra8_ok) {
    return ce;
  }
  size_t    pos    = 0U;
  ra8_err_t io_err = k_ra8_ok;
  if (!internal_walk_text_paged(src,
                                chap.root_node,
                                src->hdr.node_count,
                                out,
                                cap,
                                &pos,
                                &io_err)) {
    return (io_err != k_ra8_ok) ? io_err : k_ra8_err_invalid_size;
  }
  *out_len = pos;
  return k_ra8_ok;
}
 
ra8_err_t book_src_prefetch_chapter(const book_src_t* src, uint32_t chapter_idx)
{
  RA8_CHECK_NULL_PTR(src, s_tag_paged, "prefetch: null src");
  /* Prefetch warms a paged cache; a resident (or unbound) source has no cache. */
  if (src->vm == nullptr) {
    return k_ra8_err_invalid_state;
  }
  if (chapter_idx >= src->hdr.chapter_count) {
    return k_ra8_err_invalid_arg;
  }
  /* Resolve the chapter's root DOM node: the first content range
   * book_chapter_text_src() reads for this chapter. Reading the record here
   * also warms the chapter-table frame the same walk touches first. */
  book_chapter_t  chap = {};
  const uint32_t  coff = src->hdr.chapter_off + (chapter_idx * (uint32_t)sizeof(book_chapter_t));
  const ra8_err_t ce   = book_src_read(src, coff, &chap, (uint32_t)sizeof(book_chapter_t));
  if (ce != k_ra8_ok) {
    return ce;
  }
  /* uint64 offset math cannot overflow; an out-of-range root_node simply faults
   * in the loader and is returned verbatim (best-effort, nothing warmed). */
  const uint64_t noff =
    (uint64_t)src->hdr.node_off + ((uint64_t)chap.root_node * sizeof(book_node_t));
  return ra8_vmem_prefetch(src->vm, src->object_id, noff);
}