zenith_linux/

descriptor.rs

//! AF_XDP 描述符模块
//!
//! 实现与内核 AF_XDP ABI 兼容的描述符体系：
//! - XdpDesc: 内核 xdp_desc 结构的 Rust 表示（addr/len/options 三字段）
//! - Descriptor: 带所有权元数据的高层描述符（在 XdpDesc 基础上扩展 owner/generation）
//! - DescriptorEngine: 描述符分配/释放/守恒校验引擎
//!
//! # 内核 ABI 对齐
//!
//! Linux 内核 `xdp_desc` 结构（include/uapi/linux/bpf.h）:
//! ```c
//! struct xdp_desc {
//!     __u64 addr;      // UMEM 中的偏移地址
//!     __u32 len;      // 数据长度（字节）
//!     __u32 options;  // 选项标志（如 XDP_TX_META_DATA）
//! };
//! ```
//!
//! # 高层扩展
//!
//! Zenith 在 `XdpDesc` 基础上扩展了所有权元数据：
//! - owner: 描述符所有者（队列/Worker ID）
//! - generation: 代际号（防止 ABA 问题）

use crate::error::{DescriptorError, Result};
use std::sync::atomic::{AtomicU64, Ordering};

/// 描述符类型（高层语义）
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DescriptorType {
    /// 数据帧描述符
    DataFrame,
    /// 控制消息描述符
    ControlMessage,
    /// 保留描述符
    Reserved,
}

/// AF_XDP 内核 xdp_desc 结构的 Rust 表示
///
/// 严格对应内核 ABI，size = 16 bytes。
#[repr(C, align(8))]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct XdpDesc {
    /// UMEM 中的偏移地址（帧起始地址 = umem_base + addr）
    pub addr: u64,
    /// 数据长度（字节）
    pub len: u32,
    /// 选项标志（XDP_TX_META_DATA 等）
    pub options: u32,
}

// 编译期布局断言：XdpDesc 必须与内核 xdp_desc（include/uapi/linux/bpf.h）
// 同为 16 字节，否则与内核 ring 共享内存的描述符读写整体错位。
const _: () = assert!(
    core::mem::size_of::<XdpDesc>() == 16,
    "XdpDesc 必须与内核 xdp_desc 同为 16 字节"
);

impl XdpDesc {
    /// 创建零值描述符
    #[inline]
    pub const fn zero() -> Self {
        Self {
            addr: 0,
            len: 0,
            options: 0,
        }
    }

    /// 是否为零描述符（所有字段均为零值，内核 ring 中的空槽标记）
    ///
    /// 注意：addr=0 是合法的 UMEM 偏移（帧索引 0），
    /// 只有 addr、len、options 全为零时才表示无效描述符。
    #[inline]
    pub fn is_zero(&self) -> bool {
        self.addr == 0 && self.len == 0 && self.options == 0
    }

    /// 转换为 u64 数组（用于内核 ring 操作）
    #[inline]
    pub fn as_u64_slice(&self) -> [u64; 2] {
        // xdp_desc 为 16 字节：addr (u64) + len (u32) + options (u32)
        // 在 ring 中实际存储为 u64[2] 数组
        [self.addr, (self.len as u64) | ((self.options as u64) << 32)]
    }

    /// 从 u64 数组创建
    #[inline]
    pub fn from_u64_slice(raw: [u64; 2]) -> Self {
        Self {
            addr: raw[0],
            len: (raw[1] as u32),
            options: (raw[1] >> 32) as u32,
        }
    }
}

impl Default for XdpDesc {
    fn default() -> Self {
        Self::zero()
    }
}

/// 高层描述符
///
/// 封装 XdpDesc 并添加所有权元数据。
/// - index: 帧索引（通过 addr 计算）
/// - generation: 代际号（ABA 防护）
/// - owner: 所有者 ID（队列/Worker）
/// - desc_type: 语义类型
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Descriptor {
    /// 内核描述符（addr/len/options）
    xdp: XdpDesc,
    /// 帧索引（从 addr 派生）
    index: u32,
    /// 代际号
    generation: u16,
    /// 所有者 ID
    owner: u16,
    /// 语义类型
    desc_type: DescriptorType,
}

/// 最大合法 frame index（20-bit 帧索引域上界 2^20 - 1，AGENT.md §5.1）
///
/// 描述符范围检查必须在 frame index 域进行，禁止用 raw 64-bit addr 值；
/// 超出该域的 `addr >> frame_shift` 说明 raw addr 非法（高位信息会在
/// `as u32` 截断中静默丢失并指向错误帧），必须 fail-closed。
pub const MAX_FRAME_INDEX: u64 = (1 << 20) - 1;

