btrfs_uapi/

device.rs

//! # Device management: adding, removing, querying, and extent layout
//!
//! Covers adding and removing devices from a mounted filesystem, scanning a
//! device to register it with the kernel, querying per-device I/O error
//! statistics, checking whether all devices of a multi-device filesystem
//! are present and ready, and computing minimum device sizes from the
//! device extent tree.
//!
//! Most operations require `CAP_SYS_ADMIN`.

use crate::{
    field_size,
    filesystem::FilesystemInfo,
    raw::{
        BTRFS_DEV_EXTENT_KEY, BTRFS_DEV_STATS_RESET, BTRFS_DEV_TREE_OBJECTID,
        BTRFS_DEVICE_SPEC_BY_ID, btrfs_dev_extent,
        btrfs_dev_stat_values_BTRFS_DEV_STAT_CORRUPTION_ERRS,
        btrfs_dev_stat_values_BTRFS_DEV_STAT_FLUSH_ERRS,
        btrfs_dev_stat_values_BTRFS_DEV_STAT_GENERATION_ERRS,
        btrfs_dev_stat_values_BTRFS_DEV_STAT_READ_ERRS,
        btrfs_dev_stat_values_BTRFS_DEV_STAT_VALUES_MAX,
        btrfs_dev_stat_values_BTRFS_DEV_STAT_WRITE_ERRS, btrfs_ioc_add_dev,
        btrfs_ioc_dev_info, btrfs_ioc_devices_ready, btrfs_ioc_forget_dev,
        btrfs_ioc_get_dev_stats, btrfs_ioc_rm_dev, btrfs_ioc_rm_dev_v2,
        btrfs_ioc_scan_dev, btrfs_ioctl_dev_info_args,
        btrfs_ioctl_get_dev_stats, btrfs_ioctl_vol_args,
        btrfs_ioctl_vol_args_v2,
    },
    tree_search::{SearchKey, tree_search},
};
use nix::{errno::Errno, libc::c_char};
use std::{
    ffi::CStr,
    fs::OpenOptions,
    mem,
    os::{fd::AsRawFd, unix::io::BorrowedFd},
};
use uuid::Uuid;

/// Information about a single device within a btrfs filesystem, as returned
/// by `BTRFS_IOC_DEV_INFO`.
#[derive(Debug, Clone)]
pub struct DeviceInfo {
    /// Device ID.
    pub devid: u64,
    /// Device UUID.
    pub uuid: Uuid,
    /// Number of bytes used on this device.
    pub bytes_used: u64,
    /// Total size of this device in bytes.
    pub total_bytes: u64,
    /// Path to the block device, e.g. `/dev/sda`.
    pub path: String,
}

/// Specifies a device for operations that can address by either path or ID.
#[derive(Debug, Clone)]
pub enum DeviceSpec<'a> {
    /// A block device path (e.g. `/dev/sdb`), or the special strings
    /// `"missing"` or `"cancel"` accepted by the remove ioctl.
    Path(&'a CStr),
    /// A btrfs device ID as reported by `BTRFS_IOC_DEV_INFO`.
    Id(u64),
}

/// Per-device I/O error statistics, as returned by `BTRFS_IOC_GET_DEV_STATS`.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DeviceStats {
    /// Device ID these stats belong to.
    pub devid: u64,
    /// Number of write I/O errors (EIO/EREMOTEIO from lower layers).
    pub write_errs: u64,
    /// Number of read I/O errors (EIO/EREMOTEIO from lower layers).
    pub read_errs: u64,
    /// Number of flush I/O errors (EIO/EREMOTEIO from lower layers).
    pub flush_errs: u64,
    /// Number of checksum or bytenr corruption errors detected on read.
    pub corruption_errs: u64,
    /// Number of generation errors (blocks not written where expected).
    pub generation_errs: u64,
}

impl DeviceStats {
    /// Sum of all error counters.
    pub fn total_errs(&self) -> u64 {
        self.write_errs
            + self.read_errs
            + self.flush_errs
            + self.corruption_errs
            + self.generation_errs
    }

