ra8_cache_store_mount.c

Go to the documentation of this file.

 
#include <stdint.h>
#include <string.h>
 
#include "lx_api.h"
#include "ra8_cache_store.h"
#include "ra8_cache_store_internal.h"
#include "ra8_check.h"
#include "ra8_err.h"

static const char* const s_tag = "ra8_cache_store";

static bool s_cs_lx_system_inited = false;

typedef enum : uint32_t {
  k_ra8_cs_crc_bits = 8U,   
  k_ra8_cs_pct_full = 100U, 
} ra8_cs_shift_t;
 
/* ------------------------------------------------------------------------- */
/* Shared low-level helpers (declared in ra8_cache_store_internal.h) */
/* ------------------------------------------------------------------------- */
 
RA8_PRIV uint32_t priv_cache_store_crc32(const uint8_t* data, uint32_t len)
{
  if (data == nullptr) {
    return 0U;
  }
  if (len == 0U) {
    return 0U;
  }
  uint32_t crc = (uint32_t)k_ra8_cs_crc32_seed;
  for (uint32_t i = 0U; i < len; i++) {
    crc ^= data[i];
    for (uint8_t b = 0U; b < (uint8_t)k_ra8_cs_crc_bits; b++) {
      bool lsb = (crc & 1U) != 0U;
      crc >>= 1U;
      if (lsb) {
        crc ^= (uint32_t)k_ra8_cs_crc32_poly;
      }
    }
  }
  return crc ^ (uint32_t)k_ra8_cs_crc32_seed;
}
 
RA8_PRIV ra8_err_t priv_cache_store_sector_read(const ra8_cache_store_t* store,
                                                uint32_t                 sector,
                                                uint8_t*                 out512)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(out512, s_tag, "out512");
  UINT rc = lx_nor_flash_sector_read(store->flash, (ULONG)sector, out512);
  if (rc == (UINT)LX_SUCCESS) {
    return k_ra8_ok;
  }
  if (rc == (UINT)LX_SECTOR_NOT_FOUND) {
    return k_ra8_err_not_found;
  }
  return k_ra8_err_hw_init_failed;
}
 
RA8_PRIV ra8_err_t priv_cache_store_sector_write(ra8_cache_store_t* store,
                                                 uint32_t           sector,
                                                 const uint8_t*     in512)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(in512, s_tag, "in512");
  /* LevelX writes take a mutable buffer pointer but do not modify it. */
  UINT rc = lx_nor_flash_sector_write(store->flash, (ULONG)sector, (VOID*)(uintptr_t)in512);
  if (rc != (UINT)LX_SUCCESS) {
    return k_ra8_err_hw_init_failed;
  }
  return k_ra8_ok;
}
 
RA8_PRIV ra8_err_t priv_cache_store_sector_release(ra8_cache_store_t* store, uint32_t sector)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(store->flash, s_tag, "flash");
  UINT rc = lx_nor_flash_sector_release(store->flash, (ULONG)sector);
  if (rc != (UINT)LX_SUCCESS) {
    return k_ra8_err_hw_init_failed;
  }
  return k_ra8_ok;
}
 
RA8_PRIV int32_t priv_cache_store_index_find(const ra8_cache_store_t* store, uint32_t key)
{
  if (store == nullptr) {
    return -1;
  }
  if (store->index == nullptr) {
    return -1;
  }
  for (uint16_t i = 0U; i < store->index_cap; i++) {
    const ra8_cache_store_entry_t* e = &store->index[i];
    if ((e->flags & (uint8_t)k_ra8_cache_store_flag_in_use) == 0U) {
      continue;
    }
    if (e->key == key) {
      return (int32_t)i;
    }
  }
  return -1;
}
 
