fstool 0.4.31

//! exFAT main boot sector (a.k.a. Main Boot Sector / MBS).
//!
//! Layout per Microsoft's published exFAT specification (2019). Every
//! multi-byte field is little-endian.
//!
//! ```text
//!   off  size  name
//!     0     3  JumpBoot                  (EB 76 90)
//!     3     8  FileSystemName            ("EXFAT   ")
//!    11    53  MustBeZero
//!    64     8  PartitionOffset           (sectors; advisory)
//!    72     8  VolumeLength              (in sectors)
//!    80     4  FatOffset                 (sectors from volume start)
//!    84     4  FatLength                 (sectors per FAT)
//!    88     4  ClusterHeapOffset         (sectors from volume start)
//!    92     4  ClusterCount
//!    96     4  FirstClusterOfRootDirectory
//!   100     4  VolumeSerialNumber
//!   104     2  FileSystemRevision        (high = major, low = minor)
//!   106     2  VolumeFlags
//!   108     1  BytesPerSectorShift       (power of 2: 9..=12 → 512..4096)
//!   109     1  SectorsPerClusterShift    (power of 2: 0..=25-BPSshift)
//!   110     1  NumberOfFats              (1 or 2; TexFAT uses 2)
//!   111     1  DriveSelect
//!   112     1  PercentInUse
//!   113     7  Reserved
//!   120   390  BootCode
//!   510     2  BootSignature             (0x55 0xAA)
//! ```
//!
//! exFAT actually uses a 12-sector "boot region" (main + 8 extension +
//! OEM + reserved + checksum), with an identical backup at sectors 12..23.
//! We only need the first sector for read-only support.

use alloc::format;

/// On-disk size of the main boot sector in this implementation. exFAT
/// permits 512..=4096 byte sectors; the boot sector is always exactly one
/// sector wide and parsing reads only the first 512 bytes (every field we
/// care about lives in the first 120 bytes).
pub const BOOT_SECTOR_PARSE_SIZE: usize = 512;

/// Largest legal `ClusterCount` (2^32 - 11), per the exFAT specification —
/// see `super::layout::MAX_CLUSTER_COUNT`.
pub use super::layout::MAX_CLUSTER_COUNT;

/// Parsed exFAT boot sector. Field names follow the Microsoft spec.
#[derive(Debug, Clone)]
pub struct BootSector {
    pub partition_offset: u64,
    pub volume_length: u64,
    pub fat_offset: u32,
    pub fat_length: u32,
    pub cluster_heap_offset: u32,
    pub cluster_count: u32,
    pub first_cluster_of_root_directory: u32,
    pub volume_serial_number: u32,
    pub fs_revision_major: u8,
    pub fs_revision_minor: u8,
    pub volume_flags: u16,
    pub bytes_per_sector_shift: u8,
    pub sectors_per_cluster_shift: u8,
    pub number_of_fats: u8,
    pub drive_select: u8,
    pub percent_in_use: u8,
}

impl BootSector {
    /// Bytes per sector — 2^BytesPerSectorShift.
    pub fn bytes_per_sector(&self) -> u32 {
        1u32 << self.bytes_per_sector_shift
    }

    /// Sectors per cluster — 2^SectorsPerClusterShift.
    pub fn sectors_per_cluster(&self) -> u32 {
        1u32 << self.sectors_per_cluster_shift
    }

    /// Bytes per cluster.
    pub fn bytes_per_cluster(&self) -> u32 {
        self.bytes_per_sector() << self.sectors_per_cluster_shift
    }

    /// Byte offset of the first FAT.
    pub fn fat_byte_offset(&self) -> u64 {
        self.fat_offset as u64 * self.bytes_per_sector() as u64
    }

    /// Byte size of one FAT.
    pub fn fat_byte_length(&self) -> u64 {
        self.fat_length as u64 * self.bytes_per_sector() as u64
    }

    /// Byte offset of the cluster heap (data area; cluster 2 starts here).
    pub fn cluster_heap_byte_offset(&self) -> u64 {
        self.cluster_heap_offset as u64 * self.bytes_per_sector() as u64
    }

    /// Byte offset of cluster `n` (n >= 2).
    pub fn cluster_byte_offset(&self, cluster: u32) -> u64 {
        self.cluster_heap_byte_offset() + (cluster as u64 - 2) * self.bytes_per_cluster() as u64
    }

