Skip to content

Commit 09d4466

Browse files
sterling-tengJonathan Corbet
sterling-teng
authored and
Jonathan Corbet
committed
docs/zh_CN: add devicetree of_unittest translation
Translate .../Devicetree/of_unittest.rst into Chinese. Signed-off-by: Yanteng Si <siyanteng@loongson.cn> Reviewed-by: Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/da75225df2ac7bee8de653d95b2a872510b34f7d.1646642188.git.siyanteng@loongson.cn Signed-off-by: Jonathan Corbet <corbet@lwn.net>
1 parent c564812 commit 09d4466

2 files changed

Lines changed: 190 additions & 2 deletions

File tree

‎Documentation/translations/zh_CN/devicetree/index.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,10 @@ Open Firmware 和 Devicetree
2323
:maxdepth: 1
2424

2525
usage-model
26+
of_unittest
2627

2728
Todolist:
2829

29-
30-
* of_unittest
3130
* kernel-api
3231

3332
Devicetree Overlays

‎Documentation/translations/zh_CN/devicetree/of_unittest.rst‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
.. include:: ../disclaimer-zh_CN.rst
3+
4+
:Original: Documentation/Devicetree/of_unittest.rst
5+
6+
:翻译:
7+
8+
司延腾 Yanteng Si <siyanteng@loongson.cn>
9+
10+
:校译:
11+
12+
=================================
13+
Open Firmware Devicetree 单元测试
14+
=================================
15+
16+
作者: Gaurav Minocha <gaurav.minocha.os@gmail.com>
17+
18+
1. 概述
19+
=======
20+
21+
本文档解释了执行 OF 单元测试所需的测试数据是如何动态地附加到实时树上的，与机器的架构无关。
22+
23+
建议在继续读下去之前，先阅读以下文件。
24+
25+
(1) Documentation/devicetree/usage-model.rst
26+
(2) http://www.devicetree.org/Device_Tree_Usage
27+
28+
OF Selftest被设计用来测试提供给设备驱动开发者的接口（include/linux/of.h），以从未扁平
29+
化的设备树数据结构中获取设备信息等。这个接口被大多数设备驱动在各种使用情况下使用。
30+
31+
32+
2. 测试数据
33+
===========
34+
35+
设备树源文件（drivers/of/unittest-data/testcases.dts）包含执行drivers/of/unittest.c
36+
中自动化单元测试所需的测试数据。目前，以下设备树源包含文件（.dtsi）被包含在testcases.dt中::
37+
38+
drivers/of/unittest-data/tests-interrupts.dtsi
39+
drivers/of/unittest-data/tests-platform.dtsi
40+
drivers/of/unittest-data/tests-phandle.dtsi
41+
drivers/of/unittest-data/tests-match.dtsi
42+
43+
当内核在启用OF_SELFTEST的情况下被构建时，那么下面的make规则::
44+
45+
$(obj)/%.dtb: $(src)/%.dts FORCE
46+
$(call if_changed_dep, dtc)
47+
48+
用于将DT源文件（testcases.dts）编译成二进制blob（testcases.dtb），也被称为扁平化的DT。
49+
50+
之后，使用以下规则将上述二进制blob包装成一个汇编文件（testcases.dtb.S）::
51+
52+
$(obj)/%.dtb.S: $(obj)/%.dtb
53+
$(call cmd, dt_S_dtb)
54+
55+
汇编文件被编译成一个对象文件（testcases.dtb.o），并被链接到内核镜像中。
56+
57+
58+
2.1. 添加测试数据
59+
-----------------
60+
61+
未扁平化的设备树结构体:
62+
63+
未扁平化的设备树由连接的设备节点组成，其树状结构形式如下所述::
64+
65+
// following struct members are used to construct the tree
66+
struct device_node {
67+
...
68+
struct device_node *parent;
69+
struct device_node *child;
70+
struct device_node *sibling;
71+
...
72+
};
73+
74+
图1描述了一个机器的未扁平化设备树的通用结构，只考虑了子节点和同级指针。存在另一个指针，
75+
``*parent`` ，用于反向遍历该树。因此，在一个特定的层次上，子节点和所有的兄弟姐妹节点将
76+
有一个指向共同节点的父指针（例如，child1、sibling2、sibling3、sibling4的父指针指向
77+
根节点）::
78+
79+
root ('/')
80+
|
81+
child1 -> sibling2 -> sibling3 -> sibling4 -> null
82+
| | | |
83+
| | | null
84+
| | |
85+
| | child31 -> sibling32 -> null
86+
| | | |
87+
| | null null
88+
| |
89+
| child21 -> sibling22 -> sibling23 -> null
90+
| | | |
91+
| null null null
92+
|
93+
child11 -> sibling12 -> sibling13 -> sibling14 -> null
94+
| | | |
95+
| | | null
96+
| | |
97+
null null child131 -> null
98+
|
99+
null
100+
101+
Figure 1: 未扁平化的设备树的通用结构
102+
103+
104+
在执行OF单元测试之前，需要将测试数据附加到机器的设备树上（如果存在）。因此，当调用
105+
selftest_data_add()时，首先会读取通过以下内核符号链接到内核镜像中的扁平化设备树
106+
数据::
107+
108+
__dtb_testcases_begin - address marking the start of test data blob
109+
__dtb_testcases_end - address marking the end of test data blob
110+
111+
其次，它调用of_fdt_unflatten_tree()来解除扁平化的blob。最后，如果机器的设备树
112+
（即实时树）是存在的，那么它将未扁平化的测试数据树附加到实时树上，否则它将自己作为
113+
实时设备树附加。
114+
115+
attach_node_and_children()使用of_attach_node()将节点附加到实时树上，如下所
116+
述。为了解释这一点，图2中描述的测试数据树被附加到图1中描述的实时树上::
117+
118+
root ('/')
119+
|
120+
testcase-data
121+
|
122+
test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null
123+
| | | |
124+
test-child01 null null null
125+
126+
127+
Figure 2: 将测试数据树附在实时树上的例子。
128+
129+
根据上面的方案，实时树已经存在，所以不需要附加根('/')节点。所有其他节点都是通过在
130+
每个节点上调用of_attach_node()来附加的。
131+
132+
在函数of_attach_node()中，新的节点被附在实时树中给定的父节点的子节点上。但是，如
133+
果父节点已经有了一个孩子，那么新节点就会取代当前的孩子，并将其变成其兄弟姐妹。因此，
134+
当测试案例的数据节点被连接到上面的实时树（图1）时，最终的结构如图3所示::
135+
136+
root ('/')
137+
|
138+
testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
139+
| | | | |
140+
(...) | | | null
141+
| | child31 -> sibling32 -> null
142+
| | | |
143+
| | null null
144+
| |
145+
| child21 -> sibling22 -> sibling23 -> null
146+
| | | |
147+
| null null null
148+
|
149+
child11 -> sibling12 -> sibling13 -> sibling14 -> null
150+
| | | |
151+
null null | null
152+
|
153+
child131 -> null
154+
|
155+
null
156+
-----------------------------------------------------------------------
157+
158+
root ('/')
159+
|
160+
testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null
161+
| | | | |
162+
| (...) (...) (...) null
163+
|
164+
test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null
165+
| | | |
166+
null null null test-child01
167+
168+
169+
Figure 3: 附加测试案例数据后的实时设备树结构。
170+
171+
172+
聪明的读者会注意到，与先前的结构相比，test-child0节点成为最后一个兄弟姐妹（图2）。
173+
在连接了第一个test-child0节点之后，又连接了test-sibling1节点，该节点推动子节点
174+
（即test-child0）成为兄弟姐妹，并使自己成为子节点，如上所述。
175+
176+
如果发现一个重复的节点（即如果一个具有相同full_name属性的节点已经存在于实时树中），
177+
那么该节点不会被附加，而是通过调用函数update_node_properties()将其属性更新到活
178+
树的节点中。
179+
180+
181+
2.2. 删除测试数据
182+
-----------------
183+
184+
一旦测试用例执行完，selftest_data_remove被调用，以移除最初连接的设备节点（首先是
185+
叶子节点被分离，然后向上移动父节点被移除，最后是整个树）。selftest_data_remove()
186+
调用detach_node_and_children()，使用of_detach_node()将节点从实时设备树上分离。
187+
188+
为了分离一个节点，of_detach_node()要么将给定节点的父节点的子节点指针更新为其同级节
189+
点，要么根据情况将前一个同级节点附在给定节点的同级节点上。就这样吧。 :)

0 commit comments

Comments
 (0)