Files
UniXNU/docs/zh/porting/device-tree.md
UniXNU Docs 1446f449b6 docs(porting): cover the macOS path
The porting flow covers the macos-27.3-26C5035r profile from profile
selection to the porting record: the macOS profile page lists the profile
contents, host inputs, board.toml override, Data seed, build commands,
driver adaptations and boot checkpoints, and the steps, arm64e, packaging,
records, bring-up, building, requirements and reference pages point to it.
The iPadOS instructions are unchanged.

Porting pages link porting pages for driver topics: Develop a driver and
Brightness interface are porting pages, and component names in porting
pages are plain text. English and Chinese pages.
2026-11-10 19:26:10 +08:00

11 KiB
Raw Permalink Blame History

设备树

格式 2 编译硬件设备树,并由共享工具生成 Apple 设备树。

flowchart TD
  A[SoC DTSI] --> C[dtc]
  B[板级 DTS] --> C
  C --> D[硬件 DTB]
  D --> E[共享 ADT 生成器]
  F[OS 配置] --> E
  G[Payload 输入] --> E
  E --> H[kernel.macho.adt]

固件和 bootloader 接口使用 FDT。XNU 接收与 kernel.macho 放在一起的 ADT sidecar, DarwinBoot 从启动项目录读取它。

操作步骤

  1. 准备板级 DTS、所选 SoC DTSI 和驱动读取的属性,按配置设置源文件与 include 路径。
  2. 按硬件绑定描述父节点 cell 宽度、地址范围、中断、引用和启用节点,核对 XNU 必需节点。
  3. 将 Apple 平台属性放在所选 OS profile,按需添加板级覆盖。根卷 UUID 和 payload 交接选项应匹配实际输入。
  4. 执行独立转换,编译 DTB 并用所选输入生成 ADT。核对编译诊断、生成的节点名称与驱动匹配要求。
  5. 使用保存的输入运行 ./unixnu payload 和 ./unixnu bootimg,检查解析输出目录中的 device-tree/hardware.dtb 和 payload 报告。固件 DTB单独作为启动镜像输入。

配置

[device_tree]
source = "device:dts/myboard.dts"
include_dirs = ["soc:dts"]

payload 步骤运行 dtc,在解析后的输出目录写入 device-tree/hardware.dtb。 scripts/unixnu/devicetree.py 读取 FDT、转换硬件属性、加入 OS 与 payload 属性,最后编码 ADT。

板级 DTS 包含 SoC DTSI:

/dts-v1/;
/include/ "sm8550.dtsi"

/ {
    model = "Example SM8550 device";
    compatible = "vendor,myboard", "qcom,sm8550";
};

完整板级源码提供内存、启用的 CPU 和外设输入。参见设备模板 和 SoC 支持。

硬件绑定

属性 输入 ADT 表示
compatible, device_type, reg-names, interrupt-names, clock-names, method NUL 结尾的字符串 字符串字节
phandle, linux,phandle, #interrupt-cells, #iommu-cells, clock-frequency, timebase-frequency, transport-encoding, transport-speed 一个大端 cell 小端 u32
redistributor-stride 一或两个 cell 小端 u64
interrupt-controller, dma-coherent 空属性 空属性
reg 按父节点 cell 宽度编码的地址和长度 转换后的物理 u64 地址与长度对
interrupts 按控制器 #interrupt-cells 编码的描述符 小端 cell
interrupt-parent 控制器 phandle 小端 phandle
iommus, clocks phandle 和提供者定义的参数 cell 小端 cell
unixnu,adt-name 导出的硬件节点名 /arm-io 下的子节点名
unixnu,cluster-type CPU 节点上的 "E" 或 "P" cluster-type,该字符的小端 u32
status okay、ok 或禁用状态 选择启用节点

参与地址转换的总线声明 ranges,空 ranges 表示恒等映射。每个寄存器范围必须恰好 匹配一条转换。引用目标的 phandle 必须非零且唯一,参数数量由提供者声明。 中断描述符必须匹配选中的中断控制器。

