board_periph_sd_format.c

Go to the documentation of this file.

 
#include <string.h>
 
#include "board_periph_sd_internal.h"
#include "emu_host_io_internal.h"
 
/* ----------------------------------------------------------------------------
 * Blank-card creation (--sd-new): format an empty FAT volume in sparse storage so a
 * size/format can be set up with no pre-built image. The BPB is complete enough
 * to satisfy a host `fsck_msdos` and the firmware's ra8_fs mount alike.
 * --------------------------------------------------------------------------*/

typedef enum : uint8_t {
  k_le_byte0     = 0U,    
  k_le_byte1     = 1U,    
  k_le_byte2     = 2U,    
  k_le_byte3     = 3U,    
  k_le_shift_b1  = 8U,    
  k_le_shift_b2  = 16U,   
  k_le_shift_b3  = 24U,   
  k_le_byte_mask = 0xFFU, 
} sd_le_const_t;

RA8_INTERNAL static void internal_sd_put16(uint8_t* p, uint16_t v)
{
  p[k_le_byte0] = (uint8_t)(v & (uint16_t)k_le_byte_mask);
  p[k_le_byte1] = (uint8_t)((v >> (uint16_t)k_le_shift_b1) & (uint16_t)k_le_byte_mask);
}

RA8_INTERNAL static void internal_sd_put32(uint8_t* p, uint32_t v)
{
  p[k_le_byte0] = (uint8_t)(v & (uint32_t)k_le_byte_mask);
  p[k_le_byte1] = (uint8_t)((v >> (uint32_t)k_le_shift_b1) & (uint32_t)k_le_byte_mask);
  p[k_le_byte2] = (uint8_t)((v >> (uint32_t)k_le_shift_b2) & (uint32_t)k_le_byte_mask);
  p[k_le_byte3] = (uint8_t)((v >> (uint32_t)k_le_shift_b3) & (uint32_t)k_le_byte_mask);
}

typedef enum : uint16_t {
  k_bpb_jmp0          = 0U,   
  k_bpb_jmp1          = 1U,   
  k_bpb_jmp2          = 2U,   
  k_bpb_oem           = 3U,   
  k_bpb_bytes_per_sec = 11U,  
  k_bpb_sec_per_clus  = 13U,  
  k_bpb_resv_sec      = 14U,  
  k_bpb_num_fats      = 16U,  
  k_bpb_root_ents     = 17U,  
  k_bpb_totsec16      = 19U,  
  k_bpb_media         = 21U,  
  k_bpb_fatsz16       = 22U,  
  k_bpb_sec_per_trk   = 24U,  
  k_bpb_num_heads     = 26U,  
  k_bpb_totsec32      = 32U,  
  k_bpb_fatsz32       = 36U,  
  k_bpb16_drive_num   = 36U,  
  k_bpb16_boot_sig    = 38U,  
  k_bpb16_volid       = 39U,  
  k_bpb16_vol_label   = 43U,  
  k_bpb32_root_clus   = 44U,  
  k_bpb32_fsinfo_sec  = 48U,  
  k_bpb32_bkboot_sec  = 50U,  
  k_bpb16_fstype      = 54U,  
  k_bpb32_drive_num   = 64U,  
  k_bpb32_boot_sig    = 66U,  
  k_bpb32_volid       = 67U,  
  k_bpb32_vol_label   = 71U,  
  k_bpb32_fstype      = 82U,  
  k_bpb_sig_lo        = 510U, 
  k_bpb_sig_hi        = 511U, 
} sd_bpb_off_t;

