ra8_ftl.c

Go to the documentation of this file.

 
#include "ra8_ftl.h"
 
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_io_blockdev.h"
#include "ra8_io_blockdev_backend.h"

static const char* const s_tag = "ra8_ftl";

typedef enum : uint32_t {
  k_ra8_ftl_one_block      = 1,           
  k_ra8_ftl_req_erase_unit = 1,           
  k_ra8_ftl_count_max      = 0xFFFFFFFFU, 
} ra8_ftl_impl_const_t;
 
/* =============================================================================
 * Physical-block allocation (wear-levelling + reclamation)
 * =============================================================================
 */

RA8_INTERNAL
static ra8_err_t internal_reclaim_stale(ra8_ftl_t* ftl)
{
  RA8_CHECK_NULL_PTR(ftl, s_tag, "ftl must not be nullptr");
  RA8_CHECK_NULL_PTR(ftl->raw, s_tag, "raw must not be nullptr");
  for (uint32_t p = 0; p < ftl->physical_blocks; ++p) {
    if (ftl->pblocks[p].state != (uint8_t)k_ra8_ftl_pstate_stale) {
      continue;
    }
    const ra8_err_t e = ra8_io_blockdev_erase(ftl->raw, p, (uint32_t)k_ra8_ftl_one_block);
    if (e != k_ra8_ok) {
      return e;
    }
    ftl->pblocks[p].erase_count += 1U;
    ftl->pblocks[p].state = (uint8_t)k_ra8_ftl_pstate_free;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_pick_free(const ra8_ftl_t* ftl, uint32_t* out)
{
  RA8_CHECK_NULL_PTR(ftl, s_tag, "ftl must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "out must not be nullptr");
  bool     found = false;
  uint32_t best  = 0;
  uint32_t bestc = 0;
  for (uint32_t p = 0; p < ftl->physical_blocks; ++p) {
    if (ftl->pblocks[p].state != (uint8_t)k_ra8_ftl_pstate_free) {
      continue;
    }
    if (found) {
      if (ftl->pblocks[p].erase_count >= bestc) {
        continue;
      }
    }
    found = true;
    best  = p;
    bestc = ftl->pblocks[p].erase_count;
  }
  if (!found) {
    return k_ra8_err_no_data;
  }
  *out = best;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_alloc_blank(ra8_ftl_t* ftl, uint32_t* out)
{
  RA8_CHECK_NULL_PTR(ftl, s_tag, "ftl must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "out must not be nullptr");
  uint32_t  phys = 0;
  ra8_err_t pick = internal_pick_free(ftl, &phys);
  if (pick == k_ra8_err_no_data) {
    const ra8_err_t rec = internal_reclaim_stale(ftl);
    if (rec != k_ra8_ok) {
      return rec;
    }
    pick = internal_pick_free(ftl, &phys);
  }
  if (pick == k_ra8_err_no_data) {
    return k_ra8_err_no_mem;
  }
  /* internal_pick_free with non-null args returns only k_ra8_ok or
   * k_ra8_err_no_data. */
  if (pick != k_ra8_ok) {
    return pick; /* GCOVR_EXCL_LINE -- pick_free result set is ok or no-data only */
  }
  const ra8_err_t e = ra8_io_blockdev_erase(ftl->raw, phys, (uint32_t)k_ra8_ftl_one_block);
  if (e != k_ra8_ok) {
    return e;
  }
  ftl->pblocks[phys].erase_count += 1U;
  *out = phys;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Single-logical-block read / write
 * =============================================================================
 */

RA8_INTERNAL
static ra8_err_t internal_read_one(const ra8_ftl_t* ftl, uint32_t lbn, uint8_t* dst)
{
  RA8_CHECK_NULL_PTR(ftl, s_tag, "ftl must not be nullptr");
  RA8_CHECK_NULL_PTR(dst, s_tag, "dst must not be nullptr");
  const uint16_t phys = ftl->map[lbn];
  if (phys == (uint16_t)k_ra8_ftl_unmapped) {
    (void)memset(dst, (int)ftl->erase_value, (size_t)k_ra8_io_block_size_bytes);
    return k_ra8_ok;
  }
  return ra8_io_blockdev_read(ftl->raw, phys, (uint32_t)k_ra8_ftl_one_block, dst);
}

RA8_INTERNAL
static ra8_err_t internal_write_one(ra8_ftl_t* ftl, uint32_t lbn, const uint8_t* src)
{
  RA8_CHECK_NULL_PTR(ftl, s_tag, "ftl must not be nullptr");
  RA8_CHECK_NULL_PTR(src, s_tag, "src must not be nullptr");
  uint32_t        phys  = 0;
  const ra8_err_t alloc = internal_alloc_blank(ftl, &phys);
  if (alloc != k_ra8_ok) {
    return alloc;
  }
  const ra8_err_t prog = ra8_io_blockdev_write(ftl->raw, phys, (uint32_t)k_ra8_ftl_one_block, src);
  if (prog != k_ra8_ok) {
    return prog;
  }
  const uint16_t old = ftl->map[lbn];
  if (old != (uint16_t)k_ra8_ftl_unmapped) {
    ftl->pblocks[old].state = (uint8_t)k_ra8_ftl_pstate_stale;
  }
  ftl->pblocks[phys].state = (uint8_t)k_ra8_ftl_pstate_live;
  ftl->map[lbn]            = (uint16_t)phys;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Presented vtable
 * =============================================================================
 */

RA8_INTERNAL
static ra8_err_t internal_bounds(const ra8_ftl_t* ftl, uint32_t lba, uint32_t count)
{
  if (count > ftl->logical_blocks) {
    return k_ra8_err_out_of_range;
  }
  if (lba > ftl->logical_blocks - count) {
    return k_ra8_err_out_of_range;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_dev_read(void* ctx, uint32_t lba, uint32_t count, uint8_t* buf)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx must not be nullptr");
  RA8_CHECK_NULL_PTR(buf, s_tag, "buf must not be nullptr");
  const ra8_ftl_t* ftl = (const ra8_ftl_t*)ctx;
  const ra8_err_t  b   = internal_bounds(ftl, lba, count);
  if (b != k_ra8_ok) {
    return b;
  }
  for (uint32_t i = 0; i < count; ++i) {
    const size_t    off = (size_t)i * (size_t)k_ra8_io_block_size_bytes;
    const ra8_err_t e   = internal_read_one(ftl, lba + i, &buf[off]);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_dev_write(void* ctx, uint32_t lba, uint32_t count, const uint8_t* buf)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx must not be nullptr");
  RA8_CHECK_NULL_PTR(buf, s_tag, "buf must not be nullptr");
  ra8_ftl_t*      ftl = (ra8_ftl_t*)ctx;
  const ra8_err_t b   = internal_bounds(ftl, lba, count);
  if (b != k_ra8_ok) {
    return b;
  }
  for (uint32_t i = 0; i < count; ++i) {
    const size_t    off = (size_t)i * (size_t)k_ra8_io_block_size_bytes;
    const ra8_err_t e   = internal_write_one(ftl, lba + i, &buf[off]);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_dev_erase(void* ctx, uint32_t lba, uint32_t count)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx must not be nullptr");
  ra8_ftl_t*      ftl = (ra8_ftl_t*)ctx;
  const ra8_err_t b   = internal_bounds(ftl, lba, count);
  if (b != k_ra8_ok) {
    return b;
  }
  for (uint32_t i = 0; i < count; ++i) {
    const uint16_t old = ftl->map[lba + i];
    if (old != (uint16_t)k_ra8_ftl_unmapped) {
      ftl->pblocks[old].state = (uint8_t)k_ra8_ftl_pstate_stale;
      ftl->map[lba + i]       = (uint16_t)k_ra8_ftl_unmapped;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_dev_get_caps(const void* ctx, ra8_io_blockdev_caps_t* out)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "out must not be nullptr");
  const ra8_ftl_t* ftl         = (const ra8_ftl_t*)ctx;
  out->block_count             = ftl->logical_blocks;
  out->erase_unit_blocks       = (uint32_t)k_ra8_ftl_one_block;
  out->program_size_bytes      = (uint32_t)k_ra8_io_block_size_bytes;
  out->logical_block_bytes     = (uint16_t)k_ra8_io_block_size_bytes;
  out->erase_value             = ftl->erase_value;
  out->must_erase_before_write = false;
  out->read_only               = false;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_dev_sync(void* ctx)
{
  RA8_CHECK_NULL_PTR(ctx, s_tag, "ctx must not be nullptr");
  const ra8_ftl_t* ftl = (const ra8_ftl_t*)ctx;
  RA8_CHECK_NULL_PTR(ftl->raw, s_tag, "raw must not be nullptr");
  return ra8_io_blockdev_sync(ftl->raw);
}

static const ra8_io_blockdev_iface_t s_ftl_iface = {
  .read     = internal_dev_read,
  .write    = internal_dev_write,
  .erase    = internal_dev_erase,
  .get_caps = internal_dev_get_caps,
  .sync     = internal_dev_sync,
};
 
/* =============================================================================
 * Init / bind / diagnostics
 * =============================================================================
 */

RA8_INTERNAL
static ra8_err_t internal_check_caps(const ra8_io_blockdev_caps_t* caps,
                                     uint32_t                      logical_blocks,
                                     uint32_t                      physical_blocks,
                                     uint8_t*                      erase_out)
{
  RA8_CHECK_NULL_PTR(caps, s_tag, "caps must not be nullptr");
  RA8_CHECK_NULL_PTR(erase_out, s_tag, "erase_out must not be nullptr");
  if (caps->read_only) {
    return k_ra8_err_invalid_arg;
  }
  if (caps->erase_unit_blocks != (uint32_t)k_ra8_ftl_req_erase_unit) {
    return k_ra8_err_invalid_arg;
  }
  if (caps->block_count < physical_blocks) {
    return k_ra8_err_invalid_arg;
  }
  if (physical_blocks < logical_blocks + (uint32_t)k_ra8_ftl_min_spare) {
    return k_ra8_err_invalid_arg;
  }
  *erase_out = caps->erase_value;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_reset_tables(ra8_ftl_t* ftl)
{
  RA8_CHECK_NULL_PTR(ftl, s_tag, "ftl must not be nullptr");
  RA8_CHECK_NULL_PTR(ftl->map, s_tag, "map must not be nullptr");
  for (uint32_t l = 0; l < ftl->logical_blocks; ++l) {
    ftl->map[l] = (uint16_t)k_ra8_ftl_unmapped;
  }
  for (uint32_t p = 0; p < ftl->physical_blocks; ++p) {
    ftl->pblocks[p].state       = (uint8_t)k_ra8_ftl_pstate_free;
    ftl->pblocks[p].erase_count = 0U;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_validate_init_args(const ra8_ftl_t*         bd,
                                             const ra8_io_blockdev_t* raw,
                                             const uint16_t*          map,
                                             const ra8_ftl_pblock_t*  pblocks,
                                             const uint8_t*           scratch,
                                             uint32_t                 logical_blocks,
                                             uint32_t                 physical_blocks)
{
  RA8_CHECK_NULL_PTR(bd, s_tag, "bd must not be nullptr");
  RA8_CHECK_NULL_PTR(raw, s_tag, "raw must not be nullptr");
  RA8_CHECK_NULL_PTR(map, s_tag, "map must not be nullptr");
  RA8_CHECK_NULL_PTR(pblocks, s_tag, "pblocks must not be nullptr");
  RA8_CHECK_NULL_PTR(scratch, s_tag, "scratch must not be nullptr");
  if (logical_blocks == 0U) {
    return k_ra8_err_invalid_size;
  }
  if (physical_blocks > (uint32_t)k_ra8_ftl_max_pblocks) {
    return k_ra8_err_invalid_size;
  }
  return k_ra8_ok;
}
 
ra8_err_t ra8_ftl_init(ra8_ftl_t*               bd,
                       const ra8_io_blockdev_t* raw,
                       uint16_t*                map,
                       uint32_t                 logical_blocks,
                       ra8_ftl_pblock_t*        pblocks,
                       uint32_t                 physical_blocks,
                       uint8_t*                 scratch)
{
  const ra8_err_t va =
    internal_validate_init_args(bd, raw, map, pblocks, scratch, logical_blocks, physical_blocks);
  if (va != k_ra8_ok) {
    return va;
  }
  ra8_io_blockdev_caps_t caps = {};
  const ra8_err_t        cq   = ra8_io_blockdev_get_caps(raw, &caps);
  if (cq != k_ra8_ok) {
    return cq;
  }
  uint8_t         erase_value = 0;
  const ra8_err_t ck = internal_check_caps(&caps, logical_blocks, physical_blocks, &erase_value);
  if (ck != k_ra8_ok) {
    return ck;
  }
  bd->raw             = raw;
  bd->map             = map;
  bd->pblocks         = pblocks;
  bd->scratch         = scratch;
  bd->logical_blocks  = logical_blocks;
  bd->physical_blocks = physical_blocks;
  bd->erase_value     = erase_value;
  return internal_reset_tables(bd);
}
 
ra8_err_t ra8_ftl_as_blockdev(ra8_ftl_t* ftl, ra8_io_blockdev_t* out)
{
  RA8_CHECK_NULL_PTR(ftl, s_tag, "ftl must not be nullptr");
  RA8_CHECK_NULL_PTR(out, s_tag, "out must not be nullptr");
  if (ftl->raw == nullptr) {
    return k_ra8_err_not_initialized;
  }
  out->iface = &s_ftl_iface;
  out->ctx   = ftl;
  return k_ra8_ok;
}
 
ra8_err_t ra8_ftl_wear_stats(const ra8_ftl_t* ftl, uint32_t* max_out, uint32_t* min_out)
{
  RA8_CHECK_NULL_PTR(ftl, s_tag, "ftl must not be nullptr");
  RA8_CHECK_NULL_PTR(max_out, s_tag, "max_out must not be nullptr");
  RA8_CHECK_NULL_PTR(min_out, s_tag, "min_out must not be nullptr");
  if (ftl->pblocks == nullptr) {
    return k_ra8_err_not_initialized;
  }
  uint32_t hi = 0;
  uint32_t lo = (uint32_t)k_ra8_ftl_count_max;
  for (uint32_t p = 0; p < ftl->physical_blocks; ++p) {
    const uint32_t c = ftl->pblocks[p].erase_count;
    if (c > hi) {
      hi = c;
    }
    if (c < lo) {
      lo = c;
    }
  }
  *max_out = hi;
  *min_out = lo;
  return k_ra8_ok;
}
 
ra8_err_t ra8_ftl_phys_of(const ra8_ftl_t* ftl, uint32_t lbn, uint16_t* phys_out)
{
  RA8_CHECK_NULL_PTR(ftl, s_tag, "ftl must not be nullptr");
  RA8_CHECK_NULL_PTR(phys_out, s_tag, "phys_out must not be nullptr");
  if (ftl->map == nullptr) {
    return k_ra8_err_not_initialized;
  }
  if (lbn >= ftl->logical_blocks) {
    return k_ra8_err_out_of_range;
  }
  *phys_out = ftl->map[lbn];
  return k_ra8_ok;
}