impl Descriptor {
    /// 创建新的描述符
    #[inline]
    pub fn new(
        xdp: XdpDesc,
        index: u32,
        owner: u16,
        generation: u16,
        desc_type: DescriptorType,
    ) -> Self {
        Self {
            xdp,
            index,
            owner,
            generation,
            desc_type,
        }
    }

    /// 从内核描述符创建（自动派生 index，fail-closed）
    ///
    /// `xdp.addr >> frame_shift` 必须落入 20-bit frame index 域（≤ [`MAX_FRAME_INDEX`]）。
    /// `frame_shift` 由调用方从 [`DescriptorEngine::frame_shift`] 获取，
    /// 保证与引擎实际帧移位一致，杜绝硬编码 `>> 12` 在非 4096 帧大小下的索引坍塌。
    ///
    /// # 返回
    /// * `Ok(Self)` - 帧索引合法的描述符
    /// * `Err(DescriptorError::OutOfRange)` - `addr >> frame_shift` 超出 20-bit 帧索引域；
    ///   静默 `as u32` 截断会丢弃高 32 位并指向错误帧（甚至回绕到帧 0），
    ///   故构造期拒绝（fail-closed，参照 [`DescriptorEngine::allocate`] 的对称语义）
    #[inline]
    pub fn from_xdp(xdp: XdpDesc, owner: u16, generation: u16, frame_shift: u32) -> Result<Self> {
        let raw_index = xdp.addr >> frame_shift;
        if raw_index > MAX_FRAME_INDEX {
            return Err(DescriptorError::OutOfRange {
                descriptor: xdp.addr,
                max_valid: MAX_FRAME_INDEX,
            }
            .into());
        }
        // 上界校验后该转换必不丢失信息；仍以 try_from 形式化杜绝 `as u32` 截断语义
        let index = u32::try_from(raw_index).map_err(|_| DescriptorError::OutOfRange {
            descriptor: xdp.addr,
            max_valid: MAX_FRAME_INDEX,
        })?;
        Ok(Self {
            xdp,
            index,
            owner,
            generation,
            desc_type: DescriptorType::DataFrame,
        })
    }

    /// 获取内核描述符
    #[inline]
    pub fn xdp_desc(&self) -> &XdpDesc {
        &self.xdp
    }

    /// 获取 addr
    #[inline]
    pub fn addr(&self) -> u64 {
        self.xdp.addr
    }

    /// 获取 len
    #[inline]
    pub fn len(&self) -> u32 {
        self.xdp.len
    }

    /// 判断描述符的 len 是否为 0
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.xdp.len == 0
    }

    /// 获取 options
    #[inline]
    pub fn options(&self) -> u32 {
        self.xdp.options
    }

    /// 获取帧索引
    #[inline]
    pub fn index(&self) -> u32 {
        self.index
    }

    /// 获取所有者 ID
    #[inline]
    pub fn owner(&self) -> u16 {
        self.owner
    }

    /// 获取代际号
    #[inline]
    pub fn generation(&self) -> u16 {
        self.generation
    }

    /// 获取描述符类型
    #[inline]
    pub fn descriptor_type(&self) -> DescriptorType {
        self.desc_type
    }

    /// 设置所有者
    #[inline]
    pub fn set_owner(&mut self, new_owner: u16) {
        self.owner = new_owner;
    }

    /// 设置代际号
    #[inline]
    pub fn set_generation(&mut self, new_generation: u16) {
        self.generation = new_generation;
    }

    /// 是否为零描述符
    #[inline]
    pub fn is_zero(&self) -> bool {
        self.xdp.is_zero()
    }

    /// 转换为原始 ring 数据（两个 u64）
    #[inline]
    pub fn to_raw(&self) -> [u64; 2] {
        self.xdp.as_u64_slice()
    }
}

impl Default for Descriptor {
    fn default() -> Self {
        Self {
            xdp: XdpDesc::zero(),
            index: 0,
            generation: 0,
            owner: 0,
            desc_type: DescriptorType::Reserved,
        }
    }
}

/// 描述符校验引擎
///
/// 提供完整的描述符校验、所有权管理和守恒等式校验。
/// 单线程无锁设计：内部状态通过原子类型以 `&self` 变更
/// （单 Owner 持有 `XskSocket`，生命周期内不跨线程共享）。
///
/// # Ordering 论证
/// 本引擎由单个 `XskSocket` 独占持有，生命周期内不跨线程共享（单 Owner
/// 顺序访问，无并发发布场景）。原子类型仅用于以 `&self` 变更内部状态，
/// 因此全部使用 `Ordering::Relaxed`：不存在跨线程 happens-before 需求。
/// 若未来引入跨线程共享（如 `Arc<DescriptorEngine>`），必须重审本论证。
pub struct DescriptorEngine {
    /// 最大有效帧索引
    max_frame_index: u64,
    /// 帧地址移位（log2(frame_size)，默认 12 = 4096 字节帧）
    frame_shift: u32,
    /// 当前代际号
    current_generation: AtomicU64,
    /// 已分配描述符计数
    allocated_count: AtomicU64,
    /// 已释放描述符计数
    freed_count: AtomicU64,
    /// 活跃描述符位图（每个 bit 表示一个描述符是否活跃）
    active_bitmap: Vec<AtomicU64>,
}

