ra8_fs_fat_fmt.c

Go to the documentation of this file.

 
#include <stddef.h>
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_fs.h"
#include "ra8_fs_fat_internal.h"
 
/* =============================================================================
 * Public API: format (mkfs)
 * =============================================================================
 */
 
/* `priv_fmt_reserved_for()`: see header for the documented contract. */
uint32_t priv_fmt_reserved_for(ra8_fs_type_t type)
{
  return (type == k_ra8_fs_type_fat32) ? (uint32_t)k_fmt_resv_f32 : (uint32_t)k_fmt_resv_f16;
}

RA8_INTERNAL
static uint64_t
internal_fmt_clusters_for(const ra8_fs_fmt_geom_t* g, uint32_t spc, uint32_t* out_fatsz)
{
  /* FAT entries per DEVICE sector: 4-byte FAT32 entries or 2-byte FAT16 ones
   * (FAT12 sizes its FAT with the FAT16 figure, a deliberate overestimate). */
  const uint32_t entry_bytes = (g->type == k_ra8_fs_type_fat32) ? (uint32_t)k_fmt_fat32_entry_bytes
                                                                : (uint32_t)k_fmt_fat16_entry_bytes;
  const uint32_t entry_cap   = g->bytes_per_sector / entry_bytes;
  const uint64_t overhead    = (uint64_t)g->reserved_sectors + g->root_sectors;
  if (g->total_sectors <= overhead) {
    *out_fatsz = 0U;
    return 0U;
  }
  const uint64_t avail     = g->total_sectors - overhead;
  const uint64_t denom     = ((uint64_t)entry_cap * spc) + (uint32_t)k_fmt_num_fats;
  const uint64_t fatsz     = (avail + denom - 1U) / denom;
  *out_fatsz               = (uint32_t)fatsz;
  const uint64_t fat_total = (uint64_t)k_fmt_num_fats * fatsz;
  if (avail <= fat_total) {
    return 0U;
  }
  return (avail - fat_total) / spc;
}

RA8_INTERNAL
static bool internal_fmt_count_in_band(ra8_fs_type_t type, uint64_t count)
{
  if (type == k_ra8_fs_type_fat12) {
    return count < (uint32_t)k_cluster_count_fat12_max;
  }
  if (type == k_ra8_fs_type_fat16) {
    return (count >= (uint32_t)k_cluster_count_fat12_max) &&
           (count < (uint32_t)k_cluster_count_fat16_max);
  }
  return (count >= (uint32_t)k_cluster_count_fat16_max) &&
         (count <= (uint32_t)k_fmt_fat32_clus_cap);
}

RA8_INTERNAL
static uint32_t internal_fmt_log2(uint32_t v)
{
  uint32_t r = 0U;
  uint32_t w = v;
  while (w > 1U) {
    w >>= 1U;
    r++;
  }
  return r;
}

RA8_INTERNAL
static uint32_t internal_fmt_fat32_default_spc(uint64_t total_sectors, uint32_t bps)
{
  const uint32_t bps_shift  = internal_fmt_log2(bps);
  const uint64_t total_512  = total_sectors
                              << (bps_shift - internal_fmt_log2((uint32_t)k_ra8_fs_sector_min));
  uint32_t       clus_shift = (uint32_t)k_fmt_f32_clus_32k;
  if (total_512 <= (uint64_t)k_fmt_f32_thr_260m) {
    clus_shift = (uint32_t)k_fmt_f32_clus_512b;
  } else if (total_512 <= (uint64_t)k_fmt_f32_thr_8g) {
    clus_shift = (uint32_t)k_fmt_f32_clus_4k;
  } else if (total_512 <= (uint64_t)k_fmt_f32_thr_16g) {
    clus_shift = (uint32_t)k_fmt_f32_clus_8k;
  } else if (total_512 <= (uint64_t)k_fmt_f32_thr_32g) {
    clus_shift = (uint32_t)k_fmt_f32_clus_16k;
  } else {
    clus_shift = (uint32_t)k_fmt_f32_clus_32k;
  }
  if (clus_shift <= bps_shift) {
    return 1U;
  }
  return 1U << (clus_shift - bps_shift);
}
 
