refs_core/checkpoint.rs
1//! ReFS checkpoint (`CHKP`) — the level-1 metadata block the superblock points
2//! at, which in turn carries the pointers to the system tables (object table,
3//! allocator/container tables).
4//!
5//! # The superblock → checkpoint chain
6//!
7//! The superblock (`SUPB`, level 0) sits at a fixed cluster and holds, after its
8//! 80-byte metadata-block header, a 48-byte superblock structure whose
9//! **checkpoint references data** names the checkpoint block(s). Byte-verified
10//! against the real v3.14 volume:
11//!
12//! ```text
13//! block+0x50 superblock struct (48 bytes):
14//! +0x20 4 checkpoint references data offset (relative to the block)
15//! +0x24 4 number of checkpoint block numbers
16//! +0x28 4 self reference data offset
17//! +0x2c 4 self reference data size
18//! checkpoint references data @ block+<offset>: number-of-entries × u64
19//! ```
20//!
21//! On the real minted volume the two checkpoint block numbers are
22//! `[157156, 1885500]` — **virtual addresses** (they lie far beyond the
23//! physical partition, which is sparse). Resolving a virtual block number to a
24//! physical one requires the container table (a later phase); parsing the CHKP
25//! block itself and extracting the object-table pointer is likewise deferred to
26//! a later phase because the checkpoint block was not physically resident in the
27//! available oracle slice. P1 provides the located checkpoint block numbers so
28//! that resolution has an anchor.
29
30use crate::bytes::le_u32;
31use crate::bytes::le_u64;
32use crate::error::RefsError;
33
34/// Length of the v3 metadata-block header preceding the superblock struct.
35const V3_HEADER_LEN: usize = 80;
36
37/// Offset of the superblock's "checkpoint references data offset" field, within
38/// the superblock struct (which starts at `block + 0x50`).
39const CHECKPOINT_REFS_OFFSET_FIELD: usize = V3_HEADER_LEN + 0x20;
40
41/// Offset of the superblock's "number of checkpoint block numbers" field.
42const CHECKPOINT_COUNT_FIELD: usize = V3_HEADER_LEN + 0x24;
43
44/// A hard cap on the checkpoint-block-number count: even a maximal ReFS keeps a
45/// tiny handful of checkpoints; a count beyond this is a hostile lie and is
46/// clamped so a malformed superblock cannot drive an unbounded read.
47const MAX_CHECKPOINTS: usize = 64;
48
49/// The ReFS checkpoint.
50///
51/// P1 exposes the checkpoint *locations* named by the superblock; parsing the
52/// `CHKP` block body (system-table pointers) is a later phase (the checkpoint
53/// block is not physically resident in the current oracle slice).
54#[derive(Debug)]
55#[non_exhaustive]
56pub struct Checkpoint;
57
58impl Checkpoint {
59 /// Return the checkpoint block numbers named by a superblock metadata block.
60 ///
61 /// `superblock` is the whole superblock page (starting at the `SUPB`
62 /// signature). The checkpoint references data offset is relative to the
63 /// start of the block.
64 ///
65 /// # Errors
66 ///
67 /// [`RefsError::Truncated`] if the buffer is too short to hold the
68 /// checkpoint-references offset/count fields, or the referenced checkpoint
69 /// references data.
70 pub fn locations_from_superblock(superblock: &[u8]) -> Result<Vec<u64>, RefsError> {
71 if superblock.len() < CHECKPOINT_COUNT_FIELD + 4 {
72 return Err(RefsError::Truncated {
73 structure: "superblock checkpoint-references header",
74 need: CHECKPOINT_COUNT_FIELD + 4,
75 have: superblock.len(),
76 });
77 }
78 let refs_off = le_u32(superblock, CHECKPOINT_REFS_OFFSET_FIELD) as usize;
79 let count = (le_u32(superblock, CHECKPOINT_COUNT_FIELD) as usize).min(MAX_CHECKPOINTS);
80
81 // The checkpoint references data must lie fully within the buffer.
82 let need = refs_off
83 .checked_add(count.checked_mul(8).ok_or(RefsError::Truncated {
84 structure: "checkpoint references data (count overflow)",
85 need: usize::MAX,
86 have: superblock.len(),
87 })?)
88 .ok_or(RefsError::Truncated {
89 structure: "checkpoint references data (offset overflow)",
90 need: usize::MAX,
91 have: superblock.len(),
92 })?;
93 if need > superblock.len() {
94 return Err(RefsError::Truncated {
95 structure: "checkpoint references data",
96 need,
97 have: superblock.len(),
98 });
99 }
100
101 Ok((0..count)
102 .map(|i| le_u64(superblock, refs_off + i * 8))
103 .collect())
104 }
105}