ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
comic_cbt.c File Reference

CBT backend: walk a tar archive (unarch_tar.h) and index its pages. More...

#include <stddef.h>
#include <stdint.h>
#include "comic.h"
#include "comic_internal.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "unarch_tar.h"
Include dependency graph for comic_cbt.c:

Go to the source code of this file.

Enumerations

enum  cbt_limits_t : uint32_t {
  k_cbt_name_max = 256U ,
  k_cbt_max_members = 100000U
}
 Name scratch size for the tar member walk. More...

Functions

static ra8_err_t internal_add_member (comic_t *c, const unarch_tar_entry_t *ent, const char *name, uint16_t nlen)
 Index one tar member if it is a decodable page-image file.
ra8_err_t priv_comic_cbt_open (comic_t *c)
 Open the CBT (tar) backend: walk the archive + build the page index.
ra8_err_t priv_comic_cbt_extract (comic_t *c, const comic_page_t *p, uint8_t *buf, size_t cap, size_t *got)
 Extract one CBT page's encoded image (verbatim tar member copy).

Variables

static const char *const s_tag_cbt = "comic_cbt"
 Log tag for CBT-backend diagnostics.

Detailed Description

CBT backend: walk a tar archive (unarch_tar.h) and index its pages.

Tag
[Ring 4 / Domain] {World: NS}

The tar half of the comic facade. priv_comic_cbt_open walks the tar member chain one header at a time through the clean-room streaming walker (unarch_tar_next – ustar / pax / GNU dialects, every block charged against the unified decompression-limits policy), appending each image file member to the shared page index. tar stores members verbatim, so priv_comic_cbt_extract is a bounds-revalidated literal copy – the same demand-paged model as the CBZ / CBR backends, with zero allocation.

Unlike the tolerant CBR walk (RAR archives often carry trailing junk), a malformed tar header rejects the archive: tar's block grammar leaves no legitimate reason for an undecodable header mid-chain.

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

Definition in file comic_cbt.c.

Enumeration Type Documentation

◆ cbt_limits_t

enum cbt_limits_t : uint32_t

Name scratch size for the tar member walk.

Since
Version 0.1.0
Enumerator
k_cbt_name_max 

Longest member name indexed (bytes, incl.

path).

k_cbt_max_members 

Static upper bound on members walked.

Definition at line 43 of file comic_cbt.c.

Function Documentation

◆ internal_add_member()

ra8_err_t internal_add_member ( comic_t * c,
const unarch_tar_entry_t * ent,
const char * name,
uint16_t nlen )
static

Index one tar member if it is a decodable page-image file.

Skips directories, non-file members, and non-image / hidden names; otherwise appends the member. tar members are stored verbatim, so pack_size == raw_size and every page decodes.

Parameters
[in,out]cComic accumulating its index.
[in]entDecoded member from unarch_tar_next.
[in]nameMember name bytes.
[in]nlenMember name length.
Returns
ra8_err_t status (k_ra8_ok also for a skipped, non-page member).
Return values
k_ra8_okMember indexed or intentionally skipped.
k_ra8_err_invalid_sizePage index / name arena is full.
Precondition
ent came from unarch_tar_next; name holds nlen bytes.
c has its buffers bound.
Postcondition
On k_ra8_ok either one page was added or nothing changed (a skip).
On error the index is unchanged.
Note
Not thread-safe.
Since
Version 0.1.0

Definition at line 68 of file comic_cbt.c.

References unarch_tar_entry_t::data_off, unarch_tar_entry_t::is_file, k_ra8_ok, k_ra8_rar_method_store, priv_comic_is_page_name(), priv_comic_page_add(), and unarch_tar_entry_t::size.

Referenced by priv_comic_cbt_open().

◆ priv_comic_cbt_extract()

ra8_err_t priv_comic_cbt_extract ( comic_t * c,
const comic_page_t * p,
uint8_t * buf,
size_t cap,
size_t * got )

Extract one CBT page's encoded image (verbatim tar member copy).

Streams the member's literal bytes through unarch_tar_read, which re-validates the (potentially forged) entry bounds against the archive before any copy.

Parameters
[in]cComic with a bound CBT walker.
[in]pPage-index entry (its data_off / raw_size).
[out]bufDestination for the encoded image bytes.
[in]capCapacity of buf; must be >= p->raw_size.
[out]gotReceives the bytes written.
Returns
ra8_err_t status.
Return values
k_ra8_okMember copied into buf.
k_ra8_err_no_memcap is smaller than p->raw_size.
k_ra8_err_invalid_sizeThe member overruns the archive / short read.
Precondition
p came from this comic's CBT index.
buf holds cap writable bytes.
Postcondition
On k_ra8_ok, *got == p->raw_size.
On any error *got == 0.
Note
Not thread-safe.
Since
Version 0.1.0

Definition at line 116 of file comic_cbt.c.

References comic_page_t::data_off, unarch_tar_entry_t::data_off, unarch_tar_entry_t::is_file, k_ra8_err_invalid_state, unarch_tar_t::live, RA8_CHECK_NULL_PTR, comic_page_t::raw_size, s_tag_cbt, unarch_tar_entry_t::size, comic_t::tar, and unarch_tar_read().

Referenced by comic_page_read().

◆ priv_comic_cbt_open()

ra8_err_t priv_comic_cbt_open ( comic_t * c)

Open the CBT (tar) backend: walk the archive + build the page index.

Iterates the tar member chain (unarch_tar_next) from offset 0, appending each image file member via priv_comic_page_add. tar stores members verbatim, so every indexed page is extractable == 1 with pack_size == raw_size. The walk (and each member's declared size) is charged against the walker's embedded decompression budget.

Parameters
[in,out]cComic with c->tar bound by unarch_tar_open, kind == cbt.
Returns
ra8_err_t status.
Return values
k_ra8_okArchive walked; index populated.
k_ra8_err_invalid_sizeThe page index / name arena was too small.
k_ra8_err_decomp_*The walk breached the decompression policy.
k_ra8_err_*A tar-walk error (malformed header, ...).
Precondition
c->tar was bound by unarch_tar_open; buffers are bound.
c->size is the archive length.
Postcondition
On k_ra8_ok, the index holds every image member in archive order.
On any error the index is left partially filled (caller discards c).
Note
Not thread-safe.
Since
Version 0.1.0

Definition at line 87 of file comic_cbt.c.

References internal_add_member(), k_cbt_max_members, k_cbt_name_max, k_ra8_err_invalid_state, k_ra8_err_not_found, k_ra8_err_validation_failed, k_ra8_ok, unarch_tar_t::live, unarch_tar_entry_t::name_len, unarch_tar_entry_t::next_off, RA8_CHECK_NULL_PTR, RA8_PRIV, s_tag_cbt, comic_t::tar, and unarch_tar_next().

Referenced by internal_open_detect().

Variable Documentation

◆ s_tag_cbt

const char* const s_tag_cbt = "comic_cbt"
static

Log tag for CBT-backend diagnostics.

Definition at line 36 of file comic_cbt.c.

Referenced by priv_comic_cbt_extract(), and priv_comic_cbt_open().