ra8_fs_fat_file.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: open / close
 * =============================================================================
 */
 
/* `priv_entry_first_cluster()`: see header for the documented contract. */
uint32_t priv_entry_first_cluster(const uint8_t* entry)
{
  const uint32_t hi = priv_rd16(&entry[k_dir_off_fst_clus_hi]);
  const uint32_t lo = priv_rd16(&entry[k_dir_off_fst_clus_lo]);
  return (hi << k_shift_two_bytes) | lo;
}
 
/* `priv_entry_set_cluster_size()`: see header for the documented contract. */
void priv_entry_set_cluster_size(uint8_t* entry, uint32_t cluster, uint32_t size)
{
  priv_wr16(&entry[k_dir_off_fst_clus_hi],
            (uint16_t)((cluster >> k_shift_two_bytes) & k_word_mask));
  priv_wr16(&entry[k_dir_off_fst_clus_lo], (uint16_t)(cluster & k_word_mask));
  priv_wr32(&entry[k_dir_off_file_size], size);
}
 
/* `priv_fat_entry_apply_attr()`: see header for the documented contract. */
void priv_fat_entry_apply_attr(uint8_t* entry, uint8_t set_mask, uint8_t clear_mask)
{
  const uint8_t attr    = entry[k_dir_off_attr];
  entry[k_dir_off_attr] = (uint8_t)((uint8_t)(attr & (uint8_t)~clear_mask) | (uint8_t)set_mask);
}

