initial commit to implement FAT table write/read and setting the volume dirty status

Description: The dirty flag will be set when opening the volume to indicate that the FAT table might be out of date. In case of an unexpected close without unmount in the next mount it is visible that the FAT table is outdated and can be reread by the operating system (https://en.wikipedia.org/wiki/Design_of_the_FAT_file_system). Without this, the file must always closed before removing the sd card because otherwise the FAT table is outdated and so the files are not visible when mounting the sd card on a computer. For embedded systems it is quite likely that unexpect end can happen and always closing the file after a single write operation is a performance issue. For readonly this dirty flag is not required and therefore it will not set and reset when opening/closing a volume.

https://unix.stackexchange.com/questions/230181/why-does-linux-mark-fat-as-dirty-simply-due-to-mounting-it
Linux kernel is doing it during mount, so there is no need to ckeck it every time during a new write

Author: Murmele

src/fat/fat_table.rs

@@ -0,0 +1,62 @@
+/// FAT table definition
+///
+///
+use crate::fat::FatType;
+use byteorder::{ByteOrder, LittleEndian};
+
+/// Represents a single FAT table. It contains all information about which cluster is occupied
+/// from a file
+pub struct FatTable<'a> {
+    fat_type: FatType,
+    data: &'a mut [u8],
+}
+
+impl<'a> FatTable<'a> {
+    /// Attempt to parse a FAT table from a multiple sectors.
+    pub fn create_from_bytes(data: &'a mut [u8], fat_type: FatType) -> Result<Self, &'static str> {
+        Ok(Self { data, fat_type })
+    }
+
+    // FAT16 only
+    //define_field!(fat_id16, u16, 0);
+
+    // FAT32 only
+    //define_field!(fat_id32, u32, 0);
+
+    const FAT16_DIRTY_BIT: u16 = 15;
+    const FAT32_DIRTY_BIT: u32 = 27;
+
+    pub(crate) fn dirty(&self) -> bool {
+        match self.fat_type {
+            FatType::Fat16 => {
+                (LittleEndian::read_u16(&self.data[2..2 + 2]) & (1 << Self::FAT16_DIRTY_BIT)) == 0
+            }
+            FatType::Fat32 => {
+                (LittleEndian::read_u32(&self.data[4..4 + 4]) & (1 << Self::FAT32_DIRTY_BIT)) == 0
+            }
+        }
+    }
+
+    pub(crate) fn set_dirty(&mut self, dirty: bool) {
+        match self.fat_type {
+            FatType::Fat16 => {
+                let mut v = LittleEndian::read_u16(&self.data[2..2 + 2]);
+                if dirty {
+                    v &= !(1 << Self::FAT16_DIRTY_BIT);
+                } else {
+                    v |= 1 << Self::FAT16_DIRTY_BIT
+                }
+                LittleEndian::write_u16(&mut self.data[2..2 + 2], v);
+            }
+            FatType::Fat32 => {
+                let mut v = LittleEndian::read_u32(&self.data[4..4 + 4]);
+                if dirty {
+                    v &= !(1 << Self::FAT32_DIRTY_BIT);
+                } else {
+                    v |= 1 << Self::FAT32_DIRTY_BIT
+                }
+                LittleEndian::write_u32(&mut self.data[4..4 + 4], v);
+            }
+        }
+    }
+}

src/fat/mod.rs

@@ -45,11 +45,13 @@ impl BlockCache {
 }
 
 mod bpb;
+mod fat_table;
 mod info;
 mod ondiskdirentry;
 mod volume;
 
 pub use bpb::Bpb;
+pub use fat_table::FatTable;
 pub use info::{Fat16Info, Fat32Info, FatSpecificInfo, InfoSector};
 pub use ondiskdirentry::OnDiskDirEntry;
 pub use volume::{parse_volume, FatVolume, VolumeName};

src/fat/volume.rs

@@ -55,6 +55,10 @@ pub struct FatVolume {
     /// The block the FAT starts in. Relative to start of partition (so add
     /// `self.lba_offset` before passing to volume manager)
     pub(crate) fat_start: BlockCount,
+    /// Size of the FAT table in blocks
+    pub(crate) fat_size: BlockCount,
+    /// Number of FAT tables (Normaly there are 2 which are always synchronized (backup))
+    pub(crate) fat_nums: u8,
     /// Expected number of free clusters
     pub(crate) free_clusters_count: Option<u32>,
     /// Number of the next expected free cluster
@@ -1098,6 +1102,8 @@ where
                 blocks_per_cluster: bpb.blocks_per_cluster(),
                 first_data_block: (first_data_block),
                 fat_start: BlockCount(u32::from(bpb.reserved_block_count())),
+                fat_size: BlockCount(bpb.fat_size()),
+                fat_nums: bpb.num_fats(),
                 free_clusters_count: None,
                 next_free_cluster: None,
                 cluster_count: bpb.total_clusters(),
@@ -1135,6 +1141,8 @@ where
                 blocks_per_cluster: bpb.blocks_per_cluster(),
                 first_data_block: BlockCount(first_data_block),
                 fat_start: BlockCount(u32::from(bpb.reserved_block_count())),
+                fat_size: BlockCount(bpb.fat_size()),
+                fat_nums: bpb.num_fats(),
                 free_clusters_count: info_sector.free_clusters_count(),
                 next_free_cluster: info_sector.next_free_cluster(),
                 cluster_count: bpb.total_clusters(),

src/lib.rs

@@ -175,6 +175,10 @@ where
     VolumeStillInUse,
     /// You can't open a volume twice
     VolumeAlreadyOpen,
+    /// Volume is opened in read only mode
+    VolumeReadOnly,
+    /// Fat table is longer than supported
+    FatTableTooLarge,
     /// We can't do that yet
     Unsupported,
     /// Tried to read beyond end of file
@@ -344,6 +348,8 @@ pub(crate) struct VolumeInfo {
     idx: VolumeIdx,
     /// What kind of volume this is
     volume_type: VolumeType,
+    /// Flag to indicate if the volume was opened as read only. If read only, files cannot be opened in write mode!
+    read_only: bool,
 }
 
 /// This enum holds the data for the various different types of filesystems we

src/volume_mgr.rs

@@ -12,8 +12,8 @@ use crate::filesystem::{
     SearchIdGenerator, TimeSource, ToShortFileName, MAX_FILE_SIZE,
 };
 use crate::{
-    debug, Block, BlockCount, BlockDevice, BlockIdx, Error, RawVolume, ShortFileName, Volume,
-    VolumeIdx, VolumeInfo, VolumeType, PARTITION_ID_FAT16, PARTITION_ID_FAT16_LBA,
+    debug, Block, BlockCount, BlockDevice, BlockIdx, Error, FatVolume, RawVolume, ShortFileName,
+    Volume, VolumeIdx, VolumeInfo, VolumeType, PARTITION_ID_FAT16, PARTITION_ID_FAT16_LBA,
     PARTITION_ID_FAT32_CHS_LBA, PARTITION_ID_FAT32_LBA,
 };
 use heapless::Vec;
@@ -102,8 +102,26 @@ where
     pub fn open_volume(
         &mut self,
         volume_idx: VolumeIdx,
+        read_only: bool,
     ) -> Result<Volume<D, T, MAX_DIRS, MAX_FILES, MAX_VOLUMES>, Error<D::Error>> {
-        let v = self.open_raw_volume(volume_idx)?;
+        return self._open_volume(volume_idx, false);
+    }
+
+    /// Get a volume (or partition) based on entries in the Master Boot Record.
+    ///
+    /// We do not support GUID Partition Table disks. Nor do we support any
+    /// concept of drive letters - that is for a higher layer to handle.
+    fn _open_volume(
+        &mut self,
+        volume_idx: VolumeIdx,
+        read_only: bool,
+    ) -> Result<Volume<D, T, MAX_DIRS, MAX_FILES, MAX_VOLUMES>, Error<D::Error>> {
+        let v = self.open_raw_volume(volume_idx, read_only)?;
+        if !read_only {
+            let idx = self.get_volume_by_id(v)?;
+            let VolumeType::Fat(volume_type) = &self.open_volumes[idx].volume_type;
+            self.set_volume_status_dirty(volume_type, true)?;
+        }
         Ok(v.to_volume(self))
     }
 
@@ -114,7 +132,11 @@ where
     ///
     /// This function gives you a `RawVolume` and you must close the volume by
     /// calling `VolumeManager::close_volume`.
-    pub fn open_raw_volume(&mut self, volume_idx: VolumeIdx) -> Result<RawVolume, Error<D::Error>> {
+    pub fn open_raw_volume(
+        &mut self,
+        volume_idx: VolumeIdx,
+        read_only: bool,
+    ) -> Result<RawVolume, Error<D::Error>> {
         const PARTITION1_START: usize = 446;
         const PARTITION2_START: usize = PARTITION1_START + PARTITION_INFO_LENGTH;
         const PARTITION3_START: usize = PARTITION2_START + PARTITION_INFO_LENGTH;
@@ -192,6 +214,7 @@ where
                     volume_id: id,
                     idx: volume_idx,
                     volume_type: volume,
+                    read_only: read_only,
                 };
                 // We already checked for space
                 self.open_volumes.push(info).unwrap();
@@ -319,13 +342,49 @@ where
                 return Err(Error::VolumeStillInUse);
             }
         }
-
         let volume_idx = self.get_volume_by_id(volume)?;
+        if !self.open_volumes[volume_idx].read_only {
+            let VolumeType::Fat(volume_type) = &self.open_volumes[volume_idx].volume_type;
+            self.set_volume_status_dirty(volume_type, false)?;
+        }
+
         self.open_volumes.swap_remove(volume_idx);
 
         Ok(())
     }
 