impl std::fmt::Debug for DescriptorEngine {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("DescriptorEngine")
            .field("max_frame_index", &self.max_frame_index)
            .field("current_generation", &self.current_generation)
            .field("allocated_count", &self.allocated_count)
            .field("freed_count", &self.freed_count)
            .finish()
    }
}

impl DescriptorEngine {
    /// 创建描述符校验引擎（默认 4096 字节帧，shift = 12，fail-closed）
    ///
    /// # 参数
    /// * `max_frames` - 最大帧数量（必须 ≤ 2^20，即 20-bit 帧索引域）
    ///
    /// # 返回
    /// * `Ok(Self)` - 引擎实例
    /// * `Err(DescriptorError::InvalidCapacity)` - `max_frames > 2^20`，
    ///   拒绝构造：超域帧索引与 [`MAX_FRAME_INDEX`] 契约冲突
    pub fn new(max_frames: u64) -> Result<Self> {
        // shift = 12 静态合法（位于 11..=15 区间）
        Self::with_frame_shift(max_frames, 12)
    }

    /// 创建描述符校验引擎（显式帧移位，fail-closed）
    ///
    /// # 参数
    /// * `max_frames` - 最大帧数量（必须 ≤ 2^20，即 20-bit 帧索引域）
    /// * `frame_shift` - log2(frame_size)，合法区间 11..=15
    ///   （帧大小 2048..=32768 字节）
    ///
    /// # 返回
    /// * `Ok(Self)` - 引擎实例
    /// * `Err(DescriptorError::InvalidFrameShift)` - `frame_shift` 非法，
    ///   拒绝构造：防止 `frame_index << frame_shift` 在 debug shift-overflow
    ///   panic / release 移位掩码静默错误地址
    /// * `Err(DescriptorError::InvalidCapacity)` - `max_frames > 2^20`，
    ///   拒绝构造：20-bit frame index 域容量上限为 2^20（[`MAX_FRAME_INDEX`] + 1），
    ///   超域帧索引会与 `Descriptor::from_xdp` 的越界拒绝语义冲突
    pub fn with_frame_shift(max_frames: u64, frame_shift: u32) -> Result<Self> {
        if !(11..=15).contains(&frame_shift) {
            return Err(DescriptorError::InvalidFrameShift(frame_shift).into());
        }
        if max_frames > MAX_FRAME_INDEX + 1 {
            return Err(DescriptorError::InvalidCapacity(max_frames).into());
        }
        Ok(Self::new_unchecked(max_frames, frame_shift))
    }

    /// 内部免检构造：仅由 `new`（shift=12 静态合法）与
    /// `with_frame_shift`（已通过 11..=15 校验）调用
    fn new_unchecked(max_frames: u64, frame_shift: u32) -> Self {
        let bitmap_words = max_frames.div_ceil(64);
        let active_bitmap = (0..bitmap_words)
            .map(|_| AtomicU64::new(0))
            .collect();

        Self {
            max_frame_index: max_frames.saturating_sub(1),
            frame_shift,
            current_generation: AtomicU64::new(1),
            allocated_count: AtomicU64::new(0),
            freed_count: AtomicU64::new(0),
            active_bitmap,
        }
    }

    /// 获取帧移位（log2(frame_size)）
    #[inline]
    pub fn frame_shift(&self) -> u32 {
        self.frame_shift
    }

