【NPU】Ascend Device Plugin 系统级架构分析

Ascend Device Plugin 系统级架构分析

源码路径: mind-cluster-v26.0.1/component/ascend-device-plugin 分析日期: 2026-07-31 文件统计: 52个非测试Go源文件，约20,000行代码 制图工具: fireworks-tech-graph (Style 1: Flat Icon)

目录

一、项目整体架构与设计思路

1.1 项目定位

Ascend Device Plugin 是华为昇腾NPU的 Kubernetes Device Plugin 实现，遵循 Kubernetes Device Plugin 协议（gRPC），负责将物理NPU设备（Ascend910/310/310P）注册到K8s集群，管理设备的发现、分配、健康监控和故障处理。

1.2 设计思路

采用 分层架构 + 工厂模式 + 接口抽象 + CGO桥接 的设计：

1.3 架构分层

二、整体运行流程

2.1 进程启动流程

1. main() 入口
↓
2. initLogModule() — 初始化日志模块
↓
3. 解析命令行 Flag (–useV2 –dmVol –fdFlag –deviceType …)
↓
4. checkParam() — 参数校验 (12项check函数)
├── checkListWatchPeriod() (ListAndWatch周期)
├── checkPresetAndVolcanoRelation() (预置+Volcano关系)
├── checkUse310PMixedInsertWithVolcano()
├── checkUse310PMixedInsertWithShareDevCount()
├── checkPresetWithShareDevCount()
├── checkSoftShareDevConfigDir()
├── checkHotResetMode()
├── checkBuildScene()
├── checkLinkdownTimeout()
├── checkThirdPartyScanDelay()
├── checkDeviceResetTimeout()
└── checkShareDevCount()
↓
5. devicefactory.InitFunction()
├── initDevManager()
│ ├── AutoInit() (DCMI驱动初始化, CGO)
│ ├── NewHwAscend910Manager() / NewHwAscend310Manager() / NewHwAscend310PManager()
│ └── InitSwitchDev() (交换设备初始化)
↓
6. NewHwDevManager() 创建设备管理器
├── setAscendManager() (按设备类型设置Manager)
├── setAllDeviceAndType()
├── initPluginServer()
↓
7. ListenDevice() — 启动主循环
├── Serve() (gRPC服务协程)
├── subscribeNpuFaultEvent() (故障订阅协程)
├── pollFaultCodeCM() (故障码轮询协程)
└── ticker 定时任务 (设备信息更新)
↓
8. 阻塞等待信号 (SIGTERM/SIGINT)

2.2 运行时核心协程

进程启动后进入 ListenDevice() 主循环，同时运行多个协程：

三、子模块划分总览

3.1 模块总览

四、入口层模块 — main.go

4.1 核心作用

进程入口点，负责命令行参数解析、参数校验和初始化调度。不包含业务逻辑，只做 编排调度。

4.2 关键函数

4.3 关键Flag

五、工厂层模块 — DeviceFactory

5.1 核心作用

设备工厂层，负责根据设备类型创建对应的 Manager 实例，初始化硬件驱动，建立设备名称映射。

5.2 文件结构

5.3 关键函数

5.4 名称映射机制

ResourceType (原始: Ascend910)
↓ InitPublicNameConfig()
OldPublicType (旧公共: Ascend910A)
↓ ReplaceDevicePublicName()
DevicePublicType (新公共: HuaweiNPU-910A)

支持自定义配置文件覆盖默认映射，用于K8s资源注册名和Pod注解。

六、gRPC服务层模块 — Server

6.1 核心作用

实现 Kubernetes Device Plugin gRPC 协议，向 kubelet 上报设备列表和健康状态，处理设备分配请求，查询Pod设备资源，监控DPU健康状态。

6.2 文件结构

6.3 关键结构体

6.4 关键函数

6.5 gRPC接口

七、设备管理层模块 — Device

7.1 核心作用

NPU设备的底层管理——设备发现、健康状态、故障处理、热复位、虚拟设备（vNPU）管理。通过CGO调用DCMI驱动库操作硬件。

7.2 文件结构

7.3 继承体系

