ra8_fs_fat_exfat_stream.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"
 
/* =============================================================================
 * Growth: one cluster at a time, contiguous while it can be
 * =============================================================================
 */

RA8_INTERNAL
static ra8_err_t internal_exfat_pick_cluster(const ra8_fs_mount_t* m,
                                             uint64_t              bmp_lba,
                                             uint32_t              prefer,
                                             uint32_t*             out)
{
  const uint32_t past_end = (uint32_t)k_cluster_first_data + m->count_of_clusters;
  if ((prefer >= (uint32_t)k_cluster_first_data) && (prefer < past_end)) {
    uint8_t         is_free = 0U;
    const ra8_err_t pe      = priv_exfat_bitmap_test(m, bmp_lba, prefer, &is_free);
    if (pe != k_ra8_ok) {
      return pe;
    }
    if (is_free != 0U) {
      *out = prefer;
      return k_ra8_ok;
    }
  }
  return priv_exfat_bitmap_scan(m, bmp_lba, 1U, out);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_materialize_run(const ra8_fs_mount_t* m,
                                                uint32_t              first,
                                                uint32_t              alloc,
                                                uint32_t              tail,
                                                uint32_t              next)
{
  for (uint32_t i = 0U; (i + 1U) < alloc; i++) {
    const uint32_t  here = first + i;
    const ra8_err_t e    = priv_fat_set(m, here, here + 1U);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return priv_fat_set(m, tail, next);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_link_cluster(ra8_fs_file_t* file, uint32_t next)
{
  if (file->alloc_clusters == 0U) {
    return k_ra8_ok;
  }
  if ((file->no_fat_chain != 0U) && (next == (file->tail_cluster + 1U))) {
    return k_ra8_ok;
  }
  if (file->no_fat_chain != 0U) {
    const ra8_err_t e = internal_exfat_materialize_run(file->mount,
                                                       file->first_cluster,
                                                       file->alloc_clusters,
                                                       file->tail_cluster,
                                                       next);
    if (e != k_ra8_ok) {
      return e;
    }
    file->no_fat_chain = 0U;
  } else {
    const ra8_err_t e = priv_fat_set(file->mount, file->tail_cluster, next);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return priv_fat_set(file->mount, next, priv_eoc_write(file->mount));
}

RA8_INTERNAL
static ra8_err_t internal_exfat_grow_one(ra8_fs_file_t* file)
{
  const ra8_fs_mount_t* m       = file->mount;
  uint64_t              bmp_lba = 0U;
  ra8_err_t             e       = priv_exfat_bitmap_lba(m, &bmp_lba);
  if (e != k_ra8_ok) {
    return e;
  }
  const uint32_t prefer = (file->alloc_clusters > 0U) ? (file->tail_cluster + 1U) : 0U;
  uint32_t       next   = 0U;
  e                     = internal_exfat_pick_cluster(m, bmp_lba, prefer, &next);
  if (e != k_ra8_ok) {
    return e;
  }
  e = priv_exfat_bitmap_mark(m, bmp_lba, next, 1U);
  if (e != k_ra8_ok) {
    return e;
  }
  priv_alloc_hint_set(m, next + 1U);
  e = internal_exfat_link_cluster(file, next);
  if (e != k_ra8_ok) {
    return e;
  }
  if (file->alloc_clusters == 0U) {
    file->first_cluster      = next;
    file->cur_cluster        = next;
    file->walk_cache_idx     = 0U;
    file->walk_cache_cluster = next;
  }
  file->tail_cluster = next;
  file->alloc_clusters++;
  return k_ra8_ok;
}
 
/* `priv_exfat_ensure_clusters()`: see header for the documented contract. */
ra8_err_t priv_exfat_ensure_clusters(ra8_fs_file_t* file, uint32_t need)
{
  while (file->alloc_clusters < need) {
    const ra8_err_t e = internal_exfat_grow_one(file);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return k_ra8_ok;
}
 
/* =============================================================================
 * Directory growth: the same allocation, one directory-specific rewrite (#677)
 * =============================================================================
 *
 * A directory's on-disk allocation is structurally a file's: a run of clusters
 * that carries `NoFatChain` while it is contiguous and becomes a real FAT chain
 * the moment it is not. So directory growth reuses the machinery above --
 * ::priv_exfat_pick_cluster to prefer the tail's successor, and
 * ::priv_exfat_materialize_run for the conversion -- and adds only the two
 * things a directory needs that a mid-write file does not: the new cluster is
 * ZEROED before it is linked (a directory cluster reads as its own contents, so
 * a half-built one must never be reachable), and the directory's OWN Stream
 * entry in its parent is rewritten so `DataLength` and the `NoFatChain` flag
 * keep describing the run after the mount that grew it is gone.
 */

RA8_INTERNAL
static ra8_err_t internal_exfat_dir_survey(const ra8_fs_mount_t* m,
                                           const exfat_dir_t*    dir,
                                           uint32_t*             out_alloc,
                                           uint32_t*             out_tail,
                                           uint8_t*              out_nofat)
{
  if (dir->contig_end != 0U) {
    *out_nofat = 1U;
    *out_alloc = dir->contig_end - dir->cluster;
    *out_tail  = dir->contig_end - 1U;
    return k_ra8_ok;
  }
  *out_nofat    = 0U;
  uint32_t clus = dir->cluster;
  uint32_t held = 1U;
  for (uint32_t guard = 0U; guard < m->count_of_clusters; guard++) {
    uint32_t        next = 0U;
    const ra8_err_t e    = priv_fat_get(m, clus, &next);
    if (e != k_ra8_ok) {
      return e;
    }
    if (priv_is_eoc(m, next) != 0U) {
      break;
    }
    if (next < (uint32_t)k_cluster_first_data) {
      return k_ra8_err_protocol_error;
    }
    clus = next;
    held++;
  }
  *out_alloc = held;
  *out_tail  = clus;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_dir_link(const ra8_fs_mount_t* m,
                                         uint32_t              first,
                                         uint32_t              alloc,
                                         uint32_t              tail,
                                         uint8_t*              nofat,
                                         uint32_t              next)
{
  if ((*nofat != 0U) && (next == (tail + 1U))) {
    return k_ra8_ok; /* the run stays contiguous; NoFatChain is still true */
  }
  if (*nofat != 0U) {
    const ra8_err_t e = internal_exfat_materialize_run(m, first, alloc, tail, next);
    if (e != k_ra8_ok) {
      return e;
    }
    *nofat = 0U;
  } else {
    const ra8_err_t e = priv_fat_set(m, tail, next);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  return priv_fat_set(m, next, priv_eoc_write(m));
}

RA8_INTERNAL
static ra8_err_t internal_exfat_dir_relen(const ra8_fs_mount_t* m,
                                          const exfat_dir_t*    dir,
                                          uint64_t              new_bytes,
                                          uint8_t               nofat)
{
  uint8_t        set[k_exfat_max_set_bytes] = {};
  exfat_cursor_t cur                        = {.cluster          = dir->self_cluster,
                                               .entry_in_cluster = dir->self_index,
                                               .scanned          = 0U,
                                               .contig_end       = 0U};
  ra8_err_t      e                          = priv_exfat_next_entry(m, &cur, &set[0]);
  if (e != k_ra8_ok) {
    return e;
  }
  const uint32_t count = 1U + (uint32_t)set[k_exfat_off_file_secnt];
  if (count > (uint32_t)k_exfat_set_writable) {
    return k_ra8_err_not_supported;
  }
  for (uint32_t k = 1U; k < count; k++) {
    e = priv_exfat_next_entry(m, &cur, &set[(size_t)k * (size_t)k_exfat_entry_bytes]);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  uint8_t* strm = &set[k_exfat_entry_bytes];
  strm[k_exfat_strm_off_flags] =
    (nofat != 0U) ? (uint8_t)k_exfat_secflag_alloc : (uint8_t)k_exfat_secflag_poss;
  priv_wr64(&strm[k_exfat_off_strm_valid], new_bytes);
  priv_wr64(&strm[k_exfat_strm_off_dlen], new_bytes);
  priv_wr16(&set[k_exfat_off_file_csum],
            priv_exfat_set_checksum(set, count * (uint32_t)k_exfat_entry_bytes));
  return priv_exfat_write_dir_set(m,
                                  dir->self_cluster,
                                  dir->self_index,
                                  set,
                                  count * (uint32_t)k_exfat_entry_bytes);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_dir_append(const ra8_fs_mount_t* m,
                                           const exfat_dir_t*    dir,
                                           uint32_t              alloc,
                                           uint32_t              tail,
                                           uint8_t*              nofat)
{
  uint64_t  bmp_lba = 0U;
  ra8_err_t e       = priv_exfat_bitmap_lba(m, &bmp_lba);
  if (e != k_ra8_ok) {
    return e;
  }
  uint32_t next = 0U;
  e             = internal_exfat_pick_cluster(m, bmp_lba, tail + 1U, &next);
  if (e != k_ra8_ok) {
    return e;
  }
  e = priv_exfat_zero_cluster(m, next);
  if (e != k_ra8_ok) {
    return e;
  }
  e = priv_exfat_bitmap_mark(m, bmp_lba, next, 1U);
  if (e != k_ra8_ok) {
    return e;
  }
  priv_alloc_hint_set(m, next + 1U);
  e = internal_exfat_dir_link(m, dir->cluster, alloc, tail, nofat, next);
  if (e != k_ra8_ok) {
    return e;
  }
  return priv_exfat_seal_cluster(m, tail);
}
 
/* `priv_exfat_grow_dir()`: see header for the documented contract. */
ra8_err_t priv_exfat_grow_dir(const ra8_fs_mount_t* m, exfat_dir_t* dir)
{
  uint32_t  alloc = 0U;
  uint32_t  tail  = 0U;
  uint8_t   nofat = 0U;
  ra8_err_t e     = internal_exfat_dir_survey(m, dir, &alloc, &tail, &nofat);
  if (e != k_ra8_ok) {
    return e;
  }
  e = internal_exfat_dir_append(m, dir, alloc, tail, &nofat);
  if (e != k_ra8_ok) {
    return e;
  }
  const uint32_t new_alloc = alloc + 1U;
  const uint32_t cbytes    = priv_cluster_bytes(m);
  /* The volume root has no entry set to patch -- its extent is the boot-sector
   * FAT chain, which ::priv_exfat_dir_link just extended. A subdirectory carries
   * the location of its own set and must update it, or the next mount reads the
   * old length and cannot see the cluster this call added (#677). */
  if (dir->self_cluster >= (uint32_t)k_cluster_first_data) {
    e = internal_exfat_dir_relen(m, dir, (uint64_t)new_alloc * cbytes, nofat);
    if (e != k_ra8_ok) {
      return e;
    }
  }
  dir->contig_end = (nofat != 0U) ? (dir->cluster + new_alloc) : 0U;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_cluster_at(ra8_fs_file_t* file, uint32_t idx, uint32_t* out)
{
  if (file->no_fat_chain != 0U) {
    *out = file->first_cluster + idx;
    return k_ra8_ok;
  }
  /* Nested rather than joined, because only the inner guard has both answers
   * available: by the time a chained file is walked its waypoint is always a
   * real cluster, so a joined decision would carry a condition no input can
   * make false -- a permanent MC/DC hole. The inner guard varies with every
   * backward seek. */
  uint32_t from = file->first_cluster;
  uint32_t hops = idx;
  if (file->walk_cache_cluster >= (uint32_t)k_cluster_first_data) {
    if (idx >= file->walk_cache_idx) {
      from = file->walk_cache_cluster;
      hops = idx - file->walk_cache_idx;
    }
  }
  uint32_t cur = from;
  for (uint32_t i = 0U; i < hops; i++) {
    uint32_t        next = 0U;
    const ra8_err_t e    = priv_fat_get(file->mount, cur, &next);
    if (e != k_ra8_ok) {
      return e;
    }
    if (priv_is_eoc(file->mount, next) != 0U) {
      return k_ra8_err_invalid_state;
    }
    cur = next;
  }
  file->walk_cache_idx     = idx;
  file->walk_cache_cluster = cur;
  *out                     = cur;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_slice_at(ra8_fs_file_t* file,
                                         uint64_t       pos,
                                         uint64_t*      out_lba,
                                         uint32_t*      out_off,
                                         uint32_t*      out_room)
{
  const ra8_fs_mount_t* m      = file->mount;
  const uint32_t        cbytes = priv_cluster_bytes(m);
  const uint32_t        idx    = (uint32_t)(pos / cbytes);
  ra8_err_t             e      = priv_exfat_ensure_clusters(file, idx + 1U);
  if (e != k_ra8_ok) {
    return e;
  }
  uint32_t cur = 0U;
  e            = internal_exfat_cluster_at(file, idx, &cur);
  if (e != k_ra8_ok) {
    return e;
  }
  file->cur_cluster         = cur;
  const uint32_t in_cluster = (uint32_t)(pos % cbytes);
  *out_lba                  = priv_cluster_to_lba(m, cur) + (in_cluster / priv_bps(m));
  *out_off                  = in_cluster % priv_bps(m);
  *out_room                 = priv_bps(m) - *out_off;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_exfat_close_gap(ra8_fs_file_t* file)
{
  while (file->valid_bytes < file->offset) {
    uint64_t  lba  = 0U;
    uint32_t  off  = 0U;
    uint32_t  room = 0U;
    ra8_err_t e    = internal_exfat_slice_at(file, file->valid_bytes, &lba, &off, &room);
    if (e != k_ra8_ok) {
      return e;
    }
    const uint64_t gap = file->offset - file->valid_bytes;
    uint32_t       n   = room;
    if (gap < (uint64_t)room) {
      n = (uint32_t)gap;
    }
    e = priv_write_into_sector(file->mount, lba, off, k_zero_sector, n);
    if (e != k_ra8_ok) {
      return e;
    }
    file->valid_bytes += n;
  }
  return k_ra8_ok;
}
 
/* `priv_exfat_write_stream()`: see header for the documented contract. */
ra8_err_t priv_exfat_write_stream(ra8_fs_file_t* file, const uint8_t* buf, uint32_t len)
{
  ra8_err_t e = internal_exfat_close_gap(file);
  if (e != k_ra8_ok) {
    return e;
  }
  uint32_t consumed = 0U;
  while (consumed < len) {
    uint64_t lba  = 0U;
    uint32_t off  = 0U;
    uint32_t room = 0U;
    e             = internal_exfat_slice_at(file, file->offset, &lba, &off, &room);
    if (e != k_ra8_ok) {
      return e;
    }
    uint32_t put = len - consumed;
    if (put > room) {
      put = room;
    }
    e = priv_write_into_sector(file->mount, lba, off, &buf[consumed], put);
    if (e != k_ra8_ok) {
      return e;
    }
    consumed += put;
    file->offset += put;
    if (file->offset > file->valid_bytes) {
      file->valid_bytes = file->offset;
    }
    if (file->offset > file->size_bytes) {
      file->size_bytes = file->offset;
    }
  }
  return k_ra8_ok;
}
 
/* =============================================================================
 * Flush: the entry set says exactly what the volume holds
 * =============================================================================
 */

RA8_INTERNAL
static void internal_exfat_patch_stream(const ra8_fs_file_t* file, uint8_t* strm)
{
  uint8_t  flags = (uint8_t)k_exfat_secflag_poss;
  uint32_t first = 0U;
  if (file->alloc_clusters > 0U) {
    first = file->first_cluster;
    if (file->no_fat_chain != 0U) {
      flags = (uint8_t)k_exfat_secflag_alloc;
    }
  }
  strm[k_exfat_strm_off_flags] = flags;
  priv_wr32(&strm[k_exfat_strm_off_clus], first);
  priv_wr64(&strm[k_exfat_off_strm_valid], file->valid_bytes);
  priv_wr64(&strm[k_exfat_strm_off_dlen], file->size_bytes);
}

RA8_INTERNAL
static ra8_err_t internal_exfat_gather_set(const ra8_fs_file_t* file,
                                           uint8_t*             set,
                                           exfat_setpos_t*      at_file,
                                           exfat_setpos_t*      at_stream)
{
  exfat_cursor_t cur = {.cluster          = file->entry_set_cluster,
                        .entry_in_cluster = file->entry_set_index,
                        .scanned          = 0U};
  for (uint32_t k = 0U; k < file->entry_set_count; k++) {
    const exfat_setpos_t here = {.cluster = cur.cluster, .index = cur.entry_in_cluster};
    const ra8_err_t      e =
      priv_exfat_next_entry(file->mount, &cur, &set[(size_t)k * (size_t)k_exfat_entry_bytes]);
    if (e != k_ra8_ok) {
      return e;
    }
    if (k == 0U) {
      *at_file = here;
    }
    if (k == 1U) {
      *at_stream = here;
    }
  }
  return k_ra8_ok;
}
 
/* `priv_exfat_flush_set()`: see header for the documented contract. */
ra8_err_t priv_exfat_flush_set(ra8_fs_file_t* file)
{
  const ra8_fs_mount_t* m                          = file->mount;
  uint8_t               set[k_exfat_max_set_bytes] = {};
  exfat_setpos_t        at_file                    = {};
  exfat_setpos_t        at_stream                  = {};
  ra8_err_t             e = internal_exfat_gather_set(file, set, &at_file, &at_stream);
  if (e != k_ra8_ok) {
    return e;
  }
  /* Stamp and patch BEFORE the checksum: it covers every byte both touch, so
   * the other order writes a set a host `fsck` rejects (#601). */
  priv_exfat_file_stamp_write(set);
  /* A write also sets the archive attribute (#681): the convention a backup tool
   * clears and the OS re-sets on modification. The low byte of the 16-bit
   * FileAttributes field carries it; the other bits (read-only can never be set
   * on a handle that reached a write) are preserved. */
  set[k_exfat_off_file_attr] =
    (uint8_t)(set[k_exfat_off_file_attr] | (uint8_t)k_exfat_attr_archive);
  internal_exfat_patch_stream(file, &set[k_exfat_entry_bytes]);
  priv_wr16(&set[k_exfat_off_file_csum],
            priv_exfat_set_checksum(set, file->entry_set_count * (uint32_t)k_exfat_entry_bytes));
  e =
    priv_exfat_write_dir_set(m, at_file.cluster, at_file.index, set, (uint32_t)k_exfat_entry_bytes);
  if (e != k_ra8_ok) {
    return e;
  }
  return priv_exfat_write_dir_set(m,
                                  at_stream.cluster,
                                  at_stream.index,
                                  &set[k_exfat_entry_bytes],
                                  (uint32_t)k_exfat_entry_bytes);
}