typedef enum : uint32_t {
  k_bpb_jmp_b0          = 0xEBU,       
  k_bpb_jmp_b1          = 0x58U,       
  k_bpb_jmp_b2          = 0x90U,       
  k_bpb_oem_len         = 8U,          
  k_bpb_fstype_len      = 8U,          
  k_bpb_sig_byte_lo     = 0x55U,       
  k_bpb_sig_byte_hi     = 0xAAU,       
  k_bpb_num_fats_val    = 2U,          
  k_bpb_media_fixed     = 0xF8U,       
  k_bpb_sec_per_trk_val = 63U,         
  k_bpb_num_heads_val   = 255U,        
  k_bpb_drive_num_val   = 0x80U,       
  k_bpb_ext_boot_sig    = 0x29U,       
  k_bpb_dir_ent_size    = 32U,         
  k_bpb_fat16_div       = 256U,        
  k_bpb_fat32_div       = 128U,        
  k_fat16_eoc_clus0     = 0xFFF8U,     
  k_fat16_eoc_clus1     = 0xFFFFU,     
  k_fat32_eoc_media     = 0x0FFFFFF8U, 
  k_fat32_eoc           = 0x0FFFFFFFU, 
  k_fat32_root_clus     = 2U,          
  k_fat32_fsinfo_sec    = 1U,          
  k_fat32_bkboot_sec    = 6U,          
  k_fsi_lead_sig        = 0x41615252U, 
  k_fsi_struc_sig       = 0x61417272U, 
  k_fsi_trail_sig       = 0xAA550000U, 
  k_fsi_off_lead        = 0U,          
  k_fsi_off_struc       = 484U,        
  k_fsi_off_free        = 488U,        
  k_fsi_off_nxtfree     = 492U,        
  k_fsi_off_trail       = 508U,        
  k_fsi_free_unknown    = 0xFFFFFFFFU, 
  k_fsi_nxt_free        = 3U,          
  k_fat_ent1_off        = 2U,          
  k_fat32_ent1_off      = 4U,          
  k_fat32_ent2_off      = 8U,          
} sd_bpb_val_t;

RA8_INTERNAL static void internal_sd_boot_frame(uint8_t* img, const char* oem)
{
  img[k_bpb_jmp0] = (uint8_t)k_bpb_jmp_b0;
  img[k_bpb_jmp1] = (uint8_t)k_bpb_jmp_b1;
  img[k_bpb_jmp2] = (uint8_t)k_bpb_jmp_b2;
  (void)memcpy(&img[k_bpb_oem], oem, (size_t)k_bpb_oem_len);
  img[k_bpb_sig_lo] = (uint8_t)k_bpb_sig_byte_lo;
  img[k_bpb_sig_hi] = (uint8_t)k_bpb_sig_byte_hi;
}

void priv_board_sd_label_field(uint8_t* dst, const char* label)
{
  bool past_end = (label == nullptr);
  for (uint32_t i = 0U; i < (uint32_t)k_fmt_label_len; i++) {
    if (!past_end && (label[i] == '\0')) {
      past_end = true; /* stop reading at the NUL; pad the rest with spaces. */
    }
    dst[i] = past_end ? (uint8_t)' ' : (uint8_t)label[i];
  }
}
 
/* @brief Format an empty FAT16 volume; returns the chosen sectors-per-cluster. */
RA8_INTERNAL static uint32_t
internal_fat16_solve_geometry(uint32_t total_sectors, uint32_t root_sectors, uint32_t* fatsz)
{
  uint32_t spc = 1U;
  for (;;) {
    const uint32_t tmp1 = total_sectors - ((uint32_t)k_fmt_resv_f16 + root_sectors);
    const uint32_t tmp2 = ((uint32_t)k_bpb_fat16_div * spc) +
                          (uint32_t)k_bpb_num_fats_val; /* 256 = 512 / 2-byte ent. */
    *fatsz              = (tmp1 + tmp2 - 1U) / tmp2;
    const uint32_t data = total_sectors - (uint32_t)k_fmt_resv_f16 - (2U * *fatsz) - root_sectors;
    const uint32_t clus = data / spc;
    if (clus <= (uint32_t)k_fmt_fat16_max) {
      break;
    }
    spc *= 2U;
    if (spc >= (uint32_t)k_fmt_spc_max) {
      spc = (uint32_t)k_fmt_spc_max;
      break;
    }
  }
  return spc;
}

RA8_INTERNAL static void internal_fat16_write_bpb(uint8_t*    img,
                                                  uint32_t    total_sectors,
                                                  uint32_t    spc,
                                                  uint32_t    fatsz,
                                                  const char* label)
{
  internal_sd_boot_frame(img, "MSDOS5.0");
  internal_sd_put16(&img[k_bpb_bytes_per_sec], (uint16_t)k_fmt_sec_bytes);
  img[k_bpb_sec_per_clus] = (uint8_t)spc;
  internal_sd_put16(&img[k_bpb_resv_sec], (uint16_t)k_fmt_resv_f16);
  img[k_bpb_num_fats] = (uint8_t)k_bpb_num_fats_val;
  internal_sd_put16(&img[k_bpb_root_ents], (uint16_t)k_fmt_root_ents);
  if (total_sectors < (uint32_t)k_fmt_totsec16_max) {
    internal_sd_put16(&img[k_bpb_totsec16], (uint16_t)total_sectors);
  } else {
    internal_sd_put32(&img[k_bpb_totsec32], total_sectors);
  }
  img[k_bpb_media] = (uint8_t)k_bpb_media_fixed;
  internal_sd_put16(&img[k_bpb_fatsz16], (uint16_t)fatsz);
  internal_sd_put16(&img[k_bpb_sec_per_trk], (uint16_t)k_bpb_sec_per_trk_val);
  internal_sd_put16(&img[k_bpb_num_heads], (uint16_t)k_bpb_num_heads_val);
  img[k_bpb16_drive_num] = (uint8_t)k_bpb_drive_num_val;
  img[k_bpb16_boot_sig]  = (uint8_t)k_bpb_ext_boot_sig;
  internal_sd_put32(&img[k_bpb16_volid], (uint32_t)k_fmt_volid | total_sectors);
  priv_board_sd_label_field(&img[k_bpb16_vol_label], label);
  (void)memcpy(&img[k_bpb16_fstype], "FAT16   ", (size_t)k_bpb_fstype_len);
}

