ra8_fs_fat_name.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"

typedef enum : uint16_t {
  k_lfn_space        = 0x20U, 
  k_lfn_del          = 0x7FU, 
  k_case_seen_upper  = 0x01U, 
  k_case_seen_lower  = 0x02U, 
  k_case_seen_mixed  = 0x03U, 
  k_alias_radix      = 10U,   
  k_alias_digits_max = 6U,    
} ra8_fs_name_local_t;
 
/* =============================================================================
 * 8.3 short name pack / unpack
 * =============================================================================
 */

/* `priv_to_upper()`: see header for the documented contract. */
char priv_to_upper(char c)
{
  if (c >= 'a' && c <= 'z') {
    return (char)(c - 'a' + 'A');
  }
  return c;
}

RA8_INTERNAL
static uint8_t internal_pack_base(const char** path_io, uint8_t* out11)
{
  const char* path     = *path_io;
  uint8_t     base_len = 0;
  while (*path != '\0' && *path != '.') {
    if (base_len >= k_filename_base_len) {
      return 0U;
    }
    if ((uint32_t)(unsigned char)*path > (uint32_t)k_lfn_del) {
      return 0U; /* a packed 8.3 name here is ASCII; a UTF-8 byte is not one */
    }
    out11[base_len++] = (uint8_t)priv_to_upper(*path++);
  }
  if (base_len == 0U) {
    return 0U;
  }
  *path_io = path;
  return 1U;
}

RA8_INTERNAL
static uint8_t internal_pack_ext(const char* path, uint8_t* out11)
{
  if (*path != '.') {
    return 1U;
  }
  path++;
  uint32_t ext_len = 0U;
  while (*path != '\0') {
    if (ext_len >= (uint32_t)k_filename_ext_len) {
      return 0U;
    }
    if ((uint32_t)(unsigned char)*path > (uint32_t)k_lfn_del) {
      return 0U; /* as in the base: an 8.3 field never holds a UTF-8 byte */
    }
    out11[k_filename_base_len + ext_len] = (uint8_t)priv_to_upper(*path++);
    ext_len++;
  }
  return 1U;
}
 
/* `priv_path_to_83()`: see header for the documented contract. */
uint8_t priv_path_to_83(const char* path, uint8_t* out11)
{
  if (path == nullptr || out11 == nullptr) {
    return 0U;
  }
  while (*path == '/') {
    path++;
  }
  for (uint32_t i = 0; i < (uint32_t)k_max_8_3_name; i++) {
    out11[i] = ' ';
  }
  if (internal_pack_base(&path, out11) == 0U) {
    return 0U;
  }
  if (internal_pack_ext(path, out11) == 0U) {
    return 0U;
  }
  /* No kanji escape on the way IN. It used to sit here, mapping a packed 0xE5
   * first byte to 0x05 -- but both packers now refuse every byte above DEL, so
   * no input can produce one, and a branch nothing reaches is not a safety net.
   * The escape still matters on the way OUT, where ::priv_83_to_str() restores
   * it for a volume some Shift-JIS system wrote. */
  return 1U;
}

RA8_INTERNAL
static char internal_case_apply(char c, uint8_t lower)
{
  if (lower == 0U) {
    return c;
  }
  if ((c >= 'A') && (c <= 'Z')) {
    /* Arithmetic in an unsigned type, not on the chars themselves (MISRA 10.2
     * forbids + / - on essentially-character operands), and the cast lands on
     * a plain object rather than on the composite expression (MISRA 10.8). */
    const uint32_t lowered = (uint32_t)c + ((uint32_t)'a' - (uint32_t)'A');
    return (char)lowered;
  }
  return c;
}
 
