Add documentation to the incomplete Mass Storage class bootloader, update the virtual...

[pub/USBasp.git] / Bootloaders / Incomplete / MassStorage / Lib / VirtualFAT.h

diff --git a/Bootloaders/Incomplete/MassStorage/Lib/VirtualFAT.h b/Bootloaders/Incomplete/MassStorage/Lib/VirtualFAT.h
index fe8d770..66b5824 100644 (file)
--- a/Bootloaders/Incomplete/MassStorage/Lib/VirtualFAT.h
+++ b/Bootloaders/Incomplete/MassStorage/Lib/VirtualFAT.h
@@ -38,19 +38,68 @@
                #include <LUFA/Drivers/USB/USB.h>
 
        /* Macros: */
-               #define FIRMWARE_FILE_SIZE     (FLASHEND + 1UL)
+               /** Size of the virtual FIRMWARE.BIN file in bytes. */
+               #define FIRMWARE_FILE_SIZE_BYTES  (FLASHEND - (FLASHEND - BOOT_START_ADDR) + 1UL)
 
-               #define SECTOR_SIZE_BYTES      512
-               #define SECTOR_PER_CLUSTER     4
-               #define CLUSTER_SIZE_BYTES     (SECTOR_PER_CLUSTER * SECTOR_SIZE_BYTES)
-               #define FILE_CLUSTERS(size)    ((size / CLUSTER_SIZE_BYTES) + ((size % CLUSTER_SIZE_BYTES) ? 1 : 0))
+               /** Number of sectors that comprise a single logical disk cluster. */
+               #define SECTOR_PER_CLUSTER        4
 
-               #define LUN_MEDIA_BLOCKS       ((FIRMWARE_FILE_SIZE / SECTOR_SIZE_BYTES) + 32)
+               /** Size of a single logical sector on the disk. */
+               #define SECTOR_SIZE_BYTES         512
 
-               #define FAT_TIME(h, m, s)      ((h << 11) | (m << 5) | (s >> 1))
-               #define FAT_DATE(d, m, y)      (((y - 1980) << 9) | (m << 5) | (d << 0))
+               /** Size of a logical cluster on the disk, in bytes */
+               #define CLUSTER_SIZE_BYTES        (SECTOR_PER_CLUSTER * SECTOR_SIZE_BYTES)
+
+               /** Number of sectors required to store a given size in bytes.
+                *
+                *  \param[in] size  Size of the data that needs to be stored
+                *
+                *  \return Number of sectors required to store the given data on the disk.
+                */
+               #define FILE_SECTORS(size)        ((size / SECTOR_SIZE_BYTES)  + ((size % SECTOR_SIZE_BYTES)  ? 1 : 0))
+
+               /** Number of clusters required to store a given size in bytes.
+                *
+                *  \param[in] size  Size of the data that needs to be stored
+                *
+                *  \return Number of clusters required to store the given data on the disk.
+                */
+               #define FILE_CLUSTERS(size)       ((size / CLUSTER_SIZE_BYTES) + ((size % CLUSTER_SIZE_BYTES) ? 1 : 0))
+
+               /** Total number of logical sectors/blocks on the disk. */
+               #define LUN_MEDIA_BLOCKS          (FILE_SECTORS(FIRMWARE_FILE_SIZE_BYTES) + 32)
+
+               /** Converts a given time in HH:MM:SS format to a FAT filesystem time.
+                *
+                *  \note The minimum seconds resolution of FAT is 2, thus odd seconds
+                *        will be truncated to the previous integer multiple of 2 seconds.
+                *
+                *  \param[in] hh  Hours (0-23)
+                *  \param[in] mm  Minutes (0-59)
+                *  \param[in] ss  Seconds (0-59)
+                *
+                *  \return Given time encoded as a FAT filesystem timestamp
+                */
+               #define FAT_TIME(h, m, s)         ((hh << 11) | (mm << 5) | (ss >> 1))
+
+               /** Converts a given date in DD/MM/YYYY format to a FAT filesystem date.
+                *
+                *  \param[in] dd    Days in the month (1-31)
+                *  \param[in] mm    Months in the year (1-12)
+                *  \param[in] yyyy  Year (1980 - 2107)
+                *
+                *  \return Given date encoded as a FAT filesystem datestamp
+                */
+               #define FAT_DATE(d, m, y)         (((yyyy - 1980) << 9) | (mm << 5) | (dd << 0))
 
        /* Type Definitions: */
+               /** FAT boot block structure definition, used to identify the core
+                *  parameters of a FAT filesystem stored on a disk.
+                *
+                *  \note This definition is truncated to save space; the magic signature
+                *        0xAA55 must be appended to the very end of the block for it to
+                *        be detected by the host as a valid boot block.
+                */
                typedef struct
                {
                        uint8_t  Bootstrap[3];
@@ -72,8 +121,13 @@
                        uint32_t VolumeSerialNumber;
                        uint8_t  VolumeLabel[11];
                        uint8_t  FilesystemIdentifier[8];
+                       /* uint8_t  BootstrapProgram[448]; */
+                       /* uint16_t MagicSignature; */
                } FATBootBlock_t;
 
+               /** FAT legacy 8.3 style directory entry structure definition, used to
+                *  identify the files and folders of FAT filesystem stored on a disk.
+                */
                typedef struct
                {
                        uint8_t  Filename[8];
@@ -87,6 +141,14 @@
                } FATDirectoryEntry_t;
 
        /* Function Prototypes: */
+               #if defined(INCLUDE_FROM_VIRTUAL_FAT_C)
+                       static void UpdateFAT12ClusterEntry(uint8_t* const FATTable,
+                                                           const uint16_t Index,
+                                                           const uint16_t ChainEntry);
+                       static void WriteVirtualBlock(const uint16_t BlockNumber);
+                       static void ReadVirtualBlock(const uint16_t BlockNumber);
+               #endif
+
                void VirtualFAT_WriteBlocks(USB_ClassInfo_MS_Device_t* const MSInterfaceInfo,
                                            const uint32_t BlockAddress,
                                            uint16_t TotalBlocks);