RA8_INTERNAL static bool internal_write_sector(int image_fd, uint32_t sector, const uint8_t* data)
{
  const uint64_t        offset = (uint64_t)sector * (uint64_t)k_fmt_sec_bytes;
  const emu_io_result_t result =
    priv_emu_io_pwrite_exact(image_fd, data, (size_t)k_fmt_sec_bytes, (off_t)offset);
  return result.status == k_emu_io_ok;
}
 
bool priv_board_sd_format_fat16(int         image_fd,
                                uint32_t    total_sectors,
                                const char* label,
                                uint32_t*   out_spc)
{
  const uint32_t root_sectors = (((uint32_t)k_fmt_root_ents * (uint32_t)k_bpb_dir_ent_size) +
                                 ((uint32_t)k_fmt_sec_bytes - 1U)) /
                                (uint32_t)k_fmt_sec_bytes;
  uint32_t       fatsz        = 1U;
  const uint32_t spc          = internal_fat16_solve_geometry(total_sectors, root_sectors, &fatsz);
 
  uint8_t boot[k_fmt_sec_bytes] = {};
  uint8_t fat[k_fmt_sec_bytes]  = {};
  internal_fat16_write_bpb(boot, total_sectors, spc, fatsz, label);
  internal_sd_put16(&fat[k_le_byte0], (uint16_t)k_fat16_eoc_clus0);
  internal_sd_put16(&fat[k_fat_ent1_off], (uint16_t)k_fat16_eoc_clus1);
 
  if (!internal_write_sector(image_fd, 0U, boot)) {
    return false;
  }
  for (uint32_t f = 0U; f < (uint32_t)k_bpb_num_fats_val; ++f) {
    if (!internal_write_sector(image_fd, (uint32_t)k_fmt_resv_f16 + (f * fatsz), fat)) {
      return false;
    }
  }
  *out_spc = spc;
  return true;
}

RA8_INTERNAL static uint32_t
internal_sd_fat32_geometry(uint32_t total_sectors, uint32_t* out_fatsz, uint32_t* out_clusters)
{
  uint32_t spc      = 1U;
  uint32_t fatsz    = 1U;
  uint32_t clusters = 0U;
  for (;;) {
    const uint32_t tmp1 = total_sectors - (uint32_t)k_fmt_resv_f32;
    /* Microsoft FAT32 FAT-size divisor: ((256*spc) + NumFATs) / 2 = 128*spc + 1.
     * (Using +2 can undersize the FAT by a sector on large volumes.) */
    const uint32_t tmp2 = ((uint32_t)k_bpb_fat32_div * spc) + 1U;
    fatsz               = (tmp1 + tmp2 - 1U) / tmp2;
    const uint32_t data = total_sectors - (uint32_t)k_fmt_resv_f32 - (2U * fatsz);
    clusters            = data / spc;
    /* Grow the cluster size for big cards so the FAT stays bounded and the
     * cluster size is realistic (8 KiB at ~2 GiB, 32 KiB at ~8 GiB+), capped at
     * the FAT32 cluster ceiling. k_fmt_fat32_pref keeps small cards at 1 spc. */
    if (clusters <= (uint32_t)k_fmt_fat32_pref) {
      break;
    }
    spc *= 2U;
    if (spc >= (uint32_t)k_fmt_spc_max) {
      spc = (uint32_t)k_fmt_spc_max;
      break;
    }
  }
  *out_fatsz    = fatsz;
  *out_clusters = clusters;
  return spc;
}