/* `priv_83_to_str()`: see header for the documented contract. */
void priv_83_to_str(const uint8_t* in11, uint8_t ntres, char* out13)
{
  const uint8_t base_lower = (uint8_t)(ntres & (uint8_t)k_ntres_base_lower);
  const uint8_t ext_lower  = (uint8_t)(ntres & (uint8_t)k_ntres_ext_lower);
  uint32_t      i          = 0;
  uint32_t      j          = 0;
  for (i = 0; i < (uint32_t)k_filename_base_len; i++) {
    if (in11[i] == ' ') {
      break;
    }
    out13[j++] = internal_case_apply((char)in11[i], base_lower);
  }
  /* Restore kanji escape. */
  if (in11[0] == (uint8_t)k_dir_marker_kanji_e5) {
    out13[0] = (char)k_dir_marker_free_used;
  }
  uint8_t has_ext = 0;
  for (i = 0; i < k_filename_ext_len; i++) {
    if (in11[k_filename_base_len + i] != ' ') {
      has_ext = 1;
      break;
    }
  }
  if (has_ext != 0U) {
    out13[j++] = '.';
    for (i = 0; i < k_filename_ext_len; i++) {
      if (in11[k_filename_base_len + i] == ' ') {
        break;
      }
      out13[j++] = internal_case_apply((char)in11[k_filename_base_len + i], ext_lower);
    }
  }
  out13[j] = '\0';
}
 
/* =============================================================================
 * Long-name classification -- which on-disk shape a leaf component needs
 * =============================================================================
 */

RA8_INTERNAL
static uint8_t internal_unit_in_set(uint16_t u, const char* set)
{
  for (uint32_t i = 0U; i < (uint32_t)k_lfn_write_max; i++) {
    if (set[i] == '\0') {
      return 0U;
    }
    if ((uint32_t)(unsigned char)set[i] == (uint32_t)u) {
      return 1U;
    }
  }
  /* Unreachable: both sets are single-digit literals, so the NUL above always
   * ends the scan first. This is the Rule 2 bound's exit, not a second answer. */
  return 0U; /* GCOVR_EXCL_LINE -- arith/string invariants make fallback unreachable */
}

RA8_INTERNAL
static uint8_t internal_unit_is_lfn_legal(uint16_t u)
{
  /* Microsoft FAT specification section 7 ("Long File Name Implementation"):
   * the long name inherits the short name's illegal set minus the characters
   * VFAT deliberately allows (`+ , ; = [ ]` and space). Control characters are
   * excluded by range below, not by this table. Block scope because exactly
   * one function reads it (MISRA 8.9). */
  static const char lfn_illegal[] = "\"*/:<>?\\|";
 
  const uint32_t v = (uint32_t)u;
  if (v < (uint32_t)k_lfn_space) {
    return 0U; /* control characters, including the NUL that ends the name */
  }
  if (v == (uint32_t)k_lfn_del) {
    return 0U; /* DEL is a control code wherever it appears */
  }
  if (internal_unit_in_set(u, lfn_illegal) != 0U) {
    return 0U;
  }
  return 1U;
}

RA8_INTERNAL
static uint8_t internal_unit_is_83_legal(uint16_t u)
{
  /* Microsoft FAT specification section 6.1 ("Name Limitations"). A leaf
   * containing any of these is representable only as a long name, however
   * short it is -- `my file.txt` is eight characters of base and still cannot
   * be an 8.3 name, because of the space. Block scope: one reader (MISRA 8.9). */
  static const char sfn_extra_illegal[] = "+,;=[] ";
 
  if ((uint32_t)u > (uint32_t)k_lfn_del) {
    return 0U;
  }
  if (u == (uint16_t)(unsigned char)'.') {
    return 0U;
  }
  if (internal_unit_in_set(u, sfn_extra_illegal) != 0U) {
    return 0U;
  }
  return 1U;
}

RA8_INTERNAL
static uint32_t internal_name_dot_index(const uint16_t* leaf, uint32_t n)
{
  uint32_t dot = n;
  for (uint32_t i = 0U; i < n; i++) {
    if (leaf[i] == (uint16_t)(unsigned char)'.') {
      dot = i;
    }
  }
  return dot;
}

RA8_INTERNAL
static uint8_t internal_name_is_83(const uint16_t* leaf, uint32_t n)
{
  const uint32_t dot      = internal_name_dot_index(leaf, n);
  const uint32_t base_len = dot;
  if ((base_len == 0U) || (base_len > (uint32_t)k_filename_base_len)) {
    return 0U;
  }
  if (dot < n) {
    const uint32_t ext_len = (n - dot) - 1U;
    if ((ext_len == 0U) || (ext_len > (uint32_t)k_filename_ext_len)) {
      return 0U;
    }
  }
  for (uint32_t i = 0U; i < n; i++) {
    if (i == dot) {
      continue;
    }
    if (internal_unit_is_83_legal(leaf[i]) == 0U) {
      return 0U;
    }
  }
  return 1U;
}

