精简客户机配置文件

[bullhh]

设备树节点直通客户机设计

一、直通核心原则

设备树节点直通无需传递完整设备树，仅需精准识别并处理目标设备的核心节点与依赖资源，确保客户机可正常驱动设备。若遗漏关键依赖（如中断、时钟），会导致设备初始化失败或功能异常。

术语解释：

术语	解释
设备树 (Device Tree)	一种描述硬件组件及其连接关系的数据结构，用于将硬件信息传递给操作系统。
节点 (Node)	设备树中的基本单元，代表一个硬件设备或组件。
属性 (Property)	节点内的键值对，用于描述设备的特性和配置（如地址、中断号）。
直通 (Passthrough)	一种虚拟化技术，允许虚拟机直接访问和控制物理硬件设备。
Phandle	设备树中用于唯一标识和引用节点的32位整数值，类似于指针。
DTS/DTSI	设备树源文件（.dts）和包含文件（.dtsi），后者类似于头文件，用于共享通用配置。
DTB	由DTS编译生成的二进制设备树文件（.dtb），由Bootloader加载并传递给内核。

二、直通策略核心要点

处理对象	具体要求	说明
核心设备节点	必须直通	如目标 UART 节点/soc/uart@2800c000，需完整映射其reg（寄存器内存区域）属性
中断控制器	直通或虚拟化	设备中断需通过控制器分发，可选择直通物理控制器或由 Hypervisor 提供虚拟中断控制器
时钟源	直通或模拟	若设备依赖特定时钟（如 UART 的uartclk/apb_pclk），需直通时钟节点或由 Hypervisor 模拟时钟信号
内存区域	强制映射	设备reg属性定义的寄存器地址空间，必须完整映射到客户机地址空间
父总线节点	按需处理	如soc总线节点，仅当包含共享资源（如总线仲裁器）时需处理，否则无需直通

三、设备树节点依赖关系识别基础：phandle

1. phandle的声明方式

（1）显式声明：

在节点中使用 phandle属性直接指定一个唯一整数：

node {
	...
    phandle = <0x100>; // 显式设置 phandle 值为 0x100
};

（2）隐式声明：

使用 label（标签）为节点命名，编译器会自动生成 phandle。其他节点可以通过 &label来引用该节点，编译器会将 &label替换为对应的 phandle。

clock: clock-controller@fdd20000 { // 定义标签 clock
    compatible = "rockchip,rk3568-cru";
    reg = <0x0 0xfdd20000 0x0 0x1000>;
};

i2c@fe5b0000 {
    clocks = <&clock 0x14a>; // 通过 &clock 引用时钟节点
};

• clock是节点的标签。
• &clock会被编译器替换为 clock节点对应的 phandle值。

2. phandle 引用规则

• 源码级（dts 文件）：使用&label引用，如clocks = <&clock 0x14a>，&clock指向标签为clock的时钟节点

• 编译后（dtb 文件）：&label自动转换为phandle数值，如clocks = <0x0c 0x14a>，0x0c即clock节点的phandle值

• 逆向解析（dtb 反编译）：需通过phandle数值匹配对应的节点声明，还原节点引用关系

四、设备树相关节点查找流程

以目标节点/soc/uart@2800c000为例，完整查找流程如下：

1. 识别目标节点

/ {
	compatible = "phytium,pe2204";
	interrupt-parent = <0x01>;
	#address-cells = <0x02>;
	#size-cells = <0x02>;
	model = "Phytium Pi Board";
	
    soc {
        compatible = "simple-bus";
        #address-cells = <0x02>;
        #size-cells = <0x02>;
        dma-coherent;
        ranges;

        uart@2800c000 {
            compatible = "arm,pl011\0arm,primecell";
            reg = <0x00 0x2800c000 0x00 0x1000>;
            interrupts = <0x00 0x53 0x04>;
            clocks = <0x0c 0x0c>;
            clock-names = "uartclk\0apb_pclk";
            status = "okay";
        };
        ...
    }；
    ...
}；

2. 解析依赖属性（phandle 引用）

（1）查找中断控制器：

• interrupt-parent = <0x01>指向 phandle = 0x01。
• 搜索设备树中 phandle = <0x01>的节点：

interrupt-controller@30800000 {
    compatible = "arm,gic-v3";
    phandle = <0x01>;  // 匹配 phandle 0x01
    ...
};

• 结论：需处理中断控制器节点interrupt-controller@30800000（直通或虚拟化）。

（2）查找时钟源：

