4. 核心数据结构设计：设备描述符、请求队列、DMA缓冲区管理、错误码枚举定义

存储插件驱动的核心数据结构是连接操作系统存储栈与硬件设备之间的契约。设计不当将导致内存碎片、DMA 地址错乱、并发竞争或错误传播失效。本节从设备描述符、请求队列、DMA 缓冲区管理和错误码枚举四个维度，给出架构级定义与实现要点。

4.1 设备描述符：驱动与硬件的唯一上下文

设备描述符（Device Descriptor）是驱动实例化后维护的私有数据结构，包含硬件寄存器映射、中断状态、队列基址、电源状态等全局信息。每个 PCIe 功能（Function）对应一个描述符实例。

4.1.1 核心字段定义

字段	类型	说明
pci_dev	struct pci_dev *	PCI 设备指针，用于 MMIO 与 DMA 映射
regs	void __iomem *	BAR 空间虚拟地址，寄存器访问入口
irq_vectors	int[]	MSI-X 中断向量表，长度等于队列数
sq_base	dma_addr_t	提交队列（Submission Queue）DMA 基址
cq_base	dma_addr_t	完成队列（Completion Queue）DMA 基址
state	enum dev_state	设备状态：INIT / ACTIVE / SUSPEND / ERROR
lock	spinlock_t	描述符自旋锁，保护状态切换

/* 设备描述符结构体示例 */
struct nvme_device {
    struct pci_dev        *pdev;
    void __iomem          *regs;
    int                    irq_vectors[NVME_MAX_QUEUES];
    dma_addr_t             sq_base[NVME_MAX_QUEUES];
    dma_addr_t             cq_base[NVME_MAX_QUEUES];
    enum dev_state         state;
    spinlock_t             lock;
    struct request_queue  *rq_queue;   /* 关联的请求队列 */
    struct dma_pool       *dma_pool;   /* DMA 缓冲区池 */
};

4.2 请求队列：IO 路径的调度中枢

请求队列（Request Queue）是块设备层与驱动层之间的 IO 缓冲与调度单元。存储插件通常实现多队列模型（Multi-Queue），每个队列独立持有提交队列（SQ）和完成队列（CQ），减少锁竞争。

4.2.1 多队列架构设计

• 队列深度（Queue Depth）：每个 SQ 可容纳的未完成请求数，典型值 64~1024，受硬件限制。
• 队列对（Queue Pair）：一个 SQ 与一个 CQ 绑定，共享中断向量。
• IO 调度策略：支持轮询（Polling）与中断（Interrupt）两种完成通知模式。
• 请求生命周期：ALLOC → SUBMIT → COMPLETE → FREE，状态机由驱动维护。

/* 请求队列结构体示例 */
struct nvme_queue {
    int                qid;           /* 队列编号 */
    struct nvme_device *dev;          /* 所属设备 */
    dma_addr_t         sq_dma;        /* SQ DMA 地址 */
    dma_addr_t         cq_dma;        /* CQ DMA 地址 */
    u32                sq_tail;       /* SQ 尾指针（驱动写） */
    u32                cq_head;       /* CQ 头指针（驱动读） */
    spinlock_t         sq_lock;       /* SQ 提交锁 */
    spinlock_t         cq_lock;       /* CQ 完成锁 */
    struct list_head   pending_list;  /* 待完成请求链表 */
    struct list_head   free_list;     /* 空闲请求链表 */
};

4.2.2 请求队列关键参数对比

参数	NVMe 典型值	SATA AHCI 典型值	架构考量
队列数量	1~64K	1（NCQ 深度 32）	多队列减少锁竞争，提升 NUMA 亲和性
队列深度	64~1024	32	深度越大吞吐越高，但延迟增加
完成通知	中断 / 轮询	中断	轮询模式适合低延迟场景
请求大小	64 字节（SQE）	8 字节（FIS）	SQE 承载更多元数据

4.3 DMA 缓冲区管理：地址映射与生命周期

DMA 缓冲区是驱动与硬件共享数据的关键区域。存储插件必须管理好缓冲区的分配、映射、同步和释放，避免 Cache Coherency 问题或地址越界。

4.3.1 缓冲区管理策略