RA8_INTERNAL
static void internal_case_observe(const uint16_t* leaf, uint32_t from, uint32_t to, uint8_t* seen)
{
  for (uint32_t i = from; i < to; i++) {
    const uint32_t c = (uint32_t)leaf[i];
    if ((c >= (uint32_t)'A') && (c <= (uint32_t)'Z')) {
      *seen |= (uint8_t)k_case_seen_upper;
    } else if ((c >= (uint32_t)'a') && (c <= (uint32_t)'z')) {
      *seen |= (uint8_t)k_case_seen_lower;
    } else {
      /* Digits and punctuation carry no case; they constrain nothing. */
    }
  }
}

RA8_INTERNAL
static ra8_fs_name_kind_t
internal_name_case_kind(const uint16_t* leaf, uint32_t n, uint8_t* out_ntres)
{
  const uint32_t dot       = internal_name_dot_index(leaf, n);
  uint8_t        base_seen = 0U;
  uint8_t        ext_seen  = 0U;
  internal_case_observe(leaf, 0U, dot, &base_seen);
  if (dot < n) {
    internal_case_observe(leaf, dot + 1U, n, &ext_seen);
  }
  *out_ntres = 0U;
  if (base_seen == (uint8_t)k_case_seen_mixed) {
    return k_name_kind_long;
  }
  if (ext_seen == (uint8_t)k_case_seen_mixed) {
    return k_name_kind_long;
  }
  if (base_seen == (uint8_t)k_case_seen_lower) {
    *out_ntres |= (uint8_t)k_ntres_base_lower;
  }
  if (ext_seen == (uint8_t)k_case_seen_lower) {
    *out_ntres |= (uint8_t)k_ntres_ext_lower;
  }
  return k_name_kind_short;
}
 
/* `priv_name_classify()`: see header for the documented contract. */
ra8_fs_name_kind_t priv_name_classify(const char* leaf,
                                      uint16_t*   out_units,
                                      uint32_t*   out_nunits,
                                      uint8_t*    out83,
                                      uint8_t*    out_ntres)
{
  if ((leaf == nullptr) || (out_units == nullptr) || (out_nunits == nullptr)) {
    return k_name_kind_invalid;
  }
  if ((out83 == nullptr) || (out_ntres == nullptr)) {
    return k_name_kind_invalid;
  }
  *out_ntres = 0U;
  /* The decode is where a malformed name dies -- an over-long sequence, a raw
   * surrogate, a truncated one -- and the unit count it produces is the length
   * every on-disk structure below counts in. A byte count is neither (#606). */
  uint32_t n = 0U;
  if (priv_utf8_to_utf16(leaf, out_units, (uint32_t)k_lfn_write_max, &n) != k_ra8_ok) {
    *out_nunits = 0U;
    return k_name_kind_invalid;
  }
  *out_nunits = n;
  if (n == 0U) {
    return k_name_kind_invalid;
  }
  for (uint32_t i = 0U; i < n; i++) {
    if (internal_unit_is_lfn_legal(out_units[i]) == 0U) {
      return k_name_kind_invalid;
    }
  }
  if (internal_name_is_83(out_units, n) == 0U) {
    return k_name_kind_long;
  }
  if (priv_path_to_83(leaf, out83) == 0U) {
    /* Unreachable: priv_name_is_83() already proved the base and extension
     * lengths priv_path_to_83() checks. Kept because the two functions are
     * separately maintained and a silent disagreement would create an
     * unpacked name. */
    return k_name_kind_long; /* GCOVR_EXCL_LINE -- string invariants make fallback unreachable */
  }
  return internal_name_case_kind(out_units, n, out_ntres);
}
 
/* =============================================================================
 * Basis-name generation -- the `LONGNA~1.TXT` alias a long name is filed under
 * =============================================================================
 */

