use crate::bytes::{
get_arr, get_u8, get_u16, get_u32, get_u64, put_arr, put_u16, put_u32, put_u64,
};
use crate::flags::{flag_set, named_flags};
use super::{CSUM_FIELD_LEN, ChecksumType, DevItem, ParseError};
pub const SUPER_INFO_SIZE: usize = 4096;
pub const MIRRORS: [u64; 3] = [64 << 10, 64 << 20, 256 << 30];
#[must_use]
pub const fn holds_mirror(device_bytes: u64, at: u64) -> bool {
match at.checked_add(SUPER_INFO_SIZE as u64) {
Some(end) => end <= device_bytes,
None => false,
}
}
pub const MAGIC: [u8; 8] = *b"_BHRfS_M";
pub const SYS_CHUNK_ARRAY_SIZE: usize = 2048;
pub const LABEL_SIZE: usize = 256;
pub const MIN_BLOCK_SIZE: u32 = 4096;
pub const MAX_BLOCK_SIZE: u32 = 65536;
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct SuperFlags(u64);
flag_set!(SuperFlags: u64);
impl SuperFlags {
pub const ERROR: Self = Self(1 << 2);
pub const SEEDING: Self = Self(1 << 32);
pub const METADUMP: Self = Self(1 << 33);
pub const METADUMP_V2: Self = Self(1 << 34);
pub const CHANGING_FSID: Self = Self(1 << 35);
pub const CHANGING_FSID_V2: Self = Self(1 << 36);
pub const CHANGING_BG_TREE: Self = Self(1 << 38);
pub const CHANGING_DATA_CSUM: Self = Self(1 << 39);
pub const CHANGING_META_CSUM: Self = Self(1 << 40);
}
named_flags! {
CompatFlags: u64 {}
}
named_flags! {
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
CompatRoFlags: u64 {
FREE_SPACE_TREE("free-space-tree") = 1 << 0,
FREE_SPACE_TREE_VALID("free-space-tree-valid") = 1 << 1,
VERITY("verity") = 1 << 2,
BLOCK_GROUP_TREE("block-group-tree") = 1 << 3,
}
}
named_flags! {
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
IncompatFlags: u64 {
MIXED_BACKREF("mixed-backref") = 1 << 0,
DEFAULT_SUBVOL("default-subvol") = 1 << 1,
MIXED_GROUPS("mixed-bg") = 1 << 2,
COMPRESS_LZO("compress-lzo") = 1 << 3,
COMPRESS_ZSTD("compress-zstd") = 1 << 4,
BIG_METADATA("big-metadata") = 1 << 5,
EXTENDED_IREF("extref") = 1 << 6,
RAID56("raid56") = 1 << 7,
SKINNY_METADATA("skinny-metadata") = 1 << 8,
NO_HOLES("no-holes") = 1 << 9,
METADATA_UUID("metadata-uuid") = 1 << 10,
RAID1C34("raid1c34") = 1 << 11,
ZONED("zoned") = 1 << 12,
EXTENT_TREE_V2("extent-tree-v2") = 1 << 13,
RAID_STRIPE_TREE("raid-stripe-tree") = 1 << 14,
ENCRYPT("encrypt") = 1 << 15,
SIMPLE_QUOTA("squota") = 1 << 16,
REMAP_TREE("remap-tree") = 1 << 17,
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct SuperBlock {
pub csum: [u8; CSUM_FIELD_LEN],
pub fsid: [u8; 16],
pub bytenr: u64,
pub flags: SuperFlags,
pub magic: [u8; 8],
pub generation: u64,
pub root: u64,
pub chunk_root: u64,
pub log_root: u64,
pub total_bytes: u64,
pub bytes_used: u64,
pub root_dir_objectid: u64,
pub num_devices: u64,
pub sectorsize: u32,
pub nodesize: u32,
pub stripesize: u32,
pub sys_chunk_array_size: u32,
pub chunk_root_generation: u64,
pub compat_flags: CompatFlags,
pub compat_ro_flags: CompatRoFlags,
pub incompat_flags: IncompatFlags,
pub csum_type: ChecksumType,
pub root_level: u8,
pub chunk_root_level: u8,
pub log_root_level: u8,
pub dev_item: DevItem,
pub label: [u8; LABEL_SIZE],
pub cache_generation: u64,
pub uuid_tree_generation: u64,
pub metadata_uuid: [u8; 16],
pub nr_global_roots: u64,
pub remap_root: u64,
pub remap_root_generation: u64,
pub remap_root_level: u8,
pub sys_chunk_array: [u8; SYS_CHUNK_ARRAY_SIZE],
}
impl SuperBlock {
pub const SIZE: usize = SUPER_INFO_SIZE;
pub const CHECKSUM_OFFSET: usize = 0;
pub const BYTENR_OFFSET: usize = 48;
pub const MAGIC_OFFSET: usize = 64;
pub const GENERATION_OFFSET: usize = 72;
pub fn read_from(buf: &[u8]) -> Result<Self, ParseError> {
if buf.len() < Self::SIZE {
return Err(ParseError::TooShort {
structure: "btrfs_super_block",
need: Self::SIZE,
got: buf.len(),
});
}
let magic: [u8; 8] = get_arr(buf, Self::MAGIC_OFFSET);
if magic != MAGIC {
return Err(ParseError::BadMagic {
structure: "btrfs_super_block",
found: magic,
});
}
Ok(Self {
csum: get_arr(buf, 0),
fsid: get_arr(buf, 32),
bytenr: get_u64(buf, 48),
flags: SuperFlags::from_bits(get_u64(buf, 56)),
magic,
generation: get_u64(buf, 72),
root: get_u64(buf, 80),
chunk_root: get_u64(buf, 88),
log_root: get_u64(buf, 96),
total_bytes: get_u64(buf, 112),
bytes_used: get_u64(buf, 120),
root_dir_objectid: get_u64(buf, 128),
num_devices: get_u64(buf, 136),
sectorsize: get_u32(buf, 144),
nodesize: get_u32(buf, 148),
stripesize: get_u32(buf, 156),
sys_chunk_array_size: get_u32(buf, 160),
chunk_root_generation: get_u64(buf, 164),
compat_flags: CompatFlags::from_bits(get_u64(buf, 172)),
compat_ro_flags: CompatRoFlags::from_bits(get_u64(buf, 180)),
incompat_flags: IncompatFlags::from_bits(get_u64(buf, 188)),
csum_type: ChecksumType::from_value(get_u16(buf, 196)),
root_level: get_u8(buf, 198),
chunk_root_level: get_u8(buf, 199),
log_root_level: get_u8(buf, 200),
dev_item: DevItem::read_from(&buf[201..201 + DevItem::SIZE])?,
label: get_arr(buf, 299),
cache_generation: get_u64(buf, 555),
uuid_tree_generation: get_u64(buf, 563),
metadata_uuid: get_arr(buf, 571),
nr_global_roots: get_u64(buf, 587),
remap_root: get_u64(buf, 595),
remap_root_generation: get_u64(buf, 603),
remap_root_level: get_u8(buf, 611),
sys_chunk_array: get_arr(buf, 811),
})
}
pub fn write_to(&self, buf: &mut [u8]) {
assert!(
buf.len() >= Self::SIZE,
"a superblock needs {} bytes and was given {}",
Self::SIZE,
buf.len()
);
put_arr(buf, 0, &self.csum);
put_arr(buf, 32, &self.fsid);
put_u64(buf, 48, self.bytenr);
put_u64(buf, 56, self.flags.bits());
put_arr(buf, 64, &self.magic);
put_u64(buf, 72, self.generation);
put_u64(buf, 80, self.root);
put_u64(buf, 88, self.chunk_root);
put_u64(buf, 96, self.log_root);
put_u64(buf, 104, 0);
put_u64(buf, 112, self.total_bytes);
put_u64(buf, 120, self.bytes_used);
put_u64(buf, 128, self.root_dir_objectid);
put_u64(buf, 136, self.num_devices);
put_u32(buf, 144, self.sectorsize);
put_u32(buf, 148, self.nodesize);
put_u32(buf, 152, self.nodesize);
put_u32(buf, 156, self.stripesize);
put_u32(buf, 160, self.sys_chunk_array_size);
put_u64(buf, 164, self.chunk_root_generation);
put_u64(buf, 172, self.compat_flags.bits());
put_u64(buf, 180, self.compat_ro_flags.bits());
put_u64(buf, 188, self.incompat_flags.bits());
put_u16(buf, 196, self.csum_type.value());
buf[198] = self.root_level;
buf[199] = self.chunk_root_level;
buf[200] = self.log_root_level;
self.dev_item.write_to(&mut buf[201..201 + DevItem::SIZE]);
put_arr(buf, 299, &self.label);
put_u64(buf, 555, self.cache_generation);
put_u64(buf, 563, self.uuid_tree_generation);
put_arr(buf, 571, &self.metadata_uuid);
put_u64(buf, 587, self.nr_global_roots);
put_u64(buf, 595, self.remap_root);
put_u64(buf, 603, self.remap_root_generation);
buf[611] = self.remap_root_level;
put_arr(buf, 811, &self.sys_chunk_array);
}
#[must_use]
pub fn metadata_id(&self) -> [u8; 16] {
if self.incompat_flags.contains(IncompatFlags::METADATA_UUID) {
self.metadata_uuid
} else {
self.fsid
}
}
#[must_use]
pub fn label_bytes(&self) -> &[u8] {
let end = self
.label
.iter()
.position(|&b| b == 0)
.unwrap_or(self.label.len());
&self.label[..end]
}
#[must_use]
pub fn sys_chunk_bytes(&self) -> Option<&[u8]> {
let len = self.sys_chunk_array_size as usize;
(len <= SYS_CHUNK_ARRAY_SIZE).then(|| &self.sys_chunk_array[..len])
}
}
pub const BACKUP_ROOTS_OFFSET: usize = 2859;
pub const NUM_BACKUP_ROOTS: usize = 4;
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub struct RootBackup {
pub tree_root: u64,
pub tree_root_gen: u64,
pub chunk_root: u64,
pub chunk_root_gen: u64,
pub extent_root: u64,
pub extent_root_gen: u64,
pub fs_root: u64,
pub fs_root_gen: u64,
pub dev_root: u64,
pub dev_root_gen: u64,
pub csum_root: u64,
pub csum_root_gen: u64,
pub total_bytes: u64,
pub bytes_used: u64,
pub num_devices: u64,
pub tree_root_level: u8,
pub chunk_root_level: u8,
pub extent_root_level: u8,
pub fs_root_level: u8,
pub dev_root_level: u8,
pub csum_root_level: u8,
}
impl RootBackup {
pub const SIZE: usize = 168;
#[must_use]
pub const fn offset_of(slot: usize) -> Option<usize> {
if slot < NUM_BACKUP_ROOTS {
Some(BACKUP_ROOTS_OFFSET + slot * Self::SIZE)
} else {
None
}
}
pub fn read_from(buf: &[u8]) -> Result<Self, ParseError> {
if buf.len() < Self::SIZE {
return Err(ParseError::TooShort {
structure: "btrfs_root_backup",
need: Self::SIZE,
got: buf.len(),
});
}
Ok(Self {
tree_root: get_u64(buf, 0),
tree_root_gen: get_u64(buf, 8),
chunk_root: get_u64(buf, 16),
chunk_root_gen: get_u64(buf, 24),
extent_root: get_u64(buf, 32),
extent_root_gen: get_u64(buf, 40),
fs_root: get_u64(buf, 48),
fs_root_gen: get_u64(buf, 56),
dev_root: get_u64(buf, 64),
dev_root_gen: get_u64(buf, 72),
csum_root: get_u64(buf, 80),
csum_root_gen: get_u64(buf, 88),
total_bytes: get_u64(buf, 96),
bytes_used: get_u64(buf, 104),
num_devices: get_u64(buf, 112),
tree_root_level: get_u8(buf, 152),
chunk_root_level: get_u8(buf, 153),
extent_root_level: get_u8(buf, 154),
fs_root_level: get_u8(buf, 155),
dev_root_level: get_u8(buf, 156),
csum_root_level: get_u8(buf, 157),
})
}
pub fn write_to(&self, buf: &mut [u8]) {
assert!(
buf.len() >= Self::SIZE,
"a root backup needs {} bytes and was given {}",
Self::SIZE,
buf.len()
);
put_u64(buf, 0, self.tree_root);
put_u64(buf, 8, self.tree_root_gen);
put_u64(buf, 16, self.chunk_root);
put_u64(buf, 24, self.chunk_root_gen);
put_u64(buf, 32, self.extent_root);
put_u64(buf, 40, self.extent_root_gen);
put_u64(buf, 48, self.fs_root);
put_u64(buf, 56, self.fs_root_gen);
put_u64(buf, 64, self.dev_root);
put_u64(buf, 72, self.dev_root_gen);
put_u64(buf, 80, self.csum_root);
put_u64(buf, 88, self.csum_root_gen);
put_u64(buf, 96, self.total_bytes);
put_u64(buf, 104, self.bytes_used);
put_u64(buf, 112, self.num_devices);
buf[152] = self.tree_root_level;
buf[153] = self.chunk_root_level;
buf[154] = self.extent_root_level;
buf[155] = self.fs_root_level;
buf[156] = self.dev_root_level;
buf[157] = self.csum_root_level;
}
}
#[cfg(test)]
mod tests {
use super::*;
fn a_superblock() -> SuperBlock {
fn n(k: u64) -> u64 {
0x1000_0000_0000_0000 + k
}
fn fill<const N: usize>(k: u8) -> [u8; N] {
[k; N]
}
SuperBlock {
csum: fill(1),
fsid: fill(2),
bytenr: n(3),
flags: SuperFlags::from_bits(n(4)),
magic: MAGIC,
generation: n(5),
root: n(6),
chunk_root: n(7),
log_root: n(8),
total_bytes: n(9),
bytes_used: n(10),
root_dir_objectid: n(11),
num_devices: n(12),
sectorsize: 0x1111_0001,
nodesize: 0x1111_0002,
stripesize: 0x1111_0003,
sys_chunk_array_size: 129,
chunk_root_generation: n(13),
compat_flags: CompatFlags::from_bits(n(14)),
compat_ro_flags: CompatRoFlags::FREE_SPACE_TREE
| CompatRoFlags::FREE_SPACE_TREE_VALID
| CompatRoFlags::BLOCK_GROUP_TREE,
incompat_flags: IncompatFlags::MIXED_BACKREF
| IncompatFlags::BIG_METADATA
| IncompatFlags::EXTENDED_IREF
| IncompatFlags::SKINNY_METADATA
| IncompatFlags::NO_HOLES,
csum_type: ChecksumType::CRC32C,
root_level: 21,
chunk_root_level: 22,
log_root_level: 23,
dev_item: DevItem {
devid: n(24),
total_bytes: n(25),
bytes_used: n(26),
io_align: 0x1111_0004,
io_width: 0x1111_0005,
sector_size: 0x1111_0006,
ty: n(27),
generation: n(28),
start_offset: n(29),
dev_group: 0x1111_0007,
seek_speed: 30,
bandwidth: 31,
uuid: fill(32),
fsid: fill(33),
},
label: fill(34),
cache_generation: n(35),
uuid_tree_generation: n(36),
metadata_uuid: fill(37),
nr_global_roots: n(38),
remap_root: n(39),
remap_root_generation: n(40),
remap_root_level: 41,
sys_chunk_array: fill(42),
}
}
#[test]
fn a_superblock_round_trips_through_its_four_thousand_and_ninety_six_bytes() {
let sb = a_superblock();
let mut buf = [0u8; SuperBlock::SIZE];
sb.write_to(&mut buf);
assert_eq!(SuperBlock::read_from(&buf).expect("a full superblock"), sb);
assert_eq!(&buf[180..188], &0xbu64.to_le_bytes());
assert_eq!(&buf[188..196], &0x361u64.to_le_bytes());
assert_eq!(sb.compat_ro_flags.bits(), 0xb);
assert_eq!(sb.incompat_flags.bits(), 0x361);
}
#[test]
fn the_two_deprecated_fields_are_written_as_the_format_leaves_them() {
let sb = a_superblock();
let mut buf = [0xffu8; SuperBlock::SIZE];
sb.write_to(&mut buf);
assert_eq!(
&buf[104..112],
&0u64.to_le_bytes(),
"the log root transaction id"
);
assert_eq!(&buf[152..156], &sb.nodesize.to_le_bytes(), "the leaf size");
}
#[test]
fn the_regions_this_type_does_not_model_survive_a_write() {
let sb = a_superblock();
let mut buf = [0u8; SuperBlock::SIZE];
for (index, byte) in buf.iter_mut().enumerate().take(SuperBlock::SIZE).skip(612) {
if !(811..2859).contains(&index) {
*byte = 0x77;
}
}
sb.write_to(&mut buf);
assert!(
buf[612..811].iter().all(|&b| b == 0x77),
"the reserved bytes"
);
assert!(
buf[2859..].iter().all(|&b| b == 0x77),
"the backups and the padding"
);
}
#[test]
fn bytes_that_do_not_carry_the_magic_are_not_a_superblock() {
let sb = a_superblock();
let mut buf = [0u8; SuperBlock::SIZE];
sb.write_to(&mut buf);
buf[SuperBlock::MAGIC_OFFSET] ^= 0xff;
let err = SuperBlock::read_from(&buf).expect_err("a flipped magic");
assert!(matches!(err, ParseError::BadMagic { .. }));
assert!(matches!(
SuperBlock::read_from(&buf[..SuperBlock::SIZE - 1]),
Err(ParseError::TooShort {
need: 4096,
got: 4095,
..
})
));
}
#[test]
fn the_metadata_id_is_the_filesystem_id_until_the_feature_says_otherwise() {
let mut sb = a_superblock();
sb.metadata_uuid = [0; 16];
assert_eq!(sb.metadata_id(), sb.fsid);
sb.metadata_uuid = [0x99; 16];
sb.incompat_flags |= IncompatFlags::METADATA_UUID;
assert_eq!(sb.metadata_id(), [0x99; 16]);
}
#[test]
fn a_bootstrap_array_longer_than_the_array_is_no_array() {
let mut sb = a_superblock();
assert_eq!(sb.sys_chunk_bytes().expect("in range").len(), 129);
sb.sys_chunk_array_size = SYS_CHUNK_ARRAY_SIZE as u32;
assert_eq!(sb.sys_chunk_bytes().expect("exactly the array").len(), 2048);
sb.sys_chunk_array_size = SYS_CHUNK_ARRAY_SIZE as u32 + 1;
assert_eq!(
sb.sys_chunk_bytes(),
None,
"a length past the array is not clamped"
);
}
#[test]
fn a_label_is_the_bytes_before_its_padding() {
let mut sb = a_superblock();
sb.label = [0; LABEL_SIZE];
assert_eq!(sb.label_bytes(), b"");
sb.label[..5].copy_from_slice(b"root\x00");
assert_eq!(sb.label_bytes(), b"root");
sb.label = [b'x'; LABEL_SIZE];
assert_eq!(sb.label_bytes().len(), LABEL_SIZE);
}
#[test]
fn an_incompatible_word_names_every_bit_it_carries_including_ones_nothing_defines() {
let mut out = String::new();
a_superblock().incompat_flags.describe(&mut out);
assert_eq!(
out,
"mixed-backref, big-metadata, extref, skinny-metadata, no-holes"
);
let mut out = String::new();
IncompatFlags::from_bits(1 << 40).describe(&mut out);
assert_eq!(out, "bit 40");
let mut out = String::new();
IncompatFlags::NONE.describe(&mut out);
assert_eq!(out, "none");
}
#[test]
fn a_feature_word_reads_back_exactly_the_names_it_writes() {
for bit in 0..u64::BITS {
let one = IncompatFlags::from_bits(1 << bit);
match one.names().as_slice() {
[name] => assert_eq!(IncompatFlags::from_name(name), Some(one)),
[] => assert_ne!(one.unknown_bits(), 0, "a bit with no name and no report"),
many => panic!("one bit named {many:?}"),
}
let one = CompatRoFlags::from_bits(1 << bit);
match one.names().as_slice() {
[name] => assert_eq!(CompatRoFlags::from_name(name), Some(one)),
[] => assert_ne!(one.unknown_bits(), 0, "a bit with no name and no report"),
many => panic!("one bit named {many:?}"),
}
}
assert_eq!(IncompatFlags::from_name("SKINNY_METADATA"), None);
assert_eq!(IncompatFlags::from_name(""), None);
}
#[test]
fn no_word_is_defined_by_two_of_the_three_feature_words() {
let all = IncompatFlags::from_bits(u64::MAX).names();
for name in &all {
assert_eq!(
CompatRoFlags::from_name(name),
None,
"{name} is defined by two feature words"
);
assert_eq!(CompatFlags::from_name(name), None);
}
for name in CompatRoFlags::from_bits(u64::MAX).names() {
assert_eq!(CompatFlags::from_name(name), None);
}
let mut sorted = all.clone();
sorted.sort_unstable();
sorted.dedup();
assert_eq!(sorted.len(), all.len(), "a repeated name in {all:?}");
}
#[test]
fn the_format_defines_three_superblock_locations_and_the_third_is_a_quarter_terabyte_in() {
assert_eq!(MIRRORS, [65_536, 67_108_864, 274_877_906_944]);
for (index, &offset) in MIRRORS.iter().enumerate().skip(1) {
assert_eq!(offset, (16u64 << 10) << (12 * index as u32));
}
assert_eq!(
MIRRORS[0],
64 << 10,
"the first is fixed, not the expression"
);
}
#[test]
fn a_backup_record_round_trips_and_its_levels_sit_past_the_bytes_it_does_not_model() {
let backup = RootBackup {
tree_root: 1,
tree_root_gen: 2,
chunk_root: 3,
chunk_root_gen: 4,
extent_root: 5,
extent_root_gen: 6,
fs_root: 7,
fs_root_gen: 8,
dev_root: 9,
dev_root_gen: 10,
csum_root: 11,
csum_root_gen: 12,
total_bytes: 13,
bytes_used: 14,
num_devices: 15,
tree_root_level: 21,
chunk_root_level: 22,
extent_root_level: 23,
fs_root_level: 24,
dev_root_level: 25,
csum_root_level: 26,
};
let mut buf = [0u8; RootBackup::SIZE];
backup.write_to(&mut buf);
assert_eq!(RootBackup::read_from(&buf), Ok(backup));
assert_eq!(&buf[120..152], &[0u8; 32]);
assert_eq!(&buf[152..158], &[21, 22, 23, 24, 25, 26]);
assert_eq!(RootBackup::offset_of(0), Some(BACKUP_ROOTS_OFFSET));
assert_eq!(RootBackup::offset_of(3), Some(2859 + 3 * 168));
assert_eq!(RootBackup::offset_of(NUM_BACKUP_ROOTS), None);
assert_eq!(
BACKUP_ROOTS_OFFSET + NUM_BACKUP_ROOTS * RootBackup::SIZE,
3531
);
for got in 0..RootBackup::SIZE {
assert!(RootBackup::read_from(&vec![0u8; got]).is_err(), "{got}");
}
}
}