/* `priv_fmt_choose_geometry()`: see header for the documented contract. */
ra8_err_t priv_fmt_choose_geometry(ra8_fs_fmt_geom_t* g, uint32_t spc_hint)
{
  /* FAT's BPB records the volume size in a 32-bit field: a device whose
   * sector count does not fit cannot be described by the format at all --
   * exFAT is the right choice there, so this fails cleanly instead of
   * truncating the size (#683). */
  if (g->total_sectors > (uint64_t)UINT32_MAX) {
    return k_ra8_err_invalid_size;
  }
  bool     auto_mode = (spc_hint == 0U);
  uint32_t spc       = spc_hint;
  if (auto_mode) {
    /* FAT32 starts the sweep at the size-appropriate cluster (MS table) so a
     * big card gets a small FAT; FAT12/16 start at the minimum and grow. */
    spc = (g->type == k_ra8_fs_type_fat32)
            ? internal_fmt_fat32_default_spc(g->total_sectors, g->bytes_per_sector)
            : 1U;
  }
  for (uint32_t guard = 0U; guard <= (uint32_t)k_fmt_spc_max; guard++) {
    uint32_t       fatsz = 0U;
    const uint64_t count = internal_fmt_clusters_for(g, spc, &fatsz);
    if (internal_fmt_count_in_band(g->type, count)) {
      g->sectors_per_cluster = spc;
      g->fat_size_sectors    = fatsz;
      g->count_of_clusters   = (uint32_t)count;
      return k_ra8_ok;
    }
    if (!auto_mode || spc >= (uint32_t)k_fmt_spc_max) {
      return k_ra8_err_invalid_size;
    }
    spc *= 2U;
  }
  return k_ra8_err_invalid_size;
}

RA8_INTERNAL
static void internal_fmt_boot_prologue(uint8_t* sec)
{
  static const uint8_t k_oem[k_filename_base_len] = {'M', 'S', 'D', 'O', 'S', '5', '.', '0'};
  sec[k_fmt_off_jmp0]                             = (uint8_t)k_fmt_jmp_byte0;
  sec[k_fmt_off_jmp1]                             = (uint8_t)k_fmt_jmp_byte1;
  sec[k_fmt_off_jmp2]                             = (uint8_t)k_fmt_jmp_byte2;
  priv_byte_copy(&sec[k_fmt_off_oem], k_oem, (uint32_t)k_filename_base_len);
}
 
/* `priv_fmt_label_field()`: see header for the documented contract. */
void priv_fmt_label_field(uint8_t* dst, const char* label)
{
  /* An unlabelled FAT volume stores the spec sentinel "NO NAME    ", never
   * zeros and never a bare run of spaces: fsck.fat reads a blank BS_VolLab as a
   * corrupt label and strips it on sight, which trains people to ignore fsck
   * output on every card this firmware writes (#634). A NULL or empty label
   * therefore resolves to that sentinel before padding. */
  static const char k_no_name[] = "NO NAME";
  const char*       eff         = ((label != nullptr) && (label[0] != '\0')) ? label : k_no_name;
  bool              past_end    = false;
  for (uint32_t i = 0U; i < (uint32_t)k_fmt_label_len; i++) {
    if (!past_end && (eff[i] == '\0')) {
      past_end = true;
    }
    dst[i] = past_end ? (uint8_t)' ' : (uint8_t)eff[i];
  }
}

RA8_INTERNAL
static void internal_fmt_write_totals(uint8_t* sec, const ra8_fs_fmt_geom_t* g)
{
  if (g->type == k_ra8_fs_type_fat32) {
    priv_wr32(&sec[k_bpb_off_tot_sec_32], (uint32_t)g->total_sectors);
    priv_wr32(&sec[k_bpb_off_fat_sz_32], g->fat_size_sectors);
    return;
  }
  if (g->total_sectors < (uint64_t)(k_word_mask + 1U)) {
    priv_wr16(&sec[k_bpb_off_tot_sec_16], (uint16_t)g->total_sectors);
  } else {
    priv_wr32(&sec[k_bpb_off_tot_sec_32], (uint32_t)g->total_sectors);
  }
  priv_wr16(&sec[k_bpb_off_fat_sz_16], (uint16_t)g->fat_size_sectors);
}