• clocks = <0x0c 0x0c>指向 phandle = <0x0c>（两个时钟源相同）。
• 搜索 phandle = <0x0c>的节点：

clk100mhz {
    compatible = "fixed-clock";
    phandle = <0x0c>;  // 匹配 phandle 0x0c
    clock-frequency = <0x5f5e100>; // 100 MHz
};

• 结论：需处理时钟节点clk100mhz（直通或模拟）。

（3）其他依赖

• 若目标节点包含dmas（DMA 依赖）、power-domains（电源域依赖）、resets（复位依赖）等属性，需按上述流程逐一解析，本例中 UART 节点无此类依赖。

3. 递归检查进一步依赖

直接依赖节点可能存在自身依赖，需递归追踪至 “无依赖的根节点”，避免遗漏层级依赖。

• 中断控制器依赖检查：interrupt-controller@30800000无interrupt-parent、clocks等属性，无额外依赖；

• 时钟源依赖检查：clk100mhz为fixed-clock（固定时钟），无父时钟节点，无额外依赖；

• 若存在复杂依赖（如时钟节点依赖 PLL 时钟），需继续追踪父时钟节点，直至根时钟源（如晶振节点）。

五、节点示例及说明

1. 直接依赖属性（必查）

这些属性直接引用其他节点：

(1) 时钟依赖

clocks = <&cru 0x14a>, <&cru 0x149>;
clocks = <0x23 0x14a>;   

• 查找所有被引用的时钟节点（通过 &cru标签或 phandle值）
• 检查时钟节点的依赖链（如父时钟、PLL 等）

项目	说明
&cru	时钟控制器的标签引用（源码级）
0x23	时钟控制器的 phandle 值（编译后）
0x14a	时钟控制器内部的时钟线 ID（具体含义查芯片手册）,查找父节点时不需要
直通要求	必须包含时钟控制器节点及其所有父时钟节点

(2) 中断依赖

interrupt-parent = <&gic>;  // 中断控制器
interrupts = <0x00 0x30 0x04>; // 中断号

• 查找中断控制器节点（如 interrupt-controller@fd400000）
• 检查中断扩展（interrupts-extended）

(3) Pin 控制依赖

i2c@fe5b0000 {
    pinctrl-names = "default", "sleep";  // 定义两个状态
    pinctrl-0 = <&i2c2m0_xfer>;         // 默认状态配置
    pinctrl-1 = <&i2c2_sleep>;          // 睡眠状态配置
};

• 查找所有被引用的 pinctrl 节点（如 i2c2m0_xfer）
• 检查 pinctrl 的父节点（如 pinctrl控制器）
• 通过pinctrl-names后面的参数数量可判断有多少个 pinctrl-<n>，通过pinctrl-<n>查找关联节点

(4) DMA 依赖

dmas = <&dmac 0x10>, <&dmac 0x11>; 

• 查找 DMA 控制器节点（如 dmac@fe530000）

(5) 电源管理依赖

power-domains = <&power RK3568_PD_BUS>;

• 查找电源域控制器节点（如 power-controller）

2. 间接依赖关系（关键扩展）

(1) 时钟链依赖

对每个时钟节点递归检查：

cru: clock-controller@fdd20000 {
    clocks = <&pmucru CLK_PMU_24M_OTP>; // 父时钟
    clock-names = "xin24m";
};

• 追踪时钟的父时钟节点（直到根时钟）
• 检查时钟提供者的依赖（如晶振节点）

(2) 中断级联

对中断控制器递归检查：

gic: interrupt-controller@fd400000 {
    interrupt-parent = <&gic>; // 自引用或级联
};

• 对于级联中断控制器，追踪到根中断控制器
• 检查 MSI 父节点（如 PCIe 场景）

3. 总线拓扑依赖（结构关系）

(1) 父总线节点

soc {
    bus@ff800000 {
        i2c@fe5b0000 { ... };
    };
};

• 确认直接父节点（如 bus@ff800000）
• 检查父总线的 compatible和状态

(2) 兄弟节点冲突

查找同总线上的节点：

bus@ff800000 {
    i2c@fe5b0000 { ... };
    spi@fe610000 { ... }; // 可能共享资源
};

• 检查地址范围是否有重叠
• 检查共享资源（如时钟、中断号）

4. 特殊依赖

(1) 复位控制器

resets = <&cru SRST_I2C2>, <&cru SRST_I2C2_APB>;
reset-names = "i2c", "apb";

• 查找复位控制器节点（常与时钟控制器相同）

(2) IOMMU 依赖