生成器导出带 unixnu,adt-name 的启用节点,导出名必须唯一。驱动需要其他属性时, 在共享转换器中添加明确的类型绑定。FDT 整数 cell 先解码,再编码到 ADT。

根节点提供 model 和 compatible。一个启用的 memory 节点提供连续 DRAM 范围。 /cpus 提供 timebase-frequency,各启用 CPU 的 reg 保存 MPIDR affinity, compatible 描述 CPU。第一个启用 CPU 是启动 CPU。多 CPU 需要 /psci, 其 method 为 smc 或 hvc。

OS 属性

OS 配置在 [adt] 下声明带类型的表,例如:

[adt.chosen.string]
osenvironment = "main"

[adt.defaults.u32]
sleep-disabled = 1

支持 string、strings、u32、u64 和十六进制 bytes。 这些表填充 root、chosen、defaults、options、product 和 buttons。 共享生成器创建 CHRP NVRAM、64 字节随机种子、平台身份、根卷匹配和 payload 内存映射占位属性。

独立转换

设置设备与 SoC 源码路径,将本机平台种子导出为 UNIXNU_UNIQUE_CHIP_ID,并选择 OS 配置:

DEVICE_DIR=/path/to/device
SOC_DTS=/path/to/soc/dts
dtc -I dts -O dtb -i "$SOC_DTS" -o /tmp/board.dtb "$DEVICE_DIR/dts/myboard.dts"
python3 scripts/make-adt.py --dtb /tmp/board.dtb \
  --os-profile profiles/os/ipados-17.7.11-21H461/profile.toml \
  --board "$DEVICE_DIR/board.toml" --unique-chip-id "$UNIXNU_UNIQUE_CHIP_ID" \
  --data-ramdisk --trust-cache --output /tmp/kernel.macho.adt

命令根据提供的 payload 输入选择内存映射占位属性。unixnu build payload 使用完整 解析的配置和实际输入。

Apple 设备树编码

Apple 设备树使用紧凑节点编码:

u32 property_count
u32 child_count
每个属性:
  char name[32]
  u32 length
  u8  value[length]
  填充到 4 字节
每个子节点:
  node

每个节点带有自己的 name 属性和结尾 NUL。

共享编码器写入小端 ADT 字段,并将属性填充到四字节边界。

必需节点

通用 ArmDTPlatform 要求以下顶层节点:

节点 必需内容
/chosen random-seed、CHRP NVRAM proxy、DRAM 描述、osenvironment
/cpus 每个核心一个 cpuN 子节点
/arm-io 带 #address-cells、#size-cells、ranges 的总线节点
/defaults 平台默认值
/options 平台选项

缺少任一节点时平台专家 configure() 失败。/chosen 没有可用 NVRAM proxy 时同样失败。

NVRAM proxy

XNU 从 /chosen 发布真实 IODTNVRAM。proxy 使用 CHRP bank 格式:

属性 内容
nvram-bank-size bank 大小,32 位
nvram-bank-count bank 数量,32 位
nvram-current-bank 当前 bank,32 位
nvram-proxy-data bank 镜像

bank 镜像包含 nvram 头、带两 KiB 数据区的 common 头和 free 头。common 数据区偏移 16 处有 Adler-32 校验。

没有持久 NVRAM 控制器的设备使用空 proxy 即可。

chosen 属性

属性 类型 用途
random-seed 64 字节 内核熵种子
unique-chip-id 64 位 与 chip-id 一起生成 IOPlatformUUID
chip-id 32 位 平台身份种子
osenvironment 字符串 main、recoveryos 或 ramdisk
dram-base 64 位 物理 DRAM 基址
dram-size 64 位 物理 DRAM 大小
crypto-hash-method 字符串 Image4 哈希方法,例如 sha2-384
root-matching 字典 根卷匹配字典
ephemeral-storage 32 位 标记可写 Data 卷为临时
darwinboot-memory-size 64 位 连续窗口请求,256 MiB 到 8 GiB,2 MiB 步进
amfi-only-platform-code 32 位 保持 AMFI 平台代码策略
boot-manifest-hash 字节 owner 路径的启动 manifest 哈希

