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::{anyhow, ensure, Error};
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 = Self::read_from_bytes(buffer).unwrap();
116        ensure!(superblock.magic == F2FS_MAGIC, "Invalid F2fs magic number");
117
118        // We only support 4kB block size so we can make some simplifying assumptions.
119        ensure!(superblock.log_blocksize == 12, "Unsupported block size");
120        // So many of the data structures assume 2MB segment size so just require that.
121        ensure!(superblock.log_blocks_per_seg == 9, "Unsupported segment size");
122
123        let feature = superblock.feature;
124        ensure!(feature & !SUPPORTED_FEATURES == 0, "Unsupported feature set {feature:08x}");
125        if superblock.feature & FEATURE_ENCRYPT != 0 {
126            // We don't support encryption_level > 0 or salts.
127            ensure!(
128                superblock.encryption_level == 0 && superblock.encryption_salt == [0u8; 16],
129                "Unsupported encryption features"
130            );
131        }
132
133        if superblock.feature & FEATURE_SB_CHKSUM != 0 {
134            let offset = superblock.checksum_offset as usize;
135            let actual_checksum = f2fs_crc32(F2FS_MAGIC, &superblock.as_bytes()[..offset]);
136            ensure!(superblock.crc == actual_checksum, "Bad superblock checksum");
137        }
138        if superblock.feature & FEATURE_CASEFOLD != 0 {
139            // 1 here means 'UTF8 12.1.0' which is the version we support in Fxfs.
140            ensure!(superblock.charset_encoding == 1, "Unsupported unicode charset");
141            ensure!(superblock.charset_encoding_flags == 0, "Unsupported charset_encoding_flags");
142        }
143
144        Ok(superblock)
145    }
146
147    /// Gets the volume name as a string.
148    pub fn get_volume_name(&self) -> Result<String, Error> {
149        let volume_name = self.volume_name;
150        let end = volume_name.iter().position(|&x| x == 0).unwrap_or(volume_name.len());
151        String::from_utf16(&volume_name[..end]).map_err(|_| anyhow!("Bad UTF16 in volume name"))
152    }
153
154    /// Gets the total size of the filesystem in bytes.
155    pub fn get_total_size(&self) -> u64 {
156        (self.block_count as u64) * BLOCK_SIZE as u64
157    }
158}
f2fs_reader/superblock.rs

f2fs_reader/
superblock.rs
