ra8_fs_fat_types_internal.h

Go to the documentation of this file.

 
#pragma once
 
#include <stddef.h>
#include <stdint.h>
 
#include "ra8_attributes.h"
#include "ra8_fs.h"
 
/* ===========================================================================
 * On-disk layout enums (BPB / directory / MBR / GPT / exFAT / formatter),
 * shared by every FAT/exFAT translation unit.
 * ===========================================================================
 */
 
/* =============================================================================
 * BPB field offsets -- MS FAT spec sec 3.1, table "BPB and BS Fields".
 * Every magic number in the on-disk layout is named here; fat dispatcher
 * code reads via these offsets only.
 * =============================================================================
 */

typedef enum : uint16_t {
  k_bpb_off_bytes_per_sec = 11,  
  k_bpb_off_sec_per_clus  = 13,  
  k_bpb_off_rsvd_sec_cnt  = 14,  
  k_bpb_off_num_fats      = 16,  
  k_bpb_off_root_ent_cnt  = 17,  
  k_bpb_off_tot_sec_16    = 19,  
  k_bpb_off_fat_sz_16     = 22,  
  k_bpb_off_tot_sec_32    = 32,  
  k_bpb_off_fat_sz_32     = 36,  
  k_bpb_off_root_clus     = 44,  
  k_bpb_off_signature_lo  = 510, 
  k_bpb_off_signature_hi  = 511, 
} ra8_fs_bpb_off_t;

typedef enum : uint8_t {
  k_dir_off_name        = 0,  
  k_dir_off_attr        = 11, 
  k_dir_off_ntres       = 12, 
  k_dir_off_fst_clus_hi = 20, 
  k_dir_off_fst_clus_lo = 26, 
  k_dir_off_file_size   = 28, 
  k_dir_name_field_len  = 11, 
} ra8_fs_dir_off_t;

typedef enum : uint8_t {
  k_ntres_base_lower = 0x08U, 
  k_ntres_ext_lower  = 0x10U, 
} ra8_fs_ntres_t;

typedef enum : uint8_t {
  k_dir_marker_free_perm = 0x00, 
  k_dir_marker_free_used = 0xE5, 
  k_dir_marker_kanji_e5  = 0x05, 
  k_dir_marker_dot       = 0x2E, 
} ra8_fs_dir_marker_t;

typedef enum : uint8_t {
  k_bpb_sig_lo = 0x55, 
  k_bpb_sig_hi = 0xAA, 
} ra8_fs_sig_t;

typedef enum : uint16_t {
  k_mbr_off_part0_type    = 0x1C2U, 
  k_mbr_off_part0_lba     = 0x1C6U, 
  k_mbr_part_entry_stride = 16U,    
  k_mbr_part_entry_count  = 4U,     
} ra8_fs_mbr_off_t;

typedef enum : uint16_t {
  k_gpt_part_type_protective = 0xEEU, 
  k_gpt_header_lba           = 1U,    
  k_gpt_sig_len              = 8U,    
  k_gpt_off_entry_lba        = 0x48U, 
  k_gpt_off_entry_count      = 0x50U, 
  k_gpt_off_entry_size       = 0x54U, 
  k_gpt_entry_bytes          = 128U,  
  k_gpt_entry_scan_max       = 128U,  
  k_gpt_entry_off_first_lba  = 0x20U, 
  k_gpt_guid_len             = 16U,   
} ra8_fs_gpt_t;

typedef enum : uint16_t {
  k_exfat_off_fsname       = 3,    
  k_exfat_off_fat_lba      = 0x50, 
  k_exfat_off_fat_len      = 0x54, 
  k_exfat_off_heap_lba     = 0x58, 
  k_exfat_off_clus_count   = 0x5C, 
  k_exfat_off_root_clus    = 0x60, 
  k_exfat_off_bps_shift    = 0x6C, 
  k_exfat_off_spc_shift    = 0x6D, 
  k_exfat_off_num_fats     = 0x6E, 
  k_exfat_strm_off_flags   = 1,    
  k_exfat_strm_off_nlen    = 3,    
  k_exfat_strm_off_vlen_hi = 0x0C, 
  k_exfat_strm_off_clus    = 0x14, 
  k_exfat_strm_off_dlen    = 0x18, 
  k_exfat_strm_off_dlen_hi = 0x1C, 
  k_exfat_name_off         = 2,    
  k_exfat_upc_off_csum     = 4,    
} ra8_fs_exfat_off_t;

