4. 第一个PCIe驱动：模块初始化、probe/remove回调、设备ID表编写

编写第一个PCIe驱动是理解Linux设备模型与PCIe子系统协同工作的关键一步。一个完整的PCIe驱动核心由三部分组成：模块初始化/退出函数、probe/remove回调、以及设备ID表。本节将逐一拆解这些组件，并展示它们如何协同工作，使内核能够在设备插入时自动加载并初始化驱动。

4.1 驱动骨架：模块初始化与退出

每个PCIe驱动都必须向内核注册一个pci_driver结构体。模块初始化函数负责完成注册，退出函数负责注销。这是驱动的“入口”和“出口”。

#include <linux/module.h>
#include <linux/pci.h>

static int __init mypci_init(void)
{
    int ret;
    pr_info("mypci: module init\n");
    ret = pci_register_driver(&mypci_driver);
    if (ret)
        pr_err("mypci: failed to register driver: %d\n", ret);
    return ret;
}

static void __exit mypci_exit(void)
{
    pr_info("mypci: module exit\n");
    pci_unregister_driver(&mypci_driver);
}

module_init(mypci_init);
module_exit(mypci_exit);

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Your Name");
MODULE_DESCRIPTION("Sample PCIe Driver");

4.2 设备ID表：驱动与设备的“握手协议”

设备ID表是驱动声明“我能支持哪些设备”的清单。内核PCI子系统在枚举总线时，会遍历所有已注册驱动的ID表，匹配成功的设备才会调用该驱动的probe回调。

ID表使用struct pci_device_id结构体数组定义，并以空结构体结尾。常用匹配字段如下：

/* 设备ID表 */
#define MY_VENDOR_ID  0x10EE
#define MY_DEVICE_ID  0x7021

static const struct pci_device_id mypci_ids[] = {
    { PCI_DEVICE(MY_VENDOR_ID, MY_DEVICE_ID) },
    /* 也可以匹配多个设备 */
    { PCI_DEVICE(0x8086, 0x1234) },
    /* 通配符匹配（谨慎使用） */
    // { PCI_DEVICE(PCI_ANY_ID, PCI_ANY_ID) },
    { 0, }
};

MODULE_DEVICE_TABLE(pci, mypci_ids);

4.3 probe回调：驱动的“初始化舞台”

当内核发现一个设备的vendor/device ID与驱动的ID表匹配时，会调用probe函数。这是驱动初始化硬件、分配资源、注册接口的场所。一个典型的probe流程如下：

1. 启用设备：调用 pci_enable_device() 使能PCI配置空间访问。
2. 设置DMA掩码：调用 dma_set_mask() 和 dma_set_coherent_mask()。
3. 请求MMIO/I/O区域：使用 pci_request_regions() 或 pci_iomap()。
4. 设置总线主控：调用 pci_set_master() 使能DMA。
5. 分配私有数据结构：使用 devm_kzalloc() 等托管分配函数。
6. 注册中断：调用 request_irq() 或 pci_alloc_irq_vectors()。
7. 注册设备接口：如字符设备、net_device、misc_device等。

static int mypci_probe(struct pci_dev *pdev, const struct pci_device_id *id)
{
    struct mydev_priv *priv;
    int ret;

    pr_info("mypci: probe device %04x:%04x\n", pdev->vendor, pdev->device);

    /* 1. 启用PCI设备 */
    ret = pci_enable_device(pdev);
    if (ret)
        return ret;

    /* 2. 设置DMA掩码（64位优先） */
    ret = dma_set_mask(&pdev->dev, DMA_BIT_MASK(64));
    if (ret) {
        ret = dma_set_mask(&pdev->dev, DMA_BIT_MASK(32));
        if (ret)
            goto err_disable;
    }

    /* 3. 请求MMIO区域 */
    ret = pci_request_regions(pdev, "mypci");
    if (ret)
        goto err_disable;

    /* 4. 设置总线主控 */
    pci_set_master(pdev);

    /* 5. 分配私有数据 */
    priv = devm_kzalloc(&pdev->dev, sizeof(*priv), GFP_KERNEL);
    if (!priv) {
        ret = -ENOMEM;
        goto err_release;
    }
    pci_set_drvdata(pdev, priv);

    /* 6. 映射BAR0 */
    priv->bar0 = pci_iomap(pdev, 0, 0);
    if (!priv->bar0) {
        ret = -EIO;
        goto err_release;
    }

    /* 7. 注册中断（MSI-X优先） */
    ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_MSIX | PCI_IRQ_MSI | PCI_IRQ_LEGACY);
    if (ret < 0)
        goto err_iounmap;

    priv->irq = pci_irq_vector(pdev, 0);
    ret = request_irq(priv->irq, mypci_irq_handler, 0, "mypci", priv);
    if (ret)
        goto err_free_vectors;

    pr_info("mypci: probe success, irq=%d\n", priv->irq);
    return 0;

err_free_vectors:
    pci_free_irq_vectors(pdev);
err_iounmap:
    pci_iounmap(pdev, priv->bar0);
err_release:
    pci_release_regions(pdev);
err_disable:
    pci_disable_device(pdev);
    return ret;
}

4.4 remove回调：优雅的“退场”

remove函数是probe的逆操作，负责释放所有已分配的资源。顺序必须与probe相反，以避免悬空指针或资源泄漏。

static void mypci_remove(struct pci_dev *pdev)
{
    struct mydev_priv *priv = pci_get_drvdata(pdev);

    pr_info("mypci: remove device\n");

    /* 逆序释放：先中断，再映射，再区域，最后设备 */
    free_irq(priv->irq, priv);
    pci_free_irq_vectors(pdev);
    pci_iounmap(pdev, priv->bar0);
    pci_release_regions(pdev);
    pci_disable_device(pdev);
    /* devm_kzalloc 自动释放，无需手动kfree */
}

4.5 完整驱动结构图

下图展示了PCIe驱动从模块加载到设备移除的完整生命周期，以及各组件之间的调用关系。

4.6 完整驱动示例

将上述组件组合在一起，就构成了一个完整的PCIe驱动框架。以下代码展示了pci_driver结构体的定义与注册：

static struct pci_driver mypci_driver = {
    .name     = "mypci",
    .id_table = mypci_ids,
    .probe    = mypci_probe,
    .remove   = mypci_remove,
    /* 可选回调 */
    // .shutdown = mypci_shutdown,
    // .suspend  = mypci_suspend,
    // .resume   = mypci_resume,
};

module_pci_driver(mypci_driver);  /* 如果使用简单初始化，可替代module_init/exit */

4.7 常见错误与调试技巧