ra8_fs_fat_dir.c

Go to the documentation of this file.

 
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "ra8_attributes.h"
#include "ra8_fs.h"
#include "ra8_fs_fat_internal.h"

typedef struct {
  ra8_fs_mount_t* mount;        
  dir_walk_t      fat_walk;     
  lfn_state_t     fat_lfn;      
  exfat_cursor_t  exfat_cursor; 
  bool            finished;     
} ra8_fs_dir_private_t;
 
static_assert(sizeof(ra8_fs_dir_private_t) <= (size_t)k_ra8_fs_dir_state_bytes,
              "ra8_fs directory cursor state exceeds public storage");
static_assert(alignof(ra8_fs_dir_private_t) <= alignof(uint64_t),
              "ra8_fs directory cursor state alignment exceeds public storage");
 
/* =============================================================================
 * Public API: listdir / unlink
 * =============================================================================
 */

RA8_INTERNAL
static uint8_t internal_listdir_visit_sector(const ra8_fs_mount_t* m,
                                             const uint8_t*        buf,
                                             lfn_state_t*          lfn,
                                             ra8_fs_listdir_cb_t   cb,
                                             void*                 ctx)
{
  for (uint32_t e = 0; e < priv_dir_eps(m); e++) {
    const uint8_t* ent = &buf[(size_t)e * (size_t)k_ra8_fs_dir_entry_bytes];
    if (ent[k_dir_off_name] == k_dir_marker_free_perm) {
      return 1U;
    }
    if (ent[k_dir_off_name] == k_dir_marker_free_used) {
      priv_lfn_reset(lfn); /* a deleted slot breaks any in-progress chain */
      continue;
    }
    if (ent[k_dir_off_attr] == k_ra8_fs_attr_lfn) {
      priv_lfn_add(lfn, ent);
      continue;
    }
    if (ent[k_dir_off_name] == k_dir_marker_dot) {
      priv_lfn_reset(lfn); /* synthetic "." / ".." -- not reported to the caller */
      continue;
    }
    /* +1 for the NUL: a maximal 8.3 name "12345678.123" is 12 chars, and
     * priv_83_to_str writes the terminator at index 12 -- without the slack
     * that store overflows the buffer and corrupts the adjacent `ent` pointer,
     * mismatching the LFN checksum so the long name is dropped (matches the
     * `+ 1U` sizing already used in ra8_fs_fat_file.c). */
    char short_name[(uint32_t)k_ra8_fs_short_name_len + 1U] = {};
    /* The NTRes case flags come along: an entry this driver wrote for
     * `data.log` stores `DATA    LOG` with both flags set, and reporting it as
     * `DATA.LOG` would lose the caller's own name for no reason (#600). */
    priv_83_to_str(&ent[k_dir_off_name], ent[k_dir_off_ntres], short_name);
    /* Report the VFAT long name when the preceding chain matches; else the 8.3.
     * The chain is UTF-16 on disk and UTF-8 at this boundary, and a chain that
     * does not convert -- an unpaired surrogate, which nothing conforming
     * writes -- falls back to the alias rather than being reported under a name
     * that would not re-open it (#606). */
    char            lname[k_lfn_utf8_cap] = {};
    uint32_t        lnunits               = 0U;
    const uint16_t* lunits                = priv_lfn_units_for(lfn, &ent[k_dir_off_name], &lnunits);
    uint8_t         have_long             = 0U;
    if (lunits != nullptr) {
      have_long = (priv_utf16_to_utf8(lunits, lnunits, lname, (uint32_t)k_lfn_utf8_cap) == k_ra8_ok)
                    ? 1U
                    : 0U;
    }
    const uint32_t size = priv_rd32(&ent[k_dir_off_file_size]);
    cb((have_long != 0U) ? lname : short_name, ent[k_dir_off_attr], size, ctx);
    priv_lfn_reset(lfn);
  }
  return 0U;
}

