📚 课程目录第4章寒武纪驱动体系架构

4、寒武纪驱动体系架构：驱动分层设计、用户态与内核态交互、驱动与固件协作、主要模块划分

寒武纪NPU（神经网络处理单元）作为AI加速卡的核心计算引擎，其驱动体系并非单一的内核模块，而是一套跨越用户态、内核态与设备固件三个层面的完整软件栈。理解这套体系架构，是进行驱动开发、性能调优和问题定位的基础。本章将深入剖析寒武纪驱动的分层设计思想、用户态与内核态的交互机制、驱动与固件的协作模式，以及主要的功能模块划分，帮助开发者建立起从Host CPU到NPU计算单元的全局视图。

上图展示了寒武纪NPU驱动体系的整体架构。从纵向看，系统被清晰地划分为用户态、内核态和设备固件三个层次；从横向看，每一层内部又包含多个职责单一的功能模块。驱动开发者的工作通常聚焦于内核态驱动与固件接口的对接，但必须理解上下层之间的数据流和控制流，才能写出高效、稳定的代码。

4.1 驱动分层设计：职责边界与数据流

4.1.1 核心原理：三层隔离与解耦

寒武纪驱动采用严格的三层架构，其核心设计原则是“上层不感知下层实现细节，下层不依赖上层业务逻辑”。这种分层带来的直接好处是：

用户态（CNRT/CNCodec等）：负责AI框架的适配、算子调度、任务图构建和显存逻辑管理。它不直接操作硬件寄存器，而是通过系统调用将“任务描述”传递给内核。
内核态（cambricon_npu.ko）：作为资源管家，负责物理设备的管理、中断处理、DMA传输、内存映射和安全性校验。它不关心上层跑的是哪个AI框架，只负责将用户态的任务请求翻译为硬件可执行的命令序列。
设备固件（Firmware）：运行在NPU内部嵌入式处理器上，负责最底层的任务队列仲裁、计算核调度、功耗状态切换和错误上报。它只与内核态驱动通过Mailbox通信，不直接暴露给用户态。

这种分层设计使得每一层都可以独立演进。例如，当新一代NPU硬件调整了计算核的调度算法时，只需更新固件，内核驱动和用户态库可以保持兼容；反之，当需要支持新的AI框架时，只需在用户态增加适配层，无需改动内核和固件。

4.1.2 判断方法：如何确定一个功能应放在哪一层？

在实际开发中，经常需要判断某个新功能应该实现在哪一层。以下提供一套实用的判断准则：

是否涉及硬件寄存器直接操作？ 如果是，必须放在内核态或固件中。用户态无法直接访问BAR空间。
是否涉及进程间共享或安全隔离？ 例如多进程同时使用NPU时的资源隔离，必须由内核态驱动通过设备节点权限和文件锁机制实现。
是否对时延极度敏感（微秒级）？ 任务下发路径上的轻量级操作应尽量下沉到内核态或固件，避免用户态到内核态的频繁切换。
是否与AI框架的算子语义绑定？ 例如Tensor Shape推导、算子融合策略，这些属于用户态CNRT的职责。
是否涉及设备电源状态或时钟频率调整？ 这类操作必须由固件执行，内核驱动只负责下发请求和接收结果。

经验提醒：在寒武纪MLU370系列上，我们曾遇到一个性能问题：用户态频繁调用一个获取设备温度的小接口，导致整体推理性能下降5%。分析后发现该接口每次调用都会触发一次ioctl进入内核态，再通过Mailbox查询固件。优化方案是将温度查询改为固件主动上报（每100ms推送一次），用户态通过共享内存直接读取，彻底消除了系统调用开销。

4.1.3 案例拆解：一个矩阵乘法的旅程

以一次典型的矩阵乘法（GEMM）为例，观察数据如何穿越三层架构：

