* @brief 阻塞式读取一个字符 * @return 读取到的字符 */

* @brief 计算 context ID * @param hart_id hart ID * @param mode 模式 (0=M-mode, 1=S-mode) * @return uint32_t context ID * @note 2 个模式的 context

* @brief 获取描述符的可变引用 * * 用于设置描述符的 addr、len、flags 和 next 字段。 * 调用者必须确保索引有效（通过 AllocDesc() 分配）。 * * @param idx 描述符索引（必须 < queue_size） *

* @brief 获取 NS16550A 设备实例 * @return 设备实例指针 */

* @brief 获取 PL011 设备实例 * @return 设备实例指针 */

* @brief 读取 64 位设备特性 * * 需要分两次 32 位读取（低 32 位和高 32 位）。 * 涉及硬件寄存器写入，因此不能声明为 const。 * * @return 设备支持的 64 位特性位 * @see virtio-v1.2#4.2.2.

* @brief 返回用于注册的 DriverEntry * @return DriverEntry 常量引用 */

* @brief 返回驱动注册入口 * * 匹配 virtio,mmio 兼容字符串；MatchStatic 检查 VirtIO magic number。 */

* @brief 返回用于注册的 DriverEntry * @return DriverEntry 常量引用 */

* @brief 获取环境层状态 */

* @brief 获取 GIC CPU Interface (Redistributor) 信息 * @return Expected<std::pair<uint64_t, size_t>> */

* @brief 获取 GIC Distributor 信息 * @return Expected<std::pair<uint64_t, size_t>> */

* @brief 读取中断标识寄存器（ISR / IIR） * * 返回值 bit[0]：0=有中断挂起，1=无中断挂起 * 返回值 bit[3:1]：中断源标识 * - 0b011: 接收线状态错误 * - 0b010: 接收数据就绪 * - 0b1

* @brief 读取屏蔽后的中断状态寄存器（MIS） * * 返回经 IMSC 屏蔽后的中断状态，只包含被使能的中断源。 * * @return 中断状态位掩码 * @see ARM PL011 Technical Reference Manual */

内部接口：获取挂载表

* @brief 获取协商后的特性位 * * @return 设备和驱动程序都支持的特性位掩码 */

* @brief 获取 PSCI method 属性 * @param offset 节点偏移 * @return Expected<const char*> method 字符串 */

* @brief 获取队列最大容量 * * 涉及硬件寄存器写入，因此不能声明为 const。 * * @param queue_idx 队列索引 * @return 队列最大大小 * @see virtio-v1.2#4.2.3.2 */

* @brief 获取就绪队列大小 * @return 队列中的任务数量 */

* @brief 获取就绪队列大小 * @return size_t 队列中的任务数量 */

* @brief 获取队列大小 * @return 队列大小（0 或 1） */

* @brief 读取原始中断状态寄存器（RIS） * * 返回所有中断源的原始状态（不经 IMSC 屏蔽）。 * * @return 原始中断状态位掩码 */

* @brief 获取 reg 属性（返回第一个 reg 条目） * @param offset 节点偏移量 * @return Expected<std::pair<uint64_t, size_t>> base 和 size * @post 返回第一个 <base, size>

* @brief 计算 RequestSlot DMA 内存所需字节数 * * @return pair.first = 总字节数，pair.second = 对齐要求（字节） */

* @brief 获取多队列所需的总 DMA 内存大小 * * 调用者应根据此值预分配页对齐、已清零的 DMA 内存。 * * @param queue_count 请求的队列数量 * @param queue_size 每个队列的描述符数量（必须为 2 的幂）

* @brief 获取信号名称（调试用） * @param signum 信号编号 * @return 信号名称字符串 */

* @brief 获取性能监控统计数据 * * @return 当前统计数据的快照 * @see 架构文档 §3 */

* @brief 获取资源类型 * @return ResourceType 资源类型 */

* @brief 检查接收缓冲区是否有数据可读（不消耗数据） * @return true 如果有数据可读 */

* @brief 计算 ICENABLER 寄存器偏移 * @param n 寄存器索引 * @return uint64_t 寄存器偏移地址 */

* @brief 计算 ICFGR 寄存器偏移 * @param n 寄存器索引 * @return uint64_t 寄存器偏移地址 */

* @brief 计算 ICPENDR 寄存器偏移 * @param n 寄存器索引 * @return uint64_t 寄存器偏移地址 */

@name 构造/析构函数 @{

idle 线程入口函数

* @brief 计算 IGROUPR 寄存器偏移 * @param n 寄存器索引 * @return uint64_t 寄存器偏移地址 */

@name 构造/析构函数 @{

@name 构造/析构函数 @{

@name 构造/析构函数 @{

软中断 (IPI) 处理

* @brief 计算 IPRIORITYR 寄存器偏移 * @param n 寄存器索引 * @return uint64_t 寄存器偏移地址 */

* @brief 计算 IPRIORITYR 寄存器偏移 * @param n 寄存器索引 * @return uint64_t 寄存器偏移地址 */

* @brief 检查设备是否已激活（DRIVER_OK 已设置） */

* @brief 判断队列是否为空 * @return 队列为空返回 true，否则返回 false */

* @brief 判断队列是否为空 * @return bool 队列为空返回 true */

* @brief 判断队列是否为空 * @return 如果没有 idle 任务则返回 true */

* @brief 检查是否有中断挂起 * @return true 如果有中断挂起 */

* @brief 检查是否有中断挂起 * @return true 如果有屏蔽后的中断挂起 */

* @brief 检查信号是否不可捕获 (SIGKILL, SIGSTOP) * @param signum 信号编号 * @return true 信号不可捕获 */

* @brief 检查设备是否成功初始化 */

* @brief 检查信号编号是否有效 * @param signum 信号编号 * @return true 有效 */

检查区域是否有效（非空指针且大小非零）

* @brief 计算 ISENABLER 寄存器偏移 * @param n 寄存器索引 * @return uint64_t 寄存器偏移地址 */

* @brief 计算 ITARGETSR 寄存器偏移 * @param n 寄存器索引 * @return uint64_t 寄存器偏移地址 */

* @brief 构造函数 * @param elf_addr elf 地址 */

* @brief 构造函数 * @param header fdt 数据地址 * @pre header 指向有效的 DTB 数据 * @post fdt_header_ 已初始化并通过校验 */

* @brief 批量触发硬件通知 * * 通知设备 Available Ring 中有新的待处理请求。 * 调用者应在 EnqueueRead/EnqueueWrite 后调用此方法。 * * @param queue_index 队列索引（当前仅支持 0） *