DevManager (接口)
↑ 实现
AscendTools (基类) — 提供GetNPUs/UpdateNodeDeviceInfo等通用方法
↑ 继承
├── HwAscend910Manager (训练卡: 故障订阅/热复位/Ring重置/优雅容错)
├── HwAscend310Manager (推理卡: 简化版设备发现)
└── HwAscend310PManager (推理卡: 混插/虚拟/共享/物理4种模式)

7.4 关键函数

7.5 故障处理流程

DCMI驱动 → goFaultEventHandler (CGO回调)
↓
故障事件 → allFaultInfo channel
↓
限流器 (rate limiter)
↓
故障分级:
L1 (警告) → 记录日志，设备保持健康
L2 (降级) → 设备标记为不健康
L3 (隔离) → 设备隔离 + K8s Event通知
L5 (重置) → 触发热复位 (带内/带外)
↓
K8s Event 通知 + ConfigMap 更新 + ListAndWatch状态更新

八、公共基础层模块 — Common

8.1 核心作用

全局常量、工具函数、故障码定义、协议定义——被几乎所有其他模块引用的"单一真相源"。

8.2 文件结构

8.3 关键函数

九、K8s客户端模块 — KubeClient

9.1 核心作用

封装 Kubernetes API 交互——节点标签/注解管理、ConfigMap CRUD、Pod查询、节点Informer、容器运行时检测。

9.2 文件结构

9.3 关键函数

十、重复设备检测模块 — DuplicateDetector

10.1 核心作用

检测同一NPU设备被多个容器重复挂载的异常情况，支持Docker和Containerd两种容器运行时。

10.2 文件结构

10.3 关键函数

10.4 检测流程

1. CheckDuplicateDevices() 入口
↓
2. NewManager() → NewContainerCache() → NewClient()
↓
3. Start()
├── scanAllContainers() (全量扫描)
│ ├── 解析所有容器设备挂载信息
│ ├── StoreAllAndFindDuplicates() (批量存储+检测)
│ └── logDuplicate() (告警)
└── watchContainerEvents() (增量监听)
├── HandleNewContainer() (容器创建 → 解析+检测)
└── HandleContainerRemoval() (容器销毁 → 清理缓存)

十一、拓扑模块 — Topology

11.1 核心作用

管理拓扑文件的读写、Rack拓扑信息采集，支持文件哈希校验确保数据完整性。

11.2 文件结构

11.3 关键函数

十二、模块间调用关系与数据流

12.1 主调用链

main.go
→ DeviceFactory.InitFunction()
→ DeviceFactory.initDevManager()
→ DCMI AutoInit() (CGO驱动初始化)
→ NewHwAscend910/310/310PManager()
→ InitSwitchDev()
→ NewHwDevManager()
→ setAscendManager() (按类型设置Manager)
→ setAllDeviceAndType()
→ initPluginServer()
→ ListenDevice()
├── Serve() → gRPC Server
│ ├── ListAndWatch() → Device.GetNPUs() → DCMI
│ └── Allocate() → Device设备挂载 → 容器
├── subscribeNpuFaultEvent() → DCMI故障回调
├── pollFaultCodeCM() → KubeClient.GetConfigMap()
└── ticker → reportDeviceInfo()
→ Device.UpdateNodeDeviceInfo()
→ KubeClient.UpdateConfigMap()

12.2 数据传递矩阵

12.3 核心数据流

┌──────────┐ gRPC ┌──────────────┐
│ kubelet │ ─────────────→ │ PluginServer │
│ │ ←───────────── │ │
└──────────┘ ListAndWatch └──────┬───────┘
│
GetNPUs()│
↓
┌──────────────┐
│ Device层 │
│ (910/310/ │
│ 310P) │
└──────┬───────┘
│
CGO │
↓
┌──────────────┐
│ DCMI 驱动库 │
│ (libdcmi.so) │
└──────────────┘

┌──────────┐ ConfigMap ┌──────────────┐
│ K8s API │ ←─────────── │ KubeClient │
│ Server │ ───────────→ │ │
└──────────┘ Get/Patch └──────┬───────┘
│
↑
┌──────────────┐
│ PluginServer │ → ticker定时更新
└──────────────┘

十三、图表索引