RA8_INTERNAL
static ra8_err_t internal_truncate_existing(const ra8_fs_mount_t* handle,
                                            ra8_fs_file_t*        f,
                                            uint64_t              lba,
                                            uint32_t              off)
{
  if (f->first_cluster >= k_cluster_first_data) {
    ra8_err_t err = priv_free_chain(handle, f->first_cluster);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  f->first_cluster      = 0;
  f->cur_cluster        = 0;
  f->walk_cache_idx     = 0;
  f->walk_cache_cluster = 0; /* < 2: no read cache for a fresh file */
  f->size_bytes         = 0;
  f->offset             = 0;
  uint8_t* const buf    = priv_sec_walk();
  ra8_err_t      err    = priv_read_sector(handle, lba, buf);
  if (err != k_ra8_ok) {
    return err;
  }
  priv_entry_set_cluster_size(&buf[off], 0, 0);
  /* Truncation IS a content change -- the file went from N bytes to zero -- so
   * the modification time has to move even if the caller never writes a byte
   * afterwards. Without this, `open(write)` + `close()` left a PC-authored
   * mtime describing contents that no longer exist (#601). */
  priv_fat_entry_stamp_write(&buf[off]);
  /* A content change also sets the archive attribute, the FAT/exFAT convention a
   * backup tool clears and the OS re-sets on every modification (#681). */
  priv_fat_entry_apply_attr(&buf[off], (uint8_t)k_ra8_fs_attr_archive, 0U);
  return priv_write_sector(handle, lba, buf);
}

RA8_INTERNAL
static ra8_err_t internal_open_existing(ra8_fs_mount_t* handle,
                                        const uint8_t*  entry,
                                        uint64_t        lba,
                                        uint32_t        off,
                                        ra8_fs_mode_t   mode,
                                        ra8_fs_file_t** out_file)
{
  /* A directory is not a file (#604). Without this the write path ran
   * priv_truncate_existing() on it -- freeing the chain that held every child
   * and stamping cluster 0 / size 0 into an entry still flagged ATTR_DIRECTORY
   * -- and the read path handed back a zero-byte handle, because a directory's
   * DIR_FileSize is 0 by specification. Rejected for every mode, before the
   * file slot is allocated, so a refused open consumes nothing. */
  if ((entry[k_dir_off_attr] & (uint8_t)k_ra8_fs_attr_directory) != 0U) {
    return k_ra8_err_invalid_arg;
  }
  /* Honor the read-only attribute (#681). A writing open truncates or appends,
   * so a file a host marked read-only must be refused BEFORE the slot is taken
   * and BEFORE priv_truncate_existing() frees its chain -- the DOS/Windows
   * semantics say `open(read-only, write)` is denied, not silently obeyed. A
   * read open is untouched: reading a read-only file is exactly what the bit
   * permits. */
  if ((mode != k_ra8_fs_mode_read) &&
      ((entry[k_dir_off_attr] & (uint8_t)k_ra8_fs_attr_read_only) != 0U)) {
    return k_ra8_err_access_denied;
  }
  ra8_fs_file_t* f = priv_alloc_file_slot();
  if (f == nullptr) {
    return k_ra8_err_no_mem;
  }
  f->mount              = handle;
  f->first_cluster      = priv_entry_first_cluster(entry);
  f->cur_cluster        = f->first_cluster;
  f->walk_cache_idx     = 0U; /* read accelerator seeded at the chain head */
  f->walk_cache_cluster = f->first_cluster;
  f->size_bytes         = priv_rd32(&entry[k_dir_off_file_size]);
  f->dir_entry_lba      = lba;
  f->dir_entry_idx      = off;
  f->mode               = mode;
  f->no_fat_chain       = 0U;
  f->dirty              = 0U;
  f->in_use             = 1;
  if (mode == k_ra8_fs_mode_write) {
    ra8_err_t err = internal_truncate_existing(handle, f, lba, off);
    if (err != k_ra8_ok) {
      f->in_use = 0;
      return err;
    }
  } else if (mode == k_ra8_fs_mode_append) {
    f->offset = f->size_bytes;
  } else {
    f->offset = 0;
  }
  *out_file = f;
  return k_ra8_ok;
}

RA8_INTERNAL
static void internal_init_new_file(ra8_fs_file_t*  f,
                                   ra8_fs_mount_t* handle,
                                   ra8_fs_mode_t   mode,
                                   uint64_t        free_lba,
                                   uint32_t        free_off)
{
  f->mount              = handle;
  f->first_cluster      = 0;
  f->cur_cluster        = 0;
  f->walk_cache_idx     = 0;
  f->walk_cache_cluster = 0; /* < 2: no read cache for a fresh file */
  f->size_bytes         = 0;
  f->offset             = 0;
  f->dir_entry_lba      = free_lba;
  f->dir_entry_idx      = free_off;
  f->mode               = mode;
  f->no_fat_chain       = 0U;
  f->dirty              = 0U;
  f->in_use             = 1;
}

typedef enum : uint32_t {
  k_path_max_depth = 32U, 
} ra8_fs_path_cap_t;

RA8_INTERNAL
static ra8_err_t internal_enter_subdir(const ra8_fs_mount_t* m,
                                       const dir_loc_t*      cur,
                                       const char*           comp,
                                       uint32_t              len,
                                       dir_loc_t*            out)
{
  /* A BYTE bound, because the component is UTF-8 here: the unit-count limit is
   * ::k_lfn_write_max and lands in priv_name_classify(). Bounding the bytes by
   * the unit cap would refuse a perfectly storable name three characters into
   * a Cyrillic directory (#606). */
  if (len >= (uint32_t)k_lfn_utf8_cap) {
    return k_ra8_err_invalid_arg;
  }
  /* Sized for a long name, not an 8.3 one: once `mkdir` can create
   * `/Reading List`, every path THROUGH it has to resolve as well, and a
   * 13-byte buffer would have refused the component before the lookup. */
  char namebuf[k_lfn_utf8_cap] = {};
  for (uint32_t i = 0; i < len; i++) {
    namebuf[i] = comp[i];
  }
  namebuf[len]                              = '\0';
  uint64_t  lba                             = 0;
  uint32_t  off                             = 0;
  uint8_t   entry[k_ra8_fs_dir_entry_bytes] = {};
  ra8_err_t err = priv_dir_lookup_any(m, cur, namebuf, &lba, &off, entry);
  if (err != k_ra8_ok) {
    return err;
  }
  if ((entry[k_dir_off_attr] & k_ra8_fs_attr_directory) == 0U) {
    return k_ra8_err_invalid_arg;
  }
  const uint32_t cl = priv_entry_first_cluster(entry);
  if (cl < (uint32_t)k_cluster_first_data) {
    return k_ra8_err_protocol_error;
  }
  out->is_root = 0U;
  out->cluster = cl;
  return k_ra8_ok;
}
 
/* `priv_resolve_parent()`: see header for the documented contract. */
ra8_err_t priv_resolve_parent(const ra8_fs_mount_t* m,
                              const char*           path,
                              dir_loc_t*            out_parent,
                              const char**          out_leaf)
{
  const char* p = path;
  while (*p == '/') {
    p++;
  }
  dir_loc_t cur = {.is_root = 1U, .cluster = 0U};
  for (uint32_t depth = 0; depth < (uint32_t)k_path_max_depth; depth++) {
    const char* end = p;
    while (*end != '\0') {
      if (*end == '/') {
        break;
      }
      end++;
    }
    if (*end == '\0') {
      *out_parent = cur;
      *out_leaf   = p;
      return k_ra8_ok;
    }
    dir_loc_t       next = {};
    const ra8_err_t err  = internal_enter_subdir(m, &cur, p, (uint32_t)(end - p), &next);
    if (err != k_ra8_ok) {
      return err;
    }
    cur = next;
    p   = end;
    while (*p == '/') {
      p++;
    }
  }
  return k_ra8_err_invalid_arg; /* deeper than k_path_max_depth */
}
 
/* `priv_resolve_dir()`: see header for the documented contract. */
ra8_err_t priv_resolve_dir(const ra8_fs_mount_t* m, const char* path, dir_loc_t* out)
{
  const char* p = path;
  while (*p == '/') {
    p++;
  }
  if (*p == '\0') {
    out->is_root = 1U;
    out->cluster = 0U;
    return k_ra8_ok;
  }
  dir_loc_t       parent = {};
  const char*     leaf   = nullptr;
  const ra8_err_t err    = priv_resolve_parent(m, path, &parent, &leaf);
  if (err != k_ra8_ok) {
    return err;
  }
  uint32_t len = 0;
  while (leaf[len] != '\0') {
    len++;
  }
  if (len == 0U) {
    *out = parent; /* trailing slash: the parent is the directory */
    return k_ra8_ok;
  }
  return internal_enter_subdir(m, &parent, leaf, len, out);
}

RA8_INTERNAL
static ra8_err_t internal_create_new(ra8_fs_mount_t*  handle,
                                     const dir_loc_t* parent,
                                     const char*      leaf,
                                     ra8_fs_mode_t    mode,
                                     ra8_fs_file_t**  out_file)
{
  dir_insert_t plan = {};
  ra8_err_t    err  = priv_dir_reserve(handle, parent, leaf, &plan);
  if (err != k_ra8_ok) {
    return err;
  }
  ra8_fs_file_t* f = priv_alloc_file_slot();
  if (f == nullptr) {
    return k_ra8_err_no_mem;
  }
  uint8_t tmpl[k_ra8_fs_dir_entry_bytes] = {};
  tmpl[k_dir_off_attr]                   = (uint8_t)k_ra8_fs_attr_archive;
  priv_entry_set_cluster_size(tmpl, 0U, 0U);
  /* The template is zero-filled above, and a zero FAT date is not a date: month
   * and day are both 1-based, so 0x0000 claims month 0 of day 0 and every host
   * decodes it differently (#601). Stamped here rather than inside
   * `priv_dir_commit()` because that same commit re-files an EXISTING entry for
   * `rename`, which must keep the creation date it already has. */
  priv_fat_entry_stamp_create(tmpl);
  uint64_t lba = 0;
  uint32_t off = 0;
  err          = priv_dir_commit(handle, &plan, tmpl, &lba, &off);
  if (err != k_ra8_ok) {
    return err;
  }
  internal_init_new_file(f, handle, mode, lba, off);
  *out_file = f;
  return k_ra8_ok;
}
 
/* `priv_open_locked()`: see header for the documented contract. */
ra8_err_t priv_open_locked(ra8_fs_mount_t* handle,
                           const char*     path,
                           ra8_fs_mode_t   mode,
                           ra8_fs_file_t** out_file)
{
  if (handle == nullptr || path == nullptr || out_file == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (handle->in_use == 0U) {
    return k_ra8_err_invalid_state;
  }
  if (handle->type == k_ra8_fs_type_exfat) {
    return priv_exfat_open(handle, path, mode, out_file);
  }
  dir_loc_t       parent = {};
  const char*     leaf   = nullptr;
  const ra8_err_t rerr   = priv_resolve_parent(handle, path, &parent, &leaf);
  if (rerr != k_ra8_ok) {
    return rerr;
  }
  uint64_t        lba                             = 0;
  uint32_t        off                             = 0;
  uint8_t         entry[k_ra8_fs_dir_entry_bytes] = {};
  const ra8_err_t err = priv_dir_lookup_any(handle, &parent, leaf, &lba, &off, entry);
  if (err == k_ra8_ok) {
    return internal_open_existing(handle, entry, lba, off, mode, out_file);
  }
  if (err != k_ra8_err_not_found) {
    return err;
  }
  if (mode == k_ra8_fs_mode_read) {
    return k_ra8_err_not_found;
  }
  /* Creation no longer needs an 8.3-representable name: `priv_dir_reserve()`
   * generates the alias and reserves the chain's slots (#600). */
  return internal_create_new(handle, &parent, leaf, mode, out_file);
}

RA8_INTERNAL
static ra8_err_t internal_close_stamp(ra8_fs_file_t* file)
{
  const ra8_fs_mount_t* m = file->mount;
  /* exFAT keeps its metadata in a checksummed entry set, not one 32-byte
   * directory entry, so the close flush is the same commit every write already
   * performs -- stamp, patch, checksum, write (#602). */
  if (m->type == k_ra8_fs_type_exfat) {
    return priv_exfat_flush_set(file);
  }
  uint8_t* const sec = priv_sec_walk();
  ra8_err_t      err = priv_read_sector(m, file->dir_entry_lba, sec);
  if (err != k_ra8_ok) {
    return err;
  }
  priv_fat_entry_stamp_write(&sec[file->dir_entry_idx]);
  err = priv_write_sector(m, file->dir_entry_lba, sec);
  if (err != k_ra8_ok) {
    return err;
  }
  return priv_fsinfo_flush(m);
}
 
/* `priv_close_locked()`: see header for the documented contract. */
ra8_err_t priv_close_locked(ra8_fs_file_t* file)
{
  if (file == nullptr) {
    return k_ra8_err_null_ptr;
  }
  ra8_err_t err = k_ra8_ok;
  /* Never touch the volume through a handle that is already closed or whose
   * mount has gone: the dir-entry LBA would be read against a mount slot that
   * now describes some other card. */
  if ((file->dirty != 0U) && (file->in_use != 0U) && (file->mount != nullptr) &&
      (file->mount->in_use != 0U)) {
    err = internal_close_stamp(file);
  }
  file->dirty  = 0;
  file->in_use = 0;
  file->mount  = nullptr;
  return err;
}
 
/* =============================================================================
 * Public entry points -- the lock brackets
 * =============================================================================
 */
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t
ra8_fs_open(ra8_fs_mount_t* handle, const char* path, ra8_fs_mode_t mode, ra8_fs_file_t** out_file)
{
  priv_lock_acquire();
  const ra8_err_t err = priv_open_locked(handle, path, mode, out_file);
  priv_lock_release();
  return err;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_close(ra8_fs_file_t* file)
{
  priv_lock_acquire();
  const ra8_err_t err = priv_close_locked(file);
  priv_lock_release();
  return err;
}