RA8_INTERNAL
RA8_EXPECTS_LOCK("ra8_fs_lock")
static ra8_err_t internal_listdir_locked(const ra8_fs_mount_t* handle,
                                         const char*           path,
                                         ra8_fs_listdir_cb_t   cb,
                                         void*                 ctx)
{
  if (handle == nullptr || cb == nullptr || path == 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) {
    /* Any exFAT directory, not just the root (#605). A path that names nothing
     * reports not_found and one that names a FILE reports invalid_arg, which is
     * what the FAT side has always answered -- the two filesystems no longer
     * disagree about what "list this path" means. */
    exfat_dir_t     dir  = {};
    const ra8_err_t xerr = priv_exfat_resolve_dir(handle, path, &dir);
    if (xerr != k_ra8_ok) {
      return xerr;
    }
    return priv_exfat_listdir(handle, &dir, cb, ctx);
  }
  dir_loc_t       loc  = {};
  const ra8_err_t rerr = priv_resolve_dir(handle, path, &loc);
  if (rerr != k_ra8_ok) {
    return rerr;
  }
  dir_walk_t w = {};
  priv_dir_walk_init_loc(handle, &loc, &w);
  lfn_state_t lfn = {}; /* persists across sectors -- LFN chains can straddle them */
  priv_lfn_reset(&lfn);
  uint8_t        eod = 0;
  uint8_t* const buf = priv_sec_walk();
  while (eod == 0U) {
    ra8_err_t err = priv_read_sector(handle, w.cur_lba, buf);
    if (err != k_ra8_ok) {
      return err;
    }
    if (internal_listdir_visit_sector(handle, buf, &lfn, cb, ctx) != 0U) {
      return k_ra8_ok;
    }
    err = priv_dir_walk_next_sector(handle, &w, &eod);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  return k_ra8_ok;
}
 
RA8_EXPECTS_LOCK("ra8_fs_lock")
RA8_INTERNAL static ra8_err_t internal_fat_dir_advance_sector(ra8_fs_dir_private_t* state)
{
  uint8_t         end  = 0U;
  const ra8_err_t step = priv_dir_walk_next_sector(state->mount, &state->fat_walk, &end);
  if (end != 0U) {
    state->finished = true;
  }
  return step;
}
 
RA8_EXPECTS_LOCK("ra8_fs_lock")
RA8_INTERNAL static void internal_fat_dir_scan_sector(ra8_fs_dir_private_t* state,
                                                      const uint8_t*        sector,
                                                      ra8_fs_dirent_t*      out,
                                                      bool*                 out_entry)
{
  while (state->fat_walk.entry_idx < priv_bps(state->mount)) {
    const uint8_t* entry = &sector[state->fat_walk.entry_idx];
    state->fat_walk.entry_idx += (uint32_t)k_ra8_fs_dir_entry_bytes;
    if (entry[k_dir_off_name] == k_dir_marker_free_perm) {
      state->finished = true;
      return;
    }
    if (entry[k_dir_off_name] == k_dir_marker_free_used) {
      priv_lfn_reset(&state->fat_lfn);
      continue;
    }
    if (entry[k_dir_off_attr] == k_ra8_fs_attr_lfn) {
      priv_lfn_add(&state->fat_lfn, entry);
      continue;
    }
    if (entry[k_dir_off_name] == k_dir_marker_dot) {
      priv_lfn_reset(&state->fat_lfn);
      continue;
    }
    char short_name[(uint32_t)k_ra8_fs_short_name_len + 1U] = {};
    char long_name[k_lfn_utf8_cap]                          = {};
    priv_83_to_str(&entry[k_dir_off_name], entry[k_dir_off_ntres], short_name);
    uint32_t        units = 0U;
    const uint16_t* name_units =
      priv_lfn_units_for(&state->fat_lfn, &entry[k_dir_off_name], &units);
    const char* name = short_name;
    if (name_units != nullptr) {
      if (priv_utf16_to_utf8(name_units, units, long_name, (uint32_t)sizeof(long_name)) ==
          k_ra8_ok) {
        name = long_name;
      }
    }
    (void)memcpy(out->name, name, strlen(name) + 1U);
    out->attr       = entry[k_dir_off_attr];
    out->size_bytes = (uint64_t)priv_rd32(&entry[k_dir_off_file_size]);
    priv_lfn_reset(&state->fat_lfn);
    *out_entry = true;
    return;
  }
}
 
RA8_EXPECTS_LOCK("ra8_fs_lock")
RA8_INTERNAL static ra8_err_t
internal_fat_dir_next(ra8_fs_dir_private_t* state, ra8_fs_dirent_t* out, bool* out_entry)
{
  *out_entry = false;
  while (!state->finished) {
    if (state->fat_walk.entry_idx >= priv_bps(state->mount)) {
      const ra8_err_t step = internal_fat_dir_advance_sector(state);
      if (step != k_ra8_ok) {
        return step;
      }
      if (state->finished) {
        return k_ra8_ok;
      }
    }
    uint8_t* const  sector = priv_sec_walk();
    const ra8_err_t err    = priv_read_sector(state->mount, state->fat_walk.cur_lba, sector);
    if (err != k_ra8_ok) {
      return err;
    }
    internal_fat_dir_scan_sector(state, sector, out, out_entry);
    if (*out_entry || state->finished) {
      return k_ra8_ok;
    }
  }
  return k_ra8_ok;
}
 
RA8_EXPECTS_LOCK("ra8_fs_lock")
RA8_INTERNAL static ra8_err_t
internal_dir_open_locked(ra8_fs_mount_t* handle, const char* path, ra8_fs_dir_private_t* state)
{
  if (handle->in_use == 0U) {
    return k_ra8_err_invalid_state;
  }
  *state        = (ra8_fs_dir_private_t){.mount = handle};
  ra8_err_t err = k_ra8_ok;
  if (handle->type == k_ra8_fs_type_exfat) {
    exfat_dir_t dir = {};
    err             = priv_exfat_resolve_dir(handle, path, &dir);
    if (err == k_ra8_ok) {
      priv_exfat_cursor_init(&dir, &state->exfat_cursor);
    }
  } else {
    dir_loc_t location = {};
    err                = priv_resolve_dir(handle, path, &location);
    if (err == k_ra8_ok) {
      priv_dir_walk_init_loc(handle, &location, &state->fat_walk);
      priv_lfn_reset(&state->fat_lfn);
    }
  }
  return err;
}

RA8_INTERNAL
static ra8_err_t internal_unlink_locate(const ra8_fs_mount_t* handle,
                                        const char*           path,
                                        dir_target_t*         out,
                                        uint32_t*             out_cluster)
{
  const char*     leaf = nullptr;
  const ra8_err_t rerr = priv_resolve_parent(handle, path, &out->parent, &leaf);
  if (rerr != k_ra8_ok) {
    return rerr;
  }
  const ra8_err_t err =
    priv_dir_lookup_any(handle, &out->parent, leaf, &out->lba, &out->off, out->entry);
  if (err != k_ra8_ok) {
    return err;
  }
  /* The lookup matches on the name alone, so a directory matches like any
   * other entry. Freeing its chain orphans every file inside it -- their
   * clusters stay allocated in the FAT with nothing referencing them, which
   * fsck.fat reports as lost clusters (#604). */
  if ((out->entry[k_dir_off_attr] & (uint8_t)k_ra8_fs_attr_directory) != 0U) {
    return k_ra8_err_invalid_arg; /* a directory: ra8_fs_rmdir() is the verb */
  }
  /* Honor the read-only attribute (#681): a file a host marked read-only is not
   * deletable through the ordinary path, matching DOS/Windows `del`. Refused
   * before priv_free_chain() touches the FAT, so a denied unlink changes nothing. */
  if ((out->entry[k_dir_off_attr] & (uint8_t)k_ra8_fs_attr_read_only) != 0U) {
    return k_ra8_err_access_denied;
  }
  *out_cluster = priv_entry_first_cluster(out->entry);
  return k_ra8_ok;
}

RA8_INTERNAL
RA8_EXPECTS_LOCK("ra8_fs_lock")
static ra8_err_t internal_unlink_locked(const ra8_fs_mount_t* handle, const char* path)
{
  if (handle == nullptr || path == 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_unlink(handle, path);
  }
  dir_target_t    t       = {};
  uint32_t        cluster = 0;
  const ra8_err_t lerr    = internal_unlink_locate(handle, path, &t, &cluster);
  if (lerr != k_ra8_ok) {
    return lerr;
  }
  if (cluster >= (uint32_t)k_cluster_first_data) {
    const ra8_err_t ferr = priv_free_chain(handle, cluster);
    if (ferr != k_ra8_ok) {
      return ferr;
    }
  }
  /* The whole chain, not only the 8.3 entry: clearing one slot left the file's
   * long-name entries on disk with a checksum nothing matched, which fsck.fat
   * and chkdsk both report as orphans (#600). */
  return priv_dir_erase_chain(handle, &t.parent, t.lba, t.off, &t.entry[k_dir_off_name]);
}

RA8_INTERNAL
static ra8_err_t internal_rename_prepare(const ra8_fs_mount_t* handle,
                                         const char*           old_path,
                                         const char*           new_path,
                                         dir_loc_t*            out_parent,
                                         const char**          out_old,
                                         const char**          out_new)
{
  dir_loc_t   op = {};
  const char* ol = nullptr;
  ra8_err_t   e1 = priv_resolve_parent(handle, old_path, &op, &ol);
  if (e1 != k_ra8_ok) {
    return e1;
  }
  dir_loc_t   np = {};
  const char* nl = nullptr;
  ra8_err_t   e2 = priv_resolve_parent(handle, new_path, &np, &nl);
  if (e2 != k_ra8_ok) {
    return e2;
  }
  if (op.is_root != np.is_root) {
    return k_ra8_err_not_supported;
  }
  if (op.is_root == 0U) {
    if (op.cluster != np.cluster) {
      return k_ra8_err_not_supported;
    }
  }
  *out_parent = op;
  *out_old    = ol;
  *out_new    = nl;
  return k_ra8_ok;
}

RA8_INTERNAL
static ra8_err_t
internal_fat_rename(const ra8_fs_mount_t* handle, const char* old_path, const char* new_path)
{
  dir_target_t t    = {};
  const char*  ol   = nullptr;
  const char*  nl   = nullptr;
  ra8_err_t    perr = internal_rename_prepare(handle, old_path, new_path, &t.parent, &ol, &nl);
  if (perr != k_ra8_ok) {
    return perr;
  }
  uint64_t dup_lba                       = 0U;
  uint32_t dup_off                       = 0U;
  uint8_t  dup[k_ra8_fs_dir_entry_bytes] = {};
  if (priv_dir_lookup_any(handle, &t.parent, nl, &dup_lba, &dup_off, dup) == k_ra8_ok) {
    return k_ra8_err_exists;
  }
  ra8_err_t err = priv_dir_lookup_any(handle, &t.parent, ol, &t.lba, &t.off, t.entry);
  if (err != k_ra8_ok) {
    return err;
  }
  /* Honor the read-only attribute (#681): a read-only file is refused before any
   * new entry is filed or the old chain is erased, so the directory is untouched. */
  if ((t.entry[k_dir_off_attr] & (uint8_t)k_ra8_fs_attr_read_only) != 0U) {
    return k_ra8_err_access_denied;
  }
  dir_insert_t plan = {};
  err               = priv_dir_reserve(handle, &t.parent, nl, &plan);
  if (err != k_ra8_ok) {
    return err;
  }
  /* Access date only, deliberately. A rename changes the name, not the bytes,
   * so advancing DIR_WrtDate would tell every rsync, backup and "newest image"
   * OTA heuristic that the contents changed -- the same class of false signal
   * #601 exists to remove, only inverted. FAT has no metadata-change field, so
   * the access date is the honest record that the entry was touched. It goes on
   * the template BEFORE the commit, because since #600 a rename writes a new
   * entry rather than editing the old one in place. */
  priv_fat_entry_stamp_access(t.entry);
  uint64_t new_lba = 0U;
  uint32_t new_off = 0U;
  err              = priv_dir_commit(handle, &plan, t.entry, &new_lba, &new_off);
  if (err != k_ra8_ok) {
    return err;
  }
  return priv_dir_erase_chain(handle, &t.parent, t.lba, t.off, &t.entry[k_dir_off_name]);
}

RA8_INTERNAL
RA8_EXPECTS_LOCK("ra8_fs_lock")
static ra8_err_t
internal_rename_locked(const ra8_fs_mount_t* handle, const char* old_path, const char* new_path)
{
  if (handle == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (old_path == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (new_path == 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_rename(handle, old_path, new_path);
  }
  return internal_fat_rename(handle, old_path, new_path);
}
 
/* =============================================================================
 * Public entry points -- the lock brackets
 * =============================================================================
 */
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t
ra8_fs_listdir(const ra8_fs_mount_t* handle, const char* path, ra8_fs_listdir_cb_t cb, void* ctx)
{
  priv_lock_acquire();
  const ra8_err_t err = internal_listdir_locked(handle, path, cb, ctx);
  priv_lock_release();
  return err;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_dir_open(ra8_fs_mount_t* handle, const char* path, ra8_fs_dir_t* directory)
{
  if (handle == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (path == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (directory == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (directory->is_open) {
    return k_ra8_err_busy;
  }
  void*                       state_memory = directory->state;
  ra8_fs_dir_private_t* const state        = state_memory;
  priv_lock_acquire();
  const ra8_err_t err = internal_dir_open_locked(handle, path, state);
  priv_lock_release();
  if (err == k_ra8_ok) {
    directory->is_open = true;
  } else {
    (void)memset(directory->state, 0, sizeof(directory->state));
  }
  return err;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_dir_next(ra8_fs_dir_t* directory, ra8_fs_dirent_t* out, bool* out_entry)
{
  if (directory == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (out == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (out_entry == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (!directory->is_open) {
    return k_ra8_err_invalid_state;
  }
  *out                                     = (ra8_fs_dirent_t){};
  *out_entry                               = false;
  void*                       state_memory = directory->state;
  ra8_fs_dir_private_t* const state        = state_memory;
  priv_lock_acquire();
  ra8_err_t err = (state->mount->in_use != 0U) ? k_ra8_ok : k_ra8_err_invalid_state;
  if (err == k_ra8_ok) {
    if (!state->finished) {
      if (state->mount->type == k_ra8_fs_type_exfat) {
        err = priv_exfat_dir_next(state->mount, &state->exfat_cursor, out, out_entry);
      } else {
        err = internal_fat_dir_next(state, out, out_entry);
      }
    }
  }
  if (err == k_ra8_ok) {
    if (!*out_entry) {
      state->finished = true;
    }
  }
  priv_lock_release();
  return err;
}
 
ra8_err_t ra8_fs_dir_close(ra8_fs_dir_t* directory)
{
  if (directory == nullptr) {
    return k_ra8_err_null_ptr;
  }
  if (!directory->is_open) {
    return k_ra8_err_invalid_state;
  }
  *directory = (ra8_fs_dir_t){};
  return k_ra8_ok;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_unlink(const ra8_fs_mount_t* handle, const char* path)
{
  priv_lock_acquire();
  const ra8_err_t err = internal_unlink_locked(handle, path);
  priv_lock_release();
  return err;
}
 
RA8_OWNS_RESOURCE("ra8_fs_lock")
ra8_err_t ra8_fs_rename(const ra8_fs_mount_t* handle, const char* old_path, const char* new_path)
{
  priv_lock_acquire();
  const ra8_err_t err = internal_rename_locked(handle, old_path, new_path);
  priv_lock_release();
  return err;
}