typedef enum : uint32_t {
  k_exfat_entry_eod      = 0x00U,   
  k_exfat_entry_bitmap   = 0x81U,   
  k_exfat_entry_file     = 0x85U,   
  k_exfat_entry_stream   = 0xC0U,   
  k_exfat_entry_name     = 0xC1U,   
  k_exfat_secflag_no_fat = 0x02U,   
  k_exfat_secflag_poss   = 0x01U,   
  k_exfat_secflag_alloc  = 0x03U,   
  k_exfat_attr_read_only = 0x01U,   
  k_exfat_attr_directory = 0x10U,   
  k_exfat_attr_archive   = 0x20U,   
  k_exfat_fsname_len     = 8U,      
  k_exfat_name_per_entry = 15U,     
  k_exfat_entry_bytes    = 32U,     
  k_exfat_bps_shift_min  = 9U,      
  k_exfat_bps_shift_max  = 12U,     
  k_exfat_scan_limit     = 65536U,  
  k_exfat_name_cap       = 64U,     
  k_exfat_name_u8_cap    = 193U,    
  k_exfat_upc_words      = 2918U,   
  k_exfat_upc_run_tag    = 0xFFFFU, 
  k_exfat_csum_hi_bit    = 0x8000U, 
  k_exfat_off_file_secnt = 1U,      
  k_exfat_off_file_csum  = 2U,      
  k_exfat_off_file_attr  = 4U,      
  k_exfat_off_strm_hash  = 4U,      
  k_exfat_off_strm_valid = 8U,      
  k_exfat_bit_mask       = 7U,      
  k_exfat_bit_shift      = 3U,      
  k_exfat_inuse_bit      = 0x80U,   
  k_exfat_max_set_bytes  = 224U,    
  k_exfat_path_depth     = 32U,     
  k_exfat_dir_grow_max   = 2U,      
} ra8_fs_exfat_val_t;

typedef enum : uint16_t {
  k_exfat_foff_jump      = 0U,   
  k_exfat_foff_part_off  = 64U,  
  k_exfat_foff_vol_len   = 72U,  
  k_exfat_foff_serial    = 100U, 
  k_exfat_foff_fs_rev    = 104U, 
  k_exfat_foff_vol_flags = 106U, 
  k_exfat_foff_drive     = 111U, 
  k_exfat_foff_percent   = 112U, 
  k_exfat_foff_ext_sig   = 508U, 
  k_exfat_foff_boot_sig  = 510U, 
  k_exfat_de_second      = 32U,  
  k_exfat_de_third       = 64U,  
  k_exfat_de_first_clus  = 20U,  
  k_exfat_de_data_len    = 24U,  
  k_exfat_de_upc_csum    = 4U,   
  k_exfat_de_lbl_cnt     = 1U,   
  k_exfat_de_lbl_name    = 2U,   
} ra8_fs_exfat_fmt_off_t;

