ra8_fs_fat_time.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"
 
/* =============================================================================
 * Module state -- the installed binding
 * =============================================================================
 */

static ra8_fs_clock_t s_clock;

static bool s_clock_bound;

typedef struct {
  uint16_t date;  
  uint16_t time;  
  uint8_t  tenth; 
} fat_stamp_t;

typedef struct {
  uint32_t stamp; 
  uint8_t  inc10; 
  uint8_t  utc;   
} exfat_stamp_t;
 
/* =============================================================================
 * Clamping
 * =============================================================================
 */

RA8_INTERNAL
static uint32_t internal_clamp_u32(uint32_t v, uint32_t lo, uint32_t hi)
{
  if (v < lo) {
    return lo;
  }
  if (v > hi) {
    return hi;
  }
  return v;
}

RA8_INTERNAL
static void internal_clamp_datetime(ra8_fs_datetime_t* t)
{
  t->year  = (uint16_t)internal_clamp_u32(t->year,
                                          (uint32_t)k_fs_time_epoch_year,
                                          (uint32_t)k_fs_time_year_max);
  t->month = (uint8_t)internal_clamp_u32(t->month,
                                         (uint32_t)k_fs_time_month_min,
                                         (uint32_t)k_fs_time_month_max);
  t->day =
    (uint8_t)internal_clamp_u32(t->day, (uint32_t)k_fs_time_day_min, (uint32_t)k_fs_time_day_max);
  t->hour        = (uint8_t)internal_clamp_u32(t->hour, 0U, (uint32_t)k_fs_time_hour_max);
  t->minute      = (uint8_t)internal_clamp_u32(t->minute, 0U, (uint32_t)k_fs_time_minute_max);
  t->second      = (uint8_t)internal_clamp_u32(t->second, 0U, (uint32_t)k_fs_time_second_max);
  t->centisecond = (uint8_t)internal_clamp_u32(t->centisecond, 0U, (uint32_t)k_fs_time_centi_max);
}

RA8_INTERNAL
static bool internal_now_or_epoch(ra8_fs_datetime_t* out)
{
  *out       = (ra8_fs_datetime_t){};
  out->year  = (uint16_t)k_fs_time_epoch_year;
  out->month = (uint8_t)k_fs_time_month_min;
  out->day   = (uint8_t)k_fs_time_day_min;
  bool real  = false;
  if (s_clock_bound) {
    ra8_fs_datetime_t got = {};
    if (s_clock.now(s_clock.ctx, &got) == k_ra8_ok) {
      *out = got;
      real = true;
    }
  }
  internal_clamp_datetime(out);
  return real;
}
 
/* =============================================================================
 * Packing
 * =============================================================================
 */

RA8_INTERNAL
static uint8_t internal_tenths_of(const ra8_fs_datetime_t* t)
{
  const uint32_t odd = (uint32_t)t->second % (uint32_t)k_fs_time_second_div;
  return (uint8_t)((odd * (uint32_t)k_fs_centi_per_second) + (uint32_t)t->centisecond);
}

RA8_INTERNAL
static uint8_t internal_utc_byte(int16_t minutes)
{
  if (minutes < (int16_t)k_fs_utc_span_min) {
    return (uint8_t)k_fs_utc_unknown;
  }
  if (minutes > (int16_t)k_fs_utc_span_max) {
    return (uint8_t)k_fs_utc_unknown;
  }
  if ((int32_t)minutes % (int32_t)k_fs_utc_step_min != 0) {
    return (uint8_t)k_fs_utc_unknown;
  }
  const int32_t steps = (int32_t)minutes / (int32_t)k_fs_utc_step_min;
  return (uint8_t)((uint32_t)k_fs_utc_valid_bit |
                   ((uint32_t)steps & (uint32_t)k_fs_utc_field_mask));
}

RA8_INTERNAL
static void internal_fat_pack(const ra8_fs_datetime_t* t, fat_stamp_t* out)
{
  const uint32_t years = (uint32_t)t->year - (uint32_t)k_fs_time_epoch_year;
  out->date =
    (uint16_t)((years << (uint32_t)k_fs_date_shift_year) |
               ((uint32_t)t->month << (uint32_t)k_fs_date_shift_month) | (uint32_t)t->day);
  out->time  = (uint16_t)(((uint32_t)t->hour << (uint32_t)k_fs_time_shift_hour) |
                          ((uint32_t)t->minute << (uint32_t)k_fs_time_shift_minute) |
                          ((uint32_t)t->second / (uint32_t)k_fs_time_second_div));
  out->tenth = internal_tenths_of(t);
}