iommus = <&iommu 0>;

• 查找 IOMMU 控制器节点
• 检查 IOMMU 的电源域和时钟

(3) 物理层(PHY)依赖

phys = <&usb2phy 0>;
phy-names = "usb2-phy";

• 查找 PHY 控制器节点
• 检查 PHY 的时钟和复位

六、节点依赖完整性检查表

为确保无依赖遗漏，需按以下类别逐项检查，覆盖直接、间接、拓扑及特殊依赖场景。

检查类别	检查项	示例属性	处理要求
直接依赖	时钟引用	clocks = <&cru 0x14a>	追踪所有引用的时钟节点，及时钟节点的父时钟链
	中断控制器	interrupt-parent = <&gic>	定位中断控制器，若为级联控制器需追踪至根控制器
	Pin 控制配置	pinctrl-0 = <&i2c2m0_xfer>	查找 Pin 控制节点，及对应的 Pin 控制器节点
	DMA 控制器	dmas = <&dmac 0x10>	直通 DMA 控制器节点，确保 DMA 通道可分配
	电源域	power-domains = <&power PD_BUS>	处理电源域控制器，确保设备供电可管控
间接依赖	时钟父节点	clocks = <&pmucru CLK_PMU_24M>	从目标时钟节点递归追踪至根时钟（如 24M 晶振）
	中断级联	interrupt-parent = <&intc>	若中断控制器有父控制器，需一并处理
	寄存器父总线	ranges = <0x0 0xfe000000>	确认父总线状态为 “okay”，无需额外直通
总线拓扑	直接父节点状态	bus@ff800000 { status = "okay" }	确保父总线处于使能状态，不影响设备访问
	兄弟节点资源冲突	同总线节点的reg属性	检查地址是否重叠，避免资源抢占
特殊依赖	复位控制器	resets = <&cru SRST_I2C2>	处理复位控制器，支持设备复位功能
	IOMMU	iommus = <&vpu_iommu>	直通 IOMMU 节点，确保内存访问隔离
	PHY 控制器	phys = <&usb2phy 0>	处理 PHY 节点，支持 USB/PCIe 等高速接口
	保留内存	memory-region = <&reserved_mem>	映射保留内存区域，供设备专用

特殊说明：复杂设备（如 PCIe/USB3）

对 PCIe、USB3 等复杂设备，需额外处理独有的属性（如interrupt-map、msi-parent、ranges），此类依赖需结合芯片手册识别，由开发人员手动添加至直通配置，示例如下：

pcie@40000000 {
    compatible = "pci-host-ecam-generic";
    device_type = "pci";
    #address-cells = <0x03>;
    #size-cells = <0x02>;
    #interrupt-cells = <0x01>;
    reg = <0x00 0x40000000 0x00 0x10000000>;
    msi-parent = <0x0f>;                     //MSI中断父节点，需处理
    bus-range = <0x00 0xff>;
    interrupt-map-mask = <0x00 0x00 0x00 0x07>;
    interrupt-map = <0x00 0x00 0x00 0x01 0x01 0x00 0x00 0x00 0x04 ...>;  //中断映射表，需同步配置
    ranges = <0x1000000 0x00 0x00 0x00 0x50000000...>;  //地址范围，需确保客户机可访问
    iommu-map = <0x00 0x10 0x00 0x10000>;
    status = "okay";
};

• 对复杂设备检查项目较多，复杂的和独有的需由开发人员识别加入到配置文件的直通设备中，如interrupt-map等

七、axvisor配置文件的使用

1. 设计思路

（1）在 axvisor 实际应用场景中，设备数量庞大，如phytium e2000开发板中设备节点有100个以上。若将所有设备均直通至客户机并逐一在passthrough_devices中配置，不仅工程量巨大，还极易出现配置错误；而若仅选择性直通部分设备，又可能因遗漏相关依赖设备，导致客户机运行过程中发生故障。因此，需优先设计一套可精准查找直通设备依赖项的方案，解决设备直通的完整性与准确性问题。

（2）考虑到 axvisor 实际使用时，通常仅有少数设备无需直通。为提升配置效率，需设计一种更便捷、高效的操作方法，快速完成 “排除少数非直通设备、确认多数直通设备” 的配置流程，减少人工操作成本。

（3）主机设备树具备完整的硬件拓扑与配置信息，若能基于主机设备树进行针对性修改，再将其提供给客户机使用，可直接复用现有硬件信息框架，降低客户机设备配置的复杂度，该方案具备较高便利性，可予以保留并整合至整体设计中。

