> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/man/man4/fdt.4.md).

# fdt.4

`fdt` — Flattened Device Tree 支持

## 名称

`fdt`

## 概要

`options FDT`

`makeoptions FDT_DTS_FILE=<board name>.dts`

`options FDT_DTB_STATIC`

## 描述

*Flattened Device Tree* 是一种以统一且可移植的方式描述计算机硬件资源（无法探测或自枚举的资源）的机制。此技术的主要使用者是*嵌入式系统*，其中许多设计基于相似芯片，但引脚分配、内存布局、地址绑定、中断路由和其他资源各不相同。

无法在运行时自发现的配置数据必须从外部源提供。Flattened device tree 的概念是一种平台和架构无关的解决此类问题的方法。该想法继承自 Open Firmware IEEE 1275 device-tree 概念，并已被嵌入式行业成功采用。其工作方式如下：

* 硬件平台资源以人类可读的文本源格式*手动*描述，汇集所有非自枚举信息。
* 此源描述被转换（编译）为二进制对象，即 flattened device tree *blob*，在引导时传递给内核。
* 内核（驱动程序）从此\[外部提供的] blob 中获取硬件资源详情和依赖关系，无需在内核中嵌入任何关于底层平台硬件资源的信息。
* Flattened device tree 机制原则上不依赖任何特定的第一阶段引导加载程序或固件功能。对环境的唯一总体要求是向内核提供完整的 device tree 描述。

`fdt` 层允许内核中的任何平台代码从统一来源获取硬件资源信息，这为嵌入式应用带来优势（消除硬编码配置方式，使代码数据驱动且可扩展），从而简化移植和维护。

## 定义

**Device tree source（DTS）** device tree 源是一个文本文件，以人类可读的形式描述计算机系统的硬件资源，具有一定的层次结构（树）。在 FreeBSD 源代码仓库中，DTS 文件的默认位置是 **sys/dts** 目录。

**Device tree blob（DTB）** 文本形式的 device tree 描述（DTS 文件）首先被转换（编译）为二进制对象（device tree blob），即 DTB，再交给最终使用者（通常为内核）解析和处理其内容。

**Device tree compiler（DTC）** 在主机上执行的实用程序，将 device tree 的文本描述（DTS）转换（编译）为二进制对象（DTB）。

**Device tree bindings** 虽然 device tree 文本描述和二进制对象是传达硬件配置信息的媒介，但内容的实际含义和解释由 device tree *bindings* 定义。它们是描述 device tree 中特定节点及其属性、允许值、范围等定义（编码）的某些约定。此类参考约定由旧版 Open Firmware bindings 提供，并由 ePAPR 规范进一步补充。

## 构建世界

为使系统支持 `fdt`，需要通过 [src.conf(5)](/man/man5/src.conf.5.md) 或命令行使用 -D 定义的 `WITH_FDT` 构建旋钮来构建 FreeBSD world。

这会创建用户空间 `dtc` 编译器，并在 [loader(8)](/man/man8/loader.8.md) 中启用 `fdt` 支持。

## 构建内核

在 FreeBSD 内核级别管理 `fdt` 支持有若干选项。

**`makeoptions DTS+=<board name>.dts`** 为给定内核指定 device tree 源（DTS）文件。指定的 DTS 文件将在构建内核本身时一并转换（编译）为二进制形式。任何未以绝对路径书写的 DTS 文件名必须相对于 DTS 源的默认位置（即 **sys/dts**）指定。

**`makeoptions DTSO+=<overlay name>.dtso`** 为给定内核指定 device tree 源覆盖（DTSO）文件。覆盖文件将如上文的 `DTS` makeoption 一样随内核构建。以相对路径指定的覆盖文件将相对于所构建平台的 DTS 覆盖默认位置（即 **sys/dts/arm/overlays**）。

**`options FDT`** 在内核中启用 `fdt` 支持的主要选项。它涵盖 `fdt` 内核支持的所有低级和基础设施部分，主要包括 [fdtbus(4)](/man/man4/fdtbus.4.md) 和 [simplebus(4)](/man/man4/simplebus.4.md) 驱动程序，以及辅助例程和库。

**`makeoptions FDT_DTS_FILE=<board name>.dts`** 为给定内核指定首选（默认）device tree 源（DTS）文件。它将如上文的 `DTS` makeoption 一样随内核构建。此 makeoption 不是必需的，除非同时定义了 FDT\_DTB\_STATIC（见下文）。

**`options FDT_DTB_STATIC`** 通常，device tree blob（DTB）是一个独立文件，与内核物理分离，但此选项允许将 DTB 文件静态嵌入内核映像。注意，指定此项时 FDT\_DTS\_FILE makeoption 变为必需（因为需要指定 DTS 文件才能将其嵌入内核映像）。

## 参见

[fdtbus(4)](/man/man4/fdtbus.4.md), [openfirm(4)](/man/man4/openfirm.4.md), [simplebus(4)](/man/man4/simplebus.4.md)

## 标准

IEEE Std 1275：IEEE Boot（初始化配置）固件标准：核心要求与实践（`Open Firmware`）。

Power.org 嵌入式 Power 架构平台要求标准（`ePAPR`）。

## 历史

`fdt` 支持首次出现于 FreeBSD 9.0。

## 作者

`fdt` 支持由 Semihalf 在 FreeBSD Foundation 赞助下开发。本手册页由 Rafal Jaworowski 编写。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/man/man4/fdt.4.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.