From 907cb2459c5ea18d9853367a30d94eb232652ca4 Mon Sep 17 00:00:00 2001
From: Dean Camera <dean@fourwalledcubicle.com>
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];