+    /// Sets the volume status dirty to dirty if true, to not dirty if false
+    fn set_volume_status_dirty(
+        &self,
+        volume: &FatVolume,
+        dirty: bool,
+    ) -> Result<(), Error<D::Error>> {
+        if volume.fat_size > BlockCount(512) {
+            return Err(Error::FatTableTooLarge);
+        }
+        let mut blocks = [Block::new()];
+        self.block_device.read(
+            &mut blocks,
+            volume.lba_start + volume.fat_start,
+            "reading fat table",
+        )?;
+        let block = &mut blocks[0];
+        let mut fat_table =
+            fat::FatTable::create_from_bytes(&mut block.contents, volume.get_fat_type())
+                .map_err(Error::FormatError)?;
+        fat_table.set_dirty(dirty);
+        let fat_table_start = volume.lba_start + volume.fat_start;
+        if volume.fat_nums == 1 || volume.fat_nums == 2 {
+            self.block_device.write(&blocks, fat_table_start)?;
+            // Synchronize also backup fat table
+            if volume.fat_nums == 2 {
+                self.block_device
+                    .write(&blocks, fat_table_start + volume.fat_size)?
+            }
+        }
+        Ok(())
+    }
+
     /// Look in a directory for a named file.
     pub fn find_directory_entry<N>(
         &mut self,
@@ -479,6 +538,10 @@ where
         let volume_info = &self.open_volumes[volume_idx];
         let sfn = name.to_short_filename().map_err(Error::FilenameError)?;
 
+        if volume_info.read_only && mode != Mode::ReadOnly {
+            return Err(Error::VolumeReadOnly);
+        }
+
         let dir_entry = match &volume_info.volume_type {
             VolumeType::Fat(fat) => {
                 fat.find_directory_entry(&self.block_device, directory_info, &sfn)