RA8_PRIV int32_t priv_cache_store_index_add(ra8_cache_store_t* store,
                                            uint32_t           key,
                                            uint32_t           start_sector,
                                            uint16_t           sector_count,
                                            uint32_t           byte_len,
                                            bool               pinned)
{
  if (store == nullptr) {
    return -1;
  }
  if (store->index == nullptr) {
    return -1;
  }
  for (uint16_t i = 0U; i < store->index_cap; i++) {
    ra8_cache_store_entry_t* e = &store->index[i];
    if ((e->flags & (uint8_t)k_ra8_cache_store_flag_in_use) != 0U) {
      continue;
    }
    uint8_t flags = (uint8_t)k_ra8_cache_store_flag_in_use;
    if (pinned) {
      flags |= (uint8_t)k_ra8_cache_store_flag_pinned;
    }
    *e = (ra8_cache_store_entry_t){.key          = key,
                                   .start_sector = start_sector,
                                   .byte_len     = byte_len,
                                   .sector_count = sector_count,
                                   .flags        = flags,
                                   .reserved     = 0U};
    return (int32_t)i;
  }
  return -1;
}
 
/* ------------------------------------------------------------------------- */
/* Superblock */
/* ------------------------------------------------------------------------- */
 
RA8_PRIV ra8_err_t priv_cache_store_super_write(ra8_cache_store_t* store, uint32_t clean)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(store->staging, s_tag, "staging");
  ra8_cs_super_t sb = {.magic           = (uint32_t)k_ra8_cs_super_magic,
                       .version         = (uint32_t)k_ra8_cs_format_version,
                       .seq             = store->next_seq,
                       .clean           = clean,
                       .entry_count     = 0U,
                       .live_sectors    = store->live_sectors,
                       .next_seq        = store->next_seq,
                       .log_start       = store->log_start,
                       .data_capacity   = store->data_capacity,
                       .logical_sectors = store->logical_sectors,
                       .crc             = 0U};
  for (uint16_t i = 0U; i < store->index_cap; i++) {
    if ((store->index[i].flags & (uint8_t)k_ra8_cache_store_flag_in_use) != 0U) {
      sb.entry_count++;
    }
  }
  sb.crc = priv_cache_store_crc32((const uint8_t*)&sb, (uint32_t)(sizeof(sb) - sizeof(sb.crc)));
  (void)memset(store->staging, 0, (size_t)k_ra8_cache_store_sector_bytes);
  (void)memcpy(store->staging, &sb, sizeof(sb));
  return priv_cache_store_sector_write(store, 0U, store->staging);
}

RA8_INTERNAL static ra8_err_t internal_super_read(ra8_cache_store_t* store, ra8_cs_super_t* out_sb)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(out_sb, s_tag, "out_sb");
  if (priv_cache_store_sector_read(store, 0U, store->staging) != k_ra8_ok) {
    (void)memset(out_sb, 0, sizeof(*out_sb));
    return k_ra8_ok;
  }
  (void)memcpy(out_sb, store->staging, sizeof(*out_sb));
  return k_ra8_ok;
}

RA8_INTERNAL static bool internal_super_is_clean(const ra8_cs_super_t* sb)
{
  if (sb == nullptr) {
    return false;
  }
  if (sb->magic != (uint32_t)k_ra8_cs_super_magic) {
    return false;
  }
  uint32_t want =
    priv_cache_store_crc32((const uint8_t*)sb, (uint32_t)(sizeof(*sb) - sizeof(sb->crc)));
  if (sb->crc != want) {
    return false;
  }
  if (sb->clean != (uint32_t)k_ra8_cs_clean) {
    return false;
  }
  return true;
}
 
/* ------------------------------------------------------------------------- */
/* Directory checkpoint save / load */
/* ------------------------------------------------------------------------- */