typedef enum : uint32_t {
  k_exfat_entry_upcase   = 0x82U,       
  k_exfat_entry_label    = 0x83U,       
  k_exfat_fmt_jump0      = 0xEBU,       
  k_exfat_fmt_jump1      = 0x76U,       
  k_exfat_fmt_jump2      = 0x90U,       
  k_exfat_fmt_fs_rev     = 0x0100U,     
  k_exfat_fmt_drive      = 0x80U,       
  k_exfat_fmt_percent    = 0U,          
  k_exfat_fmt_boot_sig   = 0xAA55U,     
  k_exfat_fmt_ext_sig    = 0xAA550000U, 
  k_exfat_fmt_fat_media  = 0xFFFFFFF8U, 
  k_exfat_fmt_fat_eoc    = 0xFFFFFFFFU, 
  k_exfat_fmt_first_clus = 2U,          
  k_exfat_fmt_num_fats   = 1U,          
  k_exfat_fmt_boot_secs  = 24U,         
  k_exfat_fmt_backup_lba = 12U,         
  k_exfat_fmt_ext_first  = 1U,          
  k_exfat_fmt_ext_count  = 8U,          
  k_exfat_fmt_oem_lba    = 9U,          
  k_exfat_fmt_resv_lba   = 10U,         
  k_exfat_fmt_csum_lba   = 11U,         
  k_exfat_fmt_csum_skip0 = 106U,        
  k_exfat_fmt_csum_skip1 = 107U,        
  k_exfat_fmt_csum_skip2 = 112U,        
  k_exfat_fmt_csum_hibit = 0x80000000U, 
  /* The three size thresholds and the volume minimum below are counts of
   * 512-BYTE-EQUIVALENT sectors: a 4Kn device's sector count is scaled by
   * bytes_per_sector / 512 before the comparison, so the byte thresholds the
   * table encodes hold on every sector size. */
  k_exfat_fmt_min_sectors   = 65536U,      
  k_exfat_fmt_thr_256m      = 524288U,     
  k_exfat_fmt_thr_32g       = 67108864U,   
  k_exfat_fmt_thr_256g      = 536870912U,  
  k_exfat_fmt_clus_4k       = 12U,         
  k_exfat_fmt_clus_32k      = 15U,         
  k_exfat_fmt_clus_128k     = 17U,         
  k_exfat_fmt_clus_256k     = 18U,         
  k_exfat_fmt_geom_iters    = 4U,          
  k_exfat_fmt_upc_std_bytes = 5836U,       
  k_exfat_fmt_part_align    = 1048576U,    
  k_exfat_fmt_serial        = 0x52A8E47AU, 
  k_exfat_fmt_label_max     = 11U,         
  k_exfat_fmt_byte_bits     = 8U,          
  k_exfat_fmt_byte_full     = 0xFFU,       
} ra8_fs_exfat_fmt_val_t;

typedef enum : uint32_t {
  k_mbr_fmt_disk_sig_off     = 440U,        
  k_mbr_fmt_part0_off        = 446U,        
  k_mbr_fmt_pe_boot          = 0U,          
  k_mbr_fmt_pe_chs_start     = 1U,          
  k_mbr_fmt_pe_type          = 4U,          
  k_mbr_fmt_pe_chs_end       = 5U,          
  k_mbr_fmt_pe_lba           = 8U,          
  k_mbr_fmt_pe_nsect         = 12U,         
  k_mbr_fmt_boot_none        = 0x00U,       
  k_mbr_fmt_type_exfat       = 0x07U,       
  k_mbr_fmt_chs_heads        = 255U,        
  k_mbr_fmt_chs_spt          = 63U,         
  k_mbr_fmt_chs_max          = 16450560U,   
  k_mbr_fmt_chs_ovf_h        = 0xFEU,       
  k_mbr_fmt_chs_ovf_m        = 0xFFU,       
  k_mbr_fmt_chs_ovf_l        = 0xFFU,       
  k_mbr_fmt_chs_sec_mask     = 0x3FU,       
  k_mbr_fmt_chs_cyl_hi_mask  = 0x300U,      
  k_mbr_fmt_chs_cyl_hi_shift = 2U,          
  k_mbr_fmt_disk_sig_base    = 0x1A2B3C4DU, 
} ra8_fs_mbr_fmt_t;

typedef enum : uint32_t {
  k_cluster_first_data      = 2,           
  k_cluster_eoc_min_fat12   = 0x0FF8,      
  k_cluster_eoc_min_fat16   = 0xFFF8,      
  k_cluster_eoc_min_fat32   = 0x0FFFFFF8,  
  k_cluster_mask_fat32      = 0x0FFFFFFFU, 
  k_cluster_eoc_min_exfat   = 0xFFFFFFF8U, 
  k_cluster_eoc_write_fat12 = 0x0FFF,      
  k_cluster_eoc_write_fat16 = 0xFFFF,      
  k_cluster_eoc_write_fat32 = 0x0FFFFFFFU, 
  k_cluster_eoc_write_exfat = 0xFFFFFFFFU, 
  k_cluster_free            = 0,           
  k_cluster_count_fat12_max = 4085,        
  k_cluster_count_fat16_max = 65525,       
  k_fat12_value_mask        = 0x0FFFU,     
  k_fat12_low_nibble_mask   = 0x000FU,     
  k_fat12_high_nibble_mask  = 0xF000U,     
} ra8_fs_cluster_t;

