Bootloaders/MassStorage/Lib/VirtualFAT.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2019.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2019  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaims all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 #ifndef _VIRTUALFAT_H_
  32 #define _VIRTUALFAT_H_
  33
  34         /* Includes: */
  35                 #include <avr/io.h>
  36                 #include <avr/pgmspace.h>
  37
  38                 #include <LUFA/Drivers/USB/USB.h>
  39
  40                 #include "../BootloaderAPI.h"
  41
  42         /* Macros: */
  43                 /** Size of the virtual FLASH.BIN file in bytes. */
  44                 #define FLASH_FILE_SIZE_BYTES     (FLASHEND - (FLASHEND - BOOT_START_ADDR) - AUX_BOOT_SECTION_SIZE)
  45
  46                 /** Size of the virtual EEPROM.BIN file in bytes. */
  47                 #define EEPROM_FILE_SIZE_BYTES    E2END
  48
  49                 /** Number of sectors that comprise a single logical disk cluster. */
  50                 #define SECTOR_PER_CLUSTER        4
  51
  52                 /** Size of a single logical sector on the disk. */
  53                 #define SECTOR_SIZE_BYTES         512
  54
  55                 /** Size of a logical cluster on the disk, in bytes */
  56                 #define CLUSTER_SIZE_BYTES        (SECTOR_PER_CLUSTER * SECTOR_SIZE_BYTES)
  57
  58                 /** Number of sectors required to store a given size in bytes.
  59                  *
  60                  *  \param[in] size  Size of the data that needs to be stored
  61                  *
  62                  *  \return Number of sectors required to store the given data on the disk.
  63                  */
  64                 #define FILE_SECTORS(size)        ((size / SECTOR_SIZE_BYTES)  + ((size % SECTOR_SIZE_BYTES)  ? 1 : 0))
  65
  66                 /** Number of clusters required to store a given size in bytes.
  67                  *
  68                  *  \param[in] size  Size of the data that needs to be stored
  69                  *
  70                  *  \return Number of clusters required to store the given data on the disk.
  71                  */
  72                 #define FILE_CLUSTERS(size)       ((size / CLUSTER_SIZE_BYTES) + ((size % CLUSTER_SIZE_BYTES) ? 1 : 0))
  73
  74                 /** Total number of logical sectors/blocks on the disk. */
  75                 #define LUN_MEDIA_BLOCKS          (FILE_SECTORS(FLASH_FILE_SIZE_BYTES) + FILE_SECTORS(EEPROM_FILE_SIZE_BYTES) + 32)
  76
  77                 /** Converts a given time in HH:MM:SS format to a FAT filesystem time.
  78                  *
  79                  *  \note The minimum seconds resolution of FAT is 2, thus odd seconds
  80                  *        will be truncated to the previous integer multiple of 2 seconds.
  81                  *
  82                  *  \param[in] hh  Hours (0-23)
  83                  *  \param[in] mm  Minutes (0-59)
  84                  *  \param[in] ss  Seconds (0-59)
  85                  *
  86                  *  \return Given time encoded as a FAT filesystem timestamp
  87                  */
  88                 #define FAT_TIME(hh, mm, ss)      ((hh << 11) | (mm << 5) | (ss >> 1))
  89
  90                 /** Converts a given date in DD/MM/YYYY format to a FAT filesystem date.
  91                  *
  92                  *  \param[in] dd    Days in the month (1-31)
  93                  *  \param[in] mm    Months in the year (1-12)
  94                  *  \param[in] yyyy  Year (1980 - 2107)
  95                  *
  96                  *  \return Given date encoded as a FAT filesystem datestamp
  97                  */
  98                 #define FAT_DATE(dd, mm, yyyy)    (((yyyy - 1980) << 9) | (mm << 5) | (dd << 0))
  99
 100                 /** Bit-rotates a given 8-bit value once to the right.
 101                  *
 102                  *  \param[in] x  Value to rotate right once
 103                  *
 104                  *  \return Bit-rotated input value, rotated once to the right.
 105                  */
 106                 #define ROT8(x)                   ((((x) & 0xFE) >> 1) | (((x) & 1) ? 0x80 : 0x00))
 107
 108                 /** Computes the LFN entry checksum of a MSDOS 8.3 format file entry,
 109                  *  to associate a LFN entry with its short file entry.
 110                  *
 111                  *  \param[in] n0  MSDOS Filename character 1
 112                  *  \param[in] n1  MSDOS Filename character 2
 113                  *  \param[in] n2  MSDOS Filename character 3
 114                  *  \param[in] n3  MSDOS Filename character 4
 115                  *  \param[in] n4  MSDOS Filename character 5
 116                  *  \param[in] n5  MSDOS Filename character 6
 117                  *  \param[in] n6  MSDOS Filename character 7
 118                  *  \param[in] n7  MSDOS Filename character 8
 119                  *  \param[in] e0  MSDOS Extension character 1
 120                  *  \param[in] e1  MSDOS Extension character 2
 121                  *  \param[in] e2  MSDOS Extension character 3
 122                  *
 123                  *  \return LFN checksum of the given MSDOS 8.3 filename.
 124                  */
 125                 #define FAT_CHECKSUM(n0, n1, n2, n3, n4, n5, n6, n7, e0, e1, e2) \
 126                    (uint8_t)(ROT8(ROT8(ROT8(ROT8(ROT8(ROT8(ROT8(ROT8(ROT8(ROT8(n0)+n1)+n2)+n3)+n4)+n5)+n6)+n7)+e0)+e1)+e2)
 127
 128                 /** \name FAT Filesystem Flags */
 129                 /**@{*/
 130                 /** FAT attribute flag to indicate a read-only file. */
 131                 #define FAT_FLAG_READONLY         (1 << 0)
 132
 133                 /** FAT attribute flag to indicate a hidden file. */
 134                 #define FAT_FLAG_HIDDEN           (1 << 1)
 135
 136                 /** FAT attribute flag to indicate a system file. */
 137                 #define FAT_FLAG_SYSTEM           (1 << 2)
 138
 139                 /** FAT attribute flag to indicate a Volume name entry. */
 140                 #define FAT_FLAG_VOLUME_NAME      (1 << 3)
 141
 142                 /** FAT attribute flag to indicate a directory entry. */
 143                 #define FAT_FLAG_DIRECTORY        (1 << 4)
 144
 145                 /** FAT attribute flag to indicate a file ready for archiving. */
 146                 #define FAT_FLAG_ARCHIVE          (1 << 5)
 147
 148                 /** FAT pseudo-attribute flag to indicate a Long File Name entry. */
 149                 #define FAT_FLAG_LONG_FILE_NAME   0x0F
 150
 151                 /** Ordinal flag marker for FAT Long File Name entries to mark the last entry. */
 152                 #define FAT_ORDINAL_LAST_ENTRY    (1 << 6)
 153                 /**@}*/
 154
 155         /* Enums: */
 156                 /** Enum for the Root FAT file entry indexes on the disk. This can be used
 157                  *  to retrieve the current contents of a known directory entry.
 158                  */
 159                 enum
 160                 {
 161                         /** Volume ID directory entry, giving the name of the virtual disk. */
 162                         DISK_FILE_ENTRY_VolumeID      = 0,
 163                         /** Long File Name FAT file entry of the virtual FLASH.BIN image file. */
 164                         DISK_FILE_ENTRY_FLASH_LFN     = 1,
 165                         /** Legacy MSDOS FAT file entry of the virtual FLASH.BIN image file. */
 166                         DISK_FILE_ENTRY_FLASH_MSDOS   = 2,
 167                         /** Long File Name FAT file entry of the virtual EEPROM.BIN image file. */
 168                         DISK_FILE_ENTRY_EEPROM_LFN    = 3,
 169                         /** Legacy MSDOS FAT file entry of the virtual EEPROM.BIN image file. */
 170                         DISK_FILE_ENTRY_EEPROM_MSDOS  = 4,
 171                 };
 172
 173                 /** Enum for the physical disk blocks of the virtual disk. */
 174                 enum
 175                 {
 176                         /** Boot sector disk block. */
 177                         DISK_BLOCK_BootBlock          = 0,
 178                         /** First copy of the FAT table block. */
 179                         DISK_BLOCK_FATBlock1          = 1,
 180                         /** Second copy of the FAT table block. */
 181                         DISK_BLOCK_FATBlock2          = 2,
 182                         /** Root file and directory entries block. */
 183                         DISK_BLOCK_RootFilesBlock     = 3,
 184                         /** Start block of the disk data section. */
 185                         DISK_BLOCK_DataStartBlock     = 4,
 186                 };
 187
 188         /* Type Definitions: */
 189                 /** FAT boot block structure definition, used to identify the core
 190                  *  parameters of a FAT file system stored on a disk.
 191                  *
 192                  *  \note This definition is truncated to save space; the magic signature
 193                  *        \c 0xAA55 must be appended to the very end of the block for it
 194                  *        to be detected by the host as a valid boot block.
 195                  */
 196                 typedef struct
 197                 {
 198                         uint8_t  Bootstrap[3];
 199                         uint8_t  Description[8];
 200                         uint16_t SectorSize;
 201                         uint8_t  SectorsPerCluster;
 202                         uint16_t ReservedSectors;
 203                         uint8_t  FATCopies;
 204                         uint16_t RootDirectoryEntries;
 205                         uint16_t TotalSectors16;
 206                         uint8_t  MediaDescriptor;
 207                         uint16_t SectorsPerFAT;
 208                         uint16_t SectorsPerTrack;
 209                         uint16_t Heads;
 210                         uint32_t HiddenSectors;
 211                         uint32_t TotalSectors32;
 212                         uint16_t PhysicalDriveNum;
 213                         uint8_t  ExtendedBootRecordSig;
 214                         uint32_t VolumeSerialNumber;
 215                         uint8_t  VolumeLabel[11];
 216                         uint8_t  FilesystemIdentifier[8];
 217                         /* uint8_t  BootstrapProgram[448]; */
 218                         /* uint16_t MagicSignature; */
 219                 } FATBootBlock_t;
 220
 221                 /** FAT directory entry structure, for the various kinds of File and
 222                  *  directory descriptors on a FAT disk.
 223                  */
 224                 typedef union
 225                 {
 226                         /** VFAT Long File Name file entry. */
 227                         struct
 228                         {
 229                                 uint8_t  Ordinal;
 230                                 uint16_t Unicode1;
 231                                 uint16_t Unicode2;
 232                                 uint16_t Unicode3;
 233                                 uint16_t Unicode4;
 234                                 uint16_t Unicode5;
 235                                 uint8_t  Attribute;
 236                                 uint8_t  Reserved1;
 237                                 uint8_t  Checksum;
 238                                 uint16_t Unicode6;
 239                                 uint16_t Unicode7;
 240                                 uint16_t Unicode8;
 241                                 uint16_t Unicode9;
 242                                 uint16_t Unicode10;
 243                                 uint16_t Unicode11;
 244                                 uint16_t Reserved2;
 245                                 uint16_t Unicode12;
 246                                 uint16_t Unicode13;
 247                         } VFAT_LongFileName;
 248
 249                         /** Legacy FAT MSDOS 8.3 file entry. */
 250                         struct
 251                         {
 252                                 uint8_t  Filename[8];
 253                                 uint8_t  Extension[3];
 254                                 uint8_t  Attributes;
 255                                 uint8_t  Reserved[10];
 256                                 uint16_t CreationTime;
 257                                 uint16_t CreationDate;
 258                                 uint16_t StartingCluster;
 259                                 uint32_t FileSizeBytes;
 260                         } MSDOS_File;
 261
 262                         /** Legacy FAT MSDOS (sub-)directory entry. */
 263                         struct
 264                         {
 265                                 uint8_t  Name[11];
 266                                 uint8_t  Attributes;
 267                                 uint8_t  Reserved[10];
 268                                 uint16_t CreationTime;
 269                                 uint16_t CreationDate;
 270                                 uint16_t StartingCluster;
 271                                 uint32_t Reserved2;
 272                         } MSDOS_Directory;
 273                 } FATDirectoryEntry_t;
 274
 275         /* Function Prototypes: */
 276                 #if defined(INCLUDE_FROM_VIRTUAL_FAT_C)
 277                         static uint8_t ReadEEPROMByte(const uint8_t* const Address) ATTR_NO_INLINE;
 278
 279                         static void WriteEEPROMByte(uint8_t* const Address,
 280                                                     const uint8_t Data) ATTR_NO_INLINE;
 281
 282                         static void UpdateFAT12ClusterEntry(uint8_t* const FATTable,
 283                                                             const uint16_t Index,
 284                                                             const uint16_t ChainEntry) AUX_BOOT_SECTION;
 285
 286                         static void UpdateFAT12ClusterChain(uint8_t* const FATTable,
 287                                                             const uint16_t StartIndex,
 288                                                             const uint8_t ChainLength) AUX_BOOT_SECTION;
 289
 290                         static void ReadWriteFLASHFileBlock(const uint16_t BlockNumber,
 291                                                             uint8_t* BlockBuffer,
 292                                                             const bool Read) AUX_BOOT_SECTION;
 293
 294                         static void ReadWriteEEPROMFileBlock(const uint16_t BlockNumber,
 295                                                              uint8_t* BlockBuffer,
 296                                                              const bool Read) AUX_BOOT_SECTION;
 297                 #endif
 298
 299                 void VirtualFAT_WriteBlock(const uint16_t BlockNumber) AUX_BOOT_SECTION;
 300                 void VirtualFAT_ReadBlock(const uint16_t BlockNumber) AUX_BOOT_SECTION;
 301
 302 #endif