RA8_INTERNAL
static void internal_fmt_build_bpb_f16(uint8_t* sec, const ra8_fs_fmt_geom_t* g, const char* label)
{
  static const uint8_t k_t12[k_filename_base_len] = {'F', 'A', 'T', '1', '2', ' ', ' ', ' '};
  static const uint8_t k_t16[k_filename_base_len] = {'F', 'A', 'T', '1', '6', ' ', ' ', ' '};
  internal_fmt_boot_prologue(sec);
  priv_wr16(&sec[k_bpb_off_bytes_per_sec], (uint16_t)g->bytes_per_sector);
  sec[k_bpb_off_sec_per_clus] = (uint8_t)g->sectors_per_cluster;
  priv_wr16(&sec[k_bpb_off_rsvd_sec_cnt], (uint16_t)g->reserved_sectors);
  sec[k_bpb_off_num_fats] = (uint8_t)k_fmt_num_fats;
  priv_wr16(&sec[k_bpb_off_root_ent_cnt], (uint16_t)g->root_entries);
  sec[k_fmt_off_media] = (uint8_t)k_fmt_media_fixed;
  internal_fmt_write_totals(sec, g);
  priv_wr16(&sec[k_fmt_off_sec_per_trk], (uint16_t)k_fmt_sec_per_trk);
  priv_wr16(&sec[k_fmt_off_num_heads], (uint16_t)k_fmt_num_heads);
  sec[k_fmt_off_f16_drvnum]  = (uint8_t)k_fmt_drvnum_hd;
  sec[k_fmt_off_f16_bootsig] = (uint8_t)k_fmt_ext_bootsig;
  priv_wr32(&sec[k_fmt_off_f16_volid], (uint32_t)k_fmt_volid_base | (uint32_t)g->total_sectors);
  priv_fmt_label_field(&sec[k_fmt_off_f16_label], label);
  priv_byte_copy(&sec[k_fmt_off_f16_fstype],
                 (g->type == k_ra8_fs_type_fat12) ? k_t12 : k_t16,
                 (uint32_t)k_filename_base_len);
  sec[k_bpb_off_signature_lo] = (uint8_t)k_bpb_sig_lo;
  sec[k_bpb_off_signature_hi] = (uint8_t)k_bpb_sig_hi;
}

RA8_INTERNAL
static void internal_fmt_build_bpb_f32(uint8_t* sec, const ra8_fs_fmt_geom_t* g, const char* label)
{
  static const uint8_t k_t32[k_filename_base_len] = {'F', 'A', 'T', '3', '2', ' ', ' ', ' '};
  internal_fmt_boot_prologue(sec);
  priv_wr16(&sec[k_bpb_off_bytes_per_sec], (uint16_t)g->bytes_per_sector);
  sec[k_bpb_off_sec_per_clus] = (uint8_t)g->sectors_per_cluster;
  priv_wr16(&sec[k_bpb_off_rsvd_sec_cnt], (uint16_t)g->reserved_sectors);
  sec[k_bpb_off_num_fats] = (uint8_t)k_fmt_num_fats;
  sec[k_fmt_off_media]    = (uint8_t)k_fmt_media_fixed;
  internal_fmt_write_totals(sec, g);
  priv_wr16(&sec[k_fmt_off_sec_per_trk], (uint16_t)k_fmt_sec_per_trk);
  priv_wr16(&sec[k_fmt_off_num_heads], (uint16_t)k_fmt_num_heads);
  priv_wr32(&sec[k_bpb_off_root_clus], (uint32_t)k_fmt_root_clus_f32);
  priv_wr16(&sec[k_fmt_off_f32_fsinfo], (uint16_t)k_fmt_fsinfo_sector);
  priv_wr16(&sec[k_fmt_off_f32_bkboot], (uint16_t)k_fmt_bkboot_sector);
  sec[k_fmt_off_f32_drvnum]  = (uint8_t)k_fmt_drvnum_hd;
  sec[k_fmt_off_f32_bootsig] = (uint8_t)k_fmt_ext_bootsig;
  priv_wr32(&sec[k_fmt_off_f32_volid], (uint32_t)k_fmt_volid_base | (uint32_t)g->total_sectors);
  priv_fmt_label_field(&sec[k_fmt_off_f32_label], label);
  priv_byte_copy(&sec[k_fmt_off_f32_fstype], k_t32, (uint32_t)k_filename_base_len);
  sec[k_bpb_off_signature_lo] = (uint8_t)k_bpb_sig_lo;
  sec[k_bpb_off_signature_hi] = (uint8_t)k_bpb_sig_hi;
}