typedef enum : uint16_t {
  k_fmt_off_jmp0        = 0,   
  k_fmt_off_jmp1        = 1,   
  k_fmt_off_jmp2        = 2,   
  k_fmt_off_oem         = 3,   
  k_fmt_off_media       = 21,  
  k_fmt_off_sec_per_trk = 24,  
  k_fmt_off_num_heads   = 26,  
  k_fmt_off_f16_drvnum  = 36,  
  k_fmt_off_f16_bootsig = 38,  
  k_fmt_off_f16_volid   = 39,  
  k_fmt_off_f16_label   = 43,  
  k_fmt_off_f16_fstype  = 54,  
  k_fmt_off_f32_fsinfo  = 48,  
  k_fmt_off_f32_bkboot  = 50,  
  k_fmt_off_f32_drvnum  = 64,  
  k_fmt_off_f32_bootsig = 66,  
  k_fmt_off_f32_volid   = 67,  
  k_fmt_off_f32_label   = 71,  
  k_fmt_off_f32_fstype  = 82,  
  k_fmt_fsi_off_lead    = 0,   
  k_fmt_fsi_off_struct  = 484, 
  k_fmt_fsi_off_free    = 488, 
  k_fmt_fsi_off_nxtfree = 492, 
  k_fmt_fsi_off_trail   = 508, 
} ra8_fs_fmt_off_t;

typedef enum : uint32_t {
  k_fmt_jmp_byte0         = 0xEBU,       
  k_fmt_jmp_byte1         = 0x58U,       
  k_fmt_jmp_byte2         = 0x90U,       
  k_fmt_media_fixed       = 0xF8U,       
  k_fmt_drvnum_hd         = 0x80U,       
  k_fmt_ext_bootsig       = 0x29U,       
  k_fmt_sec_per_trk       = 63U,         
  k_fmt_num_heads         = 255U,        
  k_fmt_num_fats          = 2U,          
  k_fmt_root_ents_f16     = 512U,        
  k_fmt_resv_f16          = 1U,          
  k_fmt_resv_f32          = 32U,         
  k_fmt_root_clus_f32     = 2U,          
  k_fmt_fsinfo_sector     = 1U,          
  k_fmt_bkboot_sector     = 6U,          
  k_fmt_volid_base        = 0x52A8D200U, 
  k_fmt_fsi_lead_sig      = 0x41615252U, 
  k_fmt_fsi_struct_sig    = 0x61417272U, 
  k_fmt_fsi_trail_sig     = 0xAA550000U, 
  k_fmt_label_len         = 11U,         
  k_fmt_spc_max           = 64U,         
  k_fmt_zero_chunk_bytes  = 16384U,      
  k_fmt_fat32_entry_bytes = 4U,          
  k_fmt_fat16_entry_bytes = 2U,          
  k_fmt_fat32_clus_cap    = 0x0FFFFFF0U, 
  k_fmt_fsi_unknown       = 0xFFFFFFFFU, 
  k_fmt_fat32_nxt_free    = 3U,          
  /* Microsoft FAT spec "DskSzToSecPerClus" table (fatgen103 sec 3.3), in
   * 512-BYTE-EQUIVALENT sectors (a 4Kn device's count is scaled by
   * bytes_per_sector / 512 before comparing, so the byte thresholds hold on
   * every sector size). Picking the cluster size by disk size keeps the FAT
   * small: a 128 GB card at 512-byte clusters would need a ~1 GB FAT per
   * copy, but at 32 KB clusters only ~15 MB. The cluster picks are log2
   * cluster BYTES; sectors-per-cluster is that divided by the sector size.  */
  k_fmt_f32_thr_260m  = 532480U,   
  k_fmt_f32_thr_8g    = 16777216U, 
  k_fmt_f32_thr_16g   = 33554432U, 
  k_fmt_f32_thr_32g   = 67108864U, 
  k_fmt_f32_clus_512b = 9U,        
  k_fmt_f32_clus_4k   = 12U,       
  k_fmt_f32_clus_8k   = 13U,       
  k_fmt_f32_clus_16k  = 14U,       
  k_fmt_f32_clus_32k  = 15U,       
} ra8_fs_fmt_val_t;

typedef enum : uint16_t {
  k_byte_mask         = 0xFFU,   
  k_shift_byte        = 8,       
  k_shift_two_bytes   = 16,      
  k_shift_three_bytes = 24,      
  k_shift_nibble      = 4,       
  k_shift_word32      = 32,      
  k_nibble_mask       = 0x0F,    
  k_byte_mask_full    = 0xFF,    
  k_word_mask         = 0xFFFFU, 
  k_max_8_3_name      = 11,      
  k_dot_pos           = 8,       
  k_filename_base_len = 8,       
  k_filename_ext_len  = 3,       
  k_path_max          = 64,      
} ra8_fs_misc_t;
 