RA8_INTERNAL static uint32_t
internal_dir_pack_sector(ra8_cache_store_t* store, uint16_t* slot, uint8_t* out512)
{
  if (store == nullptr) {
    return 0U;
  }
  if (out512 == nullptr) {
    return 0U;
  }
  (void)memset(out512, 0, (size_t)k_ra8_cache_store_sector_bytes);
  uint32_t packed = 0U;
  for (uint32_t e = 0U; e < (uint32_t)k_ra8_cs_dir_per_sector; e++) {
    for (; *slot < store->index_cap; (*slot)++) {
      if ((store->index[*slot].flags & (uint8_t)k_ra8_cache_store_flag_in_use) != 0U) {
        break;
      }
    }
    if (*slot >= store->index_cap) {
      break;
    }
    const ra8_cache_store_entry_t* src = &store->index[*slot];
    ra8_cs_dir_ent_t ent = {.key          = src->key,
                            .start_sector = src->start_sector,
                            .byte_len     = src->byte_len,
                            .sector_count = src->sector_count,
                            .flags =
                              (uint16_t)(src->flags & (uint8_t)k_ra8_cache_store_flag_pinned)};
    (void)memcpy(&out512[(size_t)e * (uint32_t)k_ra8_cs_dir_ent_bytes], &ent, sizeof(ent));
    (*slot)++;
    packed++;
  }
  return packed;
}
 
RA8_PRIV ra8_err_t priv_cache_store_dir_save(ra8_cache_store_t* store, uint32_t* out_entry_count)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(out_entry_count, s_tag, "out_entry_count");
  uint32_t count = 0U;
  uint16_t slot  = 0U;
  for (uint16_t d = 0U; d < store->checkpoint_dirs; d++) {
    count += internal_dir_pack_sector(store, &slot, store->staging);
    RA8_RETURN_ON_ERROR(priv_cache_store_sector_write(store, 1U + (uint32_t)d, store->staging),
                        s_tag,
                        "dir");
  }
  *out_entry_count = count;
  return k_ra8_ok;
}

RA8_INTERNAL static void internal_dir_unpack_sector(ra8_cache_store_t* store,
                                                    const uint8_t*     in512,
                                                    uint32_t*          loaded,
                                                    uint32_t           entry_count)
{
  if (store == nullptr) {
    return;
  }
  if (in512 == nullptr) {
    return;
  }
  for (uint32_t e = 0U; e < (uint32_t)k_ra8_cs_dir_per_sector; e++) {
    if (*loaded >= entry_count) {
      break;
    }
    ra8_cs_dir_ent_t ent = {};
    (void)memcpy(&ent, &in512[(size_t)e * (uint32_t)k_ra8_cs_dir_ent_bytes], sizeof(ent));
    bool pinned = (ent.flags & (uint16_t)k_ra8_cache_store_flag_pinned) != 0U;
    (void)priv_cache_store_index_add(store,
                                     ent.key,
                                     ent.start_sector,
                                     ent.sector_count,
                                     ent.byte_len,
                                     pinned);
    store->live_sectors += ent.sector_count;
    (*loaded)++;
  }
}

RA8_INTERNAL static ra8_err_t internal_dir_load(ra8_cache_store_t* store, uint32_t entry_count)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(store->staging, s_tag, "staging");
  if (entry_count > (uint32_t)store->index_cap) {
    return k_ra8_err_invalid_state;
  }
  store->live_sectors = 0U;
  uint32_t loaded     = 0U;
  for (uint16_t d = 0U; d < store->checkpoint_dirs; d++) {
    if (loaded >= entry_count) {
      break;
    }
    RA8_RETURN_ON_ERROR(priv_cache_store_sector_read(store, 1U + (uint32_t)d, store->staging),
                        s_tag,
                        "dir");
    internal_dir_unpack_sector(store, store->staging, &loaded, entry_count);
  }
  return k_ra8_ok;
}
 
/* ------------------------------------------------------------------------- */
/* Append-log scan (unclean-shutdown replay) */
/* ------------------------------------------------------------------------- */

RA8_INTERNAL static bool
internal_hdr_read(ra8_cache_store_t* store, uint32_t s, ra8_cs_entry_hdr_t* out_hdr)
{
  if (priv_cache_store_sector_read(store, s, store->staging) != k_ra8_ok) {
    return false;
  }
  ra8_cs_entry_hdr_t h = {};
  (void)memcpy(&h, store->staging, sizeof(h));
  if (h.magic != (uint32_t)k_ra8_cs_entry_magic) {
    return false;
  }
  if (h.start_sector != s) {
    return false;
  }
  if (h.sector_count == 0U) {
    return false;
  }
  if (((uint64_t)s + (uint64_t)h.sector_count) > (uint64_t)store->logical_sectors) {
    return false;
  }
  uint32_t want =
    priv_cache_store_crc32((const uint8_t*)&h, (uint32_t)(sizeof(h) - sizeof(h.hdr_crc)));
  if (h.hdr_crc != want) {
    return false;
  }
  *out_hdr = h;
  return true;
}