2. 配置文件：

[base]
id = 1
phys_cpu_ids = [0x00, 0x100, 0x200, 0x300]
...

[kernel]
entry_point = 0x4000_0000
kernel_load_addr = 0x4000_0000
dtb_load_addr = 0x4008_0000
dtb_path = "linux-qemu_gicv3.dtb"
...

[memory]
regions = [
    [0x4000_0000, 0x4000_0000, 0x7, 1] 
]

[devices]
passthrough_devices = [
    ["intc@8000000", 0x800_0000, 0x800_0000, 0x50_000, 0x1], #[name, base_gpa, base_hpa, length, irq_id]
    ["pl011@9000000", 0x900_0000, 0x900_0000, 0x1000, 0x1],
    ["pl031@9010000", 0x901_0000, 0x901_0000, 0x1000, 0x1],
]
emu_devices = [ ]

修改后配置文件：

[devices]
passthrough_devices = [
	["all"],           #[全部设备]        
    ["pl011@9000000"], #[name] 
    ["pl031@9010000"],
]
# 新增：明确排除、不直通给客户机的设备列表
excluded_devices = [
    "interrupt-controller@30800000",   # 中断器，由 Hypervisor 模拟
    "reserved-memory",    # 预留内存区域
]
emu_devices = [ ]

3. 设备树生成流程：

（1）初始判断：dtb_path是否为空

分支	触发条件	后续动作
是（dtb_path为空）	未指定客户机设备树路径，需动态生成	进入 “设备直通规则解析” 分支，根据passthrough_devices和excluded_devices筛选直通设备
否（dtb_path非空）	已指定客户机设备树路径，直接使用	直接基于指定设备树和配置文件补全参数

（2）设备直通规则解析（dtb_path为空时）

（a）根据passthrough_devices筛选设备

• 当passthrough_devices = [["all"], ]：表示除excluded_devices外，主机所有设备均直通给客户机；
• 当passthrough_devices为具体设备列表：仅筛选列表内设备及关联依赖设备（如 UART 设备需关联中断控制器）。

（b）排除excluded_devices中设备

excluded_devices定义 “不希望直通给客户机的设备”，例如：需关联中断控制器才能直通 UART，但又不想将该中断控制器本身直通时，可将中断控制器加入excluded_devices。

（c）记录最终直通设备

汇总筛选后需直通的设备，用于补全配置文件参数和后续生成客户机设备树。

（3）客户机设备树生成与补全

（a）dtb_path为空时

• 读取主机设备树文件，补全客户机配置文件中passthrough_devices对应的设备参数（如寄存器地址、中断号等）；
• 生成客户机设备树文件。

（b）dtb_path非空时

直接使用指定的客户机设备树文件，但仍需根据客户机配置文件补全passthrough_devices相关参数（保证配置与设备树的一致性）。

（4）关键节点补全

无论设备树是动态生成还是指定的，都需根据客户机配置中的cpu和memory regions参数，补全设备树中对应的cpu节点（如核心数）和内存区域节点memory。

（5）进入原流程

完成设备树生成与补全后，继续执行虚拟化系统的原有启动 / 配置流程（如客户机启动、设备初始化）。

4. 核心配置项说明

配置项	取值与作用	示例
dtb_path	- 为空：动态生成客户机设备树 - 非空：使用指定的客户机设备树	空：dtb_path = "" 指定：dtb_path = "/path/to/guest.dtb"
excluded_devices	声明不直通给客户机的设备（支持设备路径或节点名）	excluded_devices = ["interrupt-controller@30800000", "clk_unwanted"]
passthrough_devices	- [["all"], ]：直通除excluded_devices外的所有主机设备 - 具体列表：仅直通列表内设备及关联依赖	全直通：passthrough_devices = [["all"], ] 指定设备：passthrough_devices = ["uart@2800c000", "eth@30000000"]

5. 优先级规则

客户机配置文件中关于cpu、memory的参数优先级最高，会覆盖设备树中的默认值；其次是配置文件中客户机设备树文件；最后是配置文件中[devices]参数。

6. 生成设备树流程图

[bullhh]

AxVisor FDT模块功能说明

1. 核心功能与价值

1.1 解决的核心问题

在虚拟化环境中，客户机操作系统需要通过设备树（Device Tree）来识别和配置硬件资源。然而，在许多场景下，不易获取客户机设备树文件，或者预置的设备树与实际配置文件中分配的硬件资源不匹配，从而导致出现错误。FDT模块解决了这一问题，它能够：

