ra8_fs_fat_fileio.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: read / write / seek / tell / size
 * =============================================================================
 */

RA8_INTERNAL
static ra8_err_t
internal_skip_clusters(const ra8_fs_mount_t* m, uint32_t start, uint32_t n, uint32_t* out)
{
  uint32_t cur = start;
  for (uint32_t i = 0; i < n; i++) {
    uint32_t  next = 0;
    ra8_err_t err  = priv_fat_get(m, cur, &next);
    if (err != k_ra8_ok) {
      return err;
    }
    if (priv_is_eoc(m, next) != 0U) {
      *out = cur;
      return k_ra8_err_invalid_state;
    }
    cur = next;
  }
  *out = cur;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t
internal_read_one_chunk(ra8_fs_file_t* file, uint8_t* buf, uint32_t remaining, uint32_t* out_take)
{
  const uint32_t cluster_bytes   = priv_cluster_bytes(file->mount);
  const uint32_t cluster_idx_now = (uint32_t)(file->offset / cluster_bytes);
  uint32_t       target          = 0;
  /* exFAT contiguous files (NoFatChain) have no valid FAT chain: clusters are
   * sequential from the first. FAT files (no_fat_chain == 0) walk the chain. */
  if (file->no_fat_chain != 0U) {
    target = file->first_cluster + cluster_idx_now;
  } else {
    /* Read accelerator: a sequential read advances the offset one cluster at a
     * time, so resume the FAT walk from the cached forward waypoint instead of
     * re-walking from the chain head on every sector -- O(n) over a file, not the
     * O(n^2) a per-sector walk-from-head would cost. The cache holds a valid chain
     * position (walk_cache_cluster at walk_cache_idx); use it only when it is set
     * (a real data cluster) AND the target is at or ahead of it, else walk from
     * the head.
     *
     * @par MC/DC:
     * Decision: `(walk_cache_cluster >= k_cluster_first_data) && (cluster_idx_now
     *            >= walk_cache_idx)` (2 conditions)
     * - cache set, target ahead   -> true  (resume from waypoint)
     * - cache unset (cluster < 2)  -> false (first condition independent)
     * - cache set, target behind   -> false (second condition independent; a
     *                                 backward seek re-walks from the head)
     */
    uint32_t walk_from = file->first_cluster;
    uint32_t walk_n    = cluster_idx_now;
    if ((file->walk_cache_cluster >= (uint32_t)k_cluster_first_data) &&
        (cluster_idx_now >= file->walk_cache_idx)) {
      walk_from = file->walk_cache_cluster;
      walk_n    = cluster_idx_now - file->walk_cache_idx;
    }
    ra8_err_t werr = internal_skip_clusters(file->mount, walk_from, walk_n, &target);
    if (werr != k_ra8_ok) {
      return werr;
    }
    file->walk_cache_idx     = cluster_idx_now;
    file->walk_cache_cluster = target;
  }
  file->cur_cluster                 = target;
  const uint32_t  off_in_cluster    = (uint32_t)(file->offset % cluster_bytes);
  const uint32_t  sector_in_cluster = off_in_cluster / priv_bps(file->mount);
  const uint32_t  off_in_sector     = off_in_cluster % priv_bps(file->mount);
  const uint64_t  lba = priv_cluster_to_lba(file->mount, file->cur_cluster) + sector_in_cluster;
  uint8_t* const  sec = priv_sec_io();
  const ra8_err_t err = priv_read_sector(file->mount, lba, sec);
  if (err != k_ra8_ok) {
    return err;
  }
  uint32_t take = priv_bps(file->mount) - off_in_sector;
  if (take > remaining) {
    take = remaining;
  }
  priv_byte_copy(buf, &sec[off_in_sector], take);
  *out_take = take;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t
internal_read_span(ra8_fs_file_t* file, uint8_t* buf, uint32_t remaining, uint32_t* out_take)
{
  const uint64_t valid =
    (file->mount->type == k_ra8_fs_type_exfat) ? file->valid_bytes : file->size_bytes;
  if (file->offset >= valid) {
    for (uint32_t i = 0U; i < remaining; i++) {
      buf[i] = 0U;
    }
    *out_take = remaining;
    return k_ra8_ok;
  }
  uint32_t       want = remaining;
  const uint64_t cap  = valid - file->offset;
  if ((uint64_t)want > cap) {
    want = (uint32_t)cap;
  }
  return internal_read_one_chunk(file, buf, want, out_take);
}

RA8_INTERNAL
RA8_EXPECTS_LOCK("ra8_fs_lock")
static ra8_err_t
internal_read_locked(ra8_fs_file_t* file, uint8_t* buf, uint32_t max_len, uint32_t* got_len)
{
  if (file == nullptr || buf == nullptr || got_len == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (file->in_use == 0U) {
    return k_ra8_err_invalid_state;
  }
  *got_len = 0;
  if (file->offset >= file->size_bytes || max_len == 0U) {
    return k_ra8_ok;
  }
  const uint64_t left      = file->size_bytes - file->offset;
  uint32_t       remaining = max_len;
  if ((uint64_t)max_len > left) {
    remaining = (uint32_t)left;
  }
  uint32_t produced = 0;
  while (remaining > 0U) {
    uint32_t  take = 0;
    ra8_err_t err  = internal_read_span(file, &buf[produced], remaining, &take);
    if (err != k_ra8_ok) {
      return err;
    }
    produced += take;
    file->offset += take;
    remaining -= take;
  }
  *got_len = produced;
  return k_ra8_ok;
}
 
/* `priv_alloc_eoc_cluster()`: see header for the documented contract. */
ra8_err_t priv_alloc_eoc_cluster(const ra8_fs_mount_t* m, uint32_t* out_c)
{
  ra8_err_t err = priv_alloc_cluster(m, out_c);
  if (err != k_ra8_ok) {
    return err;
  }
  return priv_fat_set(m, *out_c, priv_eoc_write(m));
}

RA8_INTERNAL
static ra8_err_t
internal_walk_grow(const ra8_fs_mount_t* m, uint32_t start, uint32_t idx, uint32_t* out_cluster)
{
  uint32_t cur = start;
  for (uint32_t i = 0; i < idx; i++) {
    uint32_t  next = 0;
    ra8_err_t err  = priv_fat_get(m, cur, &next);
    if (err != k_ra8_ok) {
      return err;
    }
    if (priv_is_eoc(m, next) != 0U) {
      uint32_t newc = 0;
      err           = priv_alloc_eoc_cluster(m, &newc);
      if (err != k_ra8_ok) {
        return err;
      }
      err = priv_fat_set(m, cur, newc);
      if (err != k_ra8_ok) {
        return err;
      }
      next = newc;
    }
    cur = next;
  }
  *out_cluster = cur;
  return k_ra8_ok;
}

ra8_err_t priv_write_into_sector(const ra8_fs_mount_t* m,
                                 uint64_t              lba,
                                 uint32_t              off_in_sector,
                                 const uint8_t*        src,
                                 uint32_t              put)
{
  uint8_t* const sec = priv_sec_io();
  ra8_err_t      err = priv_read_sector(m, lba, sec);
  if (err != k_ra8_ok) {
    return err;
  }
  priv_byte_copy(&sec[off_in_sector], src, put);
  return priv_write_sector(m, lba, sec);
}

typedef struct {
  uint32_t cluster; 
  uint32_t index;   
} write_walk_t;

RA8_INTERNAL
static ra8_err_t
internal_write_position(ra8_fs_file_t* file, write_walk_t* way, uint32_t idx, uint32_t* out_cluster)
{
  const ra8_fs_mount_t* m = file->mount;
  if (file->first_cluster < k_cluster_first_data) {
    uint32_t        c   = 0;
    const ra8_err_t err = priv_alloc_eoc_cluster(m, &c);
    if (err != k_ra8_ok) {
      return err;
    }
    file->first_cluster = c;
    file->cur_cluster   = c;
    way->cluster        = c;
    way->index          = idx;
  }
  uint32_t        cur = 0;
  const ra8_err_t err = internal_walk_grow(m, way->cluster, idx - way->index, &cur);
  if (err != k_ra8_ok) {
    return err;
  }
  way->cluster = cur;
  way->index   = idx;
  *out_cluster = cur;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t internal_write_stream(ra8_fs_file_t* file, const uint8_t* buf, uint32_t len)
{
  const ra8_fs_mount_t* m             = file->mount;
  const uint32_t        cluster_bytes = priv_cluster_bytes(m);
  uint32_t              consumed      = 0;
  /* A write may allocate/grow the chain, invalidating any cached read waypoint. */
  file->walk_cache_cluster = 0;
  write_walk_t way         = {.cluster = file->first_cluster, .index = 0U};
  while (consumed < len) {
    const uint32_t cluster_idx_now = (uint32_t)(file->offset / cluster_bytes);
    uint32_t       cur             = 0;
    ra8_err_t      err             = internal_write_position(file, &way, cluster_idx_now, &cur);
    if (err != k_ra8_ok) {
      return err;
    }
    file->cur_cluster                = cur;
    const uint32_t off_in_cluster    = (uint32_t)(file->offset % cluster_bytes);
    const uint32_t sector_in_cluster = off_in_cluster / priv_bps(m);
    const uint32_t off_in_sector     = off_in_cluster % priv_bps(m);
    const uint64_t lba = priv_cluster_to_lba(m, file->cur_cluster) + sector_in_cluster;
    uint32_t       put = priv_bps(m) - off_in_sector;
    if (put > (len - consumed)) {
      put = len - consumed;
    }
    err = priv_write_into_sector(m, lba, off_in_sector, &buf[consumed], put);
    if (err != k_ra8_ok) {
      return err;
    }
    consumed += put;
    file->offset += put;
    if (file->offset > file->size_bytes) {
      file->size_bytes = file->offset;
    }
  }
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_EXPECTS_LOCK("ra8_fs_lock")
static ra8_err_t internal_write_locked(ra8_fs_file_t* file, const uint8_t* buf, uint32_t len)
{
  if (file == nullptr || buf == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (file->in_use == 0U || file->mode == k_ra8_fs_mode_read) {
    return k_ra8_err_invalid_state;
  }
  if (len == 0U) {
    return k_ra8_ok;
  }
  if (file->mount->type == k_ra8_fs_type_exfat) {
    const ra8_err_t xe = priv_exfat_write_stream(file, buf, len);
    if (xe != k_ra8_ok) {
      return xe;
    }
    file->dirty = 1U;
    return priv_exfat_flush_set(file);
  }
  /* The FAT boundary of #676: `DIR_FileSize` is 32-bit, so a write that would
   * push the file past 4 GiB - 1 cannot be recorded and is refused whole --
   * truncating the count silently would corrupt the entry on the next flush.
   * exFAT never reaches this test (its branch returned above). */
  if (len > ((uint64_t)k_ra8_fs_fat_max_file_bytes - file->offset)) {
    return k_ra8_err_invalid_size;
  }
  ra8_err_t err = internal_write_stream(file, buf, len);
  if (err != k_ra8_ok) {
    return err;
  }
  const ra8_fs_mount_t* m      = file->mount;
  uint8_t* const        dirsec = priv_sec_walk();
  err                          = priv_read_sector(m, file->dir_entry_lba, dirsec);
  if (err != k_ra8_ok) {
    return err;
  }
  priv_entry_set_cluster_size(&dirsec[file->dir_entry_idx],
                              file->first_cluster,
                              (uint32_t)file->size_bytes);
  /* The contents just changed, so the modification time has to move with them
   * (#601). Doing it here as well as at close means a writer that is cut off
   * mid-stream still leaves an mtime describing what is actually on the card,
   * rather than whatever a PC wrote when it created the file. */
  priv_fat_entry_stamp_write(&dirsec[file->dir_entry_idx]);
  /* Same reason the archive attribute rides along: the file was modified, which
   * is exactly what the bit records (#681). */
  priv_fat_entry_apply_attr(&dirsec[file->dir_entry_idx], (uint8_t)k_ra8_fs_attr_archive, 0U);
  file->dirty = 1U;
  return priv_write_sector(m, file->dir_entry_lba, dirsec);
}

RA8_INTERNAL
RA8_EXPECTS_LOCK("ra8_fs_lock")
static ra8_err_t internal_write_file_locked(ra8_fs_mount_t* handle,
                                            const char*     path,
                                            const uint8_t*  data,
                                            uint32_t        len)
{
  if (handle == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (path == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (data == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (handle->in_use == 0U) {
    return k_ra8_err_invalid_state;
  }
  ra8_fs_file_t* f = nullptr;
  ra8_err_t      e = priv_open_locked(handle, path, k_ra8_fs_mode_write, &f);
  if (e != k_ra8_ok) {
    return e;
  }
  e                    = internal_write_locked(f, data, len);
  const ra8_err_t cerr = priv_close_locked(f);
  if (e != k_ra8_ok) {
    return e;
  }
  return cerr;
}

RA8_INTERNAL
RA8_EXPECTS_LOCK("ra8_fs_lock")
static ra8_err_t internal_seek_locked(ra8_fs_file_t* file, uint64_t offset_bytes)
{
  if (file == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (file->in_use == 0U) {
    return k_ra8_err_invalid_state;
  }
  uint64_t target = offset_bytes;
  if (target > file->size_bytes) {
    target = file->size_bytes;
  }
  file->offset = target;
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_EXPECTS_LOCK("ra8_fs_lock")
static ra8_err_t internal_tell_locked(const ra8_fs_file_t* file, uint64_t* out_offset)
{
  if (file == nullptr || out_offset == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (file->in_use == 0U) {
    return k_ra8_err_invalid_state;
  }
  *out_offset = file->offset;
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_EXPECTS_LOCK("ra8_fs_lock")
static ra8_err_t internal_size_locked(const ra8_fs_file_t* file, uint64_t* out_bytes)
{
  if (file == nullptr || out_bytes == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (file->in_use == 0U) {
    return k_ra8_err_invalid_state;
  }
  *out_bytes = file->size_bytes;
  return k_ra8_ok;
}
 
/* =============================================================================
 * Public entry points -- the lock brackets
 * =============================================================================
 */
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_read(ra8_fs_file_t* file, uint8_t* buf, uint32_t max_len, uint32_t* got_len)
{
  priv_lock_acquire();
  const ra8_err_t err = internal_read_locked(file, buf, max_len, got_len);
  priv_lock_release();
  return err;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_write(ra8_fs_file_t* file, const uint8_t* buf, uint32_t len)
{
  priv_lock_acquire();
  const ra8_err_t err = internal_write_locked(file, buf, len);
  priv_lock_release();
  return err;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t
ra8_fs_write_file(ra8_fs_mount_t* handle, const char* path, const uint8_t* data, uint32_t len)
{
  priv_lock_acquire();
  const ra8_err_t err = internal_write_file_locked(handle, path, data, len);
  priv_lock_release();
  return err;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_seek(ra8_fs_file_t* file, uint64_t offset_bytes)
{
  priv_lock_acquire();
  const ra8_err_t err = internal_seek_locked(file, offset_bytes);
  priv_lock_release();
  return err;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_tell(const ra8_fs_file_t* file, uint64_t* out_offset)
{
  priv_lock_acquire();
  const ra8_err_t err = internal_tell_locked(file, out_offset);
  priv_lock_release();
  return err;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_size(const ra8_fs_file_t* file, uint64_t* out_bytes)
{
  priv_lock_acquire();
  const ra8_err_t err = internal_size_locked(file, out_bytes);
  priv_lock_release();
  return err;
}