firmware_msc_fat.h

// Copyright 2015-2021 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at

//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#pragma once

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include <string.h>
#include <stdio.h>

#ifdef __cplusplus
 extern "C" {
#endif

#define FAT_U8(v) ((v) & 0xFF)
#define FAT_U16(v) FAT_U8(v), FAT_U8((v) >> 8)
#define FAT_U32(v) FAT_U8(v), FAT_U8((v) >> 8), FAT_U8((v) >> 16), FAT_U8((v) >> 24)

#define FAT12_TBL2B(l,h)    FAT_U8(l), FAT_U8(((l >> 8) & 0xF) | ((h << 4) & 0xF0)), FAT_U8(h >> 4)

#define FAT_MS2B(s,ms)    FAT_U8(((((s) & 0x1) * 1000) + (ms)) / 10)
#define FAT_HMS2B(h,m,s)  FAT_U8(((s) >> 1)|(((m) & 0x7) << 5)),      FAT_U8((((m) >> 3) & 0x7)|((h) << 3))
#define FAT_YMD2B(y,m,d)  FAT_U8(((d) & 0x1F)|(((m) & 0x7) << 5)),    FAT_U8((((m) >> 3) & 0x1)|((((y) - 1980) & 0x7F) << 1))

#define FAT_MS2V(s,ms)    FAT_U8(((((s) & 0x1) * 1000) + (ms)) / 10)
#define FAT_HMS2V(h,m,s)  (FAT_U8(((s) >> 1)|(((m) & 0x7) << 5)) | (FAT_U8((((m) >> 3) & 0x7)|((h) << 3)) << 8))
#define FAT_YMD2V(y,m,d)  (FAT_U8(((d) & 0x1F)|(((m) & 0x7) << 5)) | (FAT_U8((((m) >> 3) & 0x1)|((((y) - 1980) & 0x7F) << 1)) << 8))

#define FAT_B2HMS(hms)    ((hms >> 11) & 0x1F), ((hms >> 5) & 0x3F), ((hms & 0x1F) << 1)
#define FAT_B2YMD(ymd)    (((ymd >> 9) & 0x7F) + 1980), ((ymd >> 5) & 0x0F), (ymd & 0x1F)

#define FAT_FILE_ATTR_READ_ONLY     0x01
#define FAT_FILE_ATTR_HIDDEN        0x02
#define FAT_FILE_ATTR_SYSTEM        0x04
#define FAT_FILE_ATTR_VOLUME_LABEL  0x08
#define FAT_FILE_ATTR_SUBDIRECTORY  0x10
#define FAT_FILE_ATTR_ARCHIVE       0x20
#define FAT_FILE_ATTR_DEVICE        0x40

static const uint16_t DISK_SECTOR_SIZE = 512;

#define FAT_SIZE_TO_SECTORS(bytes) ((bytes) / DISK_SECTOR_SIZE) + (((bytes) % DISK_SECTOR_SIZE)?1:0)

typedef struct __attribute__ ((packed)) {
  uint8_t jump_instruction[3];
  char oem_name[8];//padded with spaces (0x20)
  uint16_t bytes_per_sector;//DISK_SECTOR_SIZE usually 512
  uint8_t sectors_per_cluster;//Allowed values are 1, 2, 4, 8, 16, 32, 64, and 128
  uint16_t reserved_sectors_count;//At least 1 for this sector, usually 32 for FAT32
  uint8_t file_alloc_tables_num;//Almost always 2; RAM disks might use 1
  uint16_t max_root_dir_entries;//FAT12 and FAT16
  uint16_t fat12_sector_num;//DISK_SECTOR_NUM FAT12 and FAT16
  uint8_t media_descriptor;
  uint16_t sectors_per_alloc_table;//FAT12 and FAT16
  uint16_t sectors_per_track;//A value of 0 may indicate LBA-only access
  uint16_t num_heads;
  uint32_t hidden_sectors_count;
  uint32_t total_sectors_32;
  uint8_t physical_drive_number;//0x00 for (first) removable media, 0x80 for (first) fixed disk
  uint8_t reserved0;
  uint8_t extended_boot_signature;//should be 0x29
  uint32_t serial_number;//0x1234 => 1234
  char volume_label[11];//padded with spaces (0x20)
  char file_system_type[8];//padded with spaces (0x20)
  uint8_t reserved[448];
  uint16_t signature;//should be 0xAA55
} fat_boot_sector_t;

typedef struct __attribute__ ((packed)) {
  union {
    struct {
      char file_name[8];//padded with spaces (0x20)
      char file_extension[3];//padded with spaces (0x20)
    };
    struct {
      uint8_t file_magic;// 0xE5:deleted, 0x05:will_be_deleted, 0x00:end_marker, 0x2E:dot_marker(. or ..)
      char file_magic_data[10];
    };
    char volume_label[11];//padded with spaces (0x20)
  };
  uint8_t file_attr;//mask of FAT_FILE_ATTR_*
  uint8_t reserved;//always 0
  uint8_t creation_time_ms;//ms * 10; max 1990 (1s 990ms)
  uint16_t creation_time_hms; // [5:6:5] => h:m:(s/2)
  uint16_t creation_time_ymd; // [7:4:5] => (y+1980):m:d
  uint16_t last_access_ymd;
  uint16_t extended_attr;
  uint16_t last_modified_hms;
  uint16_t last_modified_ymd;
  uint16_t data_start_sector;
  uint32_t file_size;
} fat_dir_entry_t;

typedef struct __attribute__ ((packed)) {
  union {
    struct {
      uint8_t number:5;
      uint8_t reserved0:1;
      uint8_t llfp:1;
      uint8_t reserved1:1;
    } seq;
    uint8_t seq_num; //0xE5: Deleted Entry
  };
  uint16_t name0[5];
  uint8_t attr; //ALWAYS 0x0F
  uint8_t type; //ALWAYS 0x00
  uint8_t dos_checksum;
  uint16_t name1[6];
  uint16_t first_cluster; //ALWAYS 0x0000
  uint16_t name2[2];
} fat_lfn_entry_t;

typedef union {
  fat_dir_entry_t dir;
  fat_lfn_entry_t lfn;
} fat_entry_t;

const char * fat_file_system_type(bool fat16);
uint16_t fat_sectors_per_alloc_table(uint32_t sector_num, bool fat16);
uint8_t * fat_add_table(uint8_t * dst, fat_boot_sector_t * boot, bool fat16);
void fat_set_table_index(uint8_t * table, uint16_t index, uint16_t value, bool fat16);
fat_boot_sector_t * fat_add_boot_sector(uint8_t * dst, uint16_t sector_num, uint16_t table_sectors, const char * file_system_type, const char * volume_label, uint32_t serial_number);
fat_dir_entry_t * fat_add_label(uint8_t * dst, const char * volume_label);
fat_dir_entry_t * fat_add_root_file(uint8_t * dst, uint8_t index, const char * file_name, const char * file_extension, size_t file_size, uint16_t data_start_sector, bool is_fat16);
uint8_t fat_lfn_checksum(const uint8_t *short_filename);

#ifdef __cplusplus
 }
#endif