RA8_INTERNAL static void internal_fat32_write_bpb(uint8_t*    img,
                                                  uint32_t    total_sectors,
                                                  uint32_t    spc,
                                                  uint32_t    fatsz,
                                                  const char* label)
{
  internal_sd_boot_frame(img, "MSDOS5.0");
  internal_sd_put16(&img[k_bpb_bytes_per_sec], (uint16_t)k_fmt_sec_bytes);
  img[k_bpb_sec_per_clus] = (uint8_t)spc;
  internal_sd_put16(&img[k_bpb_resv_sec], (uint16_t)k_fmt_resv_f32);
  img[k_bpb_num_fats] = (uint8_t)k_bpb_num_fats_val;
  internal_sd_put16(&img[k_bpb_root_ents], 0U); /* root entries: 0 for FAT32 */
  internal_sd_put16(&img[k_bpb_totsec16], 0U);  /* totsec16: 0, use totsec32 */
  img[k_bpb_media] = (uint8_t)k_bpb_media_fixed;
  internal_sd_put16(&img[k_bpb_fatsz16], 0U); /* fatsz16: 0 for FAT32 */
  internal_sd_put16(&img[k_bpb_sec_per_trk], (uint16_t)k_bpb_sec_per_trk_val);
  internal_sd_put16(&img[k_bpb_num_heads], (uint16_t)k_bpb_num_heads_val);
  internal_sd_put32(&img[k_bpb_totsec32], total_sectors);
  internal_sd_put32(&img[k_bpb_fatsz32], fatsz); /* BPB_FATSz32 */
  internal_sd_put32(&img[k_bpb32_root_clus], (uint32_t)k_fat32_root_clus);
  internal_sd_put16(&img[k_bpb32_fsinfo_sec], (uint16_t)k_fat32_fsinfo_sec);
  internal_sd_put16(&img[k_bpb32_bkboot_sec], (uint16_t)k_fat32_bkboot_sec);
  img[k_bpb32_drive_num] = (uint8_t)k_bpb_drive_num_val;
  img[k_bpb32_boot_sig]  = (uint8_t)k_bpb_ext_boot_sig;
  internal_sd_put32(&img[k_bpb32_volid], (uint32_t)k_fmt_volid | total_sectors);
  priv_board_sd_label_field(&img[k_bpb32_vol_label], label);
  (void)memcpy(&img[k_bpb32_fstype], "FAT32   ", (size_t)k_bpb_fstype_len);
}
 
bool priv_board_sd_format_fat32(int         image_fd,
                                uint32_t    total_sectors,
                                const char* label,
                                uint32_t*   out_spc)
{
  uint32_t       fatsz    = 0U;
  uint32_t       clusters = 0U;
  const uint32_t spc      = internal_sd_fat32_geometry(total_sectors, &fatsz, &clusters);
  uint8_t        boot[k_fmt_sec_bytes] = {};
  uint8_t        fsi[k_fmt_sec_bytes]  = {};
  uint8_t        fat[k_fmt_sec_bytes]  = {};
  internal_fat32_write_bpb(boot, total_sectors, spc, fatsz, label);
  internal_sd_put32(&fsi[k_fsi_off_lead], (uint32_t)k_fsi_lead_sig);
  internal_sd_put32(&fsi[k_fsi_off_struc], (uint32_t)k_fsi_struc_sig);
  internal_sd_put32(&fsi[k_fsi_off_free],
                    (clusters > 0U) ? (clusters - 1U) : (uint32_t)k_fsi_free_unknown);
  internal_sd_put32(&fsi[k_fsi_off_nxtfree], (uint32_t)k_fsi_nxt_free);
  internal_sd_put32(&fsi[k_fsi_off_trail], (uint32_t)k_fsi_trail_sig);
  internal_sd_put32(&fat[k_le_byte0], (uint32_t)k_fat32_eoc_media);
  internal_sd_put32(&fat[k_fat32_ent1_off], (uint32_t)k_fat32_eoc);
  internal_sd_put32(&fat[k_fat32_ent2_off], (uint32_t)k_fat32_eoc);
 
  if (!internal_write_sector(image_fd, 0U, boot) ||
      !internal_write_sector(image_fd, (uint32_t)k_fat32_fsinfo_sec, fsi) ||
      !internal_write_sector(image_fd, (uint32_t)k_fat32_bkboot_sec, boot)) {
    return false;
  }
  for (uint32_t f = 0U; f < (uint32_t)k_bpb_num_fats_val; f++) {
    if (!internal_write_sector(image_fd, (uint32_t)k_fmt_resv_f32 + (f * fatsz), fat)) {
      return false;
    }
  }
  *out_spc = spc;
  return true;
}