/* ===========================================================================
 * Cross-TU typedefs (directory walk, directory location, LFN state,
 * exFAT cursor, formatter geometry).
 * ===========================================================================
 */

typedef struct {
  uint8_t  is_root_fixed;     
  uint32_t fixed_remaining;   
  uint32_t cluster;           
  uint32_t sector_in_cluster; 
  uint64_t cur_lba;           
  uint32_t entry_idx;         
  uint32_t cluster_hops;      
} dir_walk_t;

typedef struct {
  uint8_t  is_root; 
  uint32_t cluster; 
} dir_loc_t;

typedef enum : uint32_t {
  k_lfn_off_seq        = 0U,      
  k_lfn_off_type       = 12U,     
  k_lfn_off_checksum   = 13U,     
  k_lfn_off_clus_lo    = 26U,     
  k_lfn_seq_order_mask = 0x1FU,   
  k_lfn_seq_last       = 0x40U,   
  k_lfn_chars_per_ent  = 13U,     
  k_lfn_max_entries    = 19U,     
  k_lfn_utf8_cap       = 742U,    
  k_lfn_unicode_pad    = 0xFFFFU, 
  k_sfn_csum_high_bit  = 0x80U,   
  k_lfn_write_max      = 247U,    
  k_lfn_erase_max      = 20U,     
  k_lfn_alias_tail_max = 999999U, 
  k_lfn_alias_base_max = 6U,      
} ra8_fs_lfn_t;

typedef struct {
  uint16_t units[k_lfn_write_max]; 
  uint8_t  checksum;               
  uint8_t  have;                   
} lfn_state_t;

typedef enum : uint8_t {
  k_name_kind_invalid = 0U, 
  k_name_kind_short   = 1U, 
  k_name_kind_long    = 2U, 
} ra8_fs_name_kind_t;

typedef struct {
  uint64_t lba; 
  uint32_t off; 
} dir_pos_t;

typedef struct {
  dir_walk_t w;   
  uint32_t   ent; 
} dir_slot_t;

typedef struct {
  dir_loc_t parent;                          
  uint64_t  lba;                             
  uint32_t  off;                             
  uint8_t   entry[k_ra8_fs_dir_entry_bytes]; 
} dir_target_t;

typedef struct {
  dir_slot_t start;                  
  uint16_t   units[k_lfn_write_max]; 
  uint32_t   nunits;                 
  uint8_t    name83[k_max_8_3_name]; 
  uint8_t    ntres;                  
  uint8_t    lfn_entries;            
} dir_insert_t;

typedef struct {
  uint32_t cluster;          
  uint32_t entry_in_cluster; 
  uint32_t scanned;          
  uint32_t contig_end;       
} exfat_cursor_t;

typedef struct {
  uint32_t cluster;      
  uint32_t contig_end;   
  uint32_t self_cluster; 
  uint32_t self_index;   
} exfat_dir_t;

typedef enum : uint32_t {
  k_exfat_set_max_entries = 19U, 
  k_exfat_set_writable    = 7U,  
  k_exfat_set_min_entries = 3U,  
} exfat_set_const_t;

typedef struct {
  uint32_t cluster; 
  uint32_t index;   
} exfat_setpos_t;

typedef struct {
  ra8_fs_type_t type;                
  uint64_t      total_sectors;       
  uint32_t      bytes_per_sector;    
  uint32_t      sectors_per_cluster; 
  uint32_t      reserved_sectors;    
  uint32_t      fat_size_sectors;    
  uint32_t      root_entries;        
  uint32_t      root_sectors;        
  uint32_t      count_of_clusters;   
} ra8_fs_fmt_geom_t;

typedef enum : uint8_t {
  k_fs_sec_role_walk = 0U, 
  k_fs_sec_role_fat  = 1U, 
  k_fs_sec_role_fat2 = 2U, 
  k_fs_sec_role_io   = 3U, 
  k_fs_sec_roles     = 4U, 
} ra8_fs_sec_role_t;

RA8_PRIV extern uint8_t g_fs_scratch[k_ra8_fs_sector_max];