    /// 分配描述符（从帧索引创建）
    ///
    /// # 参数
    /// * `frame_index` - 帧索引
    /// * `owner` - 所有者 ID
    ///
    /// # 返回
    /// * `Result<Descriptor>` - 新描述符
    pub fn allocate(&self, frame_index: u32, owner: u16) -> Result<Descriptor> {
        // 范围检查与 verify 对称：越界帧索引 fail-closed（此前仅 verify 检查，
        // allocate 静默接受并在 set_bitmap 中丢弃越界位，语义不对称）
        if u64::from(frame_index) > self.max_frame_index {
            return Err(DescriptorError::OutOfRange {
                descriptor: u64::from(frame_index) << self.frame_shift,
                max_valid: self.max_frame_index,
            }
            .into());
        }

        // 位图已置位 = 帧已分配：fail-closed 拒绝重复分配（此前静默放行，
        // 位图重幂等置位 + allocated_count 递增 → 双计数破坏守恒等式）
        if self.get_bitmap(frame_index) {
            return Err(DescriptorError::AlreadyAllocated(u64::from(frame_index)).into());
        }

        let generation = self.current_generation.load(Ordering::Relaxed) as u16;

        // 设置位图位
        self.set_bitmap(frame_index, true);

        self.allocated_count.fetch_add(1, Ordering::Relaxed);

        // 构建 XdpDesc：addr = frame_index << frame_shift（按配置帧大小）
        let xdp = XdpDesc {
            addr: u64::from(frame_index) << self.frame_shift,
            len: 0,
            options: 0,
        };

        Ok(Descriptor::new(
            xdp,
            frame_index,
            owner,
            generation,
            DescriptorType::DataFrame,
        ))
    }

    /// 释放描述符
    ///
    /// # 参数
    /// * `desc` - 要释放的描述符
    ///
    /// # 返回
    /// * `Result<()>` - 成功或错误
    pub fn release(&self, desc: &Descriptor) -> Result<()> {
        let index = desc.index();
        if !self.get_bitmap(index) {
            return Err(DescriptorError::AlreadyFreed(desc.addr()).into());
        }

        self.set_bitmap(index, false);
        self.freed_count.fetch_add(1, Ordering::Relaxed);

        Ok(())
    }

    /// 回滚 allocate（清除位图 + 递减计数，不生成描述符）
    ///
    /// 用于 `fill_descriptors` 等"先批量 allocate 再 enqueue"场景：
    /// enqueue 失败时帧已位图置位但未入环，形成孤立帧；
    /// 通过位图为权威回滚，恢复 allocated == freed + active 守恒等式。
    ///
    /// # 参数
    /// * `frame_index` - 要回滚的帧索引
    ///
    /// # 返回
    /// * `true` - 位图存在且已清除；`false` - 帧索引越界或位图未置位（fail-closed 不 panic）
    pub fn rollback_allocate(&self, frame_index: u32) -> bool {
        if u64::from(frame_index) > self.max_frame_index {
            return false;
        }
        if !self.get_bitmap(frame_index) {
            return false;
        }
        self.set_bitmap(frame_index, false);
        // sub 饱和兜底：若 INVARIANT 破坏（allocated_count == 0），不 panic
        let _ = self.allocated_count.fetch_sub(1, Ordering::Relaxed);
        true
    }

    /// 校验描述符有效性
    ///
    /// 基于位图的权威校验：检查帧索引范围、活跃状态和所有权。
    /// 位图是描述符有效性的唯一权威来源，不依赖描述符字段值。
    ///
    /// # 参数
    /// * `desc` - 要校验的描述符
    /// * `expected_owner` - 期望的所有者
    ///
    /// # 返回
    /// * `Result<()>` - 成功或错误
    pub fn verify(&self, desc: &Descriptor, expected_owner: u16) -> Result<()> {
        let index = desc.index();
        if (index as u64) > self.max_frame_index {
            return Err(DescriptorError::OutOfRange {
                descriptor: desc.addr(),
                max_valid: self.max_frame_index,
            }
            .into());
        }

        // 位图是有效性的权威来源
        if !self.get_bitmap(index) {
            return Err(DescriptorError::AlreadyFreed(desc.addr()).into());
        }

        if desc.owner() != expected_owner {
            return Err(DescriptorError::OwnershipMismatch {
                expected: expected_owner as u32,
                actual: desc.owner() as u32,
            }
            .into());
        }

        Ok(())
    }

    /// 事务化所有权迁移
    ///
    /// 原子性地将描述符的所有者从 old_owner 迁移到 new_owner。
    ///
    /// # 参数
    /// * `desc` - 描述符引用
    /// * `old_owner` - 旧所有者
    /// * `new_owner` - 新所有者
    ///
    /// # 返回
    /// * `Result<Descriptor>` - 新的描述符（已迁移所有者）
    pub fn transfer_ownership(
        &self,
        desc: &Descriptor,
        old_owner: u16,
        new_owner: u16,
    ) -> Result<Descriptor> {
        self.verify(desc, old_owner)?;

        // 代际号计算：先在 u64 域完成 fetch_add + 1（杜绝 `as u16 + 1` 的
        // 截断后溢出 panic），再校验范围落入 u16；超出范围 Fail-Closed 返回错误。
        let next = self.current_generation.fetch_add(1, Ordering::Relaxed).wrapping_add(1);
        let new_generation = u16::try_from(next).map_err(|_| {
            DescriptorError::TransactionFailed(format!("代际号 {next} 超出 u16 范围"))
        })?;
        let mut new_desc = *desc;
        new_desc.set_owner(new_owner);
        new_desc.set_generation(new_generation);

        Ok(new_desc)
    }