static const uint8_t s_fmt_zero_chunk[k_fmt_zero_chunk_bytes] = {};

RA8_INTERNAL
static ra8_err_t
internal_fmt_zero_run(const ra8_fs_backend_t* backend, uint64_t lba, uint64_t count, uint32_t bps)
{
  const uint32_t chunk_secs = (uint32_t)k_fmt_zero_chunk_bytes / bps;
  uint64_t       done       = 0U;
  while (done < count) {
    uint32_t chunk = chunk_secs;
    if ((uint64_t)chunk > (count - done)) {
      chunk = (uint32_t)(count - done);
    }
    const ra8_err_t err = backend->write_block(backend->ctx, lba + done, chunk, s_fmt_zero_chunk);
    if (err != k_ra8_ok) {
      return err;
    }
    done += chunk;
  }
  return k_ra8_ok;
}
 
/* `priv_fmt_clear_region()`: see header for the documented contract. */
ra8_err_t
priv_fmt_clear_region(const ra8_fs_backend_t* backend, uint64_t lba, uint64_t count, uint32_t bps)
{
  if ((backend->erase_blocks != nullptr) &&
      (backend->erase_blocks(backend->ctx, lba, count) == k_ra8_ok)) {
    return k_ra8_ok; /* erased and verified zero -- skip the zero-write */
  }
  /* No erase hook, or erase could not guarantee a zero read-back: write zeros. */
  return internal_fmt_zero_run(backend, lba, count, bps);
}