• 自动生成客户机设备树：当客户机未提供设备树时，根据主机设备树和虚拟机配置文件自动生成适配的设备树
• 资源精准映射：确保客户机设备树准确反映分配的CPU、内存和直通设备资源
• 地址自动填充：根据设备树自动识别直通设备地址，不需要人工写入配置文件中

1.2 实现的价值

• 简化配置管理：用户只需在配置文件中指定资源需求，无需手动编写复杂的设备树
• 提高兼容性：生成的设备树与客户机配置文件完全兼容

1.3 功能概述

FDT模块主要有以下功能：

1. 解析主机设备树获取系统硬件信息，如各节点地址
2. 读取虚拟机TOML配置文件获取资源分配信息，如memory和CPU
3. 根据配置信息生成客户机CPU节点和memory节点
4. 识别配置文件中的直通设备并分析其关联设备
5. 构建完整的客户机设备树并输出DTB格式数据

2. 配置文件格式说明

2.1 CPU配置

在TOML配置文件中，CPU资源配置位于[base]节：

[base]
# 虚拟机使用的CPU核心数
cpu_num = 2
# 分配的物理CPU核心ID列表
phys_cpu_ids = [0x200, 0x00]
# CPU集合掩码（已废弃，由phys_cpu_ids自动生成）
# phys_cpu_sets = [1, 4]

配置说明：

• cpu_num：指定虚拟机使用的CPU核心数量
• phys_cpu_ids：指定分配给虚拟机的物理CPU核心ID列表
• phys_cpu_sets：CPU核心的位掩码表示（已废弃，由系统根据phys_cpu_ids自动生成）

注意：在早期版本中，需要手动配置phys_cpu_sets参数。但经过优化后，系统现在能够通过set_phys_cpu_sets函数自动根据phys_cpu_ids生成对应的CPU集合掩码，因此不再需要手动配置该参数。

2.2 内存配置

内存资源配置位于[kernel]节：

[kernel]
# 内存区域配置，格式为[基地址, 大小, 权限标志, 映射类型]
memory_regions = [
    [0x20_4000_0000, 0x4000_0000, 0x7, 1], # 系统RAM，映射类型1表示MAP_IDENTICAL
]

配置说明：

• memory_regions：内存区域配置列表
• 每个内存区域格式：[基地址, 大小, 权限标志, 映射类型]
• 映射类型：0表示MAP_ALLOC（分配映射），1表示MAP_IDENTICAL（恒等映射）
• 权限标志：位掩码表示内存访问权限

2.3 直通设备配置

直通设备配置位于[devices]节：

[devices]
# Pass-through devices.
# Name Base-Ipa Base-Pa Length Alloc-Irq.
passthrough_devices = [
	# ["uart@feb40000", 0xfeb4_0000, 0xfeb4_0000, 0x1000, 0x1],
	# ["/syscon@fdc20000", 0, 0, 0, 0],
    ["/syscon@fdc20000"],
    ["/pinctrl/gpio3@fe760000"], #从根节点开始的完整路径
    ["/"],        #根节点，表示所有设备都直通
]

配置说明：

• passthrough_devices：直通设备配置列表
• 设备配置有两种格式：
  1. 简单格式：[设备路径] - 仅指定设备在主机设备树中的路径
  2. 完整格式：[设备路径, 客户机地址, 主机地址, 长度, 中断号] - 明确指定设备的地址映射信息
• 设备路径：设备在主机设备树中的完整路径
• 客户机地址：设备在客户机地址空间中的映射地址（可选）
• 主机地址：设备在主机物理地址空间中的实际地址（可选）
• 长度：设备占用的地址空间大小（可选）
• 中断号：设备使用的中断号（可选）

3. 设备直通机制

3.1 直通设备配置格式

配置文件中的直通设备采用以下格式：

[设备路径]

或

[设备路径, 客户机地址, 主机地址, 长度, 中断号]

配置项说明：

• 设备路径：设备在主机设备树中的完整路径，用于在设备树中定位设备节点
• 客户机地址：设备在客户机地址空间中的映射地址（可选）
• 主机地址：设备在主机物理地址空间中的实际地址（可选）
• 长度：设备占用的地址空间大小（可选）
• 中断号：设备使用的中断号（可选）

3.2 设备关联关系发现

为确保直通设备正常工作，自动发现以下关联设备：