    /// Decode from the first 512 bytes of LBA 0.
    ///
    /// The fields and their range checks live in
    /// `super::layout::Boot`, shared with the allocator-free driver;
    /// this wraps them in the crate's error type.
    pub fn decode(b: &[u8; BOOT_SECTOR_PARSE_SIZE]) -> crate::Result<Self> {
        let raw = super::layout::Boot::decode(b)
            .map_err(|e| crate::Error::InvalidImage(format!("exfat: {e}")))?;
        Ok(Self {
            partition_offset: raw.partition_offset,
            volume_length: raw.volume_length,
            fat_offset: raw.fat_offset,
            fat_length: raw.fat_length,
            cluster_heap_offset: raw.cluster_heap_offset,
            cluster_count: raw.cluster_count,
            first_cluster_of_root_directory: raw.first_cluster_of_root_directory,
            volume_serial_number: raw.volume_serial_number,
            fs_revision_major: raw.fs_revision_major,
            fs_revision_minor: raw.fs_revision_minor,
            volume_flags: raw.volume_flags,
            bytes_per_sector_shift: raw.bytes_per_sector_shift,
            sectors_per_cluster_shift: raw.sectors_per_cluster_shift,
            number_of_fats: raw.number_of_fats,
            drive_select: raw.drive_select,
            percent_in_use: raw.percent_in_use,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Hand-craft a 512-byte boot sector for round-trip testing. Mirrors a
    /// 64 MiB volume with 512-byte sectors and 4 KiB clusters.
    fn make_boot_sector() -> [u8; BOOT_SECTOR_PARSE_SIZE] {
        let mut b = [0u8; BOOT_SECTOR_PARSE_SIZE];
        b[0..3].copy_from_slice(&[0xEB, 0x76, 0x90]);
        b[3..11].copy_from_slice(b"EXFAT   ");
        // 11..64 is MustBeZero — leave as zero.
        b[64..72].copy_from_slice(&0u64.to_le_bytes()); // partition_offset
        b[72..80].copy_from_slice(&131072u64.to_le_bytes()); // volume_length (64 MiB / 512)
        b[80..84].copy_from_slice(&2048u32.to_le_bytes()); // fat_offset
        b[84..88].copy_from_slice(&128u32.to_le_bytes()); // fat_length
        b[88..92].copy_from_slice(&2304u32.to_le_bytes()); // cluster_heap_offset
        b[92..96].copy_from_slice(&16_096u32.to_le_bytes()); // cluster_count
        b[96..100].copy_from_slice(&5u32.to_le_bytes()); // first_cluster_of_root_directory
        b[100..104].copy_from_slice(&0xCAFE_F00Du32.to_le_bytes()); // volume_serial
        b[104..106].copy_from_slice(&0x0100u16.to_le_bytes()); // revision = 1.0
        b[106..108].copy_from_slice(&0u16.to_le_bytes()); // volume_flags
        b[108] = 9; // BytesPerSectorShift = 9 → 512
        b[109] = 3; // SectorsPerClusterShift = 3 → 8 sectors/cluster = 4 KiB
        b[110] = 1; // NumberOfFats
        b[111] = 0x80; // DriveSelect
        b[112] = 0; // PercentInUse
        b[510] = 0x55;
        b[511] = 0xAA;
        b
    }

    /// A ClusterCount near `u32::MAX` would overflow the `cluster_count + 2`
    /// end-of-range arithmetic used throughout the module (and make the
    /// allocator's `clamp(2, max)` panic once the sum wrapped below 2).
    #[test]
    fn rejects_cluster_count_above_the_spec_maximum() {
        let mut b = make_boot_sector();
        b[92..96].copy_from_slice(&MAX_CLUSTER_COUNT.to_le_bytes());
        assert_eq!(
            BootSector::decode(&b).unwrap().cluster_count,
            MAX_CLUSTER_COUNT
        );
        for over in [MAX_CLUSTER_COUNT + 1, u32::MAX - 1, u32::MAX] {
            b[92..96].copy_from_slice(&over.to_le_bytes());
            assert!(
                BootSector::decode(&b).is_err(),
                "ClusterCount {over} should be rejected"
            );
        }
    }

    #[test]
    fn decode_handcrafted() {
        let b = make_boot_sector();
        let bs = BootSector::decode(&b).unwrap();
        assert_eq!(bs.bytes_per_sector(), 512);
        assert_eq!(bs.sectors_per_cluster(), 8);
        assert_eq!(bs.bytes_per_cluster(), 4096);
        assert_eq!(bs.fat_offset, 2048);
        assert_eq!(bs.fat_length, 128);
        assert_eq!(bs.cluster_heap_offset, 2304);
        assert_eq!(bs.cluster_count, 16_096);
        assert_eq!(bs.first_cluster_of_root_directory, 5);
        assert_eq!(bs.volume_serial_number, 0xCAFE_F00D);
        assert_eq!(bs.fs_revision_major, 1);
        assert_eq!(bs.fs_revision_minor, 0);
        assert_eq!(bs.number_of_fats, 1);
        // Cluster 2 begins at cluster_heap_offset.
        assert_eq!(bs.cluster_byte_offset(2), 2304 * 512);
        assert_eq!(bs.cluster_byte_offset(3), 2304 * 512 + 4096);
    }

    #[test]
    fn rejects_missing_magic() {
        let mut b = make_boot_sector();
        b[3] = b'X';
        assert!(BootSector::decode(&b).is_err());
    }

    #[test]
    fn rejects_bad_signature() {
        let mut b = make_boot_sector();
        b[510] = 0;
        assert!(BootSector::decode(&b).is_err());
    }

    #[test]
    fn rejects_nonzero_must_be_zero() {
        let mut b = make_boot_sector();
        b[20] = 0xFF;
        assert!(BootSector::decode(&b).is_err());
    }

    #[test]
    fn rejects_invalid_bps_shift() {
        let mut b = make_boot_sector();
        b[108] = 13; // > 12
        assert!(BootSector::decode(&b).is_err());
    }
}