3. NAPI 的初始化与注册

NAPI 机制的启用始于驱动初始化阶段。在设备被内核发现并分配 net_device 结构体之后，驱动必须在 probe 回调中完成 NAPI 实例的创建与注册。本章将深入剖析 netif_napi_add() 函数的原型、参数含义、注册时机以及多队列场景下的注册策略。

3.1 netif_napi_add() 函数原型与参数详解

netif_napi_add() 是内核提供给驱动注册 NAPI 实例的核心 API，定义在 <linux/netdevice.h> 中。其函数原型如下：

void netif_napi_add(struct net_device *dev,
                    struct napi_struct *napi,
                    int (*poll)(struct napi_struct *, int),
                    int weight);

四个参数的含义与使用要点如下表所示：

调用 netif_napi_add() 后，内核会完成以下初始化工作：

• 将 napi->dev 指向传入的 dev；
• 将 napi->poll 和 napi->weight 赋值为传入参数；
• 初始化 NAPI 实例的链表节点、状态标志位和就绪队列；
• 将 NAPI 实例添加到设备 dev->napi_list 链表中，完成注册。

3.2 NAPI 实例的注册时机：驱动 probe 阶段

NAPI 实例的注册必须发生在设备初始化流程的 probe 阶段，即在 struct net_device_ops 中的 ndo_open 被调用之前。典型的注册时序如下：

1. 分配 net_device：调用 alloc_etherdev() 或 alloc_netdev() 分配网络设备结构体。
2. 设置硬件参数：读取 PCI 配置空间、映射 BAR 空间、初始化 DMA 队列等。
3. 分配驱动私有数据：在私有结构中为每个 RX 队列分配 napi_struct 实例。
4. 调用 netif_napi_add()：为每个 RX 队列注册 NAPI 实例。
5. 注册 net_device：调用 register_netdev() 将设备注册到内核网络子系统。

以下是一个典型的驱动 probe 函数片段：

static int mydrv_probe(struct pci_dev *pdev, const struct pci_device_id *id)
{
    struct net_device *ndev;
    struct mydrv_priv *priv;
    int i, ret;

    // 1. 分配 net_device
    ndev = alloc_etherdev(sizeof(struct mydrv_priv));
    if (!ndev)
        return -ENOMEM;

    pci_set_drvdata(pdev, ndev);
    priv = netdev_priv(ndev);

    // 2. 初始化硬件（省略具体实现）
    ret = mydrv_init_hw(pdev, priv);
    if (ret)
        goto err_free_netdev;

    // 3. 为每个 RX 队列注册 NAPI
    for (i = 0; i < priv->num_rx_queues; i++) {
        netif_napi_add(ndev, &priv->napi[i], mydrv_poll, 64);
    }

    // 4. 注册网络设备
    ret = register_netdev(ndev);
    if (ret)
        goto err_free_napi;

    return 0;

err_free_napi:
    // 清理已注册的 NAPI 实例
    for (i = 0; i < priv->num_rx_queues; i++)
        netif_napi_del(&priv->napi[i]);
err_free_netdev:
    free_netdev(ndev);
    return ret;
}

3.3 多队列网卡的 NAPI 注册策略

现代高速网卡普遍支持多 RX 队列（RSS / 多队列），每个队列可以独立触发中断并拥有独立的 NAPI 实例。多队列场景下的 NAPI 注册策略直接影响 CPU 负载均衡和收包性能。

3.3.1 一对一策略：每队列独立 NAPI

这是最常用的策略，每个 RX 硬件队列对应一个独立的 napi_struct 实例。中断亲和性（IRQ affinity）将每个队列的中断绑定到不同的 CPU 核心，实现并行收包。

// 一对一注册示例
for (i = 0; i < priv->num_rx_queues; i++) {
    netif_napi_add(ndev, &priv->napi[i], mydrv_poll, 64);
    // 后续通过 irq_set_affinity_hint 将队列 i 的中断绑定到 CPU i
}

3.3.2 多对一策略：多队列共享 NAPI

在低端硬件或虚拟化场景中，多个 RX 队列可以共享同一个 NAPI 实例。此时 poll 回调需要遍历所有共享队列，从每个队列中收取报文。该策略减少了 NAPI 实例数量，但牺牲了并行度。

// 多对一注册示例（所有队列共享一个 NAPI）
netif_napi_add(ndev, &priv->napi, mydrv_poll_multi, 64);

// poll 回调中遍历所有队列
static int mydrv_poll_multi(struct napi_struct *napi, int budget)
{
    struct mydrv_priv *priv = container_of(napi, struct mydrv_priv, napi);
    int work_done = 0;
    int i;

    for (i = 0; i < priv->num_rx_queues; i++) {
        work_done += mydrv_poll_queue(&priv->rx_queue[i], budget - work_done);
        if (work_done >= budget)
            break;
    }
    return work_done;
}

3.3.3 策略对比

3.4 注册后的清理与反注册

在驱动卸载（remove 回调）或设备热拔时，必须使用 netif_napi_del() 反注册所有 NAPI 实例。该函数将 NAPI 实例从设备的 napi_list 中移除，并确保没有正在执行的 poll 回调。

static void mydrv_remove(struct pci_dev *pdev)
{
    struct net_device *ndev = pci_get_drvdata(pdev);
    struct mydrv_priv *priv = netdev_priv(ndev);
    int i;

    unregister_netdev(ndev);

    // 反注册所有 NAPI 实例
    for (i = 0; i < priv->num_rx_queues; i++)
        netif_napi_del(&priv->napi[i]);

    free_netdev(ndev);
}