1. 后代设备发现：识别直通设备下的所有子节点，确保设备功能完整性
2. 依赖设备分析：分析设备的时钟、电源、复位等依赖关系
3. 递归处理：递归发现依赖设备的依赖关系，构建完整的设备依赖图
4. phandle解析：利用设备树的phandle机制解析设备间的引用关系
5. cells处理：根据#*-cells属性解析phandle引用的附加参数

4. 使用示例

4.1 配置文件示例

[base]
# Guest vm id.
id = 1
# Guest vm name.
name = "linux"
# Virtualization type.
vm_type = 1
# The number of virtual CPUs.
cpu_num = 2
# The physical CPU ids.
phys_cpu_ids = [0x200, 0x00]
# Guest vm physical cpu sets. (已废弃，由系统自动生成)
# phys_cpu_sets = [1, 4]

[kernel]
# The entry point of the kernel image.
entry_point = 0x20_4008_0000
# The location of image: "memory" | "fs".
# Load from file system.
image_location = "memory"
# The load address of the kernel image.
kernel_load_addr = 0x20_4008_0000
## The file path of the kernel image.
kernel_path = "/path/phytium-Image"
## The file path of the device tree blob (DTB).
dtb_load_addr = 0x20_4000_0000
#dtb_path = "/path/axvisor/tmp/linux-aarch64-e2000_smp2.dtb"
# Memory regions with format (`base_paddr`, `size`, `flags`, `map_type`).
# For `map_type`, 0 means `MAP_ALLOC`, 1 means `MAP_IDENTICAL`.
memory_regions = [
  [0x20_4000_0000, 0x4000_0000, 0x7, 1], # System RAM MAP_IDENTICAL
]

[devices]
# Emu_devices.
# Name Base-Ipa Ipa_len Alloc-Irq Emu-Type EmuConfig.
interrupt_mode = "passthrough"
emu_devices = []

# Pass-through devices.
# Name Base-Ipa Base-Pa Length Alloc-Irq.
passthrough_devices = [
    ["/syscon@fdc20000"],
    ["/pinctrl/gpio3@fe760000"],
    #["ethernet@fe010000/rx-queues-config"],
    #["rkvenc-opp-table"],
    ["/"],
]

# Devices that are not desired to be passed through to the guest
excluded_devices = [
    ["/interrupt-controller@30800000"],
]

4.2 生成的设备树结构

根据上述配置，生成的客户机设备树将包含：

• 2个CPU核心节点（对应phys_cpu_ids指定的核心0x200和0x00）

• 1个内存节点（对应配置的内存区域0x20_4000_0000，大小0x4000_0000）

• 指定路径的直通设备节点及其依赖设备

  cpus {
  #address-cells = <0x02>;
  #size-cells = <0x00>;

    cpu-map {
  
    	cluster0 {
  
    		core0 {
    			cpu = <0x05>;
    		};
    	};
  
    	cluster1 {
  
    		core0 {
    			cpu = <0x06>;
    		};
    	};
  
    	cluster2 {
  
    		core0 {
    			cpu = <0x07>;
    		};
  
    		core1 {
    			cpu = <0x08>;
    		};
    	};
    };
  
    cpu@0 {
    	device_type = "cpu";
    	compatible = "phytium,ftc310\0arm,armv8";
    	reg = <0x00 0x200>;
    	enable-method = "psci";
    	clocks = <0x09 0x02>;
    	capacity-dmips-mhz = <0xb22>;
    	phandle = <0x07>;
    };
  
    cpu@1 {
    	device_type = "cpu";
    	compatible = "phytium,ftc310\0arm,armv8";
    	reg = <0x00 0x201>;
    	enable-method = "psci";
    	clocks = <0x09 0x02>;
    	capacity-dmips-mhz = <0xb22>;
    	phandle = <0x08>;
    };
  
    cpu@100 {
    	device_type = "cpu";
    	compatible = "phytium,ftc664\0arm,armv8";
    	reg = <0x00 0x00>;
    	enable-method = "psci";
    	clocks = <0x09 0x00>;
    	capacity-dmips-mhz = <0x161c>;
    	phandle = <0x05>;
    };
  
    cpu@101 {
    	device_type = "cpu";
    	compatible = "phytium,ftc664\0arm,armv8";
    	reg = <0x00 0x100>;
    	enable-method = "psci";
    	clocks = <0x09 0x01>;
    	capacity-dmips-mhz = <0x161c>;
    	phandle = <0x06>;
    };
  

  };

5. 核心机制原理

5.1 phandle机制

设备树使用phandle（pointer handle）机制建立设备间的引用关系：

