4. pci_dma_set_mask 函数原型：参数解析、返回值含义与内核版本差异

pci_dma_set_mask 是 PCI 设备驱动配置 DMA 寻址能力最核心的接口。高位寻址设备（64-bit DMA capable）必须通过该函数告知内核：设备能够访问的物理地址范围。错误配置将导致 DMA 映射失败、数据损坏或内核 panic。

4.1 函数原型与参数解析

函数原型定义在 <linux/pci-dma-compat.h>（内核 5.x 之前）或 <linux/dma-mapping.h>（内核 5.x+）：

int pci_dma_set_mask(struct pci_dev *pdev, u64 mask);

mask 参数构造规则：

• 使用 DMA_BIT_MASK(n) 宏：生成低 n 位全 1 的掩码，即设备可访问 0 ~ 2^n - 1 地址范围
• 常见值：DMA_BIT_MASK(32) = 0x00000000FFFFFFFF，DMA_BIT_MASK(64) = 0xFFFFFFFFFFFFFFFF
• 高位设备若仅支持 48-bit 地址线，应使用 DMA_BIT_MASK(48)，而非 64-bit 掩码

4.2 返回值含义与错误处理

高位设备典型错误场景：

• IOMMU 限制： IOMMU 地址窗口小于设备请求的掩码，返回 -EIO
• 平台内存映射： 某些 SoC 平台高位内存不可 DMA 访问，内核拒绝 64-bit 掩码
• 设备未使能总线主控： 调用 pci_set_master 前调用本函数，返回 -EIO

/* 高位设备标准配置模式 */
if (!pci_set_dma_mask(pdev, DMA_BIT_MASK(64))) {
    dev_info(&pdev->dev, "64-bit DMA mask configured\n");
    /* 设置一致性掩码为 64-bit */
    pci_set_consistent_dma_mask(pdev, DMA_BIT_MASK(64));
} else if (!pci_set_dma_mask(pdev, DMA_BIT_MASK(48))) {
    dev_info(&pdev->dev, "48-bit DMA mask configured (fallback)\n");
    pci_set_consistent_dma_mask(pdev, DMA_BIT_MASK(48));
} else if (!pci_set_dma_mask(pdev, DMA_BIT_MASK(32))) {
    dev_warn(&pdev->dev, "32-bit DMA mask configured (limited)\n");
    pci_set_consistent_dma_mask(pdev, DMA_BIT_MASK(32));
} else {
    dev_err(&pdev->dev, "No suitable DMA mask available\n");
    return -ENXIO;
}

4.3 内核版本差异与演进

不同内核版本对 pci_dma_set_mask 的实现和接口有显著差异，高位设备驱动必须根据目标内核版本选择正确的调用方式：

版本迁移建议：

• 内核 5.18 及之前： 继续使用 pci_dma_set_mask，代码可读性高
• 内核 5.19 ~ 6.x： 使用 dma_set_mask(&pdev->dev, mask) 替代
• 新驱动开发： 直接使用 dma_set_mask_and_coherent 一次设置两个掩码

/* 内核 5.19+ 推荐写法 */
struct device *dev = &pdev->dev;

if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(64))) {
    dev_err(dev, "Failed to set 64-bit DMA mask\n");
    return -ENXIO;
}
dev_info(dev, "64-bit DMA mask configured (unified API)\n");

4.4 函数调用流程与内核决策路径

下图展示了 pci_dma_set_mask 从驱动调用到内核最终决策的完整路径，特别标注了高位寻址设备的关键检查点：

4.5 高位设备配置实战清单

配置高位寻址设备的 pci_dma_set_mask 时，请按以下清单逐项确认：

1. 确认设备地址线宽度： 读取设备能力寄存器（如 PCIe Device Capabilities Register 的 Max Payload Size 字段间接推断）
2. 使能总线主控： 在调用 pci_dma_set_mask 前必须调用 pci_set_master(pdev)
3. 选择最小必要掩码： 优先使用 DMA_BIT_MASK(64)，若失败则降级
4. 同步一致性掩码： 每次设置 DMA 掩码后立即调用 pci_set_consistent_dma_mask
5. 检查返回值： 非零返回值必须处理，不能忽略
6. 版本适配： 根据内核版本选择 pci_dma_set_mask 或 dma_set_mask