• 预分配池（DMA Pool）：在驱动初始化时分配固定大小的 DMA 缓冲区，减少运行时分配开销。
• 流式映射（Streaming DMA）：适用于一次性 IO 请求，使用 dma_map_single() / dma_unmap_single()。
• 一致性映射（Consistent DMA）：适用于控制结构（如 SQ/CQ），使用 dma_alloc_coherent()，保证 CPU 与硬件视角一致。
• IOMMU 兼容：通过 dma_map_ops 抽象，支持虚拟化场景下的地址翻译。

/* DMA 缓冲区分配与映射示例 */
/* 分配一致性内存用于提交队列 */
struct nvme_command *sq;
dma_addr_t sq_dma;

sq = dma_alloc_coherent(&pdev->dev,
                        queue_depth * sizeof(struct nvme_command),
                        &sq_dma,
                        GFP_KERNEL);
if (!sq)
    return -ENOMEM;

/* 流式映射 IO 数据缓冲区 */
dma_addr_t data_dma = dma_map_single(&pdev->dev,
                                     data_buf,
                                     data_len,
                                     DMA_TO_DEVICE);
if (dma_mapping_error(&pdev->dev, data_dma))
    goto unmap_sq;

4.3.2 缓冲区生命周期对比

类型	分配函数	映射持久性	典型用途	注意事项
一致性映射	dma_alloc_coherent	长期有效	SQ / CQ / 控制结构	内存不可缓存，写性能较低
流式映射	dma_map_single	单次 IO	数据缓冲区	需在 IO 完成后立即解映射
SG 列表映射	dma_map_sg	单次 IO	分散/聚集 IO	需遍历 SG 条目，注意对齐
DMA 池	dma_pool_alloc	长期复用	固定大小请求	需配合 dma_pool_destroy 清理

4.4 错误码枚举定义：可诊断的错误传播体系

错误码枚举（Error Code Enumeration）是驱动与上层存储栈、用户态工具之间的错误契约。统一的错误码体系可以快速定位硬件故障、协议异常或资源耗尽。

4.4.1 错误码分类与定义

错误域	枚举值	含义	触发场景
硬件错误	DEV_ERR_HW_FAULT	硬件致命错误	PCIe 链路断开、寄存器读回全 F
硬件错误	DEV_ERR_TIMEOUT	请求超时	CQ 长时间无完成
协议错误	DEV_ERR_INVALID_CMD	命令格式错误	SQE 中 opcode 或 PRP 字段非法
协议错误	DEV_ERR_ABORTED	命令被硬件中止	队列深度超限或电源状态切换
资源错误	DEV_ERR_NOMEM	内存分配失败	DMA 缓冲区或请求结构体不足
资源错误	DEV_ERR_QUEUE_FULL	队列已满	SQ 尾指针追上头指针
状态错误	DEV_ERR_BAD_STATE	设备状态不允许操作	SUSPEND 状态下提交 IO

/* 错误码枚举定义示例 */
enum nvme_dev_err {
    /* 硬件错误 (0x01-0x0F) */
    DEV_ERR_HW_FAULT       = 0x01,
    DEV_ERR_TIMEOUT        = 0x02,
    DEV_ERR_LINK_DOWN      = 0x03,

    /* 协议错误 (0x10-0x2F) */
    DEV_ERR_INVALID_CMD    = 0x10,
    DEV_ERR_ABORTED        = 0x11,
    DEV_ERR_DATA_UNDERRUN  = 0x12,
    DEV_ERR_DATA_OVERRUN   = 0x13,

    /* 资源错误 (0x30-0x3F) */
    DEV_ERR_NOMEM          = 0x30,
    DEV_ERR_QUEUE_FULL     = 0x31,
    DEV_ERR_DMA_MAP_FAIL   = 0x32,

    /* 状态错误 (0x40-0x4F) */
    DEV_ERR_BAD_STATE      = 0x40,
    DEV_ERR_NOT_READY      = 0x41,
};

4.4.2 错误传播路径

1. 硬件检测：寄存器状态位或 CQ 完成状态字段指示错误。
2. 驱动捕获：中断处理或轮询线程读取错误码，转换为 enum nvme_dev_err。
3. 请求回调：通过 blk_mq_complete_request() 携带错误码返回块层。
4. 日志上报：调用 dev_err() 打印错误上下文，供运维工具解析。