RA8_INTERNAL
static void internal_fat_stamp_now(fat_stamp_t* out)
{
  ra8_fs_datetime_t t = {};
  (void)internal_now_or_epoch(&t); /* FAT has no offset field: real or epoch, same packing */
  internal_fat_pack(&t, out);
}

RA8_INTERNAL
static void internal_exfat_pack(const ra8_fs_datetime_t* t, bool real, exfat_stamp_t* out)
{
  const uint32_t years = (uint32_t)t->year - (uint32_t)k_fs_time_epoch_year;
  const uint32_t date  = (years << (uint32_t)k_fs_xf_shift_year) |
                         ((uint32_t)t->month << (uint32_t)k_fs_xf_shift_month) | (uint32_t)t->day;
  const uint32_t time  = ((uint32_t)t->hour << (uint32_t)k_fs_time_shift_hour) |
                         ((uint32_t)t->minute << (uint32_t)k_fs_time_shift_minute) |
                         ((uint32_t)t->second / (uint32_t)k_fs_time_second_div);
  out->stamp           = (date << (uint32_t)k_fs_xf_shift_date) | time;
  out->inc10           = internal_tenths_of(t);
  /* An offset is a claim about a real instant. The epoch placeholder is not
   * one, so saying "this is UTC" about it would be a fabrication -- exFAT's
   * OffsetValid-clear encoding exists for exactly that case. A caller-supplied
   * `utime` reading IS a real instant, so its offset is honoured. */
  out->utc = real ? internal_utc_byte(t->utc_offset_min) : (uint8_t)k_fs_utc_unknown;
}

RA8_INTERNAL
static void internal_exfat_stamp_now(exfat_stamp_t* out)
{
  ra8_fs_datetime_t t    = {};
  const bool        real = internal_now_or_epoch(&t);
  internal_exfat_pack(&t, real, out);
}
 
/* =============================================================================
 * Stampers -- what the create / write / rename paths call
 * =============================================================================
 */
 
/* `priv_fat_entry_stamp_create()`: see header for the documented contract. */
void priv_fat_entry_stamp_create(uint8_t* entry)
{
  fat_stamp_t s = {};
  internal_fat_stamp_now(&s);
  entry[k_dir_off_crt_time_tenth] = s.tenth;
  priv_wr16(&entry[k_dir_off_crt_time], s.time);
  priv_wr16(&entry[k_dir_off_crt_date], s.date);
  priv_wr16(&entry[k_dir_off_lst_acc_date], s.date);
  priv_wr16(&entry[k_dir_off_wrt_time], s.time);
  priv_wr16(&entry[k_dir_off_wrt_date], s.date);
}
 
/* `priv_fat_entry_stamp_write()`: see header for the documented contract. */
void priv_fat_entry_stamp_write(uint8_t* entry)
{
  fat_stamp_t s = {};
  internal_fat_stamp_now(&s);
  priv_wr16(&entry[k_dir_off_wrt_time], s.time);
  priv_wr16(&entry[k_dir_off_wrt_date], s.date);
  priv_wr16(&entry[k_dir_off_lst_acc_date], s.date);
}
 
/* `priv_fat_entry_stamp_access()`: see header for the documented contract. */
void priv_fat_entry_stamp_access(uint8_t* entry)
{
  fat_stamp_t s = {};
  internal_fat_stamp_now(&s);
  priv_wr16(&entry[k_dir_off_lst_acc_date], s.date);
}
 
/* `priv_exfat_file_stamp_create()`: see header for the documented contract. */
void priv_exfat_file_stamp_create(uint8_t* file_entry)
{
  exfat_stamp_t s = {};
  internal_exfat_stamp_now(&s);
  priv_wr32(&file_entry[k_exfat_off_file_ctime], s.stamp);
  priv_wr32(&file_entry[k_exfat_off_file_mtime], s.stamp);
  priv_wr32(&file_entry[k_exfat_off_file_atime], s.stamp);
  file_entry[k_exfat_off_file_c10ms] = s.inc10;
  file_entry[k_exfat_off_file_m10ms] = s.inc10;
  file_entry[k_exfat_off_file_cutc]  = s.utc;
  file_entry[k_exfat_off_file_mutc]  = s.utc;
  file_entry[k_exfat_off_file_autc]  = s.utc;
}
 