阶段	所在层	关键操作	耗时占比
1. 算子构建	用户态	将GEMM算子转换为内部任务节点，分配输出Tensor显存	~5%
2. 任务下发	用户态→内核态	调用ioctl(CN_IOCTL_SUBMIT_TASK)，携带任务描述符指针	~10%
3. 命令翻译	内核态	校验任务合法性，将任务描述符转换为硬件命令字，写入命令缓冲区	~15%
4. 门铃通知	内核态→固件	写Doorbell寄存器，通知固件新任务到达	~2%
5. 硬件执行	固件	任务调度器分配计算核，DMA引擎搬运数据，执行矩阵乘	~60%
6. 完成通知	固件→内核态	写中断寄存器，触发MSI-X中断	~3%
7. 唤醒用户态	内核态→用户态	中断处理函数唤醒等待队列，用户态poll返回可读事件	~5%

从表中可以看出，真正耗时的部分在固件执行阶段（60%），而驱动路径上的开销主要集中在任务翻译（15%）和上下文切换（10%）。这提示我们：优化驱动时，应重点减少不必要的内存拷贝和系统调用次数，例如使用批量任务提交接口（一次ioctl提交多个任务）来摊薄固定开销。

4.2 用户态与内核态交互：ioctl、mmap与事件机制

4.2.1 核心原理：三种交互通道

寒武纪驱动为用户态提供了三种主要的交互通道，每种通道适用于不同场景：

ioctl（控制通道）：用于低频、控制类的操作，如设备打开/关闭、上下文创建、任务提交、参数查询。ioctl携带一个命令码和一个参数结构体指针，内核驱动通过copy_from_user/copy_to_user完成数据交换。
mmap（数据通道）：用于高频、大块数据的零拷贝访问。用户态通过mmap将设备内存（显存）或内核态分配的DMA缓冲区映射到用户地址空间，直接读写，避免每次访问都经过系统调用。
poll/eventfd（事件通道）：用于异步通知。用户态线程阻塞在poll上等待任务完成事件，内核中断处理函数在任务完成时唤醒等待队列。eventfd则提供更轻量级的跨进程事件通知。

4.2.2 操作流程：一次完整的任务提交与等待

// 用户态代码示意（伪代码）
int fd = open("/dev/cambricon_npu0", O_RDWR);
// 1. 创建上下文
cn_ctx_t ctx;
ioctl(fd, CN_IOCTL_CREATE_CTX, &ctx);
// 2. 分配显存（通过mmap映射）
void *dev_mem = mmap(NULL, size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, offset);
// 3. 准备任务描述符
cn_task_t task = { .type = GEMM, .input_addr = dev_mem, .output_addr = dev_mem+0x1000 };
// 4. 提交任务（ioctl）
ioctl(fd, CN_IOCTL_SUBMIT_TASK, &task);
// 5. 等待完成（poll）
struct pollfd pfd = { .fd = fd, .events = POLLIN };
poll(&pfd, 1, -1);
// 6. 读取结果
// ... 从dev_mem中读取输出数据

这段代码展示了标准的使用流程。值得注意的是，CN_IOCTL_SUBMIT_TASK在内核态的实现中，会执行以下关键步骤：

调用access_ok验证用户态指针合法性。
通过copy_from_user将任务描述符拷贝到内核缓冲区。
检查任务描述符中的显存地址是否属于当前上下文（防止越权访问）。
将任务描述符翻译为硬件命令字，写入与该上下文绑定的命令缓冲区（Ring Buffer）。
写Doorbell寄存器通知固件。

4.2.3 常见误区与风险

风险提示：一个常见的错误是在用户态直接使用write()系统调用向设备节点写入任务数据。寒武纪设备节点默认不实现write操作，因为任务提交需要携带复杂的结构化参数，且需要内核进行安全校验。如果强行使用write，会返回-EINVAL。正确的做法是使用ioctl。另外，mmap映射的显存区域在任务执行期间不能被munmap，否则可能导致内核访问非法地址，引发系统崩溃。