    /// 查询帧是否已被引擎分配（位图是否置位）
    ///
    /// 供 Fill Ring 预填/补填路径判定「帧是否已登记」：与 `allocate` 的
    /// `AlreadyAllocated` fail-closed 配套，避免从 0 重复登记已分配帧。
    #[inline]
    pub fn is_allocated(&self, index: u32) -> bool {
        self.get_bitmap(index)
    }

    /// 增加全局代际号（fail-closed：与 `transfer_ownership` 同域约束）
    ///
    /// 代际域为 u16（`Descriptor.generation: u16`）；原实现可无限增长，
    /// 与 `transfer_ownership`「超 u16::MAX 拒绝」语义不一致——调用方若把
    /// 返回值截断成 u16 会静默回绕。超域时返回错误而非截断。
    ///
    /// # 返回
    /// * `Ok(u64)` - 递增后的新代际号（≤ u16::MAX）
    /// * `Err(DescriptorError::TransactionFailed)` - 代际号超出 u16 范围
    #[inline]
    pub fn bump_generation(&self) -> Result<u64> {
        let next = self
            .current_generation
            .fetch_add(1, Ordering::Relaxed)
            .wrapping_add(1);
        if next > u64::from(u16::MAX) {
            return Err(DescriptorError::TransactionFailed(format!(
                "代际号 {next} 超出 u16 范围"
            ))
            .into());
        }
        Ok(next)
    }

    /// 获取守恒统计
    #[inline]
    pub fn conservation_stats(&self) -> (u64, u64) {
        (
            self.allocated_count.load(Ordering::Relaxed),
            self.freed_count.load(Ordering::Relaxed),
        )
    }

    /// 检查守恒等式：allocated == freed + active
    pub fn verify_conservation(&self) -> bool {
        let (allocated, freed) = self.conservation_stats();
        let active = self.count_active();
        allocated == freed + active
    }

    /// 统计活跃描述符数量
    fn count_active(&self) -> u64 {
        let mut count = 0u64;
        for word in &self.active_bitmap {
            count += word.load(Ordering::Relaxed).count_ones() as u64;
        }
        count
    }

    /// 设置位图位
    fn set_bitmap(&self, index: u32, value: bool) {
        let word_idx = (index / 64) as usize;
        let bit_idx = index % 64;
        if word_idx < self.active_bitmap.len() {
            if value {
                self.active_bitmap[word_idx].fetch_or(1u64 << bit_idx, Ordering::Relaxed);
            } else {
                self.active_bitmap[word_idx].fetch_and(!(1u64 << bit_idx), Ordering::Relaxed);
            }
        }
    }