RA8_INTERNAL
static uint8_t internal_alias_map_unit(uint16_t u)
{
  if ((uint32_t)u > (uint32_t)k_lfn_del) {
    return (uint8_t)'_';
  }
  const char up = priv_to_upper((char)(unsigned char)u);
  if (internal_unit_is_83_legal((uint16_t)(unsigned char)up) == 0U) {
    return (uint8_t)'_';
  }
  return (uint8_t)up;
}

RA8_INTERNAL
static uint32_t
internal_alias_collect(const uint16_t* leaf, uint32_t from, uint32_t to, uint32_t cap, uint8_t* out)
{
  uint32_t got = 0U;
  for (uint32_t i = from; (i < to) && (got < cap); i++) {
    const uint16_t u = leaf[i];
    if ((u == (uint16_t)(unsigned char)' ') || (u == (uint16_t)(unsigned char)'.')) {
      continue;
    }
    out[got] = internal_alias_map_unit(u);
    got++;
  }
  return got;
}

RA8_INTERNAL
static uint32_t internal_alias_ext_dot(const uint16_t* leaf, uint32_t n)
{
  uint32_t dot = n;
  for (uint32_t i = 1U; (i + 1U) < n; i++) {
    if (leaf[i] == (uint16_t)(unsigned char)'.') {
      dot = i;
    }
  }
  return dot;
}

RA8_INTERNAL
static uint32_t internal_alias_digits(uint32_t tail)
{
  uint32_t digits = 1U;
  uint32_t scale  = (uint32_t)k_alias_radix;
  /* Bounded by the six-digit cap the alias probe never exceeds. */
  while ((digits < (uint32_t)k_alias_digits_max) && (tail >= scale)) {
    digits++;
    scale *= (uint32_t)k_alias_radix;
  }
  return digits;
}
 
/* `priv_lfn_alias_basis()`: see header for the documented contract. */
void priv_lfn_alias_basis(const uint16_t* leaf, uint32_t n, uint32_t tail, uint8_t* out11)
{
  for (uint32_t i = 0U; i < (uint32_t)k_max_8_3_name; i++) {
    out11[i] = ' ';
  }
  const uint32_t dot                       = internal_alias_ext_dot(leaf, n);
  uint8_t        base[k_filename_base_len] = {};
  uint32_t base_len = internal_alias_collect(leaf, 0U, dot, (uint32_t)k_filename_base_len, base);
  if (base_len == 0U) {
    base[0]  = (uint8_t)'_'; /* a name of nothing but dots and spaces */
    base_len = 1U;
  }
  if (dot < n) {
    (void)internal_alias_collect(leaf,
                                 dot + 1U,
                                 n,
                                 (uint32_t)k_filename_ext_len,
                                 &out11[k_filename_base_len]);
  }
  const uint32_t digits = internal_alias_digits(tail);
  uint32_t       keep   = ((uint32_t)k_filename_base_len - digits) - 1U;
  if (base_len < keep) {
    keep = base_len;
  }
  for (uint32_t i = 0U; i < keep; i++) {
    out11[i] = base[i];
  }
  out11[keep]   = (uint8_t)'~';
  uint32_t rest = tail;
  for (uint32_t d = 0U; d < digits; d++) {
    const uint32_t digit       = rest % (uint32_t)k_alias_radix;
    out11[(keep + digits) - d] = (uint8_t)((uint32_t)'0' + digit);
    rest /= (uint32_t)k_alias_radix;
  }
  /* No kanji escape is needed here: every byte written above is an upper-case
   * ASCII letter, a digit, '_', '~' or a space, and none of those is 0xE5. */
}
 
/* =============================================================================
 * Directory walking
 * =============================================================================
 */

RA8_INTERNAL
static void internal_dir_walk_init_root(const ra8_fs_mount_t* m, dir_walk_t* w)
{
  if (m->type == k_ra8_fs_type_fat32) {
    w->is_root_fixed     = 0;
    w->fixed_remaining   = 0;
    w->cluster           = m->root_cluster;
    w->sector_in_cluster = 0;
    w->cur_lba           = priv_cluster_to_lba(m, w->cluster);
  } else {
    const uint32_t root_dir_sectors =
      ((m->root_entries * k_ra8_fs_dir_entry_bytes) + (priv_bps(m) - 1U)) / priv_bps(m);
    w->is_root_fixed     = 1;
    w->fixed_remaining   = root_dir_sectors;
    w->cluster           = 0;
    w->sector_in_cluster = 0;
    w->cur_lba           = m->first_root_lba;
  }
  w->entry_idx    = 0;
  w->cluster_hops = 0;
}
 
