f2fs_reader/
superblock.rs

1// Copyright 2025 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4use anyhow::{Error, anyhow, ensure};
5use zerocopy::{FromBytes, Immutable, IntoBytes, KnownLayout};
6
7pub const F2FS_MAGIC: u32 = 0xf2f52010;
8// There are two consecutive superblocks, 1kb each.
9pub const SUPERBLOCK_OFFSET: u64 = 1024;
10// We only support 4kB blocks.
11pub const BLOCK_SIZE: usize = 4096;
12// We only support 2MB segments.
13pub const BLOCKS_PER_SEGMENT: usize = 512;
14pub const SEGMENT_SIZE: usize = BLOCK_SIZE * BLOCKS_PER_SEGMENT;
15
16// Simple CRC used to validate data structures.
17pub fn f2fs_crc32(mut seed: u32, buf: &[u8]) -> u32 {
18    const CRC_POLY: u32 = 0xedb88320;
19    for ch in buf {
20        seed ^= *ch as u32;
21        for _ in 0..8 {
22            seed = (seed >> 1) ^ (if (seed & 1) == 1 { CRC_POLY } else { 0 });
23        }
24    }
25    seed
26}
27
28#[repr(C, packed)]
29#[derive(Copy, Clone, Debug, PartialEq, FromBytes, Immutable, IntoBytes, KnownLayout)]
30pub struct SuperBlock {
31    pub magic: u32,                 // F2FS_MAGIC
32    pub major_ver: u16,             // Major Version
33    pub minor_ver: u16,             // Minor Version
34    pub log_sectorsize: u32,        // log2 sector size in bytes
35    pub log_sectors_per_block: u32, // log2 # of sectors per block
36    pub log_blocksize: u32,         // log2 block size in bytes
37    pub log_blocks_per_seg: u32,    // log2 # of blocks per segment
38    pub segs_per_sec: u32,          // # of segments per section
39    pub secs_per_zone: u32,         // # of sections per zone
40    pub checksum_offset: u32,       // checksum offset in super block
41    pub block_count: u64,           // total # of user blocks
42    pub section_count: u32,         // total # of sections
43    pub segment_count: u32,         // total # of segments
44    pub segment_count_ckpt: u32,    // # of segments for checkpoint
45    pub segment_count_sit: u32,     // # of segments for SIT
46    pub segment_count_nat: u32,     // # of segments for NAT
47    pub segment_count_ssa: u32,     // # of segments for SSA
48    pub segment_count_main: u32,    // # of segments for main area
49    pub segment0_blkaddr: u32,      // start block address of segment 0
50    pub cp_blkaddr: u32,            // start block address of checkpoint
51    pub sit_blkaddr: u32,           // start block address of SIT
52    pub nat_blkaddr: u32,           // start block address of NAT
53    pub ssa_blkaddr: u32,           // start block address of SSA
54    pub main_blkaddr: u32,          // start block address of main area
55    pub root_ino: u32,              // root inode number
56    pub node_ino: u32,              // node inode number
57    pub meta_ino: u32,              // meta inode number
58    pub uuid: [u8; 16],             // 128-bit uuid for volume
59    pub volume_name: [u16; 512],    // volume name
60    pub extension_count: u32,       // # of extensions
61    pub extension_list: [[u8; 8]; 64],
62    pub cp_payload: u32, // # of checkpoint trailing blocks for SIT bitmap
63
64    // The following fields are not in the Fuchsia fork.
65    pub kernel_version: [u8; 256],
66    pub init_kernel_version: [u8; 256],
67    pub feature: u32,
68    pub encryption_level: u8,
69    pub encryption_salt: [u8; 16],
70    pub devices: [Device; 8],
71    pub quota_file_ino: [u32; 3],
72    pub hot_extension_count: u8,
73    pub charset_encoding: u16,
74    pub charset_encoding_flags: u16,
75    pub stop_checkpoint_reason: [u8; 32],
76    pub errors: [u8; 16],
77    _reserved: [u8; 258],
78    pub crc: u32,
79}
80
81pub const FEATURE_ENCRYPT: u32 = 0x00000001;
82pub const FEATURE_EXTRA_ATTR: u32 = 0x00000008;
83pub const FEATURE_PROJECT_QUOTA: u32 = 0x00000010;
84pub const FEATURE_QUOTA_INO: u32 = 0x00000080;
85pub const FEATURE_VERITY: u32 = 0x00000400;
86pub const FEATURE_SB_CHKSUM: u32 = 0x00000800;
87pub const FEATURE_CASEFOLD: u32 = 0x00001000;
88
89const SUPPORTED_FEATURES: u32 = FEATURE_ENCRYPT
90    | FEATURE_EXTRA_ATTR
91    | FEATURE_PROJECT_QUOTA
92    | FEATURE_QUOTA_INO
93    | FEATURE_VERITY
94    | FEATURE_SB_CHKSUM
95    | FEATURE_CASEFOLD;
96
97#[repr(C, packed)]
98#[derive(Copy, Clone, Debug, PartialEq, FromBytes, Immutable, IntoBytes, KnownLayout)]
99pub struct Device {
100    pub path: [u8; 64],
101    pub total_segments: u32,
102}
103
104impl SuperBlock {
105    /// Reads the superblock from an device/image.
106    pub async fn read_from_device(
107        device: &dyn storage_device::Device,
108        offset: u64,
109    ) -> Result<Self, Error> {
110        // Reads must be block aligned. Superblock is always first block of device.
111        assert!(offset < BLOCK_SIZE as u64);
112        let mut block = device.allocate_buffer(BLOCK_SIZE).await;
113        device.read(0, block.as_mut()).await?;
114        let buffer = &block.as_slice()[offset as usize..];
115        let superblock =
116            Self::read_from_bytes(buffer).map_err(|e| anyhow!("Failed to read superblock {e}"))?;
117        ensure!(superblock.magic == F2FS_MAGIC, "Invalid F2fs magic number");
118
119        // We only support 4kB block size so we can make some simplifying assumptions.
120        ensure!(superblock.log_blocksize == 12, "Unsupported block size");
121        // So many of the data structures assume 2MB segment size so just require that.
122        ensure!(superblock.log_blocks_per_seg == 9, "Unsupported segment size");
123
124        let feature = superblock.feature;
125        ensure!(feature & !SUPPORTED_FEATURES == 0, "Unsupported feature set {feature:08x}");
126        if superblock.feature & FEATURE_ENCRYPT != 0 {
127            // We don't support encryption_level > 0 or salts.
128            ensure!(
129                superblock.encryption_level == 0 && superblock.encryption_salt == [0u8; 16],
130                "Unsupported encryption features"
131            );
132        }
133
134        if superblock.feature & FEATURE_SB_CHKSUM != 0 {
135            let offset = superblock.checksum_offset as usize;
136            let actual_checksum = f2fs_crc32(F2FS_MAGIC, &superblock.as_bytes()[..offset]);
137            ensure!(superblock.crc == actual_checksum, "Bad superblock checksum");
138        }
139        if superblock.feature & FEATURE_CASEFOLD != 0 {
140            // 1 here means 'UTF8 12.1.0' which is the version we support in Fxfs.
141            ensure!(superblock.charset_encoding == 1, "Unsupported unicode charset");
142            // We expect NO_COMPAT_FALLBACK to always be set.
143            // Without this flag, missing hashes will be handled by exhaustive search of directories.
144            const NO_COMPAT_FALLBACK: u16 = 2;
145            ensure!(
146                superblock.charset_encoding_flags == NO_COMPAT_FALLBACK,
147                "Unsupported charset_encoding_flags"
148            );
149        }
150
151        Ok(superblock)
152    }
153
154    /// Gets the volume name as a string.
155    pub fn get_volume_name(&self) -> Result<String, Error> {
156        let volume_name = self.volume_name;
157        let end = volume_name.iter().position(|&x| x == 0).unwrap_or(volume_name.len());
158        String::from_utf16(&volume_name[..end]).map_err(|_| anyhow!("Bad UTF16 in volume name"))
159    }
160
161    /// Gets the total size of the filesystem in bytes.
162    pub fn get_total_size(&self) -> u64 {
163        (self.block_count as u64) * BLOCK_SIZE as u64
164    }
165}
f2fs_reader/superblock.rs

f2fs_reader/
superblock.rs