4.3 驱动与固件协作：命令队列与中断机制

4.3.1 核心原理：生产者-消费者模型

内核驱动与固件之间采用经典的生产者-消费者模型进行协作。内核驱动是生产者，将翻译好的硬件命令写入命令队列；固件是消费者，从队列中取出命令并调度执行。这个模型的核心数据结构是Ring Buffer（环形缓冲区）和Doorbell（门铃寄存器）。

Ring Buffer：位于设备内存或主机内存的一段连续区域，由内核驱动分配并映射到固件可见的地址空间。缓冲区头部有写指针（由驱动维护）和读指针（由固件维护）。
Doorbell：一个特殊的MMIO寄存器。驱动写完命令后，向Doorbell写入一个递增的序列号，固件轮询或中断感知到Doorbell变化后，开始从Ring Buffer中取命令执行。
中断机制：任务完成时，固件向主机发送MSI-X中断。内核中断处理函数识别中断来源（哪个队列、哪个上下文），然后调用对应的完成回调函数，唤醒等待的用户态进程。

4.3.2 协作流程：命令下发与完成通知

步骤	执行者	操作内容	同步方式
1	内核驱动	获取Ring Buffer写锁，写入N条命令	自旋锁
2	内核驱动	更新写指针，执行wmb()内存屏障	内存屏障
3	内核驱动	写Doorbell寄存器，值+1	MMIO写
4	固件	轮询Doorbell变化，读取读指针到写指针之间的命令	轮询/中断
5	固件	解析命令，调度计算核执行	硬件调度
6	固件	执行完成后，更新读指针，写完成队列	内存写
7	固件	触发MSI-X中断	中断
8	内核驱动	中断处理函数读取完成队列，唤醒等待进程	tasklet/softirq

这个流程中，最关键的性能瓶颈在于步骤3和步骤7的MMIO写和中断延迟。MMIO写通常需要几百纳秒，而中断处理从触发到唤醒用户态进程可能需要5-10微秒。对于需要微秒级延迟的推理场景，寒武纪提供了轮询模式（Busy Polling），即用户态通过忙等读取完成标志，绕过中断路径，将延迟降低到2微秒以内。

4.3.3 实战场景：中断风暴的排查与解决

在某次压力测试中，我们遇到一个异常现象：当NPU利用率达到80%以上时，系统整体吞吐量反而下降，且CPU占用率飙升。通过cat /proc/interrupts发现，MSI-X中断数量达到每秒30万次，远超正常水平。

分析过程：

初步怀疑是固件频繁触发中断。通过固件日志确认，每个小任务（如单次卷积）完成后都触发了一次中断。
进一步分析发现，用户态框架将一个大模型拆分为上千个小算子任务，每个任务都独立提交并等待完成，导致中断频率极高。
查看驱动代码，发现中断处理函数中包含了较重的操作：获取全局锁、遍历所有上下文、更新统计信息。

解决方案：

在用户态启用任务合并（Task Batching），将多个小算子合并为一个大的任务图提交，减少任务数量。
在内核驱动中启用中断聚合（Interrupt Coalescing），设置一个时间窗口（如50微秒），窗口内的多个完成事件合并为一次中断触发。
将中断处理函数中的统计信息更新改为原子操作，避免全局锁竞争。

结果对比：优化后，中断频率从30万次/秒降至2万次/秒，CPU占用率下降15%，整体吞吐量提升22%。这个案例说明，驱动与固件的协作机制需要根据实际负载特征进行调优，不能一味追求低延迟而忽略中断开销。

4.4 主要模块划分：从设备管理到内存管理

4.4.1 核心原理：六大核心模块

寒武纪内核驱动（cambricon_npu.ko）内部可划分为六个核心模块，每个模块职责单一，模块间通过定义良好的接口通信：