/* `priv_dir_walk_init_loc()`: see header for the documented contract. */
void priv_dir_walk_init_loc(const ra8_fs_mount_t* m, const dir_loc_t* loc, dir_walk_t* w)
{
  if (loc->is_root != 0U) {
    internal_dir_walk_init_root(m, w);
    return;
  }
  w->is_root_fixed     = 0;
  w->fixed_remaining   = 0;
  w->cluster           = loc->cluster;
  w->sector_in_cluster = 0;
  w->cur_lba           = priv_cluster_to_lba(m, loc->cluster);
  w->entry_idx         = 0;
  w->cluster_hops      = 0;
}
 
/* `priv_dir_walk_next_sector()`: see header for the documented contract. */
ra8_err_t priv_dir_walk_next_sector(const ra8_fs_mount_t* m, dir_walk_t* w, uint8_t* out_eod)
{
  *out_eod = 0;
  if (w->is_root_fixed != 0U) {
    if (w->fixed_remaining <= 1U) {
      *out_eod = 1;
      return k_ra8_ok;
    }
    w->fixed_remaining--;
    w->cur_lba++;
    w->entry_idx = 0;
    return k_ra8_ok;
  }
  /* FAT32 cluster-chain root. */
  w->sector_in_cluster++;
  if (w->sector_in_cluster >= m->sectors_per_cluster) {
    uint32_t  next = 0;
    ra8_err_t err  = priv_fat_get(m, w->cluster, &next);
    if (err != k_ra8_ok) {
      return err;
    }
    if (priv_is_eoc(m, next) != 0U) {
      *out_eod = 1;
      return k_ra8_ok;
    }
    /* Cycle guard (NASA Rule 2): a healthy chain visits at most
     * count_of_clusters distinct clusters; more means a corrupt loop. */
    w->cluster_hops++;
    if (w->cluster_hops > m->count_of_clusters) {
      return k_ra8_err_protocol_error;
    }
    w->cluster           = next;
    w->sector_in_cluster = 0;
    w->cur_lba           = priv_cluster_to_lba(m, w->cluster);
  } else {
    w->cur_lba++;
  }
  w->entry_idx = 0;
  return k_ra8_ok;
}
 
/* `priv_dir_find()`: see header for the documented contract. */
ra8_err_t priv_dir_find(const ra8_fs_mount_t* m,
                        const dir_loc_t*      loc,
                        const uint8_t*        name83,
                        uint64_t*             out_lba,
                        uint32_t*             out_entry_off,
                        uint8_t               out_entry[k_ra8_fs_dir_entry_bytes])
{
  dir_walk_t w = {};
  priv_dir_walk_init_loc(m, loc, &w);
  uint8_t        eod = 0;
  uint8_t* const buf = priv_sec_walk();
  while (eod == 0U) {
    ra8_err_t err = priv_read_sector(m, w.cur_lba, buf);
    if (err != k_ra8_ok) {
      return err;
    }
    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 k_ra8_err_not_found;
      }
      if (ent[k_dir_off_name] == k_dir_marker_free_used) {
        continue;
      }
      if (ent[k_dir_off_attr] == k_ra8_fs_attr_lfn) {
        continue;
      }
      if (priv_byte_equal(ent, name83, k_dir_name_field_len) != 0U) {
        *out_lba       = w.cur_lba;
        *out_entry_off = e * (uint32_t)k_ra8_fs_dir_entry_bytes;
        priv_byte_copy(out_entry, ent, k_ra8_fs_dir_entry_bytes);
        return k_ra8_ok;
      }
    }
    err = priv_dir_walk_next_sector(m, &w, &eod);
    if (err != k_ra8_ok) {
      return err;
    }
  }
  return k_ra8_err_not_found;
}