    /// 获取位图位
    fn get_bitmap(&self, index: u32) -> bool {
        let word_idx = (index / 64) as usize;
        let bit_idx = index % 64;
        if word_idx < self.active_bitmap.len() {
            (self.active_bitmap[word_idx].load(Ordering::Relaxed) >> bit_idx) & 1 == 1
        } else {
            false
        }
    }
}

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

    #[test]
    fn test_xdp_desc_zero() {
        let desc = XdpDesc::zero();
        assert!(desc.is_zero());
        assert_eq!(desc.addr, 0);
        assert_eq!(desc.len, 0);
        assert_eq!(desc.options, 0);
    }

    #[test]
    fn test_xdp_desc_roundtrip() {
        let desc = XdpDesc {
            addr: 0x1000,
            len: 1500,
            options: 0x42,
        };
        let raw = desc.as_u64_slice();
        let recovered = XdpDesc::from_u64_slice(raw);
        assert_eq!(recovered, desc);
    }

    #[test]
    fn test_descriptor_creation() {
        let xdp = XdpDesc {
            addr: 4096,
            len: 1500,
            options: 0,
        };
        let desc = Descriptor::new(xdp, 1, 1, 1, DescriptorType::DataFrame);
        assert_eq!(desc.index(), 1);
        assert_eq!(desc.addr(), 4096);
        assert_eq!(desc.len(), 1500);
        assert_eq!(desc.owner(), 1);
        assert_eq!(desc.generation(), 1);
        assert_eq!(desc.descriptor_type(), DescriptorType::DataFrame);
    }

    #[test]
    fn test_descriptor_modify() {
        let xdp = XdpDesc::zero();
        let mut desc = Descriptor::new(xdp, 0, 1, 1, DescriptorType::DataFrame);
        desc.set_owner(2);
        assert_eq!(desc.owner(), 2);
        desc.set_generation(5);
        assert_eq!(desc.generation(), 5);
    }

    #[test]
    fn test_descriptor_from_xdp() {
        let xdp = XdpDesc {
            addr: 8192, // frame index = 8192 >> 12 = 2
            len: 64,
            options: 0,
        };
        let desc = Descriptor::from_xdp(xdp, 3, 42, 12).unwrap();
        assert_eq!(desc.index(), 2);
        assert_eq!(desc.addr(), 8192);
        assert_eq!(desc.owner(), 3);
        assert_eq!(desc.generation(), 42);
    }

    #[test]
    fn test_descriptor_from_xdp_out_of_range_rejected() {
        // addr >> 12 = 2^20，恰好越出 20-bit frame index 域 → fail-closed（AGENT.md §5.1）
        let xdp = XdpDesc {
            addr: (1u64 << 20) << 12,
            len: 64,
            options: 0,
        };
        let result = Descriptor::from_xdp(xdp, 1, 1, 12);
        assert!(matches!(
            result,
            Err(LinuxError::Descriptor(DescriptorError::OutOfRange { .. }))
        ));
    }

    #[test]
    fn test_descriptor_from_xdp_high_bits_truncation_rejected() {
        // addr >> 12 = 2^32：`as u32` 会静默截断为 0 并指向帧 0 → 必须构造期拒绝
        let xdp = XdpDesc {
            addr: (1u64 << 32) << 12,
            len: 0,
            options: 0,
        };
        assert!(Descriptor::from_xdp(xdp, 1, 1, 12).is_err());
    }

    #[test]
    fn test_descriptor_from_xdp_max_valid_index() {
        // addr >> 12 = 2^20 - 1（20-bit 域最大合法值）→ 接受
        let xdp = XdpDesc {
            addr: MAX_FRAME_INDEX << 12,
            len: 0,
            options: 0,
        };
        let desc = Descriptor::from_xdp(xdp, 1, 1, 12).unwrap();
        assert_eq!(desc.index() as u64, MAX_FRAME_INDEX);
    }

    #[test]
    fn test_descriptor_from_xdp_non_default_frame_shift() {
        // frame_shift=11（帧大小 2048）：addr=4096 >> 11 = 2，与 shift=12 的 addr=8192 >> 12 = 2 等价
        let xdp = XdpDesc {
            addr: 4096, // 4096 >> 11 = 2
            len: 64,
            options: 0,
        };
        let desc = Descriptor::from_xdp(xdp, 1, 1, 11).unwrap();
        assert_eq!(desc.index(), 2);

        // shift=15（帧大小 32768）：addr=65536 >> 15 = 2
        let xdp2 = XdpDesc {
            addr: 65536,
            len: 64,
            options: 0,
        };
        let desc2 = Descriptor::from_xdp(xdp2, 1, 1, 15).unwrap();
        assert_eq!(desc2.index(), 2);
    }

    #[test]
    fn test_descriptor_engine_allocate_release() {
        let engine = DescriptorEngine::new(1024).unwrap();

        let desc = engine.allocate(0, 1).unwrap();
        assert_eq!(desc.index(), 0);
        assert_eq!(desc.owner(), 1);
        assert_eq!(desc.addr(), 0);

        engine.verify(&desc, 1).unwrap();
        engine.release(&desc).unwrap();

        let result = engine.verify(&desc, 1);
        assert!(result.is_err());
    }

    #[test]
    fn test_descriptor_engine_zero_rejected() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let zero = Descriptor::default();
        let result = engine.verify(&zero, 1);
        assert!(result.is_err());
    }

    #[test]
    fn test_descriptor_ownership_transfer() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc = engine.allocate(0, 1).unwrap();
        let new_desc = engine.transfer_ownership(&desc, 1, 2).unwrap();
        assert_eq!(new_desc.owner(), 2);
        assert_eq!(new_desc.index(), 0);
    }

    #[test]
    fn test_descriptor_conservation() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc1 = engine.allocate(0, 1).unwrap();
        let _desc2 = engine.allocate(1, 1).unwrap();
        engine.release(&desc1).unwrap();
        assert!(engine.verify_conservation());
        let (allocated, freed) = engine.conservation_stats();
        assert_eq!(allocated, 2);
        assert_eq!(freed, 1);
    }

    #[test]
    fn test_descriptor_out_of_range() {
        let engine = DescriptorEngine::new(100).unwrap();
        let xdp = XdpDesc {
            addr: (2000u64) << 12,
            len: 0,
            options: 0,
        };
        let desc = Descriptor::new(xdp, 2000, 1, 1, DescriptorType::DataFrame);
        let result = engine.verify(&desc, 1);
        assert!(result.is_err());
    }

    #[test]
    fn test_already_freed_rejected() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc = engine.allocate(5, 1).unwrap();
        engine.release(&desc).unwrap();
        let result = engine.release(&desc);
        assert!(result.is_err());
    }

    #[test]
    fn test_ownership_mismatch() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc = engine.allocate(10, 2).unwrap();
        let result = engine.verify(&desc, 1);
        assert!(result.is_err());
    }

    #[test]
    fn test_frame_index_boundary_zero() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc = engine.allocate(0, 1).unwrap();
        assert_eq!(desc.index(), 0);
        assert_eq!(desc.addr(), 0);
        engine.verify(&desc, 1).unwrap();
    }

    #[test]
    fn test_frame_index_boundary_one() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc = engine.allocate(1, 1).unwrap();
        assert_eq!(desc.index(), 1);
        assert_eq!(desc.addr(), 4096);
        engine.verify(&desc, 1).unwrap();
    }

    #[test]
    fn test_frame_index_20bit_max() {
        let max_frames = 0x100000u64; // 2^20 = 1,048,576
        let engine = DescriptorEngine::new(max_frames).unwrap();

        let max_index = (max_frames - 1) as u32;
        let desc = engine.allocate(max_index, 1).unwrap();
        assert_eq!(desc.index(), max_index);
        assert_eq!(desc.addr(), (max_index as u64) << 12);
        engine.verify(&desc, 1).unwrap();
    }

    #[test]
    fn test_frame_index_out_of_range() {
        let engine = DescriptorEngine::new(100).unwrap();
        let xdp = XdpDesc {
            addr: (200u64) << 12,
            len: 0,
            options: 0,
        };
        let desc = Descriptor::new(xdp, 200, 1, 1, DescriptorType::DataFrame);
        let result = engine.verify(&desc, 1);
        assert!(result.is_err());
    }

    #[test]
    fn test_descriptor_default_is_zero() {
        let desc = Descriptor::default();
        assert!(desc.is_zero());
        assert_eq!(desc.index(), 0);
        assert_eq!(desc.owner(), 0);
        assert_eq!(desc.generation(), 0);
        assert_eq!(desc.descriptor_type(), DescriptorType::Reserved);
    }

    #[test]
    fn test_xdp_desc_default_is_zero() {
        let desc = XdpDesc::default();
        assert!(desc.is_zero());
        assert_eq!(desc.addr, 0);
        assert_eq!(desc.len, 0);
        assert_eq!(desc.options, 0);
    }

    #[test]
    fn test_xdp_desc_not_zero_with_addr_only() {
        let desc = XdpDesc {
            addr: 4096,
            len: 0,
            options: 0,
        };
        assert!(!desc.is_zero());
    }

    #[test]
    fn test_xdp_desc_not_zero_with_len_only() {
        let desc = XdpDesc {
            addr: 0,
            len: 100,
            options: 0,
        };
        assert!(!desc.is_zero());
    }

    #[test]
    fn test_xdp_desc_not_zero_with_options_only() {
        let desc = XdpDesc {
            addr: 0,
            len: 0,
            options: 1,
        };
        assert!(!desc.is_zero());
    }

    #[test]
    fn test_descriptor_to_raw_roundtrip() {
        let xdp = XdpDesc {
            addr: 0x12345678,
            len: 1500,
            options: 0xDEAD,
        };
        let desc = Descriptor::new(xdp, 0, 1, 2, DescriptorType::DataFrame);
        let raw = desc.to_raw();
        let recovered = XdpDesc::from_u64_slice(raw);
        assert_eq!(recovered, xdp);
    }

    #[test]
    fn test_generation_bump() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let initial = engine.bump_generation().unwrap();
        assert!(initial > 1);

        let next = engine.bump_generation().unwrap();
        assert_eq!(next, initial + 1);
    }

    #[test]
    fn test_generation_bump_overflow_fail_closed() {
        // Fail-Closed：bump_generation 与 transfer_ownership 同域约束，
        // 代际号超出 u16::MAX 必须返回错误而非静默超域/截断回绕
        let engine = DescriptorEngine::new(1024).unwrap();
        engine
            .current_generation
            .store(u64::from(u16::MAX), Ordering::Relaxed);
        let result = engine.bump_generation();
        assert!(result.is_err(), "代际号越界必须 Fail-Closed");
    }

    #[test]
    fn test_transfer_ownership_increments_generation() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc = engine.allocate(0, 1).unwrap();
        let original_gen = desc.generation();

        let new_desc = engine.transfer_ownership(&desc, 1, 2).unwrap();
        assert_eq!(new_desc.owner(), 2);
        assert_eq!(new_desc.index(), 0);
        assert!(new_desc.generation() > original_gen);
    }

    #[test]
    fn test_transfer_ownership_wrong_old_owner_fails() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc = engine.allocate(0, 1).unwrap();
        let result = engine.transfer_ownership(&desc, 99, 2);
        assert!(result.is_err());
    }

    #[test]
    fn test_transfer_ownership_generation_overflow_fails() {
        // Fail-Closed：代际号超出 u16 范围时返回错误，而非截断/溢出 panic
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc = engine.allocate(0, 1).unwrap();
        // 将全局代际计数器推到 u16 上限（下一次 +1 即越界）
        engine.current_generation.store(u64::from(u16::MAX), Ordering::Relaxed);
        let result = engine.transfer_ownership(&desc, 1, 2);
        assert!(result.is_err(), "代际号越界必须 Fail-Closed");
    }

    #[test]
    fn test_multiple_allocations_and_releases() {
        let engine = DescriptorEngine::new(1024).unwrap();
        let mut descs = Vec::new();

        for i in 0..100 {
            let desc = engine.allocate(i, (i % 10) as u16).unwrap();
            descs.push(desc);
        }

        assert!(engine.verify_conservation());
        let (allocated, freed) = engine.conservation_stats();
        assert_eq!(allocated, 100);
        assert_eq!(freed, 0);

        for desc in &descs[..50] {
            engine.release(desc).unwrap();
        }

        assert!(engine.verify_conservation());
        let (allocated, freed) = engine.conservation_stats();
        assert_eq!(allocated, 100);
        assert_eq!(freed, 50);

        for desc in &descs[50..] {
            engine.release(desc).unwrap();
        }

        assert!(engine.verify_conservation());
        let (allocated, freed) = engine.conservation_stats();
        assert_eq!(allocated, 100);
        assert_eq!(freed, 100);
    }

    #[test]
    fn test_already_in_use_check() {
        // Fail-Closed：重复分配位图已置位的帧必须返回 AlreadyAllocated，
        // 而非幂等置位 + allocated_count 递增的双计数（破坏守恒等式）
        let engine = DescriptorEngine::new(1024).unwrap();
        let desc = engine.allocate(42, 1).unwrap();
        engine.verify(&desc, 1).unwrap();
        assert!(engine.is_allocated(42));

        let result = engine.allocate(42, 2);
        assert!(
            matches!(
                result,
                Err(LinuxError::Descriptor(DescriptorError::AlreadyAllocated(42)))
            ),
            "已分配帧重复分配必须返回 AlreadyAllocated，实际 {result:?}"
        );
        // 失败分配不得改变守恒统计（allocated == freed + active 仍恒等）
        let (allocated, freed) = engine.conservation_stats();
        assert_eq!(allocated, 1);
        assert_eq!(freed, 0);
        assert!(engine.verify_conservation());
    }

    #[test]
    fn test_engine_capacity_fail_closed_over_20bit() {
        // Fail-Closed：20-bit 帧索引域容量上限为 2^20，超域拒绝构造
        assert!(DescriptorEngine::new((1u64 << 20) + 1).is_err());
        assert!(DescriptorEngine::new(u64::MAX).is_err());
        assert!(DescriptorEngine::with_frame_shift((1u64 << 20) + 1, 12).is_err());
        // 边界：恰好 2^20 合法；越界帧移位仍按原语义拒绝
        assert!(DescriptorEngine::new(1u64 << 20).is_ok());
        assert!(DescriptorEngine::with_frame_shift(1024, 16).is_err());
    }

    #[test]
    fn test_descriptor_engine_debug_format() {
        let engine = DescriptorEngine::new(256).unwrap();
        let debug = format!("{:?}", engine);
        assert!(debug.contains("DescriptorEngine"));
        assert!(debug.contains("max_frame_index"));
        assert!(debug.contains("current_generation"));
    }

    #[test]
    fn test_descriptor_type_variants() {
        let types = vec![
            DescriptorType::DataFrame,
            DescriptorType::ControlMessage,
            DescriptorType::Reserved,
        ];
        for desc_type in types {
            let xdp = XdpDesc::zero();
            let desc = Descriptor::new(xdp, 0, 0, 0, desc_type);
            assert_eq!(desc.descriptor_type(), desc_type);
        }
    }

    #[test]
    fn test_large_descriptor_engine() {
        let engine = DescriptorEngine::new(65536).unwrap();
        let desc = engine.allocate(65535, 1).unwrap();
        assert_eq!(desc.index(), 65535);
        engine.verify(&desc, 1).unwrap();
        engine.release(&desc).unwrap();
        assert!(engine.verify_conservation());
    }
}