apfs_core/
volume.rs

1//! Volume superblock (`apfs_superblock_t`, magic `APFS_MAGIC = 'BSPA'` →
2//! "APSB" → LE `0x42535041`) and per-volume navigation roots.
3//!
4//! Each volume's APSB (Apple *APFS Reference*, `apfs_superblock_t`) carries the
5//! volume's own object map (`apfs_omap_oid`), the file-system tree root
6//! (`apfs_root_tree_oid`, a virtual oid resolved through the volume omap), the
7//! extent-reference tree (`apfs_extentref_tree_oid`), the snapshot-metadata tree
8//! (`apfs_snap_meta_tree_oid`), the volume role/flags, `apfs_volname`, and
9//! `apfs_fs_index`.
10//!
11//! Field offsets (little-endian on disk), after the 32-byte `obj_phys_t` header
12//! — verified verbatim against libfsapfs `fsapfs_volume_superblock` and the raw
13//! self-minted fixture:
14//!
15//! | off | size | field                                |
16//! |-----|------|--------------------------------------|
17//! | 32  | 4    | `apfs_magic` ("APSB")                |
18//! | 36  | 4    | `apfs_fs_index`                      |
19//! | 40  | 8    | `apfs_features` (compatible)         |
20//! | 48  | 8    | `apfs_readonly_compatible_features`  |
21//! | 56  | 8    | `apfs_incompatible_features`         |
22//! | 116 | 4    | `apfs_root_tree_type`                |
23//! | 128 | 8    | `apfs_omap_oid` (volume omap block)  |
24//! | 136 | 8    | `apfs_root_tree_oid` (virtual)       |
25//! | 144 | 8    | `apfs_extentref_tree_oid`            |
26//! | 152 | 8    | `apfs_snap_meta_tree_oid`            |
27//! | 240 | 16   | `apfs_vol_uuid`                      |
28//! | 256 | 8    | `apfs_fs_flags`                      |
29//! | 704 | 256  | `apfs_volname[APFS_VOLNAME_LEN]`     |
30
31use crate::object::{fletcher64_checksum, fletcher64_stored, ObjPhys};
32
33/// Volume superblock magic `APFS_MAGIC` ('BSPA', "APSB" in a hex dump).
34pub const APFS_MAGIC: u32 = 0x4253_5041;
35
36/// Object type code `OBJECT_TYPE_FS 0xd` — the APSB object type (low 16 bits of
37/// `o_type`).
38const OBJECT_TYPE_FS: u16 = 0xd;
39
40// `apfs_superblock_t` field offsets after the 32-byte `obj_phys_t` header.
41const OFF_MAGIC: usize = 32;
42const OFF_FS_INDEX: usize = 36;
43const OFF_FEATURES: usize = 40;
44const OFF_RO_COMPAT_FEATURES: usize = 48;
45const OFF_INCOMPAT_FEATURES: usize = 56;
46const OFF_ROOT_TREE_TYPE: usize = 116;
47const OFF_OMAP_OID: usize = 128;
48const OFF_ROOT_TREE_OID: usize = 136;
49const OFF_EXTENTREF_TREE_OID: usize = 144;
50const OFF_SNAP_META_TREE_OID: usize = 152;
51const OFF_VOL_UUID: usize = 240;
52const OFF_FS_FLAGS: usize = 256;
53const OFF_VOLNAME: usize = 704;
54
55/// `APFS_VOLNAME_LEN` (Apple) — the fixed `apfs_volname` field size in bytes.
56const VOLNAME_LEN: usize = 256;
57
58/// Minimum readable APSB length: header through the volume name field.
59const APSB_MIN_LEN: usize = OFF_VOLNAME + VOLNAME_LEN;
60
61/// A parsed volume superblock (subset; `#[non_exhaustive]` for additive growth).
62///
63/// The fs-tree navigation entry points ([`Self::root_tree_oid`] /
64/// [`Self::omap_oid`]) are consumed by [`crate::dir`] for name→inode path
65/// resolution.
66#[derive(Debug, Clone)]
67#[non_exhaustive]
68pub struct ApfsVolume {
69    oid: u64,
70    xid: u64,
71    fs_index: u32,
72    features: u64,
73    readonly_compatible_features: u64,
74    incompatible_features: u64,
75    root_tree_type: u32,
76    omap_oid: u64,
77    root_tree_oid: u64,
78    extentref_tree_oid: u64,
79    snap_meta_tree_oid: u64,
80    uuid: [u8; 16],
81    fs_flags: u64,
82    name: String,
83}
84
85impl ApfsVolume {
86    /// Parse and validate an APSB block (magic-by-type + signature + Fletcher-64
87    /// checksum) before trusting any field.
88    ///
89    /// # Errors
90    /// [`crate::ApfsError::UnexpectedObjectType`] on a short block, a non-FS
91    /// object type, or a wrong `apfs_magic` signature (carrying the offending
92    /// value); [`crate::ApfsError::ChecksumMismatch`] on a Fletcher-64 failure.
93    pub fn parse(block: &[u8]) -> crate::Result<Self> {
94        if block.len() < APSB_MIN_LEN {
95            return Err(crate::ApfsError::UnexpectedObjectType {
96                structure: "apfs_superblock",
97                expected: APFS_MAGIC,
98                found: 0,
99            });
100        }
101        // Object-type gate: the block must be an FS (volume superblock) object.
102        let Some(hdr) = ObjPhys::parse(block) else {
103            return Err(crate::ApfsError::UnexpectedObjectType {
104                structure: "apfs_superblock",
105                expected: APFS_MAGIC,
106                found: 0,
107            }); // cov:unreachable: len checked >= APSB_MIN_LEN > OBJ_PHYS_LEN
108        };
109        if hdr.obj_type() != OBJECT_TYPE_FS {
110            return Err(crate::ApfsError::UnexpectedObjectType {
111                structure: "apfs_superblock",
112                expected: u32::from(OBJECT_TYPE_FS),
113                found: hdr.obj_type_raw,
114            });
115        }
116
117        // Signature gate: apfs_magic == "APSB".
118        let magic = crate::bytes::le_u32(block, OFF_MAGIC);
119        if magic != APFS_MAGIC {
120            return Err(crate::ApfsError::UnexpectedObjectType {
121                structure: "apfs_superblock",
122                expected: APFS_MAGIC,
123                found: magic,
124            });
125        }
126
127        // Checksum gate before trusting the tree oids.
128        let stored = fletcher64_stored(block);
129        let computed = fletcher64_checksum(block);
130        if stored != computed {
131            return Err(crate::ApfsError::ChecksumMismatch {
132                block: hdr.oid,
133                stored,
134                computed,
135            });
136        }
137
138        // Volume name: a NUL-terminated UTF-8 string within the 256-byte field.
139        let name = decode_volname(block, OFF_VOLNAME, VOLNAME_LEN);
140
141        Ok(Self {
142            oid: hdr.oid,
143            xid: hdr.xid,
144            fs_index: crate::bytes::le_u32(block, OFF_FS_INDEX),
145            features: crate::bytes::le_u64(block, OFF_FEATURES),
146            readonly_compatible_features: crate::bytes::le_u64(block, OFF_RO_COMPAT_FEATURES),
147            incompatible_features: crate::bytes::le_u64(block, OFF_INCOMPAT_FEATURES),
148            root_tree_type: crate::bytes::le_u32(block, OFF_ROOT_TREE_TYPE),
149            omap_oid: crate::bytes::le_u64(block, OFF_OMAP_OID),
150            root_tree_oid: crate::bytes::le_u64(block, OFF_ROOT_TREE_OID),
151            extentref_tree_oid: crate::bytes::le_u64(block, OFF_EXTENTREF_TREE_OID),
152            snap_meta_tree_oid: crate::bytes::le_u64(block, OFF_SNAP_META_TREE_OID),
153            uuid: crate::bytes::arr::<16>(block, OFF_VOL_UUID),
154            fs_flags: crate::bytes::le_u64(block, OFF_FS_FLAGS),
155            name,
156        })
157    }
158
159    /// The volume superblock object id (`nx_o.o_oid`).
160    #[must_use]
161    pub fn oid(&self) -> u64 {
162        self.oid
163    }
164
165    /// The transaction id of this volume superblock (`nx_o.o_xid`). Used as the
166    /// xid for resolving virtual fs-tree oids through the volume omap.
167    #[must_use]
168    pub fn xid(&self) -> u64 {
169        self.xid
170    }
171
172    /// `apfs_fs_index` — this volume's index within the container's `nx_fs_oid[]`.
173    #[must_use]
174    pub fn fs_index(&self) -> u32 {
175        self.fs_index
176    }
177
178    /// `apfs_features` — compatible feature flags.
179    #[must_use]
180    pub fn features(&self) -> u64 {
181        self.features
182    }
183
184    /// `apfs_readonly_compatible_features` — read-only-compatible feature flags.
185    #[must_use]
186    pub fn readonly_compatible_features(&self) -> u64 {
187        self.readonly_compatible_features
188    }
189
190    /// `apfs_incompatible_features` — incompatible feature flags (the
191    /// case-insensitivity / normalization bits affect directory-name matching).
192    #[must_use]
193    pub fn incompatible_features(&self) -> u64 {
194        self.incompatible_features
195    }
196
197    /// `apfs_root_tree_type` — the storage-flag + object-type word of the
198    /// file-system root tree (the root tree is virtual, so its high bits carry
199    /// the virtual storage flag).
200    #[must_use]
201    pub fn root_tree_type(&self) -> u32 {
202        self.root_tree_type
203    }
204
205    /// `apfs_omap_oid` — the block address of this volume's object map
206    /// (`omap_phys_t`, a physical object). The fs-tree's virtual oids resolve
207    /// through this omap.
208    #[must_use]
209    pub fn omap_oid(&self) -> u64 {
210        self.omap_oid
211    }
212
213    /// Return this volume superblock with its `omap_oid` replaced.
214    ///
215    /// A *snapshot's* frozen `apfs_superblock_t` carries `apfs_omap_oid == 0`:
216    /// snapshots have no object map of their own and are read through the
217    /// **live** volume's omap, resolved at the snapshot's `xid` (the omap B-tree
218    /// retains historical `(oid, xid) → paddr` mappings that snapshots pin). A
219    /// point-in-time view therefore keeps the frozen superblock's `root_tree_oid`
220    /// and `xid` but borrows the live volume's omap. See
221    /// [`crate::snapshot::mount_snapshot`].
222    #[must_use]
223    pub fn with_omap_oid(mut self, omap_oid: u64) -> Self {
224        self.omap_oid = omap_oid;
225        self
226    }
227
228    /// `apfs_root_tree_oid` — the **virtual** oid of the file-system tree root
229    /// (`FSTREE`). Resolve it through the volume omap ([`Self::omap_oid`]) at
230    /// [`Self::xid`] to get the root node's physical block address.
231    #[must_use]
232    pub fn root_tree_oid(&self) -> u64 {
233        self.root_tree_oid
234    }
235
236    /// `apfs_extentref_tree_oid` — the extent-reference tree oid.
237    #[must_use]
238    pub fn extentref_tree_oid(&self) -> u64 {
239        self.extentref_tree_oid
240    }
241
242    /// `apfs_snap_meta_tree_oid` — the snapshot-metadata tree oid.
243    #[must_use]
244    pub fn snap_meta_tree_oid(&self) -> u64 {
245        self.snap_meta_tree_oid
246    }
247
248    /// `apfs_vol_uuid` — the volume UUID.
249    #[must_use]
250    pub fn uuid(&self) -> [u8; 16] {
251        self.uuid
252    }
253
254    /// `apfs_fs_flags` — volume flags (e.g. encryption state bits).
255    #[must_use]
256    pub fn fs_flags(&self) -> u64 {
257        self.fs_flags
258    }
259
260    /// The volume name (`apfs_volname`).
261    #[must_use]
262    pub fn name(&self) -> &str {
263        &self.name
264    }
265}
266
267/// Decode a fixed-width, NUL-terminated UTF-8 volume name field. Bytes after the
268/// first NUL (or the whole field if there is none) are dropped; invalid UTF-8 is
269/// replaced (never panics).
270fn decode_volname(block: &[u8], offset: usize, len: usize) -> String {
271    let Some(field) = block.get(offset..offset + len) else {
272        return String::new(); // cov:unreachable: caller checks block.len() >= APSB_MIN_LEN
273    };
274    let end = field.iter().position(|&b| b == 0).unwrap_or(field.len());
275    String::from_utf8_lossy(&field[..end]).into_owned()
276}
apfs_core/volume.rs

apfs_core/
volume.rs