/* `priv_exfat_file_stamp_write()`: see header for the documented contract. */
void priv_exfat_file_stamp_write(uint8_t* file_entry)
{
  exfat_stamp_t s = {};
  internal_exfat_stamp_now(&s);
  priv_wr32(&file_entry[k_exfat_off_file_mtime], s.stamp);
  priv_wr32(&file_entry[k_exfat_off_file_atime], s.stamp);
  file_entry[k_exfat_off_file_m10ms] = s.inc10;
  file_entry[k_exfat_off_file_mutc]  = s.utc;
  file_entry[k_exfat_off_file_autc]  = s.utc;
}
 
/* `priv_exfat_file_stamp_access()`: see header for the documented contract. */
void priv_exfat_file_stamp_access(uint8_t* file_entry)
{
  exfat_stamp_t s = {};
  internal_exfat_stamp_now(&s);
  priv_wr32(&file_entry[k_exfat_off_file_atime], s.stamp);
  file_entry[k_exfat_off_file_autc] = s.utc;
}
 
/* `priv_fat_entry_set_times()`: see header for the documented contract. */
void priv_fat_entry_set_times(uint8_t*                 entry,
                              const ra8_fs_datetime_t* create,
                              const ra8_fs_datetime_t* modify,
                              const ra8_fs_datetime_t* access)
{
  if (create != nullptr) {
    ra8_fs_datetime_t t = *create;
    internal_clamp_datetime(&t);
    fat_stamp_t s = {};
    internal_fat_pack(&t, &s);
    entry[k_dir_off_crt_time_tenth] = s.tenth;
    priv_wr16(&entry[k_dir_off_crt_time], s.time);
    priv_wr16(&entry[k_dir_off_crt_date], s.date);
  }
  if (modify != nullptr) {
    ra8_fs_datetime_t t = *modify;
    internal_clamp_datetime(&t);
    fat_stamp_t s = {};
    internal_fat_pack(&t, &s);
    priv_wr16(&entry[k_dir_off_wrt_time], s.time);
    priv_wr16(&entry[k_dir_off_wrt_date], s.date);
  }
  if (access != nullptr) {
    ra8_fs_datetime_t t = *access;
    internal_clamp_datetime(&t);
    fat_stamp_t s = {};
    internal_fat_pack(&t, &s);
    priv_wr16(&entry[k_dir_off_lst_acc_date], s.date);
  }
}
 
/* `priv_exfat_file_set_times()`: see header for the documented contract. */
void priv_exfat_file_set_times(uint8_t*                 file_entry,
                               const ra8_fs_datetime_t* create,
                               const ra8_fs_datetime_t* modify,
                               const ra8_fs_datetime_t* access)
{
  if (create != nullptr) {
    ra8_fs_datetime_t t = *create;
    internal_clamp_datetime(&t);
    exfat_stamp_t s = {};
    internal_exfat_pack(&t, true, &s);
    priv_wr32(&file_entry[k_exfat_off_file_ctime], s.stamp);
    file_entry[k_exfat_off_file_c10ms] = s.inc10;
    file_entry[k_exfat_off_file_cutc]  = s.utc;
  }
  if (modify != nullptr) {
    ra8_fs_datetime_t t = *modify;
    internal_clamp_datetime(&t);
    exfat_stamp_t s = {};
    internal_exfat_pack(&t, true, &s);
    priv_wr32(&file_entry[k_exfat_off_file_mtime], s.stamp);
    file_entry[k_exfat_off_file_m10ms] = s.inc10;
    file_entry[k_exfat_off_file_mutc]  = s.utc;
  }
  if (access != nullptr) {
    ra8_fs_datetime_t t = *access;
    internal_clamp_datetime(&t);
    exfat_stamp_t s = {};
    internal_exfat_pack(&t, true, &s);
    priv_wr32(&file_entry[k_exfat_off_file_atime], s.stamp);
    file_entry[k_exfat_off_file_autc] = s.utc;
  }
}
 
/* =============================================================================
 * Public API: clock binding
 * =============================================================================
 */
 
ra8_err_t ra8_fs_set_clock(const ra8_fs_clock_t* clock)
{
  if (clock == nullptr) {
    s_clock_bound = false;
    s_clock       = (ra8_fs_clock_t){};
    return k_ra8_ok;
  }
  if (clock->now == nullptr) {
    return k_ra8_err_invalid_arg;
  }
  s_clock       = *clock;
  s_clock_bound = true;
  return k_ra8_ok;
}