• 每个设备节点通过phandle属性获得唯一标识符
• 其他设备节点通过在属性中引用phandle值来建立依赖关系
• 常见的phandle引用属性包括clocks、power-domains、phys等

5.2 cells机制

设备树使用cells机制描述phandle引用的附加参数：

• 目标设备节点通过#*-cells属性声明需要的参数数量
• 常见的cells属性包括#clock-cells、#power-domain-cells、#interrupt-cells等
• 引用属性中phandle后跟随相应数量的specifier参数

5.3 递归依赖发现

为了确保设备功能完整性，采用递归方式发现设备依赖：

• 分析设备属性中的phandle引用
• 递归处理依赖设备的依赖关系
• 避免循环依赖导致的无限循环
• 构建完整的设备依赖关系图

[bullhh]

AxVisor 设备树配置使用说明

本文档详细说明了在 AxVisor 中如何配置和使用设备树（FDT）来生成客户机 VM 的设备树。

本文档所述功能只在aarch64 架构下支持。

1. 概述

AxVisor 支持两种方式生成客户机 VM 的设备树：

1. 使用预定义的设备树文件：通过 [kernel] 部分的 dtb_path 指定设备树文件路径
2. 动态生成设备树：当 dtb_path 字段未使用时，根据配置文件中的参数动态生成设备树

无论采用哪种方式，CPU 节点和内存节点都会根据配置进行更新。

2. 配置文件结构

配置文件采用 TOML 格式，主要包含以下几个部分：

[base]
# 基本配置信息

[kernel]
# 内核和设备树配置

[devices]
# 设备配置信息

3. 设备树处理机制

3.1 使用预定义设备树文件

当 [kernel] 部分的 dtb_path 配置了设备树文件路径时：

[kernel]
dtb_path = "/path/to/device-tree.dtb"

AxVisor 会优先使用提供的设备树文件，并根据以下配置更新其中的 CPU 节点和内存节点：

• CPU 节点根据 [base] 部分的 phys_cpu_ids 更新
• 内存节点根据 [kernel] 部分的 memory_regions 更新

注意：当使用预定义设备树文件时，[devices] 部分的 passthrough_devices 和 excluded_devices 配置将被忽略。

3.2 动态生成设备树

当 [kernel] 部分的 dtb_path 未添加时：

[kernel]
# dtb_path = ""

AxVisor 会根据配置文件中的参数动态生成客户机设备树：

1. CPU 节点：根据 [base] 部分的 phys_cpu_ids 生成
2. 内存节点：根据 [kernel] 部分的 memory_regions 生成
3. 其他设备节点：根据 [devices] 部分的 passthrough_devices 和 excluded_devices 生成

4. 配置参数详解

4.1 基本配置 [base]

[base]
id = 1                      # 客户机 VM ID
name = "linux-qemu"         # 客户机 VM 名称
vm_type = 1                 # 虚拟化类型
cpu_num = 1                 # 虚拟 CPU 数量
phys_cpu_ids = [0]          # 客户机 VM 物理 CPU 集合

注意：配置文件中的 phys_cpu_sets 字段已不再需要手动配置。AxVisor 会根据主机设备树和 phys_cpu_ids 自动识别并生成相应的 CPU 集合掩码。

4.2 内核配置 [kernel]

[kernel]
entry_point = 0x8020_0000           # 内核镜像入口点
image_location = "memory"           # 镜像位置 ("memory" | "fs")
kernel_path = "tmp/Image"           # 内核镜像文件路径
kernel_load_addr = 0x8020_0000      # 内核镜像加载地址
dtb_path = "tmp/linux.dtb"          # 设备树文件路径（空字符串表示动态生成）
dtb_load_addr = 0x8000_0000         # 设备树加载地址

# 内存区域配置，格式为 (基地址, 大小, 标志, 映射类型)
memory_regions = [
  [0x8000_0000, 0x1000_0000, 0x7, 0], # 系统 RAM 1G MAP_IDENTICAL
]

4.3 设备配置 [devices]

[devices]
# 直通设备配置（仅在动态生成设备树时生效）
passthrough_devices = [
  ["/intc"],
]

# 排除设备配置（仅在动态生成设备树时生效）
excluded_devices = [
  ["/intc"],
]

注意：直通设备配置已简化，现在只需要提供从根节点开始的完整路径即可，如 ["/intc"]。设备的地址、大小等信息会根据设备树自动识别并直通，无需手动填写。

5. 设备直通机制

5.1 直通设备配置

passthrough_devices 定义了需要直通给客户机的设备节点：