unique-chip-id 和 chip-id 生成 IOPlatformUUID。缺少它们时,以零超时调用 gethostuuid() 的进程会一直等待。

memory-map

/chosen/memory-map 保存 DarwinBoot 填充的占位符:

属性 长度 填充内容
RAMDisk 16 字节 dense Data 镜像地址和大小
PackedRAMDisk 16 字节 packed Data 镜像地址和大小
TrustCache 16 字节 trust cache 地址和大小

每个输入都需要占位符。缺少占位符时 DarwinBoot 返回 EFI_COMPROMISED_DATA。

CPU

cpu0 {
  name = "cpu0";
  state = "running";
  reg = <0>;
  device_type = "cpu";
  compatible = "arm,cortex-a715";
  timebase-frequency = <19200000>;
}

第一个 CPU 是启动 CPU,reg 是 MPIDR affinity 值。多于一个 CPU 时加入 /psci 节点,compatible = "arm,psci-1.0",method 为 "smc" 或 "hvc"。

arm-io

arm-io {
  name = "arm-io";
  device_type = "arm-io";
  #address-cells = <2>;
  #size-cells = <2>;
  ranges = <0 0 0x100000000>;
  intc {
    name = "intc";
    compatible = "arm,gic-v3";
    reg = <...>;
  };
}

ranges 映射总线窗口。共享生成器先将源寄存器转换为物理地址,再生成单一窗口的 arm-io:从最低的导出寄存器(向下对齐到 16 MiB)到最高的导出寄存器。子节点 reg 是相对窗口基址的偏移。XNU 把该基址读作 SoC 基址且要求非零,因此低于 16 MiB 的导出寄存器会报错。

product 与 buttons

/product 提供产品名和型号,/buttons 提供按钮名称和 home-button-type。MobileGestalt 和平台代码读取这些节点。完整属性、手势设置和设备系列切换见 MobileGestalt 身份。

平台默认值

/defaults 提供平台选项。例如 sleep-disabled = <1> 在未实现 suspend 时阻止 CPU 停驻。

格式 1 ADT 工具

格式 1 使用 [payload.adt] tool 选择设备脚本,参数见 Payload。 脚本提供必需节点、CHRP NVRAM、随机种子、身份、根卷匹配和内存映射占位属性。

UEFI 设备树

固件通过 EFI_DTB_TABLE 暴露自己的 FDT。UniXNU 可以修改它并传给 EFI 或 Linux 菜单项。

菜单项选择设备树:

[[entry]]
id = "linux"
type = "linux"
path = "Payloads/Image"
dtb = "DeviceTree/board.dtb"

dtb = "firmware" 使用固件树,路径使用负载卷上的文件。树复制时预留 64 KiB,先应用全局补丁,再应用菜单项补丁,最后应用 [entry.chosen]。

补丁支持 set、delete-prop、add-node、delete-node 和 overlay:

[[dt_patch]]
op = "set"
node = "/chosen"
prop = "bootargs"
value = "console=ttyAMA0"

[[dt_patch]]
op = "overlay"
file = "DeviceTree/board.dtbo"

DarwinBoot 读取 .adt sidecar。xnu 菜单项设置 dtb 时会在加载器请求中携带设备树,发布版 DarwinBoot 会拒绝带非空设备树的请求。

启动镜像设备树

启动镜像在 gzip 流后携带设备树。原有 bootloader 可能需要固件树中没有的节点。

[[bootimg.dtb_node]]
path = "/reserved-memory/splash_region"
props = [
  { name = "label", type = "s", value = "cont_splash_region" },
  { name = "reg", type = "x", value = ["0x0", "0xb8000000", "0x0", "0x2b00000"] },
]

unixnu bootimg 用 fdtput 应用这些节点,并校验整数属性往返一致。

参考生成器

生成器 用途
scripts/qemu-entry/make-dt.py 单 CPU、可选 GICv3、VirtIO 和 NVRAM 的 QEMU fixture
scripts/make-adt.py 硬件 DTB 与 OS/板级配置到 ADT
格式 1 设备 make-<device>-adt.py 设备专用生成器

QEMU 生成器是最小完整示例。真实板级的数值记录在设备页面。

下一步