RA8_INTERNAL static void
internal_scan_accept(ra8_cache_store_t* store, const ra8_cs_entry_hdr_t* h, uint32_t* max_seq)
{
  bool pinned = (h->flags & (uint16_t)k_ra8_cache_store_flag_pinned) != 0U;
  if (priv_cache_store_index_find(store, h->key) >= 0) {
    return; /* write-once: a duplicate key on flash is ignored (keep the first). */
  }
  if (priv_cache_store_index_add(store,
                                 h->key,
                                 h->start_sector,
                                 h->sector_count,
                                 h->byte_len,
                                 pinned) < 0) {
    return; /* index full: stop indexing further entries. */
  }
  store->live_sectors += h->sector_count;
  if (h->seq > *max_seq) {
    *max_seq = h->seq;
  }
}

RA8_INTERNAL static ra8_err_t internal_scan_log(ra8_cache_store_t* store)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(store->staging, s_tag, "staging");
  store->live_sectors = 0U;
  uint32_t max_seq    = 0U;
  uint32_t s          = store->log_start;
  for (uint32_t guard = store->log_start; guard < store->logical_sectors; guard++) {
    if (s >= store->logical_sectors) {
      break;
    }
    ra8_cs_entry_hdr_t h = {};
    if (!internal_hdr_read(store, s, &h)) {
      s += 1U;
      continue;
    }
    internal_scan_accept(store, &h, &max_seq);
    s += h.sector_count;
  }
  store->next_seq = max_seq + 1U;
  return k_ra8_ok;
}
 
/* ------------------------------------------------------------------------- */
/* init */
/* ------------------------------------------------------------------------- */

