3. NAPI 数据结构：napi_struct 结构体详解

NAPI 轮询机制的核心数据结构是 napi_struct，它位于 <linux/netdevice.h> 中。每个支持 NAPI 的网卡驱动都会为每个接收队列（或每个设备）分配一个 napi_struct 实例。该结构体将设备驱动、软中断处理以及轮询逻辑紧密关联在一起，是理解 NAPI 收包流程的基石。

3.1 napi_struct 核心字段

下表列出了 napi_struct 中最关键的字段及其作用：

3.2 poll 函数指针详解

poll 是 NAPI 机制中驱动与内核协议栈之间的核心契约。软中断（net_rx_action）在轮询到某个 NAPI 实例时，会调用该函数指针。驱动开发者必须实现此函数，其典型逻辑如下：

1. 从硬件 RX 描述符环中批量读取报文：通过 DMA 地址获取已接收的数据包。
2. 构造 sk_buff 并提交给协议栈：调用 napi_gro_receive() 或 netif_receive_skb() 将报文送入上层处理。
3. 返回实际处理的报文数量：返回值不能超过传入的 budget（即 napi_struct->weight）。
4. 判断是否退出轮询：如果处理的报文数小于 budget，说明硬件队列已空，驱动应调用 napi_complete() 结束轮询并重新开启硬中断。

// 典型的驱动 poll 函数伪代码
static int my_napi_poll(struct napi_struct *napi, int budget)
{
    struct my_priv *priv = container_of(napi, struct my_priv, napi);
    int work_done = 0;

    // 1. 从硬件 RX 环中批量取包，最多取 budget 个
    while (work_done < budget) {
        struct sk_buff *skb = my_hw_dequeue(priv);
        if (!skb)
            break; // 硬件队列已空

        // 2. 提交 skb 到协议栈（GRO 路径）
        napi_gro_receive(napi, skb);
        work_done++;
    }

    // 3. 判断是否完成本轮轮询
    if (work_done < budget) {
        // 硬件队列已空，关闭 NAPI 调度，重新开启硬中断
        napi_complete_done(napi, work_done);
        my_hw_enable_interrupts(priv);
    }

    return work_done;
}

3.3 状态标志位：NAPI_STATE_SCHED 等

napi_struct->state 字段使用位图来管理 NAPI 实例的多种状态。内核定义了以下标准标志位：

状态转换的核心逻辑：

• 当硬中断触发时，驱动调用 napi_schedule()，该函数会设置 NAPI_STATE_SCHED 标志，并将 NAPI 实例加入当前 CPU 的 poll_list，然后触发软中断 NET_RX_SOFTIRQ。
• 软中断 net_rx_action 遍历 poll_list，对每个 NAPI 实例调用其 poll 函数。
• 当 poll 函数返回且实际处理量小于 budget 时，驱动调用 napi_complete()，该函数清除 NAPI_STATE_SCHED 和 NAPI_STATE_LISTED 标志，并将 NAPI 实例从 poll_list 中移除。
• 如果在 SCHED 状态下又有新中断到达，中断处理函数会设置 NAPI_STATE_MISSED 标志，确保在下次轮询结束时重新调度 NAPI，避免丢包。

3.4 NAPI 数据结构关系图

下图展示了 napi_struct 与软中断、设备驱动以及协议栈之间的协作关系：

3.5 多队列网卡中的 NAPI 实例布局

现代多队列网卡（如 Intel ixgbe、Mellanox mlx5）通常为每个 RX 队列分配独立的 napi_struct 实例。这种设计允许每个 CPU 核心独立处理一个队列的报文，实现收包处理的并行化。驱动在初始化时会为每个队列创建 NAPI 实例，并将其绑定到特定的 CPU（通过 irq_affinity 或 RPS 机制）。

// 多队列驱动中 NAPI 实例的典型初始化模式
struct my_rx_queue {
    struct napi_struct napi;
    // ... 其他队列相关字段
};

static int my_probe(struct pci_dev *pdev, ...)
{
    struct my_priv *priv;
    int i;

    priv = kzalloc(sizeof(*priv), GFP_KERNEL);
    for (i = 0; i < priv->num_rx_queues; i++) {
        struct my_rx_queue *rxq = &priv->rx_queues[i];
        // 初始化 NAPI，绑定 poll 函数，设置 weight
        netif_napi_add(priv->netdev, &rxq->napi, my_poll, 64);
    }
    // ...
}