    /// Returns `true` if every counter is zero.
    pub fn is_clean(&self) -> bool {
        self.total_errs() == 0
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn dev_stats_default_is_clean() {
        let stats = DeviceStats::default();
        assert!(stats.is_clean());
        assert_eq!(stats.total_errs(), 0);
    }

    #[test]
    fn dev_stats_total_errs() {
        let stats = DeviceStats {
            devid: 1,
            write_errs: 1,
            read_errs: 2,
            flush_errs: 3,
            corruption_errs: 4,
            generation_errs: 5,
        };
        assert_eq!(stats.total_errs(), 15);
        assert!(!stats.is_clean());
    }

    #[test]
    fn dev_stats_single_error_not_clean() {
        let stats = DeviceStats {
            corruption_errs: 1,
            ..DeviceStats::default()
        };
        assert!(!stats.is_clean());
        assert_eq!(stats.total_errs(), 1);
    }
}

/// Copy the bytes of `path` (without the nul terminator) into `name`,
/// returning `ENAMETOOLONG` if the path (including the terminator that the
/// kernel expects to already be present via zeroing) does not fit.
fn copy_path_to_name(name: &mut [c_char], path: &CStr) -> nix::Result<()> {
    let bytes = path.to_bytes(); // excludes nul terminator
    if bytes.len() >= name.len() {
        return Err(Errno::ENAMETOOLONG);
    }
    for (i, &b) in bytes.iter().enumerate() {
        name[i] = b as c_char;
    }
    // The remainder of `name` is already zeroed by the caller (mem::zeroed).
    Ok(())
}

/// Open `/dev/btrfs-control` for read+write, mapping any `std::io::Error` to
/// the appropriate `nix::errno::Errno`.
fn open_control() -> nix::Result<std::fs::File> {
    OpenOptions::new()
        .read(true)
        .write(true)
        .open("/dev/btrfs-control")
        .map_err(|e| {
            Errno::from_raw(e.raw_os_error().unwrap_or(nix::libc::ENODEV))
        })
}

/// Query information about the device with the given `devid` on the filesystem
/// referred to by `fd`.
///
/// Returns `None` if no device with that ID exists (`ENODEV`).
pub fn device_info(
    fd: BorrowedFd,
    devid: u64,
) -> nix::Result<Option<DeviceInfo>> {
    let mut raw: btrfs_ioctl_dev_info_args = unsafe { mem::zeroed() };
    raw.devid = devid;

    match unsafe { btrfs_ioc_dev_info(fd.as_raw_fd(), &mut raw) } {
        Err(Errno::ENODEV) => return Ok(None),
        Err(e) => return Err(e),
        Ok(_) => {}
    }

    let path = unsafe { CStr::from_ptr(raw.path.as_ptr() as *const _) }
        .to_string_lossy()
        .into_owned();

    Ok(Some(DeviceInfo {
        devid: raw.devid,
        uuid: Uuid::from_bytes(raw.uuid),
        bytes_used: raw.bytes_used,
        total_bytes: raw.total_bytes,
        path,
    }))
}

/// Query information about all devices in the filesystem referred to by `fd`,
/// using the device count from a previously obtained [`FilesystemInfo`].
///
/// Iterates devids `1..=max_id`, skipping any that return `ENODEV` (holes in
/// the devid space are normal when devices have been removed).
pub fn device_info_all(
    fd: BorrowedFd,
    fs_info: &FilesystemInfo,
) -> nix::Result<Vec<DeviceInfo>> {
    let mut devices = Vec::with_capacity(fs_info.num_devices as usize);
    for devid in 1..=fs_info.max_id {
        if let Some(info) = device_info(fd, devid)? {
            devices.push(info);
        }
    }
    Ok(devices)
}

/// Add a device to the btrfs filesystem referred to by `fd`.
///
/// `path` must be the path to an unmounted block device. The kernel requires
/// `CAP_SYS_ADMIN`.
pub fn device_add(fd: BorrowedFd, path: &CStr) -> nix::Result<()> {
    let mut raw: btrfs_ioctl_vol_args = unsafe { mem::zeroed() };
    copy_path_to_name(&mut raw.name, path)?;
    unsafe { btrfs_ioc_add_dev(fd.as_raw_fd(), &raw) }?;
    Ok(())
}

/// Remove a device from the btrfs filesystem referred to by `fd`.
///
/// The device can be specified either by path or by its btrfs device ID via
/// [`DeviceSpec`]. Uses `BTRFS_IOC_RM_DEV_V2` and falls back to the older
/// `BTRFS_IOC_RM_DEV` ioctl on kernels that do not support the v2 variant
/// (only possible when removing by path). The kernel requires `CAP_SYS_ADMIN`.
///
/// Errors: ENOTTY or EOPNOTSUPP from `RM_DEV_V2` triggers an automatic
/// fallback to the v1 ioctl (path-based removal only; by-ID removal
/// requires v2 and will propagate the error).  EBUSY if the device holds
/// the only copy of some data and cannot be removed.
pub fn device_remove(fd: BorrowedFd, spec: DeviceSpec) -> nix::Result<()> {
    let mut args: btrfs_ioctl_vol_args_v2 = unsafe { mem::zeroed() };

    match spec {
        DeviceSpec::Id(devid) => {
            args.flags = BTRFS_DEVICE_SPEC_BY_ID as u64;
            // SAFETY: devid is the active union member when BTRFS_DEVICE_SPEC_BY_ID is set.
            args.__bindgen_anon_2.devid = devid;
            unsafe { btrfs_ioc_rm_dev_v2(fd.as_raw_fd(), &args) }?;
        }
        DeviceSpec::Path(path) => {
            // SAFETY: name is the active union member when flags == 0.
            unsafe {
                copy_path_to_name(&mut args.__bindgen_anon_2.name, path)
            }?;
            match unsafe { btrfs_ioc_rm_dev_v2(fd.as_raw_fd(), &args) } {
                Ok(_) => {}
                // Fall back to the old single-arg ioctl on kernels that either
                // don't know about v2 (ENOTTY) or don't recognise our flags (EOPNOTSUPP).
                Err(Errno::ENOTTY) | Err(Errno::EOPNOTSUPP) => {
                    let mut old: btrfs_ioctl_vol_args =
                        unsafe { mem::zeroed() };
                    copy_path_to_name(&mut old.name, path)?;
                    unsafe { btrfs_ioc_rm_dev(fd.as_raw_fd(), &old) }?;
                }
                Err(e) => return Err(e),
            }
        }
    }

    Ok(())
}

/// Register a block device with the kernel's btrfs device scanner so that
/// multi-device filesystems containing it can be mounted.
///
/// Opens `/dev/btrfs-control` and issues `BTRFS_IOC_SCAN_DEV`. `path` must
/// be the path to a block device that contains a btrfs filesystem member.
pub fn device_scan(path: &CStr) -> nix::Result<()> {
    let ctl = open_control()?;
    let mut raw: btrfs_ioctl_vol_args = unsafe { mem::zeroed() };
    copy_path_to_name(&mut raw.name, path)?;
    unsafe { btrfs_ioc_scan_dev(ctl.as_raw_fd(), &raw) }?;
    Ok(())
}

/// Unregister a device (or all stale devices) from the kernel's btrfs device
/// scanner.
///
/// Opens `/dev/btrfs-control` and issues `BTRFS_IOC_FORGET_DEV`. If `path`
/// is `None`, all devices that are not part of a currently mounted filesystem
/// are unregistered. If `path` is `Some`, only that specific device path is
/// unregistered.
pub fn device_forget(path: Option<&CStr>) -> nix::Result<()> {
    let ctl = open_control()?;
    let mut raw: btrfs_ioctl_vol_args = unsafe { mem::zeroed() };
    if let Some(p) = path {
        copy_path_to_name(&mut raw.name, p)?;
    }
    unsafe { btrfs_ioc_forget_dev(ctl.as_raw_fd(), &raw) }?;
    Ok(())
}

/// Check whether all member devices of the filesystem that contains `path`
/// are available and the filesystem is ready to mount.
///
/// Opens `/dev/btrfs-control` and issues `BTRFS_IOC_DEVICES_READY`. `path`
/// must be the path to one of the block devices belonging to the filesystem.
/// Returns `Ok(())` when all devices are present; returns an error (typically
/// `ENOENT` or `ENXIO`) if the set is incomplete.
pub fn device_ready(path: &CStr) -> nix::Result<()> {
    let ctl = open_control()?;
    // BTRFS_IOC_DEVICES_READY is declared _IOR but the kernel reads the device
    // path from args.name, so we pass a mut pointer as ioctl_read! requires.
    let mut raw: btrfs_ioctl_vol_args = unsafe { mem::zeroed() };
    copy_path_to_name(&mut raw.name, path)?;
    unsafe { btrfs_ioc_devices_ready(ctl.as_raw_fd(), &mut raw) }?;
    Ok(())
}

/// Query I/O error statistics for the device identified by `devid` within the
/// filesystem referred to by `fd`.
///
/// If `reset` is `true`, the kernel atomically returns the current values and
/// then resets all counters to zero. The kernel requires `CAP_SYS_ADMIN`.
pub fn device_stats(
    fd: BorrowedFd,
    devid: u64,
    reset: bool,
) -> nix::Result<DeviceStats> {
    let mut raw: btrfs_ioctl_get_dev_stats = unsafe { mem::zeroed() };
    raw.devid = devid;
    raw.nr_items = btrfs_dev_stat_values_BTRFS_DEV_STAT_VALUES_MAX as u64;
    if reset {
        raw.flags = BTRFS_DEV_STATS_RESET as u64;
    }

    unsafe { btrfs_ioc_get_dev_stats(fd.as_raw_fd(), &mut raw) }?;

    Ok(DeviceStats {
        devid,
        write_errs: raw.values
            [btrfs_dev_stat_values_BTRFS_DEV_STAT_WRITE_ERRS as usize],
        read_errs: raw.values
            [btrfs_dev_stat_values_BTRFS_DEV_STAT_READ_ERRS as usize],
        flush_errs: raw.values
            [btrfs_dev_stat_values_BTRFS_DEV_STAT_FLUSH_ERRS as usize],
        corruption_errs: raw.values
            [btrfs_dev_stat_values_BTRFS_DEV_STAT_CORRUPTION_ERRS as usize],
        generation_errs: raw.values
            [btrfs_dev_stat_values_BTRFS_DEV_STAT_GENERATION_ERRS as usize],
    })
}

const DEV_EXTENT_LENGTH_OFF: usize =
    std::mem::offset_of!(btrfs_dev_extent, length);

const SZ_1M: u64 = 1024 * 1024;
const SZ_32M: u64 = 32 * 1024 * 1024;

/// Number of superblock mirror copies btrfs maintains.
const BTRFS_SUPER_MIRROR_MAX: usize = 3;

/// Return the byte offset of superblock mirror `i`.
///
/// Mirror 0 is at 64 KiB, mirror 1 at 64 MiB, mirror 2 at 256 GiB.
fn sb_offset(i: usize) -> u64 {
    match i {
        0 => 64 * 1024,
        _ => 1u64 << (20 + 10 * (i as u64)),
    }
}

/// A contiguous physical byte range on a device (inclusive end).
#[derive(Debug, Clone, Copy)]
struct Extent {
    start: u64,
    /// Inclusive end byte.
    end: u64,
}

/// Compute the minimum size to which device `devid` can be shrunk.
///
/// Walks the device tree for all `DEV_EXTENT_KEY` items belonging to
/// `devid`, sums their lengths, then adjusts for extents that sit beyond
/// the sum by checking whether they can be relocated into holes closer to
/// the start of the device. The algorithm matches `btrfs inspect-internal
/// min-dev-size` from btrfs-progs.
///
/// Requires `CAP_SYS_ADMIN`.
pub fn device_min_size(fd: BorrowedFd, devid: u64) -> nix::Result<u64> {
    let mut min_size: u64 = SZ_1M;
    let mut extents: Vec<Extent> = Vec::new();
    let mut holes: Vec<Extent> = Vec::new();
    let mut last_pos: Option<u64> = None;

    tree_search(
        fd,
        SearchKey::for_objectid_range(
            BTRFS_DEV_TREE_OBJECTID as u64,
            BTRFS_DEV_EXTENT_KEY,
            devid,
            devid,
        ),
        |hdr, data| {
            if data.len()
                < DEV_EXTENT_LENGTH_OFF + field_size!(btrfs_dev_extent, length)
            {
                return Ok(());
            }
            let phys_start = hdr.offset;
            let len = read_le_u64(data, DEV_EXTENT_LENGTH_OFF);

            min_size += len;

            // Extents are prepended (descending end offset) so that the
            // adjustment pass processes the highest-addressed extent first.
            extents.push(Extent {
                start: phys_start,
                end: phys_start + len - 1,
            });

            if let Some(prev_end) = last_pos
                && prev_end != phys_start
            {
                holes.push(Extent {
                    start: prev_end,
                    end: phys_start - 1,
                });
            }

            last_pos = Some(phys_start + len);
            Ok(())
        },
    )?;

    // Sort extents by descending end offset for the adjustment pass.
    extents.sort_by(|a, b| b.end.cmp(&a.end));

    adjust_min_size(&mut extents, &mut holes, &mut min_size);

    Ok(min_size)
}

/// Check whether a byte range `[start, end]` contains a superblock mirror.
fn hole_includes_sb_mirror(start: u64, end: u64) -> bool {
    (0..BTRFS_SUPER_MIRROR_MAX).any(|i| {
        let bytenr = sb_offset(i);
        bytenr >= start && bytenr <= end
    })
}

/// Adjust `min_size` downward by relocating tail extents into holes.
///
/// Processes extents in descending order of end offset. If an extent sits
/// beyond the current `min_size`, try to find a hole large enough to
/// relocate it. If no hole fits, the device cannot be shrunk past that
/// extent and `min_size` is set to its end + 1.
///
/// Adds scratch space (largest relocated extent + 32 MiB for a potential
/// system chunk allocation) when any relocation is needed.
fn adjust_min_size(
    extents: &mut Vec<Extent>,
    holes: &mut Vec<Extent>,
    min_size: &mut u64,
) {
    let mut scratch_space: u64 = 0;

    while let Some(&ext) = extents.first() {
        if ext.end < *min_size {
            break;
        }

        let extent_len = ext.end - ext.start + 1;

        // Find the first hole large enough to hold this extent.
        let hole_idx = holes.iter().position(|h| {
            let hole_len = h.end - h.start + 1;
            hole_len >= extent_len
        });

        let Some(idx) = hole_idx else {
            *min_size = ext.end + 1;
            break;
        };

        // If the target hole contains a superblock mirror location,
        // pessimistically assume we need one more extent worth of space.
        if hole_includes_sb_mirror(
            holes[idx].start,
            holes[idx].start + extent_len - 1,
        ) {
            *min_size += extent_len;
        }

        // Shrink or remove the hole.
        let hole_len = holes[idx].end - holes[idx].start + 1;
        if hole_len > extent_len {
            holes[idx].start += extent_len;
        } else {
            holes.remove(idx);
        }

        extents.remove(0);

        if extent_len > scratch_space {
            scratch_space = extent_len;
        }
    }

    if scratch_space > 0 {
        *min_size += scratch_space;
        // Chunk allocation may require a new system chunk (up to 32 MiB).
        *min_size += SZ_32M;
    }
}

fn read_le_u64(buf: &[u8], off: usize) -> u64 {
    u64::from_le_bytes(buf[off..off + 8].try_into().unwrap())
}