btrfs_uapi/
chunk.rs

1//! # Per-device physical allocation data from the chunk tree
2//!
3//! Walks the chunk tree to determine how many bytes each device has allocated,
4//! broken down by block-group profile flags.  This is the data source for the
5//! per-device breakdown in `btrfs filesystem usage`.
6//!
7//! Also exposes the full per-stripe chunk list used by `inspect-internal
8//! list-chunks`, including the bytes-used figure from the extent tree.
9//!
10//! Requires `CAP_SYS_ADMIN`.
11
12use crate::{
13    field_size,
14    raw::{
15        BTRFS_BLOCK_GROUP_ITEM_KEY, BTRFS_CHUNK_ITEM_KEY, BTRFS_CHUNK_TREE_OBJECTID,
16        BTRFS_EXTENT_TREE_OBJECTID, BTRFS_FIRST_CHUNK_TREE_OBJECTID, btrfs_block_group_item,
17        btrfs_chunk, btrfs_stripe,
18    },
19    space::BlockGroupFlags,
20    tree_search::{SearchKey, tree_search},
21};
22use std::os::unix::io::BorrowedFd;
23
24/// Physical allocation of one block-group profile on one device, as read
25/// from the chunk tree.
26///
27/// `bytes` is the sum of `stripe_len` over all chunk stripes that land on
28/// `devid` and share the same `flags`.  This is the physical space the device
29/// contributes to that profile, not the logical (usable) space.
30#[derive(Debug, Clone, PartialEq, Eq)]
31pub struct DeviceAllocation {
32    /// btrfs device ID.
33    pub devid: u64,
34    /// Combined block-group type and profile flags, e.g.
35    /// `BlockGroupFlags::DATA | BlockGroupFlags::RAID1`.
36    pub flags: BlockGroupFlags,
37    /// Physical bytes allocated on this device for chunks with these flags.
38    pub bytes: u64,
39}
40
41const CHUNK_LENGTH_OFF: usize = std::mem::offset_of!(btrfs_chunk, length);
42const CHUNK_STRIPE_LEN_OFF: usize = std::mem::offset_of!(btrfs_chunk, stripe_len);
43const CHUNK_TYPE_OFF: usize = std::mem::offset_of!(btrfs_chunk, type_);
44const CHUNK_NUM_STRIPES_OFF: usize = std::mem::offset_of!(btrfs_chunk, num_stripes);
45const CHUNK_FIRST_STRIPE_OFF: usize = std::mem::offset_of!(btrfs_chunk, stripe);
46
47const STRIPE_SIZE: usize = std::mem::size_of::<btrfs_stripe>();
48const STRIPE_DEVID_OFF: usize = std::mem::offset_of!(btrfs_stripe, devid);
49const STRIPE_OFFSET_OFF: usize = std::mem::offset_of!(btrfs_stripe, offset);
50
51// Minimum item length: the btrfs_chunk struct with exactly one stripe.
52const CHUNK_MIN_LEN: usize = CHUNK_FIRST_STRIPE_OFF + STRIPE_SIZE; // 80
53
54/// One physical chunk stripe as seen in the chunk tree, with usage data from
55/// the extent tree.
56///
57/// For striped profiles (RAID0, RAID10, …) each logical chunk maps to
58/// multiple stripes on different devices; each stripe yields one `ChunkEntry`.
59/// For non-striped profiles (single, DUP) there is one `ChunkEntry` per chunk.
60#[derive(Debug, Clone, PartialEq, Eq)]
61pub struct ChunkEntry {
62    /// btrfs device ID that holds this stripe.
63    pub devid: u64,
64    /// Physical byte offset of this stripe on the device.
65    pub physical_start: u64,
66    /// Logical byte offset of the chunk within the filesystem address space.
67    pub logical_start: u64,
68    /// Logical length of the chunk in bytes (shared across all stripes of
69    /// the same chunk).
70    pub length: u64,
71    /// Combined block-group type and profile flags.
72    pub flags: BlockGroupFlags,
73    /// Bytes currently used within this chunk, as reported by the extent tree.
74    /// `0` if the block-group item could not be read.
75    pub used: u64,
76}
77
78/// Walk the chunk tree of the filesystem referred to by `fd` and return the
79/// physical allocation of each block-group profile on each device.
80///
81/// The result may contain multiple entries with the same `devid` when a
82/// device participates in chunks of different profiles (e.g. both
83/// `DATA|SINGLE` and `METADATA|DUP`).  Entries with the same `(devid, flags)`
84/// pair are merged — there will be at most one entry per unique pair.
85///
86/// Internally, each `BTRFS_CHUNK_ITEM_KEY` payload is a packed `btrfs_chunk`
87/// struct followed by `num_stripes - 1` additional `btrfs_stripe` structs.
88/// The `stripe_len` field of each stripe is accumulated per `(devid, flags)`
89/// to produce the physical byte counts in the returned list.
90pub fn device_chunk_allocations(fd: BorrowedFd) -> nix::Result<Vec<DeviceAllocation>> {
91    let mut allocs: Vec<DeviceAllocation> = Vec::new();
92
93    tree_search(
94        fd,
95        SearchKey::for_type(
96            BTRFS_CHUNK_TREE_OBJECTID as u64,
97            BTRFS_CHUNK_ITEM_KEY as u32,
98        ),
99        |_hdr, data| {
100            if let Some((stripe_len, flags, stripes)) = parse_chunk(data) {
101                for devid in stripes {
102                    accumulate(&mut allocs, devid, flags, stripe_len);
103                }
104            }
105            Ok(())
106        },
107    )?;
108
109    Ok(allocs)
110}
111
112/// Walk the chunk tree and return one [`ChunkEntry`] per stripe, including
113/// bytes-used from the extent tree.
114///
115/// The returned list is in chunk-tree order (ascending logical offset); call
116/// sites are responsible for any further sorting.  For each logical chunk the
117/// `used` field is populated by a single extent-tree lookup; if that lookup
118/// fails the field is set to `0` rather than propagating an error.
119///
120/// Requires `CAP_SYS_ADMIN`.
121pub fn chunk_list(fd: BorrowedFd) -> nix::Result<Vec<ChunkEntry>> {
122    let mut entries: Vec<ChunkEntry> = Vec::new();
123
124    tree_search(
125        fd,
126        SearchKey::for_objectid_range(
127            BTRFS_CHUNK_TREE_OBJECTID as u64,
128            BTRFS_CHUNK_ITEM_KEY as u32,
129            BTRFS_FIRST_CHUNK_TREE_OBJECTID as u64,
130            BTRFS_FIRST_CHUNK_TREE_OBJECTID as u64,
131        ),
132        |hdr, data| {
133            if let Some(stripes) = parse_chunk_stripes(data) {
134                let logical_start = hdr.offset;
135                let length = read_le_u64(data, CHUNK_LENGTH_OFF);
136                let type_bits = read_le_u64(data, CHUNK_TYPE_OFF);
137                let flags = BlockGroupFlags::from_bits_truncate(type_bits);
138                let used = block_group_used(fd, logical_start).unwrap_or(0);
139                for (devid, physical_start) in stripes {
140                    entries.push(ChunkEntry {
141                        devid,
142                        physical_start,
143                        logical_start,
144                        length,
145                        flags,
146                        used,
147                    });
148                }
149            }
150            Ok(())
151        },
152    )?;
153
154    Ok(entries)
155}
156
157/// Look up the bytes-used counter for the block group at `logical_start` by
158/// searching for `BTRFS_BLOCK_GROUP_ITEM_KEY` in the extent tree.
159///
160/// Returns `None` if the block group item is not found or cannot be read.
161fn block_group_used(fd: BorrowedFd, logical_start: u64) -> Option<u64> {
162    let mut used: Option<u64> = None;
163    tree_search(
164        fd,
165        SearchKey {
166            tree_id: BTRFS_EXTENT_TREE_OBJECTID as u64,
167            min_objectid: logical_start,
168            max_objectid: logical_start,
169            min_type: BTRFS_BLOCK_GROUP_ITEM_KEY,
170            max_type: BTRFS_BLOCK_GROUP_ITEM_KEY,
171            min_offset: 0,
172            max_offset: u64::MAX,
173            min_transid: 0,
174            max_transid: u64::MAX,
175        },
176        |_hdr, data| {
177            let used_off = std::mem::offset_of!(btrfs_block_group_item, used);
178            if data.len() >= used_off + field_size!(btrfs_block_group_item, used) {
179                used = Some(read_le_u64(data, used_off));
180            }
181            Ok(())
182        },
183    )
184    .ok()?;
185    used
186}
187
188/// Parse a raw chunk item payload.
189///
190/// Returns `(stripe_len, flags, devids)` on success, or `None` if the buffer
191/// is too small to be a valid chunk item.
192fn parse_chunk(data: &[u8]) -> Option<(u64, BlockGroupFlags, impl Iterator<Item = u64> + '_)> {
193    if data.len() < CHUNK_MIN_LEN {
194        return None;
195    }
196
197    let stripe_len = read_le_u64(data, CHUNK_STRIPE_LEN_OFF);
198    let type_bits = read_le_u64(data, CHUNK_TYPE_OFF);
199    let num_stripes = read_le_u16(data, CHUNK_NUM_STRIPES_OFF) as usize;
200    let _length = read_le_u64(data, CHUNK_LENGTH_OFF);
201
202    // Sanity-check: the item must be large enough to hold all stripes.
203    let expected_len = CHUNK_FIRST_STRIPE_OFF + num_stripes * STRIPE_SIZE;
204    if data.len() < expected_len || num_stripes == 0 {
205        return None;
206    }
207
208    let flags = BlockGroupFlags::from_bits_truncate(type_bits);
209
210    let devids = (0..num_stripes).map(move |i| {
211        let stripe_off = CHUNK_FIRST_STRIPE_OFF + i * STRIPE_SIZE;
212        read_le_u64(data, stripe_off + STRIPE_DEVID_OFF)
213    });
214
215    Some((stripe_len, flags, devids))
216}
217
218/// Parse a raw chunk item payload and return an iterator of `(devid,
219/// physical_start)` pairs for each stripe.
220///
221/// Returns `None` if the buffer is too small to be a valid chunk item.
222fn parse_chunk_stripes(data: &[u8]) -> Option<impl Iterator<Item = (u64, u64)> + '_> {
223    if data.len() < CHUNK_MIN_LEN {
224        return None;
225    }
226
227    let num_stripes = read_le_u16(data, CHUNK_NUM_STRIPES_OFF) as usize;
228    let expected_len = CHUNK_FIRST_STRIPE_OFF + num_stripes * STRIPE_SIZE;
229    if data.len() < expected_len || num_stripes == 0 {
230        return None;
231    }
232
233    let iter = (0..num_stripes).map(move |i| {
234        let stripe_off = CHUNK_FIRST_STRIPE_OFF + i * STRIPE_SIZE;
235        let devid = read_le_u64(data, stripe_off + STRIPE_DEVID_OFF);
236        let physical_start = read_le_u64(data, stripe_off + STRIPE_OFFSET_OFF);
237        (devid, physical_start)
238    });
239
240    Some(iter)
241}
242
243/// Add `stripe_len` bytes to the `(devid, flags)` entry, creating it if
244/// it does not yet exist.
245fn accumulate(allocs: &mut Vec<DeviceAllocation>, devid: u64, flags: BlockGroupFlags, bytes: u64) {
246    if let Some(entry) = allocs
247        .iter_mut()
248        .find(|a| a.devid == devid && a.flags == flags)
249    {
250        entry.bytes += bytes;
251    } else {
252        allocs.push(DeviceAllocation {
253            devid,
254            flags,
255            bytes,
256        });
257    }
258}
259
260fn read_le_u64(buf: &[u8], off: usize) -> u64 {
261    u64::from_le_bytes(buf[off..off + 8].try_into().unwrap())
262}
263
264fn read_le_u16(buf: &[u8], off: usize) -> u16 {
265    u16::from_le_bytes(buf[off..off + 2].try_into().unwrap())
266}
btrfs_uapi/chunk.rs

btrfs_uapi/
chunk.rs