passthrough_devices = [
  ["/"],              # 直通根节点及其所有子节点
  ["/intc"],          # 直通 /intc 节点及其子节点
]

设备节点格式为从根节点开始的全局路径（如 /intc），在直通时会将以下节点包含在客户机设备树中：

1. 指定的直通节点本身
2. 直通节点的所有后代节点
3. 与直通设备相关的依赖节点

注意：

1. 此配置仅在动态生成设备树时生效，当使用预定义设备树文件时将被忽略。
2. 直通设备配置已简化，现在只需要提供从根节点开始的完整路径即可，设备的地址、大小等信息会根据设备树自动识别并直通。

5.2 排除设备配置

excluded_devices 定义了不希望直通给客户机的设备节点：

excluded_devices = [
  ["/timer"],         # 排除 /timer 节点及其子节点
]

在查找所有直通节点后，会将排除的节点及其后代节点从最终的客户机设备树中移除。

注意：此配置仅在动态生成设备树时生效，当使用预定义设备树文件时将被忽略。

6. 示例配置

6.1 使用预定义设备树文件的配置

[base]
id = 1
name = "linux-qemu"
vm_type = 1
cpu_num = 2
phys_cpu_ids = [0, 1]
# phys_cpu_sets 不再需要手动配置，会自动根据 phys_cpu_ids 生成

[kernel]
entry_point = 0x8020_0000
image_location = "memory"
kernel_path = "tmp/Image"
kernel_load_addr = 0x8020_0000
dtb_path = "/home/user/device-tree.dtb"  # 使用预定义设备树文件
dtb_load_addr = 0x8000_0000

memory_regions = [
  [0x8000_0000, 0x1000_0000, 0x7, 1], # System RAM 1G MAP_IDENTICAL
]

[devices]
# 注意：以下配置在使用预定义设备树时将被忽略
passthrough_devices = [
  ["/intc"],
]
excluded_devices = [
  ["/timer"],
]

6.2 动态生成设备树的配置

[base]
id = 1
name = "linux-qemu"
vm_type = 1
cpu_num = 2
phys_cpu_ids = [0, 1]
# phys_cpu_sets 不再需要手动配置，会自动根据 phys_cpu_ids 生成

[kernel]
entry_point = 0x8020_0000
image_location = "memory"
kernel_path = "tmp/Image"
kernel_load_addr = 0x8020_0000
# dtb_path = ""  # 不使用该字段表示动态生成设备树
dtb_load_addr = 0x8000_0000

memory_regions = [
  [0x8000_0000, 0x1000_0000, 0x7, 1], # System RAM 1G MAP_IDENTICAL
]

[devices]
# 以下配置仅在动态生成设备树时生效
# 注意：直通设备配置已简化，现在只需要提供从根节点开始的完整路径即可
passthrough_devices = [
  ["/"],
  ["/intc"],
]

excluded_devices = [
  ["/timer"],
  ["/watchdog"],
]

7. 处理流程

1. 检查 dtb_path：

   • 如果使用 dtb_path 字段，则加载并使用预定义的设备树文件，此时 passthrough_devices 和 excluded_devices 配置将被忽略
   • 如果未使用 dtb_path 字段，则动态生成设备树，此时 passthrough_devices 和 excluded_devices 配置生效

2. CPU 节点处理：

   • 根据 phys_cpu_ids 配置更新或生成 CPU 节点
   • 只包含配置中指定的 CPU
   • 自动根据 phys_cpu_ids 生成 phys_cpu_sets，无需手动配置

3. 内存节点处理：

   • 根据 memory_regions 配置更新或生成内存节点
   • 按照指定的地址和大小创建内存区域

4. 设备节点处理（仅在动态生成时）：

   • 根据 passthrough_devices 确定需要包含的设备节点
   • 包括直通节点、其后代节点以及相关依赖节点
   • 根据 excluded_devices 排除指定的设备节点及其后代节点

5. 生成最终设备树：

   • 将处理后的节点组合成完整的设备树
   • 存储在全局缓存中供后续使用

8. 特别配置

1. qemu 启动参数：

  arceos_args = ["BUS=mmio", "BLK=y", "LOG=info", "SMP=4", "MEM=8g",
                "QEMU_ARGS=\"-machine gic-version=3  -cpu cortex-a72 -append 'root=/dev/vda rw init=/init' \"",
                "DISK_IMG=\"tmp/qemu/rootfs.img\"",]

其中当不提供设备树时 -append 'root=/dev/vda rw init=/init'参数必须添加，目的是在主机设备树中添加chosen节点的bootargs属性。