ra8_fs_fat_exfat_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"
 
/* ===========================================================================
 * exFAT format (mkfs)
 * ===========================================================================
 */

typedef struct {
  uint64_t part_lba;        
  uint64_t total_sectors;   
  uint32_t bps;             
  uint8_t  bps_shift;       
  uint8_t  spc_shift;       
  uint32_t spc;             
  uint32_t fat_offset;      
  uint32_t fat_length;      
  uint32_t heap_offset;     
  uint32_t cluster_count;   
  uint32_t bitmap_bytes;    
  uint32_t bitmap_clusters; 
  uint32_t upcase_cluster;  
  uint32_t upcase_clusters; 
  uint32_t root_cluster;    
  uint32_t used_clusters;   
} exfat_geom_t;
 
/* `priv_exfat_csum32()`: see header for the documented contract. */
uint32_t priv_exfat_csum32(uint32_t cs, const uint8_t* buf, uint32_t len)
{
  for (uint32_t i = 0U; i < len; i++) {
    cs = (((cs & 1U) != 0U) ? (uint32_t)k_exfat_fmt_csum_hibit : 0U) + (cs >> 1) + (uint32_t)buf[i];
  }
  return cs;
}

RA8_INTERNAL
static uint8_t internal_exfat_spc_shift(uint64_t total_sectors, uint8_t bps_shift)
{
  /* The subtraction is guarded even though every caller passes 9..12: the
   * analyzer cannot see the cross-function bound, and an under-9 shift here
   * would be a 2^32-sized left shift rather than a wrong answer. */
  const uint32_t scale      = ((uint32_t)bps_shift > (uint32_t)k_exfat_bps_shift_min)
                                ? ((uint32_t)bps_shift - (uint32_t)k_exfat_bps_shift_min)
                                : 0U;
  const uint64_t total_512  = total_sectors << scale;
  uint32_t       clus_shift = (uint32_t)k_exfat_fmt_clus_256k;
  if (total_512 <= (uint64_t)k_exfat_fmt_thr_256m) {
    clus_shift = (uint32_t)k_exfat_fmt_clus_4k;
  } else if (total_512 <= (uint64_t)k_exfat_fmt_thr_32g) {
    clus_shift = (uint32_t)k_exfat_fmt_clus_32k;
  } else if (total_512 <= (uint64_t)k_exfat_fmt_thr_256g) {
    clus_shift = (uint32_t)k_exfat_fmt_clus_128k;
  } else {
    clus_shift = (uint32_t)k_exfat_fmt_clus_256k;
  }
  if (clus_shift <= (uint32_t)bps_shift) {
    return 0U;
  }
  return (uint8_t)(clus_shift - (uint32_t)bps_shift);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_geometry(uint64_t total_sectors, exfat_geom_t* g)
{
  g->total_sectors = total_sectors;
  g->spc_shift     = internal_exfat_spc_shift(total_sectors, g->bps_shift);
  g->spc           = 1U << g->spc_shift;
  g->fat_offset    = (uint32_t)k_exfat_fmt_boot_secs;
  if (total_sectors <= g->fat_offset) {
    return k_ra8_err_invalid_size;
  }
  uint32_t clusters = (uint32_t)((total_sectors - g->fat_offset) / g->spc);
  g->fat_length     = 0U;
  g->heap_offset    = 0U;
  for (uint32_t i = 0U; i < (uint32_t)k_exfat_fmt_geom_iters; i++) {
    const uint64_t fat_bytes = ((uint64_t)clusters + 2U) * 4U;
    const uint32_t fat_len   = (uint32_t)((fat_bytes + g->bps - 1U) / g->bps);
    const uint32_t heap      = g->fat_offset + fat_len;
    if (total_sectors <= heap) {
      return k_ra8_err_invalid_size;
    }
    const uint32_t next = (uint32_t)((total_sectors - heap) / g->spc);
    g->fat_length       = fat_len;
    g->heap_offset      = heap;
    if (next == clusters) {
      break;
    }
    clusters = next;
  }
  g->cluster_count             = (uint32_t)((total_sectors - g->heap_offset) / g->spc);
  const uint32_t cluster_bytes = g->spc * g->bps;
  g->bitmap_bytes =
    (g->cluster_count + (uint32_t)k_exfat_fmt_byte_bits - 1U) / (uint32_t)k_exfat_fmt_byte_bits;
  g->bitmap_clusters = (g->bitmap_bytes + cluster_bytes - 1U) / cluster_bytes;
  g->upcase_clusters = ((uint32_t)k_exfat_fmt_upc_std_bytes + cluster_bytes - 1U) / cluster_bytes;
  g->upcase_cluster  = (uint32_t)k_exfat_fmt_first_clus + g->bitmap_clusters;
  g->root_cluster    = g->upcase_cluster + g->upcase_clusters;
  g->used_clusters   = g->bitmap_clusters + g->upcase_clusters + 1U; /* bitmap + up-case + root */
  if (g->cluster_count < g->used_clusters) {
    return k_ra8_err_invalid_size;
  }
  return k_ra8_ok;
}

RA8_INTERNAL
static void internal_exfat_build_vbr(uint8_t* sec, const exfat_geom_t* g)
{
  for (uint32_t i = 0U; i < g->bps; i++) {
    sec[i] = 0U;
  }
  sec[(uint32_t)k_exfat_foff_jump]         = (uint8_t)k_exfat_fmt_jump0;
  sec[(uint32_t)k_exfat_foff_jump + 1U]    = (uint8_t)k_exfat_fmt_jump1;
  sec[(uint32_t)k_exfat_foff_jump + 2U]    = (uint8_t)k_exfat_fmt_jump2;
  static const char nm[k_exfat_fsname_len] = {'E', 'X', 'F', 'A', 'T', ' ', ' ', ' '};
  for (uint32_t i = 0U; i < (uint32_t)k_exfat_fsname_len; i++) {
    sec[(uint32_t)k_exfat_off_fsname + i] = (uint8_t)nm[i];
  }
  priv_wr64(&sec[k_exfat_foff_part_off], g->part_lba);
  priv_wr64(&sec[k_exfat_foff_vol_len], g->total_sectors);
  priv_wr32(&sec[k_exfat_off_fat_lba], g->fat_offset);
  priv_wr32(&sec[k_exfat_off_fat_len], g->fat_length);
  priv_wr32(&sec[k_exfat_off_heap_lba], g->heap_offset);
  priv_wr32(&sec[k_exfat_off_clus_count], g->cluster_count);
  priv_wr32(&sec[k_exfat_off_root_clus], g->root_cluster);
  priv_wr32(&sec[k_exfat_foff_serial], (uint32_t)k_exfat_fmt_serial ^ (uint32_t)g->total_sectors);
  priv_wr16(&sec[k_exfat_foff_fs_rev], (uint16_t)k_exfat_fmt_fs_rev);
  sec[k_exfat_off_bps_shift]          = g->bps_shift;
  sec[k_exfat_off_spc_shift]          = g->spc_shift;
  sec[k_exfat_off_num_fats]           = (uint8_t)k_exfat_fmt_num_fats;
  sec[(uint32_t)k_exfat_foff_drive]   = (uint8_t)k_exfat_fmt_drive;
  sec[(uint32_t)k_exfat_foff_percent] = (uint8_t)k_exfat_fmt_percent;
  priv_wr16(&sec[k_exfat_foff_boot_sig], (uint16_t)k_exfat_fmt_boot_sig);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_wr_dual(const ra8_fs_backend_t* b,
                                        uint64_t                part_lba,
                                        uint32_t                lba,
                                        const uint8_t*          buf)
{
  const ra8_err_t err = b->write_block(b->ctx, part_lba + lba, 1U, buf);
  if (err != k_ra8_ok) {
    return err;
  }
  return b->write_block(b->ctx, part_lba + lba + (uint32_t)k_exfat_fmt_backup_lba, 1U, buf);
}

RA8_INTERNAL
static void internal_exfat_put32(uint8_t* buf, uint32_t idx, uint32_t val)
{
  priv_wr32(&buf[(size_t)idx * 4U], val);
}

RA8_INTERNAL
static ra8_err_t
internal_exfat_write_boot_tail(const ra8_fs_backend_t* backend, const exfat_geom_t* g, uint32_t cs)
{
  /* Sectors 1-8: extended boot (ext-boot signature only). The extended boot
   * signature sits in the sector's LAST four bytes (exFAT spec sec 3.2). */
  for (uint32_t i = 0U; i < g->bps; i++) {
    g_fs_scratch[i] = 0U;
  }
  priv_wr32(
    &g_fs_scratch[g->bps - ((uint32_t)k_ra8_fs_sector_min - (uint32_t)k_exfat_foff_ext_sig)],
    (uint32_t)k_exfat_fmt_ext_sig);
  for (uint32_t s = (uint32_t)k_exfat_fmt_ext_first;
       s < (uint32_t)k_exfat_fmt_ext_first + (uint32_t)k_exfat_fmt_ext_count;
       s++) {
    cs                = priv_exfat_csum32(cs, g_fs_scratch, g->bps);
    const ra8_err_t e = internal_exfat_wr_dual(backend, g->part_lba, s, g_fs_scratch);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  /* Sectors 9 (OEM) + 10 (reserved): all zero. */
  for (uint32_t i = 0U; i < g->bps; i++) {
    g_fs_scratch[i] = 0U;
  }
  cs = priv_exfat_csum32(cs, g_fs_scratch, g->bps);
  ra8_err_t err =
    internal_exfat_wr_dual(backend, g->part_lba, (uint32_t)k_exfat_fmt_oem_lba, g_fs_scratch);
  if (err != k_ra8_ok) {
    return err;
  }
  cs  = priv_exfat_csum32(cs, g_fs_scratch, g->bps);
  err = internal_exfat_wr_dual(backend, g->part_lba, (uint32_t)k_exfat_fmt_resv_lba, g_fs_scratch);
  if (err != k_ra8_ok) {
    return err;
  }
  /* Checksum sector: every 32-bit word = the boot checksum. */
  for (uint32_t i = 0U; i < (g->bps / 4U); i++) {
    internal_exfat_put32(g_fs_scratch, i, cs);
  }
  return internal_exfat_wr_dual(backend, g->part_lba, (uint32_t)k_exfat_fmt_csum_lba, g_fs_scratch);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_write_boot(const ra8_fs_backend_t* backend, const exfat_geom_t* g)
{
  internal_exfat_build_vbr(g_fs_scratch, g);
  /* Boot checksum over sector 0 skips bytes 106,107 (VolumeFlags) and 112
   * (PercentInUse): fold [0,106), [108,112), [113,bps). */
  uint32_t cs = priv_exfat_csum32(0U, &g_fs_scratch[0], (uint32_t)k_exfat_fmt_csum_skip0);
  cs = priv_exfat_csum32(cs,
                         &g_fs_scratch[k_exfat_off_bps_shift],
                         (uint32_t)k_exfat_fmt_csum_skip2 - (uint32_t)k_exfat_off_bps_shift);
  cs = priv_exfat_csum32(cs,
                         &g_fs_scratch[(uint32_t)k_exfat_fmt_csum_skip2 + 1U],
                         g->bps - ((uint32_t)k_exfat_fmt_csum_skip2 + 1U));
  const ra8_err_t err = internal_exfat_wr_dual(backend, g->part_lba, 0U, g_fs_scratch);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_exfat_write_boot_tail(backend, g, cs);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_write_fat(const ra8_fs_backend_t* backend, const exfat_geom_t* g)
{
  ra8_err_t err =
    priv_fmt_clear_region(backend, g->part_lba + g->fat_offset, g->fat_length, g->bps);
  if (err != k_ra8_ok) {
    return err;
  }
  for (uint32_t i = 0U; i < g->bps; i++) {
    g_fs_scratch[i] = 0U;
  }
  internal_exfat_put32(g_fs_scratch, 0U, (uint32_t)k_exfat_fmt_fat_media);
  internal_exfat_put32(g_fs_scratch, 1U, (uint32_t)k_exfat_fmt_fat_eoc);
  const uint32_t bmp_last = (uint32_t)k_exfat_fmt_first_clus + g->bitmap_clusters - 1U;
  for (uint32_t c = (uint32_t)k_exfat_fmt_first_clus; c <= bmp_last; c++) {
    const uint32_t next = (c < bmp_last) ? (c + 1U) : (uint32_t)k_exfat_fmt_fat_eoc;
    internal_exfat_put32(g_fs_scratch, c, next);
  }
  const uint32_t upc_last = g->upcase_cluster + g->upcase_clusters - 1U;
  for (uint32_t c = g->upcase_cluster; c <= upc_last; c++) {
    const uint32_t next = (c < upc_last) ? (c + 1U) : (uint32_t)k_exfat_fmt_fat_eoc;
    internal_exfat_put32(g_fs_scratch, c, next);
  }
  internal_exfat_put32(g_fs_scratch, g->root_cluster, (uint32_t)k_exfat_fmt_fat_eoc);
  return backend->write_block(backend->ctx, g->part_lba + g->fat_offset, 1U, g_fs_scratch);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_write_bitmap(const ra8_fs_backend_t* backend, const exfat_geom_t* g)
{
  const uint64_t bmp_lba     = g->part_lba + g->heap_offset;
  const uint32_t bmp_sectors = g->bitmap_clusters * g->spc;
  ra8_err_t      err         = priv_fmt_clear_region(backend, bmp_lba, bmp_sectors, g->bps);
  if (err != k_ra8_ok) {
    return err;
  }
  for (uint32_t i = 0U; i < g->bps; i++) {
    g_fs_scratch[i] = 0U;
  }
  const uint32_t full = g->used_clusters / (uint32_t)k_exfat_fmt_byte_bits;
  for (uint32_t i = 0U; i < full; i++) {
    g_fs_scratch[i] = (uint8_t)k_exfat_fmt_byte_full;
  }
  const uint32_t rem = g->used_clusters % (uint32_t)k_exfat_fmt_byte_bits;
  if (rem != 0U) {
    g_fs_scratch[full] = (uint8_t)((1U << rem) - 1U);
  }
  return backend->write_block(backend->ctx, bmp_lba, 1U, g_fs_scratch);
}

RA8_INTERNAL
static uint32_t internal_exfat_label_utf16(uint8_t* dst, const char* label)
{
  uint32_t n = 0U;
  if (label != nullptr) {
    for (; (n < (uint32_t)k_exfat_fmt_label_max) && (label[n] != '\0'); n++) {
      dst[(size_t)n * 2U]        = (uint8_t)label[n];
      dst[((size_t)n * 2U) + 1U] = 0U;
    }
  }
  return n;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_write_root(const ra8_fs_backend_t* backend,
                                           const exfat_geom_t*     g,
                                           uint32_t                upcase_csum,
                                           const char*             label)
{
  const uint64_t lba = (uint64_t)g->heap_offset +
                       ((uint64_t)(g->root_cluster - (uint32_t)k_exfat_fmt_first_clus) * g->spc);
  /* Zero the WHOLE root cluster, not just the sector the three system entries
   * land in. The rest must read as end-of-directory (0x00), or a directory that
   * fills past the first sector -- or a rename that relocates an entry set into
   * it -- runs the scan straight into whatever the device held before the format
   * (#603). Directory growth already zeroes every cluster it appends; the initial
   * root cluster was the one spot that skipped it. */
  const ra8_err_t ze = priv_fmt_clear_region(backend, g->part_lba + lba, g->spc, g->bps);
  if (ze != k_ra8_ok) {
    return ze;
  }
  for (uint32_t i = 0U; i < g->bps; i++) {
    g_fs_scratch[i] = 0U;
  }
  /* Allocation Bitmap entry (0x81). */
  g_fs_scratch[0] = (uint8_t)k_exfat_entry_bitmap;
  priv_wr32(&g_fs_scratch[k_exfat_de_first_clus], (uint32_t)k_exfat_fmt_first_clus);
  priv_wr32(&g_fs_scratch[k_exfat_de_data_len], g->bitmap_bytes);
  /* Up-case Table entry (0x82). */
  uint8_t* upc = &g_fs_scratch[k_exfat_de_second];
  upc[0]       = (uint8_t)k_exfat_entry_upcase;
  priv_wr32(&upc[k_exfat_de_upc_csum], upcase_csum);
  priv_wr32(&upc[k_exfat_de_first_clus], g->upcase_cluster);
  priv_wr32(&upc[k_exfat_de_data_len], (uint32_t)k_exfat_fmt_upc_std_bytes);
  /* Volume Label entry (0x83). */
  uint8_t*       lbl      = &g_fs_scratch[k_exfat_de_third];
  const uint32_t n        = internal_exfat_label_utf16(&lbl[k_exfat_de_lbl_name], label);
  lbl[0]                  = (uint8_t)k_exfat_entry_label;
  lbl[k_exfat_de_lbl_cnt] = (uint8_t)n;
  return backend->write_block(backend->ctx, g->part_lba + lba, 1U, g_fs_scratch);
}

RA8_INTERNAL
static void internal_exfat_lba_to_chs(uint32_t lba, uint8_t* out3)
{
  if (lba >= (uint32_t)k_mbr_fmt_chs_max) {
    out3[0] = (uint8_t)k_mbr_fmt_chs_ovf_h;
    out3[1] = (uint8_t)k_mbr_fmt_chs_ovf_m;
    out3[2] = (uint8_t)k_mbr_fmt_chs_ovf_l;
    return;
  }
  const uint32_t spt  = (uint32_t)k_mbr_fmt_chs_spt;
  const uint32_t hpc  = (uint32_t)k_mbr_fmt_chs_heads;
  const uint32_t cyl  = lba / (hpc * spt);
  const uint32_t head = (lba / spt) % hpc;
  const uint32_t sec  = (lba % spt) + 1U;
  out3[0]             = (uint8_t)head;
  out3[1]             = (uint8_t)((sec & (uint32_t)k_mbr_fmt_chs_sec_mask) |
                                  ((cyl & (uint32_t)k_mbr_fmt_chs_cyl_hi_mask) >>
                                   (uint32_t)k_mbr_fmt_chs_cyl_hi_shift));
  out3[2]             = (uint8_t)(cyl & (uint32_t)k_byte_mask);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_write_mbr(const ra8_fs_backend_t* backend,
                                          uint32_t                bps,
                                          uint32_t                part_lba,
                                          uint32_t                part_sectors)
{
  for (uint32_t i = 0U; i < bps; i++) {
    g_fs_scratch[i] = 0U;
  }
  priv_wr32(&g_fs_scratch[k_mbr_fmt_disk_sig_off],
            (uint32_t)k_mbr_fmt_disk_sig_base ^ part_sectors);
  uint8_t* pe           = &g_fs_scratch[k_mbr_fmt_part0_off];
  pe[k_mbr_fmt_pe_boot] = (uint8_t)k_mbr_fmt_boot_none;
  internal_exfat_lba_to_chs(part_lba, &pe[k_mbr_fmt_pe_chs_start]);
  pe[k_mbr_fmt_pe_type] = (uint8_t)k_mbr_fmt_type_exfat;
  internal_exfat_lba_to_chs((part_lba + part_sectors) - 1U, &pe[k_mbr_fmt_pe_chs_end]);
  priv_wr32(&pe[k_mbr_fmt_pe_lba], part_lba);
  priv_wr32(&pe[k_mbr_fmt_pe_nsect], part_sectors);
  priv_wr16(&g_fs_scratch[k_exfat_foff_boot_sig], (uint16_t)k_exfat_fmt_boot_sig);
  return backend->write_block(backend->ctx, 0U, 1U, g_fs_scratch);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_fmt_place(uint64_t  total_sectors,
                                          uint32_t  bps,
                                          uint8_t*  out_bps_shift,
                                          uint32_t* out_part_lba,
                                          uint32_t* out_part_sectors)
{
  uint32_t bps_shift = 0U;
  for (uint32_t w = bps; w > 1U; w >>= 1U) {
    bps_shift++;
  }
  const uint32_t part_lba = (uint32_t)k_exfat_fmt_part_align / bps;
  const uint64_t min_total =
    (uint64_t)part_lba +
    (((uint64_t)k_exfat_fmt_min_sectors * (uint32_t)k_ra8_fs_sector_min) / bps);
  if (total_sectors < min_total) {
    return k_ra8_err_not_supported;
  }
  /* The MBR this formatter writes records the partition in 32-bit fields, so
   * a device whose partition would not fit them (past 2 TiB at 512-byte
   * sectors) is refused with a clean error rather than a truncated table.
   * Beyond-2-TiB media formatted elsewhere (GPT) mount and address fine. */
  if ((total_sectors - part_lba) > (uint64_t)UINT32_MAX) {
    return k_ra8_err_not_supported;
  }
  *out_bps_shift    = (uint8_t)bps_shift;
  *out_part_lba     = part_lba;
  *out_part_sectors = (uint32_t)(total_sectors - part_lba);
  return k_ra8_ok;
}
 
/* `priv_exfat_format()`: see header for the documented contract. */
ra8_err_t priv_exfat_format(const ra8_fs_backend_t* backend,
                            uint64_t                total_sectors,
                            uint32_t                bps,
                            const char*             label)
{
  uint8_t   bps_shift    = 0U;
  uint32_t  part_lba     = 0U;
  uint32_t  part_sectors = 0U;
  ra8_err_t err =
    internal_exfat_fmt_place(total_sectors, bps, &bps_shift, &part_lba, &part_sectors);
  if (err != k_ra8_ok) {
    return err;
  }
  exfat_geom_t g = {.bps = bps, .bps_shift = bps_shift};
  err            = internal_exfat_geometry(part_sectors, &g);
  if (err != k_ra8_ok) {
    return err;
  }
  g.part_lba = part_lba;
  /* The bitmap/up-case/root chains are seeded in FAT sector 0 only. */
  if ((g.root_cluster * 4U) >= bps) {
    return k_ra8_err_not_supported;
  }
  err = internal_exfat_write_mbr(backend, bps, part_lba, part_sectors);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_exfat_write_boot(backend, &g);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_exfat_write_fat(backend, &g);
  if (err != k_ra8_ok) {
    return err;
  }
  err = internal_exfat_write_bitmap(backend, &g);
  if (err != k_ra8_ok) {
    return err;
  }
  const uint64_t upcase_lba =
    g.part_lba + g.heap_offset +
    ((uint64_t)(g.upcase_cluster - (uint32_t)k_exfat_fmt_first_clus) * g.spc);
  uint32_t upcase_csum = 0U;
  err                  = priv_exfat_write_upcase(backend, upcase_lba, bps, &upcase_csum);
  if (err != k_ra8_ok) {
    return err;
  }
  return internal_exfat_write_root(backend, &g, upcase_csum, label);
}