Skip to main content

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}