RA8_INTERNAL static ra8_err_t internal_validate_cfg(const ra8_cache_store_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg");
  RA8_CHECK_NULL_PTR(cfg->nor_flash, s_tag, "nor_flash");
  if (cfg->nor_driver_init == nullptr) {
    ra8_log_error(s_tag, "nor_driver_init");
    return k_ra8_err_null_ptr;
  }
  RA8_CHECK_NULL_PTR(cfg->index, s_tag, "index");
  RA8_CHECK_NULL_PTR(cfg->staging, s_tag, "staging");
  if (cfg->index_cap == 0U) {
    return k_ra8_err_invalid_size;
  }
  if (cfg->staging_bytes < (uint32_t)k_ra8_cache_store_sector_bytes) {
    return k_ra8_err_invalid_size;
  }
  if (cfg->overprovision_pct > (uint8_t)k_ra8_cache_store_max_overprov) {
    return k_ra8_err_invalid_arg;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_geometry(ra8_cache_store_t*           store,
                                                const ra8_cache_store_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg");
  uint32_t dirs          = ((uint32_t)cfg->index_cap + (uint32_t)k_ra8_cs_dir_per_sector - 1U) /
                           (uint32_t)k_ra8_cs_dir_per_sector;
  store->checkpoint_dirs = (uint16_t)dirs;
  store->log_start       = 1U + dirs;
  store->logical_sectors = cfg->logical_sectors;
  if (cfg->logical_sectors < (store->log_start + (uint32_t)k_ra8_cache_store_min_sectors)) {
    return k_ra8_err_invalid_size;
  }
  uint32_t op     = (cfg->overprovision_pct != 0U) ? (uint32_t)cfg->overprovision_pct
                                                   : (uint32_t)k_ra8_cache_store_overprov_pct;
  uint32_t usable = cfg->logical_sectors - store->log_start;
  store->data_capacity =
    (usable * ((uint32_t)k_ra8_cs_pct_full - op)) / (uint32_t)k_ra8_cs_pct_full;
  if (store->data_capacity == 0U) {
    store->data_capacity = 1U;
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_open_levelx(ra8_cache_store_t*           store,
                                                   const ra8_cache_store_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg");
  if (!s_cs_lx_system_inited) {
    (void)lx_nor_flash_initialize();
    s_cs_lx_system_inited = true;
  }
  /* LevelX takes a mutable CHAR* name but never writes it. */
  CHAR* nm = (cfg->name != nullptr) ? (CHAR*)(uintptr_t)cfg->name : (CHAR*)(uintptr_t)"ra8_cache";
  if (cfg->format) {
    if (lx_nor_flash_format(store->flash, nm, cfg->nor_driver_init, LX_NULL) != (UINT)LX_SUCCESS) {
      return k_ra8_err_hw_init_failed;
    }
  }
  if (lx_nor_flash_open(store->flash, nm, cfg->nor_driver_init) != (UINT)LX_SUCCESS) {
    return k_ra8_err_hw_init_failed;
  }
  /* Stamp an empty clean superblock at format time so a fresh mount loads the
   * (empty) checkpoint instead of scanning the whole -- as-yet unmapped -- log
   * region, which on LevelX would allocate a physical sector per read. */
  if (cfg->format) {
    RA8_RETURN_ON_ERROR(priv_cache_store_super_write(store, (uint32_t)k_ra8_cs_clean),
                        s_tag,
                        "format super");
  }
  return k_ra8_ok;
}

RA8_INTERNAL static ra8_err_t internal_recover(ra8_cache_store_t* store, const ra8_cs_super_t* sb)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(sb, s_tag, "sb");
  if (internal_super_is_clean(sb)) {
    store->next_seq    = sb->next_seq;
    store->flash_state = (uint8_t)k_ra8_cs_clean;
    return internal_dir_load(store, sb->entry_count);
  }
  store->flash_state = (uint8_t)k_ra8_cs_dirty;
  return internal_scan_log(store);
}

RA8_INTERNAL static ra8_err_t internal_mount(ra8_cache_store_t* store)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(store->staging, s_tag, "staging");
  ra8_cs_super_t sb = {};
  RA8_RETURN_ON_ERROR(internal_super_read(store, &sb), s_tag, "super");
  return internal_recover(store, &sb);
}

RA8_INTERNAL static void internal_init_fields(ra8_cache_store_t*           store,
                                              const ra8_cache_store_cfg_t* cfg)
{
  if (store == nullptr) {
    return;
  }
  if (cfg == nullptr) {
    return;
  }
  *store           = (ra8_cache_store_t){};
  store->flash     = cfg->nor_flash;
  store->index     = cfg->index;
  store->staging   = cfg->staging;
  store->index_cap = cfg->index_cap;
  for (uint16_t i = 0U; i < store->index_cap; i++) {
    store->index[i] = (ra8_cache_store_entry_t){};
  }
  store->next_seq     = 1U;
  store->live_sectors = 0U;
}

RA8_INTERNAL static ra8_err_t internal_bringup(ra8_cache_store_t*           store,
                                               const ra8_cache_store_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_CHECK_NULL_PTR(cfg, s_tag, "cfg");
  RA8_RETURN_ON_ERROR(internal_geometry(store, cfg), s_tag, "geometry");
  RA8_RETURN_ON_ERROR(internal_open_levelx(store, cfg), s_tag, "levelx open");
  RA8_RETURN_ON_ERROR(internal_mount(store), s_tag, "mount");
  return k_ra8_ok;
}
 
ra8_err_t ra8_cache_store_init(ra8_cache_store_t* store, const ra8_cache_store_cfg_t* cfg)
{
  RA8_CHECK_NULL_PTR(store, s_tag, "store");
  RA8_RETURN_ON_ERROR(internal_validate_cfg(cfg), s_tag, "cfg");
  internal_init_fields(store, cfg);
  RA8_RETURN_ON_ERROR(internal_bringup(store, cfg), s_tag, "bringup");
  store->inited = true;
  return k_ra8_ok;
}