RA8_INTERNAL
static ra8_err_t internal_fmt_seed_fats(const ra8_fs_backend_t* backend, const ra8_fs_fmt_geom_t* g)
{
  for (uint32_t i = 0U; i < g->bytes_per_sector; i++) {
    g_fs_scratch[i] = 0U;
  }
  if (g->type == k_ra8_fs_type_fat32) {
    priv_wr32(&g_fs_scratch[0], (uint32_t)k_cluster_eoc_min_fat32 | (uint32_t)k_fmt_media_fixed);
    priv_wr32(&g_fs_scratch[4], (uint32_t)k_cluster_eoc_write_fat32);
    priv_wr32(&g_fs_scratch[8], (uint32_t)k_cluster_eoc_write_fat32);
  } else if (g->type == k_ra8_fs_type_fat16) {
    priv_wr16(&g_fs_scratch[0],
              (uint16_t)((uint32_t)k_cluster_eoc_min_fat16 | (uint32_t)k_fmt_media_fixed));
    priv_wr16(&g_fs_scratch[2], (uint16_t)k_cluster_eoc_write_fat16);
  } else {
    /* FAT12: 1.5-byte entries. FAT[0]=0xF<media>, FAT[1]=0xFFF, packed LE. */
    g_fs_scratch[0] = (uint8_t)k_fmt_media_fixed;
    g_fs_scratch[1] = (uint8_t)k_byte_mask;
    g_fs_scratch[2] = (uint8_t)k_byte_mask;
  }
  for (uint32_t f = 0U; f < (uint32_t)k_fmt_num_fats; f++) {
    const uint64_t  fat_lba = (uint64_t)g->reserved_sectors + ((uint64_t)f * g->fat_size_sectors);
    const ra8_err_t err     = backend->write_block(backend->ctx, fat_lba, 1U, g_fs_scratch);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_fmt_write_fsinfo(const ra8_fs_backend_t*  backend,
                                           const ra8_fs_fmt_geom_t* g,
                                           const uint8_t*           boot_sec)
{
  if (g->type != k_ra8_fs_type_fat32) {
    return k_ra8_ok;
  }
  for (uint32_t i = 0U; i < g->bytes_per_sector; i++) {
    g_fs_scratch[i] = 0U;
  }
  priv_wr32(&g_fs_scratch[k_fmt_fsi_off_lead], (uint32_t)k_fmt_fsi_lead_sig);
  priv_wr32(&g_fs_scratch[k_fmt_fsi_off_struct], (uint32_t)k_fmt_fsi_struct_sig);
  const uint32_t free_count =
    (g->count_of_clusters > 0U) ? (g->count_of_clusters - 1U) : (uint32_t)k_fmt_fsi_unknown;
  priv_wr32(&g_fs_scratch[k_fmt_fsi_off_free], free_count);
  priv_wr32(&g_fs_scratch[k_fmt_fsi_off_nxtfree], (uint32_t)k_fmt_fat32_nxt_free);
  priv_wr32(&g_fs_scratch[k_fmt_fsi_off_trail], (uint32_t)k_fmt_fsi_trail_sig);
  ra8_err_t err =
    backend->write_block(backend->ctx, (uint64_t)k_fmt_fsinfo_sector, 1U, g_fs_scratch);
  if (err != k_ra8_ok) {
    return err;
  }
  return backend->write_block(backend->ctx, (uint64_t)k_fmt_bkboot_sector, 1U, boot_sec);
}
 
/* `priv_fmt_spc_valid()`: see header for the documented contract. */
bool priv_fmt_spc_valid(uint8_t spc)
{
  if (spc == 0U) {
    return true;
  }
  if (spc > (uint32_t)k_fmt_spc_max) {
    return false;
  }
  return ((uint32_t)spc & ((uint32_t)spc - 1U)) == 0U;
}
 
/* `priv_fmt_emit_volume()`: see header for the documented contract. */
ra8_err_t
priv_fmt_emit_volume(const ra8_fs_backend_t* backend, const ra8_fs_fmt_geom_t* g, const char* label)
{
  uint8_t* const boot = priv_sec_walk();
  priv_byte_fill(boot, 0U, g->bytes_per_sector);
  if (g->type == k_ra8_fs_type_fat32) {
    internal_fmt_build_bpb_f32(boot, g, label);
  } else {
    internal_fmt_build_bpb_f16(boot, g, label);
  }
  /* Clear the FAT region plus the (contiguous) root region first, so no stale
   * non-zero FAT word survives as an orphan cluster. Erase the whole span in
   * one go when the card guarantees zero-after-erase, else stream zeros. Doing
   * this BEFORE the metadata writes means an erase that rounds into the reserved
   * region cannot clobber the boot sector / FSInfo written below. */
  const uint64_t fat_total = (uint64_t)k_fmt_num_fats * g->fat_size_sectors;
  const uint64_t root_span =
    (g->type == k_ra8_fs_type_fat32) ? g->sectors_per_cluster : g->root_sectors;
  ra8_err_t err =
    priv_fmt_clear_region(backend, g->reserved_sectors, fat_total + root_span, g->bytes_per_sector);
  if (err != k_ra8_ok) {
    return err;
  }
  /* Now lay the metadata: boot sector, FAT seeds (rewrite FAT sector 0 of each
   * copy with the media + EOC reserved entries), then FAT32 FSInfo + backup. */
  err = backend->write_block(backend->ctx, 0U, 1U, boot);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_fmt_seed_fats(backend, g);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_fmt_write_fsinfo(backend, g, boot);
}