模块名称	核心职责	关键数据结构	对外接口
设备管理模块	PCIe设备探测/移除、设备节点创建、电源管理	cambricon_device, pci_driver	probe/remove/suspend/resume
上下文管理模块	创建/销毁上下文、维护上下文与队列的映射关系	cambricon_ctx, idr	cn_ioctl_create_ctx/destroy_ctx
命令队列模块	Ring Buffer分配、命令写入、Doorbell触发	cmd_queue, ring_buffer	cn_queue_submit/cn_queue_flush
中断处理模块	MSI-X中断注册、中断分发、完成回调	msix_entry, irq_handler	request_irq/free_irq
内存管理模块	显存分配/释放、IOMMU映射、DMA缓冲区管理	cambricon_mem, sg_table	cn_mem_alloc/cn_mem_free
虚拟化模块	VFIO直通支持、设备分片（MDEV）	vfio_device, mdev_parent	vfio_ops/mdev_ops

4.4.2 模块间协作：以内存分配为例

当用户态调用cnMalloc分配显存时，各模块的协作流程如下：

用户态CNRT发起ioctl(CN_IOCTL_ALLOC_MEM)，传入大小和对齐要求。
上下文管理模块验证当前上下文是否有效，获取上下文锁。
内存管理模块调用dma_alloc_coherent或sg_alloc_table分配物理连续内存（或通过IOMMU映射分散页）。
内存管理模块将分配到的物理地址转换为设备可见的IOVA地址，并记录在上下文的显存映射表中。
通过copy_to_user将设备地址返回给用户态。

这个流程中，如果启用了SMMU/IOMMU，步骤3会变为：分配不连续物理页，然后建立IOVA到物理页的映射表。这增加了灵活性，但每次DMA传输时硬件需要多一次地址转换，带来约5%的性能损耗。因此，寒武纪驱动默认对大于2MB的大块显存使用连续物理内存分配，对小块显存使用IOMMU映射。

4.4.3 常见误区与设计复盘

  设计复盘：在早期版本的驱动中，上下文管理模块和命令队列模块耦合较紧——每个上下文直接持有一个命令队列的指针，导致无法实现多队列并发。后来重构为“上下文-队列”分离设计：一个上下文可以绑定多个命令队列，一个命令队列也可以被多个上下文共享（通过引用计数）。这个改动使得多进程共享NPU的场景下，不同进程的任务可以并行提交到不同队列，显著提升了多租户场景的吞吐量。复盘经验：模块划分时，应尽量保持数据结构的松耦合，避免为了短期便利而牺牲长期扩展性。

风险提示：在编写内核驱动时，严禁在中断上下文（hardirq）中调用可能睡眠的函数，如kmalloc(GFP_KERNEL)、mutex_lock。寒武纪驱动的中断处理函数只做两件事：读取完成队列、唤醒等待队列。所有需要睡眠的操作（如释放内存、更新统计）都推迟到workqueue或tasklet中执行。违反这一原则会导致内核死锁或系统崩溃。

4.5 本章总结与核心要点

寒武纪NPU驱动体系架构的核心可以概括为“三层协同、两通道交互、一队列协作”：

三层协同：用户态负责业务逻辑，内核态负责资源管理，固件负责硬件执行。每一层都有明确的职责边界，通过标准接口通信。
两通道交互：ioctl用于控制面（低频、小数据量），mmap用于数据面（高频、大数据量）。事件通道（poll/eventfd）用于异步通知。
一队列协作：内核驱动与固件通过Ring Buffer + Doorbell机制实现高效的生产者-消费者协作，中断机制负责完成通知。

对于驱动开发者而言，理解这套架构的意义在于：当遇到性能瓶颈时，能够快速定位问题出在用户态调度、内核态翻译、还是固件执行环节；当需要新增功能时，能够准确判断应该修改哪一层；当系统出现异常时，能够通过各层的日志和计数器快速缩小排查范围。下一阶段的学习中，我们将深入每个模块的具体实现细节，从代码层面理解这些设计思想如何落地。