[TOOLS] Add DTC (Devicetree Compiler) tools #10431
Conversation
📌 Code Review Assignment🏷️ Tag: documentationPath: Changed Files (Click to expand)
📊 Current Review Status (Last Updated: 2025-06-25 11:12 UTC)
📝 Review Instructions
|
|
For windows: RT-Thread/env-windows#37 |
| @@ -0,0 +1,270 @@ | |||
| # DTC (Devicetree Compiler) | |||
There was a problem hiding this comment.
请将这行改成：
@page page_device_dtc Devicetree Compiler然后在 documentation/6.components/device-driver/INDEX.md 中加入一行，位置我觉得可以放在第二个。
- .....
- @subpage page_device_dtc
- ......
这样这个 markdown 文件就可以转化成一个 html page 了，目前内核文档一旦合入 master 后会及时同步在：https://rt-thread.github.io/rt-thread/。如果要在 merge 之前，在本地查看文档修改后生成的 html 的效果，可以参考 https://rt-thread.github.io/rt-thread/page_howto_doxygen.html#autotoc_md3
| @@ -0,0 +1,270 @@ | |||
| # DTC (Devicetree Compiler) | |||
|
|
|||
| ## Introduction to the DTC | |||
There was a problem hiding this comment.
这个缩小一级，即将 ## 改成 #
以下各级标题依次类推。
|
|
||
| ## Introduction to the DTC | ||
|
|
||
| Device Tree Compiler, dtc, takes as input a device-tree in a given format and outputs a device-tree in another format for booting kernels on embedded systems. |
There was a problem hiding this comment.
takes a device-tree as input in a ......
There was a problem hiding this comment.
| Device Tree Compiler, dtc, takes as input a device-tree in a given format and outputs a device-tree in another format for booting kernels on embedded systems. | ||
| Typically, the input format is "dts" (device-tree source), a human readable source format, and creates a "dtb" (device-tree binary), or binary format as output. | ||
|
|
||
| > If you not install dtc tools in your host system, the dtc module will tell you how to do. |
There was a problem hiding this comment.
If you have not installed dtc tools ......
| ### Generate DTS | ||
|
|
||
| When you get a DTB or FDT file from firmware or the other runtime system, you may want to convert it to dts for reading easier. Just do in your Python or SConscript, dummpy.dtb, eg.: |
There was a problem hiding this comment.
最后一句话没看懂是写的什么意思？你是想说，下面是一个 SConscript 文件的例子，假设需要转化的 DTB 文件是 “dummpy.dtb”。如果是这个意思，机翻如下：
The following is an example of an SConscript file, assuming that the DTB file to be converted is dummpy.dtb.
|
|
||
| #### Include and Macros | ||
|
|
||
| Gog, dtc is not supports preprocess like C preprocessor (cpp), but you can use cpp to do it in the dts, don't worry, we have appended the step in dtc module. |
There was a problem hiding this comment.
Gog 是什么？
“ we have appended the step in dtc module.” 这是想表达什么意思？是想说我们已经支持了预处理吗？如果是这样，可以直接说：we have supported preprocessor in dts.
我通读了一下这一段 “Include and Macros” 很可惜感觉没有看明白想说什么？能够先用中文在这里介绍一下？
| dtc.dts_to_dtb(RTT_ROOT, ["dummpy.dts"], include_paths = ['dm/include', 'firmware']) | ||
| ``` | ||
|
|
||
| Maybe you have other ideas? |
There was a problem hiding this comment.
文档中不要出现反问，没有确定的东西不要出现在指导文档中感觉没有意义。
| }; | ||
| }; | ||
|
|
||
| dsp { |
There was a problem hiding this comment.
我记得更好的做法是，对于 soc 级别的 dtsi 文件中，所有的设备都应该 disabled。在 board level 的 dts 文件中再选择性的 enable 即可。
|
|
||
| When you have some `dt-bindings` include files or macros, like this: | ||
|
|
||
| ```c |
There was a problem hiding this comment.
dts 语法是 json，所以这里感觉用
```json
更好
|
|
||
| ### Raw options | ||
|
|
||
| DTC have more raw options than generate dts show by `dtc --help`, like to append them like this: |
There was a problem hiding this comment.
这里是不是没有断句？没有看懂说什么。
是否可以先写出中文，然后机翻一下？
|
有个 general 的疑问，RT-Thread 的 dts 是准备全部重写还是打算尽量复用 linux 中的 dts？ |
尽可能重用linux dts，所以语法也基本上是linux的一套 |
语法是一样的，不分 Linux 还是 RT-Thread，只是部分驱动对设备树的解析方式是复用 Linux 的，文档已经更新，烦请继续 review。 |
There was a problem hiding this comment.
Pull Request Overview
This PR introduces Devicetree Compiler (DTC) support by adding a new Python tool for converting DTS to DTB and vice versa, along with detailed documentation for its usage.
- Added a new Python module (tools/dtc.py) with functions to convert between DTS and DTB files.
- Updated documentation with a dedicated page and index entry for DTC instructions.
Reviewed Changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| tools/dtc.py | Added functions for DTS to DTB and DTB to DTS conversion using dtc. |
| documentation/6.components/device-driver/ofw/dtc.md | Comprehensive documentation for installing and using the DTC tool. |
| documentation/6.components/device-driver/INDEX.md | Added a reference to the new DTC documentation page. |
Signed-off-by: GuEe-GUI <[email protected]>
| if value != 0 and os.system("dtc -v") != 0: | ||
| print(__dtc_install_tip) | ||
|
|
||
| def dts_to_dtb(RTT_ROOT, dts_list, options = "", include_paths = [], ignore_warning = []): |
There was a problem hiding this comment.
主要来说是加了两个dts/dtb互转的函数？或者是否可以加scons的build？
There was a problem hiding this comment.
并不知道怎么给 scons 添加 build 规则，也没有找到相关资料
There was a problem hiding this comment.
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
高级设备树编译和转换的SCons Builder
支持DTS和DTB文件之间的互相转换，包含更多编译选项
"""
import os
import SCons.Builder
import SCons.Action
import SCons.Util
def dtc_action(target, source, env):
"""DTS到DTB的转换动作"""
dtc = env.get('DTC', 'dtc')
dts_file = str(source[0])
dtb_file = str(target[0])
# 构建命令
cmd_parts = [dtc]
# 添加编译选项
if env.get('DT_FLAGS'):
cmd_parts.extend(env['DT_FLAGS'])
# 添加包含路径
for include_path in env.get('DT_INCLUDES', []):
cmd_parts.extend(['-i', include_path])
# 添加预处理器定义
for define in env.get('DT_DEFINES', []):
cmd_parts.extend(['-D', define])
# 基本参数
cmd_parts.extend(['-I', 'dts', '-O', 'dtb', '-o', dtb_file, dts_file])
cmd = ' '.join(cmd_parts)
return env.Execute(cmd)
def dts_action(target, source, env):
"""DTB到DTS的转换动作"""
dtc = env.get('DTC', 'dtc')
dtb_file = str(source[0])
dts_file = str(target[0])
# 构建命令
cmd_parts = [dtc]
# 添加反编译选项
if env.get('DT_DECOMPILE_FLAGS'):
cmd_parts.extend(env['DT_DECOMPILE_FLAGS'])
# 基本参数
cmd_parts.extend(['-I', 'dtb', '-O', 'dts', '-o', dts_file, dtb_file])
cmd = ' '.join(cmd_parts)
return env.Execute(cmd)
def dt_validate_action(target, source, env):
"""设备树验证动作"""
dtc = env.get('DTC', 'dtc')
dts_file = str(source[0])
cmd = f'{dtc} -I dts -O dtb -f {dts_file}'
return env.Execute(cmd)
def dt_overlay_action(target, source, env):
"""设备树覆盖编译动作"""
dtc = env.get('DTC', 'dtc')
base_dts = str(source[0])
overlay_dts = str(source[1])
output_dtb = str(target[0])
# 先编译基础设备树
base_dtb = str(target[0]) + '.base'
base_cmd = f'{dtc} -I dts -O dtb -o {base_dtb} {base_dts}'
# 编译覆盖
overlay_dtb = str(target[0]) + '.overlay'
overlay_cmd = f'{dtc} -I dts -O dtb -o {overlay_dtb} {overlay_dts}'
# 应用覆盖
apply_cmd = f'{dtc} -I dtb -O dtb -o {output_dtb} -@ {base_dtb} {overlay_dtb}'
return env.Execute(base_cmd) and env.Execute(overlay_cmd) and env.Execute(apply_cmd)
def generate(env):
"""生成高级设备树builder"""
# 创建DTS到DTB的builder
dtc_builder = SCons.Builder.Builder(
action=SCons.Action.Action(dtc_action, 'Compiling DTS to DTB: $TARGET'),
suffix='.dtb',
src_suffix='.dts',
source_scanner=None,
target_scanner=None,
emitter=None
)
# 创建DTB到DTS的builder
dts_builder = SCons.Builder.Builder(
action=SCons.Action.Action(dts_action, 'Decompiling DTB to DTS: $TARGET'),
suffix='.dts',
src_suffix='.dtb',
source_scanner=None,
target_scanner=None,
emitter=None
)
# 创建设备树验证builder
validate_builder = SCons.Builder.Builder(
action=SCons.Action.Action(dt_validate_action, 'Validating DTS: $SOURCE'),
suffix='.valid',
src_suffix='.dts',
source_scanner=None,
target_scanner=None,
emitter=None
)
# 创建设备树覆盖builder
overlay_builder = SCons.Builder.Builder(
action=SCons.Action.Action(dt_overlay_action, 'Applying DTS overlay: $TARGET'),
suffix='.dtb',
src_suffix='.dts',
source_scanner=None,
target_scanner=None,
emitter=None
)
# 将builder添加到环境中
env.Append(BUILDERS={
'DTS2DTB': dtc_builder,
'DTB2DTS': dts_builder,
'DTValidate': validate_builder,
'DTOverlay': overlay_builder
})
# 设置默认的dtc工具路径
if 'DTC' not in env:
dtc_path = env.WhereIs('dtc')
if dtc_path:
env['DTC'] = dtc_path
else:
env['DTC'] = 'dtc'
# 设置默认编译选项
if 'DT_FLAGS' not in env:
env['DT_FLAGS'] = ['-W', 'no-unit_address_vs_reg']
if 'DT_DECOMPILE_FLAGS' not in env:
env['DT_DECOMPILE_FLAGS'] = ['-s']
# 设置默认包含路径
if 'DT_INCLUDES' not in env:
env['DT_INCLUDES'] = []
# 设置默认预处理器定义
if 'DT_DEFINES' not in env:
env['DT_DEFINES'] = []
def exists(env):
"""检查builder是否存在"""
return True 在SConstruct中
# 导入设备树builder
import dt_builder
# 添加基本设备树builder
dt_builder.generate(env)
# 配置DTC工具路径（如果需要自定义路径）
# env['DTC'] = r'C:\path\to\your\dtc.exe'
# 设置高级编译选项
env['DT_FLAGS'] = ['-W', 'no-unit_address_vs_reg', '-W', 'no-graph_port']
env['DT_DECOMPILE_FLAGS'] = ['-s', '--sort']
env['DT_INCLUDES'] = ['./include'] # 如果有include目录
env['DT_DEFINES'] = ['CONFIG_DEBUG=1']
# 基本设备树编译任务
# DTS到DTB转换
env.DTS2DTB('example.dtb', 'example.dts')
# DTB到DTS转换
env.DTB2DTS('example_decompiled.dts', 'example.dtb')|
直接重写的，重新看就好 |
拉取/合并请求描述：(PR description)
[
Devicetree Compiler for dts build
]
当前拉取/合并请求的状态 Intent for your PR
必须选择一项 Choose one (Mandatory):
代码质量 Code Quality：
我在这个拉取/合并请求中已经考虑了 As part of this pull request, I've considered the following:
#if 0代码，不包含已经被注释了的代码 All redundant code is removed and cleaned up