From 907cb2459c5ea18d9853367a30d94eb232652ca4 Mon Sep 17 00:00:00 2001 From: Dean Camera Date: Fri, 29 Mar 2013 10:29:11 +0000 Subject: [PATCH] Minor documentation improvements. --- .../MassStorage/BootloaderMassStorage.txt | 9 +------ Bootloaders/MassStorage/Lib/VirtualFAT.h | 24 ++++++++++++++----- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/Bootloaders/MassStorage/BootloaderMassStorage.txt b/Bootloaders/MassStorage/BootloaderMassStorage.txt index e072d2d248..d518d7b91c 100644 --- a/Bootloaders/MassStorage/BootloaderMassStorage.txt +++ b/Bootloaders/MassStorage/BootloaderMassStorage.txt @@ -171,16 +171,9 @@ * \par In some cases, the application is not fully loaded into the device. * Write-caching on some operating systems may interfere with the normal * operation of the bootloader. Write caching should be disabled when using the - * Mass Storage bootloader, or the filesystem synced via an appropriate command + * Mass Storage bootloader, or the file system synced via an appropriate command * (such as the OS's normal disk ejection command) before disconnecting the device. * - * \par On Linux machines, written data may be corrupted. - * Linux systems appear to attempt a full filesystem re-write when the virtual - * firmware file of the bootloader is written to normally, causing corrupt - * device programming. On Linux systems, new firmware should be copied over - * in-place via the \c dd command on the virtual file to ensure the filesystem - * is left intact. - * * \par After loading an application, it is not run automatically on startup. * Some USB AVR boards ship with the BOOTRST fuse set, causing the bootloader * to run automatically when the device is reset. In most cases, the BOOTRST diff --git a/Bootloaders/MassStorage/Lib/VirtualFAT.h b/Bootloaders/MassStorage/Lib/VirtualFAT.h index 820fe54d56..58f5723f9a 100644 --- a/Bootloaders/MassStorage/Lib/VirtualFAT.h +++ b/Bootloaders/MassStorage/Lib/VirtualFAT.h @@ -122,29 +122,41 @@ //@} /* Enums: */ + /** Enum for the Root FAT file entry indexes on the disk. This can be used + * to retrieve the current contents of a known directory entry. + */ enum { + /** Volume ID directory entry, giving the name of the virtual disk. */ DISK_FILE_ENTRY_VolumeID = 0, + /** Long File Name FAT file entry of the virtual firmware image file. */ DISK_FILE_ENTRY_FirmwareLFN = 1, + /** Legacy MSDOS FAT file entry of the virtual firmware image file. */ DISK_FILE_ENTRY_FirmwareMSDOS = 2, }; + /** Enum for the physical disk blocks of the virtual disk. */ enum { + /** Boot sector disk block. */ DISK_BLOCK_BootBlock = 0, + /** First copy of the FAT table block. */ DISK_BLOCK_FATBlock1 = 1, + /** Second copy of the FAT table block. */ DISK_BLOCK_FATBlock2 = 2, + /** Root file and directory entries block. */ DISK_BLOCK_RootFilesBlock = 3, + /** Start block of the disk data section. */ DISK_BLOCK_DataStartBlock = 4, }; /* Type Definitions: */ /** FAT boot block structure definition, used to identify the core - * parameters of a FAT filesystem stored on a disk. + * parameters of a FAT file system 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. + * \c 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 { @@ -176,7 +188,7 @@ */ typedef union { - /** FAT Long File Name directory entry. */ + /** VFAT Long File Name file entry. */ struct { uint8_t Ordinal; @@ -199,7 +211,7 @@ uint16_t Unicode13; } VFAT_LongFileName; - /** FAT MSDOS 8.3 legacy file entry. */ + /** Legacy FAT MSDOS 8.3 file entry. */ struct { uint8_t Filename[8]; @@ -212,7 +224,7 @@ uint32_t FileSizeBytes; } MSDOS_File; - /** FAT MSDOS (sub-)directory entry. */ + /** Legacy FAT MSDOS (sub-)directory entry. */ struct { uint8_t Name[11];