1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 .. include:: ../disclaimer-zh_CN.rst 3 .. include:: ../disclaimer-zh_CN.rst
4 4
5 :Original: Documentation/doc-guide/parse-heade 5 :Original: Documentation/doc-guide/parse-headers.rst
6 6
7 :译者: 吴想成 Wu XiangCheng <bobwxc@email. 7 :译者: 吴想成 Wu XiangCheng <bobwxc@email.cn>
8 8
9 ===================== 9 =====================
10 包含用户空间API头文件 10 包含用户空间API头文件
11 ===================== 11 =====================
12 12
13 有时，为了描述用户空间API并在代 13 有时，为了描述用户空间API并在代码和文档之间生成交叉引用，需要包含头文件和示例
14 C代码。为用户空间API文件添加交叉 14 C代码。为用户空间API文件添加交叉引用还有一个好处：如果在文档中找不到相应符号，
15 Sphinx将生成警告。这有助于保持用 15 Sphinx将生成警告。这有助于保持用户空间API文档与内核更改同步。
16 :ref:`parse_headers.pl <parse_headers_zh>` 提 16 :ref:`parse_headers.pl <parse_headers_zh>` 提供了生成此类交叉引用的一种方法。
17 在构建文档时，必须通过Makefile调 17 在构建文档时，必须通过Makefile调用它。有关如何在内核树中使用它的示例，请参阅
18 ``Documentation/userspace-api/media/Makefile`` 18 ``Documentation/userspace-api/media/Makefile`` 。
19 19
20 .. _parse_headers_zh: 20 .. _parse_headers_zh:
21 21
22 parse_headers.pl 22 parse_headers.pl
23 ---------------- 23 ----------------
24 24
25 脚本名称 25 脚本名称
26 ~~~~~~~~ 26 ~~~~~~~~
27 27
28 28
29 parse_headers.pl——解析一个C文件， 29 parse_headers.pl——解析一个C文件，识别函数、结构体、枚举、定义并对Sphinx文档
30 创建交叉引用。 30 创建交叉引用。
31 31
32 32
33 用法概要 33 用法概要
34 ~~~~~~~~ 34 ~~~~~~~~
35 35
36 36
37 \ **parse_headers.pl**\ [<选项>] <C文件> 37 \ **parse_headers.pl**\ [<选项>] <C文件> <输出文件> [<例外文件>]
38 38
39 <选项> 可以是： --debug, --help 或 --us 39 <选项> 可以是： --debug, --help 或 --usage 。
40 40
41 41
42 选项 42 选项
43 ~~~~ 43 ~~~~
44 44
45 45
46 46
47 \ **--debug**\ 47 \ **--debug**\
48 48
49 开启脚本详细模式，在调试时很有 49 开启脚本详细模式，在调试时很有用。
50 50
51 51
52 \ **--usage**\ 52 \ **--usage**\
53 53
54 打印简短的帮助信息并退出。 54 打印简短的帮助信息并退出。
55 55
56 56
57 57
58 \ **--help**\ 58 \ **--help**\
59 59
60 打印更详细的帮助信息并退出。 60 打印更详细的帮助信息并退出。
61 61
62 62
63 说明 63 说明
64 ~~~~ 64 ~~~~
65 65
66 通过C头文件或源文件（<C文件>）中 66 通过C头文件或源文件（<C文件>）中为描述API的文档编写的带交叉引用的 ..预格式化
67 文本 块将文件转换成重构文本（RST 67 文本 块将文件转换成重构文本（RST）。它接受一个可选的<例外文件>，其中描述了
68 哪些元素将被忽略或指向非默认引 68 哪些元素将被忽略或指向非默认引用。
69 69
70 输出被写入到<输出文件>。 70 输出被写入到<输出文件>。
71 71
72 它能够识别定义、函数、结构体、t 72 它能够识别定义、函数、结构体、typedef、枚举和枚举符号，并为它们创建交叉引用。
73 它还能够区分用于指定Linux ioctl的 ` 73 它还能够区分用于指定Linux ioctl的 ``#define`` 。
74 74
75 <例外文件> 包含两种类型的语句： 75 <例外文件> 包含两种类型的语句： \ **ignore**\ 或 \ **replace**\ .
76 76
77 ignore标记的语法为： 77 ignore标记的语法为：
78 78
79 79
80 ignore \ **type**\ \ **name**\ 80 ignore \ **type**\ \ **name**\
81 81
82 The \ **ignore**\ 意味着它不会为类型 82 The \ **ignore**\ 意味着它不会为类型为 \ **type**\ 的 \ **name**\ 符号生成
83 交叉引用。 83 交叉引用。
84 84
85 85
86 replace标记的语法为： 86 replace标记的语法为：
87 87
88 88
89 replace \ **type**\ \ **name**\ \ **new_valu 89 replace \ **type**\ \ **name**\ \ **new_value**\
90 90
91 The \ **replace**\ 味着它将为 \ **type** 91 The \ **replace**\ 味着它将为 \ **type**\ 类型的 \ **name**\ 符号生成交叉引
92 用，但是它将使用 \ **new_value**\ 来 92 用，但是它将使用 \ **new_value**\ 来取代默认的替换规则。
93 93
94 94
95 这两种语句中， \ **type**\ 可以是以 95 这两种语句中， \ **type**\ 可以是以下任一项：
96 96
97 97
98 \ **ioctl**\ 98 \ **ioctl**\
99 99
100 ignore 或 replace 语句应用于ioctl定义 100 ignore 或 replace 语句应用于ioctl定义，如：
101 101
102 #define VIDIOC_DBG_S_REGISTER _IOW( 102 #define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct v4l2_dbg_register)
103 103
104 104
105 105
106 \ **define**\ 106 \ **define**\
107 107
108 ignore 或 replace 语句应用于在<C文件 108 ignore 或 replace 语句应用于在<C文件>中找到的任何其他 ``#define`` 。
109 109
110 110
111 111
112 \ **typedef**\ 112 \ **typedef**\
113 113
114 ignore 和 replace 语句应用于<C文件> 114 ignore 和 replace 语句应用于<C文件>中的typedef语句。
115 115
116 116
117 117
118 \ **struct**\ 118 \ **struct**\
119 119
120 ignore 和 replace 语句应用于<C文件> 120 ignore 和 replace 语句应用于<C文件>中的结构体名称语句。
121 121
122 122
123 123
124 \ **enum**\ 124 \ **enum**\
125 125
126 ignore 和 replace 语句应用于<C文件> 126 ignore 和 replace 语句应用于<C文件>中的枚举名称语句。
127 127
128 128
129 129
130 \ **symbol**\ 130 \ **symbol**\
131 131
132 ignore 和 replace 语句应用于<C文件> 132 ignore 和 replace 语句应用于<C文件>中的枚举值名称语句。
133 133
134 replace语句中， \ **new_value**\ 会自 134 replace语句中， \ **new_value**\ 会自动使用 \ **typedef**\ , \ **enum**\
135 和 \ **struct**\ 类型的 :c:type: 引用 135 和 \ **struct**\ 类型的 :c:type: 引用；以及 \ **ioctl**\ , \ **define**\ 和
136 \ **symbol**\ 类型的 :ref: 。引用的 136 \ **symbol**\ 类型的 :ref: 。引用的类型也可以在replace语句中显式定义。
137 137
138 138
139 示例 139 示例
140 ~~~~ 140 ~~~~
141 141
142 142
143 ignore define _VIDEODEV2_H 143 ignore define _VIDEODEV2_H
144 144
145 145
146 忽略<C文件>中的 #define _VIDEODEV2_H 。 146 忽略<C文件>中的 #define _VIDEODEV2_H 。
147 147
148 ignore symbol PRIVATE 148 ignore symbol PRIVATE
149 149
150 150
151 如下结构体： 151 如下结构体：
152 152
153 enum foo { BAR1, BAR2, PRIVATE }; 153 enum foo { BAR1, BAR2, PRIVATE };
154 154
155 不会为 \ **PRIVATE**\ 生成交叉引用。 155 不会为 \ **PRIVATE**\ 生成交叉引用。
156 156
157 replace symbol BAR1 :c:type:\`foo\` 157 replace symbol BAR1 :c:type:\`foo\`
158 replace symbol BAR2 :c:type:\`foo\` 158 replace symbol BAR2 :c:type:\`foo\`
159 159
160 160
161 如下结构体： 161 如下结构体：
162 162
163 enum foo { BAR1, BAR2, PRIVATE }; 163 enum foo { BAR1, BAR2, PRIVATE };
164 164
165 它会让BAR1和BAR2枚举符号交叉引用C 165 它会让BAR1和BAR2枚举符号交叉引用C域中的foo符号。
166 166
167 167
168 168
169 缺陷 169 缺陷
170 ~~~~ 170 ~~~~
171 171
172 172
173 请向Mauro Carvalho Chehab <mchehab@kernel.org 173 请向Mauro Carvalho Chehab <mchehab@kernel.org>报告有关缺陷。
174 174
175 中文翻译问题请找中文翻译维护者 175 中文翻译问题请找中文翻译维护者。
176 176
177 177
178 版权 178 版权
179 ~~~~ 179 ~~~~
180 180
181 181
182 版权所有 (c) 2016 Mauro Carvalho Chehab <mc 182 版权所有 (c) 2016 Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
183 183
184 许可证 GPLv2：GNU GPL version 2 <https://g 184 许可证 GPLv2：GNU GPL version 2 <https://gnu.org/licenses/gpl.html>
185 185
186 这是自由软件：你可以自由地修改 186 这是自由软件：你可以自由地修改和重新发布它。
187 在法律允许的范围内，**不提供任 187 在法律允许的范围内，**不提供任何保证**。
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.