Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Merge tag 'Chinese-doc-6.16-rc1' of gitolite.kernel.org:pub/scm/linux/kernel/git/alexs/linux into docs-mw
Chinese translation docs for 6.16-rc1 from Alex Shi
This is the Chinese translation subtree for 6.16-rc1. It just
includes few changes:
- MAINTAINERS: Change Yanteng's email address
- docs/zh_CN: Add how-to of Chinese translation
- Add networking translation index
- Docs/zh_CN: Translate msg_zerocopy.rst to Simplified Chinese
Signed-off-by: Alex Shi <alexs@kernel.org>
+853
-11
+459
Documentation/translations/zh_CN/how-to.rst
+459
Documentation/translations/zh_CN/how-to.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
=========================
4
+
Linux内核中文文档翻译规范
5
+
=========================
6
+
7
+
修订记录：
8
+
- v1.0 2025年3月28日，司延腾、慕冬亮共同编写了该规范。
9
+
10
+
制定规范的背景
11
+
==============
12
+
13
+
过去几年，在广大社区爱好者的友好合作下，Linux 内核中文文档迎来了蓬勃的发
14
+
展。在翻译的早期，一切都是混乱的，社区对译稿只有一个准确翻译的要求，以鼓
15
+
励更多的开发者参与进来，这是从0到1的必然过程，所以早期的中文文档目录更加
16
+
具有多样性，不过好在文档不多，维护上并没有过大的压力。
17
+
18
+
然而，世事变幻，不觉有年，现在内核中文文档在前进的道路上越走越远，很多潜
19
+
在的问题逐渐浮出水面，而且随着中文文档数量的增加，翻译更多的文档与提高中
20
+
文文档可维护性之间的矛盾愈发尖锐。由于文档翻译的特殊性，很多开发者并不会
21
+
一直更新文档，如果中文文档落后英文文档太多，文档更新的工作量会远大于重新
22
+
翻译。而且邮件列表中陆续有新的面孔出现，他们那股热情，就像燃烧的火焰，能
23
+
瞬间点燃整个空间，可是他们的补丁往往具有个性，这会给审阅带来了很大的困难，
24
+
reviewer 们只能耐心地指导他们如何与社区更好地合作，但是这项工作具有重复
25
+
性，长此以往，会渐渐浇灭 reviewer 审阅的热情。
26
+
27
+
虽然内核文档中已经有了类似的贡献指南，但是缺乏专门针对于中文翻译的，尤其
28
+
是对于新手来说，浏览大量的文档反而更加迷惑，该文档就是为了缓解这一问题而
29
+
编写，目的是为提供给新手一个快速翻译指南。
30
+
31
+
详细的贡献指南：Documentation/translations/zh_CN/process/index.rst。
32
+
33
+
环境搭建
34
+
========
35
+
36
+
工欲善其事必先利其器，如果您目前对内核文档翻译满怀热情，并且会独立地安装
37
+
linux 发行版和简单地使用 linux 命令行，那么可以迅速开始了。若您尚不具备该
38
+
能力，很多网站上会有详细的手把手教程，最多一个上午，您应该就能掌握对应技
39
+
能。您需要注意的一点是，请不要使用 root 用户进行后续步骤和文档翻译。
40
+
41
+
拉取开发树
42
+
----------
43
+
44
+
中文文档翻译工作目前独立于 linux-doc 开发树开展，所以您需要拉取该开发树，
45
+
打开终端命令行执行::
46
+
47
+
git clone git://git.kernel.org/pub/scm/linux/kernel/git/alexs/linux.git
48
+
49
+
如果您遇到网络连接问题，也可以执行以下命令::
50
+
51
+
git clone https://mirrors.hust.edu.cn/git/kernel-doc-zh.git linux
52
+
53
+
这是 Alex 开发树的镜像库，每两个小时同步一次上游。如果您了解到更快的 mirror，
54
+
请随时 **添加** 。
55
+
56
+
命令执行完毕后，您会在当前目录下得到一个 linux 目录，该目录就是您之后的工作
57
+
仓库，请把它放在一个稳妥的位置。
58
+
59
+
安装文档构建环境
60
+
----------------
61
+
62
+
内核仓库里面提供了一个半自动化脚本，执行该脚本，会检测您的发行版中需要安
63
+
装哪些软件包，请按照命令行提示进行安装，通常您只需要复制命令并执行就行。
64
+
::
65
+
66
+
cd linux
67
+
./scripts/sphinx-pre-install
68
+
69
+
以Fedora为例，它的输出是这样的::
70
+
71
+
You should run:
72
+
73
+
sudo dnf install -y dejavu-sans-fonts dejavu-sans-mono-fonts dejavu-serif-fonts google-noto-sans-cjk-fonts graphviz-gd latexmk librsvg2-tools texlive-anyfontsize texlive-capt-of texlive-collection-fontsrecommended texlive-ctex texlive-eqparbox texlive-fncychap texlive-framed texlive-luatex85 texlive-multirow texlive-needspace texlive-tabulary texlive-threeparttable texlive-upquote texlive-wrapfig texlive-xecjk
74
+
75
+
Sphinx needs to be installed either:
76
+
1) via pip/pypi with:
77
+
78
+
/usr/bin/python3 -m venv sphinx_latest
79
+
. sphinx_latest/bin/activate
80
+
pip install -r ./Documentation/sphinx/requirements.txt
81
+
82
+
If you want to exit the virtualenv, you can use:
83
+
deactivate
84
+
85
+
2) As a package with:
86
+
87
+
sudo dnf install -y python3-sphinx
88
+
89
+
Please note that Sphinx >= 3.0 will currently produce false-positive
90
+
warning when the same name is used for more than one type (functions,
91
+
structs, enums,...). This is known Sphinx bug. For more details, see:
92
+
https://github.com/sphinx-doc/sphinx/pull/8313
93
+
94
+
请您按照提示复制打印的命令到命令行执行，您必须具备 root 权限才能执行 sudo
95
+
开头的命令。
96
+
97
+
如果您处于一个多用户环境中，为了避免对其他人造成影响，建议您配置单用户
98
+
sphinx 虚拟环境，即只需要执行::
99
+
100
+
/usr/bin/python3 -m venv sphinx_latest
101
+
. sphinx_latest/bin/activate
102
+
pip install -r ./Documentation/sphinx/requirements.txt
103
+
104
+
最后执行以下命令退出虚拟环境::
105
+
106
+
deactivate
107
+
108
+
您可以在任何需要的时候再次执行以下命令进入虚拟环境::
109
+
110
+
. sphinx_latest/bin/activate
111
+
112
+
进行第一次文档编译
113
+
------------------
114
+
115
+
进入开发树目录::
116
+
117
+
cd linux
118
+
119
+
这是一个标准的编译和调试流程，请每次构建时都严格执行::
120
+
121
+
. sphinx_latest/bin/activate
122
+
make cleandocs
123
+
make htmldocs
124
+
deactivate
125
+
126
+
检查编译结果
127
+
------------
128
+
129
+
编译输出在Documentation/output/目录下，请用浏览器打开该目录下对应
130
+
的文件进行检查。
131
+
132
+
git和邮箱配置
133
+
-------------
134
+
135
+
打开命令行执行::
136
+
137
+
sudo dnf install git-email
138
+
vim ~/.gitconfig
139
+
140
+
这里是我的一个配置文件示范，请根据您的邮箱域名服务商提供的手册替换到对
141
+
应的字段。
142
+
::
143
+
144
+
[user]
145
+
name = Yanteng Si # 这会出现在您的补丁头部签名栏
146
+
email = si.yanteng@linux.dev # 这会出现在您的补丁头部签名栏
147
+
148
+
[sendemail]
149
+
from = Yanteng Si <si.yanteng@linux.dev> # 这会出现在您的补丁头部
150
+
smtpencryption = ssl
151
+
smtpserver = smtp.migadu.com
152
+
smtpuser = si.yanteng@linux.dev
153
+
smtppass = <passwd> # 建议使用第三方客户端专用密码
154
+
chainreplyto = false
155
+
smtpserverport = 465
156
+
157
+
关于邮件客户端的配置，请查阅Documentation/translations/zh_CN/process/email-clients.rst。
158
+
159
+
开始翻译文档
160
+
============
161
+
162
+
文档索引结构
163
+
------------
164
+
165
+
目前中文文档是在Documentation/translations/zh_CN/目录下进行，该
166
+
目录结构最终会与Documentation/结构一致，所以您只需要将您感兴趣的英文
167
+
文档文件和对应的 index.rst 复制到 zh_CN 目录下对应的位置，然后修改更
168
+
上一级的 index 即可开始您的翻译。
169
+
170
+
为了保证翻译的文档补丁被顺利合并，不建议多人同时翻译一个目录，因为这会
171
+
造成补丁之间互相依赖，往往会导致一部分补丁被合并，另一部分产生冲突。
172
+
173
+
如果实在无法避免两个人同时对一个目录进行翻译的情况，请将补丁制作进一个补
174
+
丁集。但是不推荐刚开始就这么做，因为经过实践，在没有指导的情况下，新手很
175
+
难一次处理好这个补丁集。
176
+
177
+
请执行以下命令，新建开发分支::
178
+
179
+
git checkout docs-next
180
+
git branch my-trans
181
+
git checkout my-trans
182
+
183
+
译文格式要求
184
+
------------
185
+
186
+
- 每行长度最多不超过40个字符
187
+
- 每行长度请保持一致
188
+
- 标题的下划线长度请按照一个英文一个字符、一个中文两个字符与标题对齐
189
+
- 其它的修饰符请与英文文档保持一致
190
+
191
+
此外在译文的头部，您需要插入以下内容::
192
+
193
+
.. SPDX-License-Identifier: GPL-2.0
194
+
.. include:: ../disclaimer-zh_CN.rst #您需要了解该文件的路径，根
195
+
据您实际翻译的文档灵活调整
196
+
197
+
:Original: Documentation/xxx/xxx.rst #替换为您翻译的英文文档路径
198
+
199
+
:翻译:
200
+
201
+
司延腾 Yanteng Si <si.yanteng@linux.dev> #替换为您自己的联系方式
202
+
203
+
翻译技巧
204
+
--------
205
+
206
+
中文文档有每行40字符限制，因为一个中文字符等于2个英文字符。但是社区并没有
207
+
那么严格，一个诀窍是将您的翻译的内容与英文原文的每行长度对齐即可，这样，
208
+
您也不必总是检查有没有超限。
209
+
210
+
如果您的英文阅读能力有限，可以考虑使用辅助翻译工具，例如 deepseek 。但是您
211
+
必须仔细地打磨，使译文达到“信达雅”的标准。
212
+
213
+
**请注意** 社区不接受纯机器翻译的文档，社区工作建立在信任的基础上，请认真对待。
214
+
215
+
编译和检查
216
+
----------
217
+
218
+
请执行::
219
+
220
+
. sphinx_latest/bin/activate
221
+
make cleandocs
222
+
make htmldocs
223
+
224
+
解决与您翻译的文档相关的 warning 和 error，然后执行::
225
+
226
+
make cleandocs #该步骤不能省略，否则可能不会再次输出真实存在的警告
227
+
make htmldocs
228
+
deactivate
229
+
230
+
进入 output 目录用浏览器打开您翻译的文档，检查渲染的页面是否正常，如果正常，
231
+
继续进行后续步骤，否则请尝试解决。
232
+
233
+
制作补丁
234
+
========
235
+
236
+
提交改动
237
+
--------
238
+
239
+
执行以下命令，在弹出的交互式页面中填写必要的信息。
240
+
::
241
+
242
+
git add .
243
+
git commit -s -v
244
+
245
+
请参考以下信息进行输入::
246
+
247
+
docs/zh_CN: Add self-protection index Chinese translation
248
+
249
+
Translate .../security/self-protection.rst into Chinese.
250
+
251
+
Update the translation through commit b080e52110ea #请执行git log <您翻译的英文文档路径> 复制最顶部第一个补丁的sha值的前12位，替换掉12位sha值。
252
+
("docs: update self-protection __ro_after_init status")
253
+
254
+
Signed-off-by: Yanteng Si <si.yanteng@linux.dev> #如果您前面的步骤正确执行，该行会自动显示，否则请检查gitconfig文件。
255
+
256
+
保存并退出。
257
+
258
+
**请注意** 以上四行，缺少任何一行，您都将会在第一轮审阅后返工，如果您需要一个更加明确的示例，请对 zh_CN 目录执行 git log。
259
+
260
+
导出补丁和制作封面
261
+
------------------
262
+
263
+
这个时候，可以导出补丁，做发送邮件列表最后的准备了。命令行执行::
264
+
265
+
git format-patch -N
266
+
267
+
然后命令行会输出类似下面的内容::
268
+
269
+
0001-docs-zh_CN-add-xxxxxxxx.patch
270
+
0002-docs-zh_CN-add-xxxxxxxx.patch
271
+
……
272
+
273
+
测试补丁
274
+
--------
275
+
276
+
内核提供了一个补丁检测脚本，请执行::
277
+
278
+
./scripts/checkpatch.pl *.patch
279
+
280
+
参考脚本输出，解决掉所有的 error 和 warning，通常情况下，只有下面这个
281
+
warning 不需要解决::
282
+
283
+
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
284
+
285
+
一个简单的解决方法是一次只检查一个补丁，然后打上该补丁，直接对译文进行修改，
286
+
然后执行以下命令为补丁追加更改::
287
+
288
+
git checkout docs-next
289
+
git branch test-trans
290
+
git am 0001-xxxxx.patch
291
+
./scripts/checkpatch.pl 0001-xxxxx.patch
292
+
直接修改您的翻译
293
+
git add .
294
+
git am --amend
295
+
保存退出
296
+
git am 0002-xxxxx.patch
297
+
……
298
+
299
+
重新导出再次检测，重复这个过程，直到处理完所有的补丁。
300
+
301
+
最后，如果检测时没有 warning 和 error 需要被处理或者您只有一个补丁，请跳
302
+
过下面这个步骤，否则请重新导出补丁制作封面::
303
+
304
+
git format-patch -N --cover-letter --thread=shallow #N为您的补丁数量,N一般要大于1。
305
+
306
+
然后命令行会输出类似下面的内容::
307
+
308
+
0000-cover-letter.patch
309
+
0001-docs-zh_CN-add-xxxxxxxx.patch
310
+
0002-docs-zh_CN-add-xxxxxxxx.patch
311
+
312
+
您需要用编辑器打开0号补丁，修改两处内容::
313
+
314
+
vim 0000-cover-letter.patch
315
+
316
+
...
317
+
Subject: [PATCH 0/1] *** SUBJECT HERE *** #修改该字段，概括您的补丁集都做了哪些事情
318
+
319
+
*** BLURB HERE *** #修改该字段，详细描述您的补丁集做了哪些事情
320
+
321
+
Yanteng Si (1):
322
+
docs/zh_CN: add xxxxx
323
+
...
324
+
325
+
如果您只有一个补丁，则可以不制作封面，即0号补丁，只需要执行::
326
+
327
+
git format-patch -1
328
+
329
+
把补丁提交到邮件列表
330
+
====================
331
+
332
+
恭喜您，您的文档翻译现在可以提交到邮件列表了。
333
+
334
+
获取维护者和审阅者邮箱以及邮件列表地址
335
+
--------------------------------------
336
+
337
+
内核提供了一个自动化脚本工具，请执行::
338
+
339
+
./scripts/get_maintainer.pl *.patch
340
+
341
+
将输出的邮箱地址保存下来。
342
+
343
+
将补丁提交到邮件列表
344
+
--------------------
345
+
346
+
打开上面您保存的邮件地址，执行::
347
+
348
+
git send-email *.patch --to <maintainer email addr> --cc <others addr> #一个to对应一个地址，一个cc对应一个地址，有几个就写几个。
349
+
350
+
执行该命令时，请确保网络通常，邮件发送成功一般会返回250。
351
+
352
+
您可以先发送给自己，尝试发出的 patch 是否可以用 'git am' 工具正常打上。
353
+
如果检查正常， 您就可以放心的发送到社区评审了。
354
+
355
+
如果该步骤被中断，您可以检查一下，继续用上条命令发送失败的补丁，一定不要再
356
+
次发送已经发送成功的补丁。
357
+
358
+
积极参与审阅过程并迭代补丁
359
+
==========================
360
+
361
+
补丁提交到邮件列表并不代表万事大吉，您还需要积极回复 maintainer 和
362
+
reviewer 的评论，做到每条都有回复，每个回复都落实到位。
363
+
364
+
如何回复评论
365
+
------------
366
+
367
+
- 请先将您的邮箱客户端信件回复修改为 **纯文本** 格式，并去除所有签名，尤其是
368
+
企业邮箱。
369
+
- 然后点击回复按钮，并将要回复的邮件带入，
370
+
- 在第一条评论行尾换行，输入您的回复
371
+
- 在第二条评论行尾换行，输入您的回复
372
+
- 直到处理完最后一条评论，换行空两行输入问候语和署名
373
+
374
+
注意，信件回复请尽量使用英文。
375
+
376
+
迭代补丁
377
+
--------
378
+
379
+
建议您每回复一条评论，就修改一处翻译。然后重新生成补丁，相信您现在已经具
380
+
备了灵活使用 git am --amend 的能力。
381
+
382
+
每次迭代一个补丁，不要一次多个::
383
+
384
+
git am <您要修改的补丁>
385
+
直接对文件进行您的修改
386
+
git add .
387
+
git commit --amend
388
+
389
+
当您将所有的评论落实到位后，导出第二版补丁，并修改封面::
390
+
391
+
git format-patch -N -v 2 --cover-letter --thread=shallow
392
+
393
+
打开0号补丁，在 BLURB HERE 处编写相较于上个版本，您做了哪些改动。
394
+
395
+
然后执行::
396
+
397
+
git send-email v2* --to <maintainer email addr> --cc <others addr>
398
+
399
+
这样，新的一版补丁就又发送到邮件列表等待审阅，之后就是重复这个过程。
400
+
401
+
审阅周期
402
+
--------
403
+
404
+
因为有时邮件列表比较繁忙，您的邮件可能会被淹没，如果超过两周没有得到任何
405
+
回复，请自己回复自己，回复的内容为 Ping.
406
+
407
+
最终，如果您落实好了所有的评论，并且一段时间后没有最新的评论，您的补丁将
408
+
会先进入 Alex 的开发树，然后进入 linux-doc 开发树，最终在下个窗口打开
409
+
时合并进 mainline 仓库。
410
+
411
+
紧急处理
412
+
--------
413
+
414
+
如果您发送到邮件列表之后。发现发错了补丁集，尤其是在多个版本迭代的过程中；
415
+
自己发现了一些不妥的翻译；发送错了邮件列表……
416
+
417
+
git email默认会抄送给您一份，所以您可以切换为审阅者的角色审查自己的补丁，
418
+
并留下评论，描述有何不妥，将在下个版本怎么改，并付诸行动，重新提交，但是
419
+
注意频率，每天提交的次数不要超过两次。
420
+
421
+
新手任务
422
+
--------
423
+
对于首次参与 Linux 内核中文文档翻译的新手，建议您在 linux 目录中运行以下命令：
424
+
::
425
+
426
+
./script/checktransupdate.py -l zh_CN``
427
+
428
+
该命令会列出需要翻译或更新的英文文档。
429
+
430
+
关于详细操作说明，请参考： Documentation/translations/zh_CN/doc-guide/checktransupdate.rst\
431
+
432
+
进阶
433
+
----
434
+
435
+
希望您不只是单纯的翻译内核文档，在熟悉了一起与社区工作之后，您可以审阅其他
436
+
开发者的翻译，或者提出具有建设性的主张。与此同时，与文档对应的代码更加有趣，
437
+
而且需要完善的地方还有很多，勇敢地去探索，然后提交你的想法吧。
438
+
439
+
常见的问题
440
+
==========
441
+
442
+
Maintainer回复补丁不能正常apply
443
+
-------------------------------
444
+
445
+
这通常是因为您的补丁与邮件列表其他人的补丁产生了冲突，别人的补丁先被 apply 了，
446
+
您的补丁集就无法成功 apply 了，这需要您更新本地分支，在本地解决完冲突后再次提交。
447
+
448
+
请尽量避免冲突，不要多个人同时翻译一个目录。翻译之前可以通过 git log 查看您感
449
+
兴趣的目录近期有没有其他人翻译，如果有，请提前私信联系对方，请求其代为发送您
450
+
的补丁。如果对方未来一个月内没有提交新补丁的打算，您可以独自发送。
451
+
452
+
回信被邮件列表拒收
453
+
------------------
454
+
455
+
大部分情况下，是由于您发送了非纯文本格式的信件，请尽量避免使用 webmail，推荐
456
+
使用邮件客户端，比如 thunderbird，记得在设置中的回信配置那改为纯文本发送。
457
+
458
+
如果超过了24小时，您依旧没有在<https://lore.kernel.org/linux-doc/>发现您的邮
459
+
件，请联系您的网络管理员帮忙解决。
+10
-10
Documentation/translations/zh_CN/index.rst
+10
-10
Documentation/translations/zh_CN/index.rst
···
21
21
这是中文内核文档树的顶级目录。内核文档，就像内核本身一样，在很大程度上是一
22
22
项正在进行的工作；当我们努力将许多分散的文件整合成一个连贯的整体时尤其如此。
23
23
另外，随时欢迎您对内核文档进行改进；如果您想提供帮助，请加入vger.kernel.org
24
-
上的linux-doc邮件列表。
24
+
上的linux-doc邮件列表，并按照Documentation/translations/zh_CN/how-to.rst的
25
+
指引提交补丁。提交补丁之前请确保执行"make htmldocs”后无与翻译有关的异常输出。
25
26
26
-
顺便说下，中文文档也需要遵守内核编码风格，风格中中文和英文的主要不同就是中文
27
-
的字符标点占用两个英文字符宽度，所以，当英文要求不要超过每行100个字符时，
28
-
中文就不要超过50个字符。另外，也要注意'-'，'='等符号与相关标题的对齐。在将
29
-
补丁提交到社区之前，一定要进行必要的 ``checkpatch.pl`` 检查和编译测试，确保
30
-
在 ``make htmldocs/pdfdocs`` 中不增加新的告警，最后，安装检查你生成的
31
-
html/pdf 文件，确认它们看起来是正常的。
27
+
如何翻译内核文档
28
+
----------------
32
29
33
-
提交之前请确认你的补丁可以正常提交到中文文档维护库:
34
-
https://git.kernel.org/pub/scm/linux/kernel/git/alexs/linux.git/
35
-
如果你的补丁依赖于其他人的补丁, 可以与其他人商量后由某一个人合并提交。
30
+
翻译文档本身是一件很简单的事情，但是提交补丁需要注意一些细节，为了保证内核中文文档的高质量可持续发展，提供了一份翻译指南。
31
+
32
+
.. toctree::
33
+
:maxdepth: 1
34
+
35
+
how-to.rst
36
36
37
37
与Linux 内核社区一起工作
38
38
------------------------
+160
Documentation/translations/zh_CN/networking/index.rst
+160
Documentation/translations/zh_CN/networking/index.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
.. include:: ../disclaimer-zh_CN.rst
4
+
5
+
:Original: Documentation/networking/index.rst
6
+
7
+
:翻译:
8
+
9
+
王亚鑫 Wang Yaxin <wang.yaxin@zte.com.cn>
10
+
11
+
:校译:
12
+
13
+
网络
14
+
====
15
+
16
+
有关网络设备（netdev）开发过程的详细指南，请参考：:ref:`netdev-FAQ`
17
+
18
+
目录：
19
+
20
+
.. toctree::
21
+
:maxdepth: 1
22
+
23
+
msg_zerocopy
24
+
25
+
Todolist:
26
+
27
+
* af_xdp
28
+
* bareudp
29
+
* batman-adv
30
+
* can
31
+
* can_ucan_protocol
32
+
* device_drivers/index
33
+
* diagnostic/index
34
+
* dsa/index
35
+
* devlink/index
36
+
* caif/index
37
+
* ethtool-netlink
38
+
* ieee802154
39
+
* iso15765-2
40
+
* j1939
41
+
* kapi
42
+
* failover
43
+
* net_dim
44
+
* net_failover
45
+
* page_pool
46
+
* phy
47
+
* sfp-phylink
48
+
* alias
49
+
* bridge
50
+
* snmp_counter
51
+
* checksum-offloads
52
+
* segmentation-offloads
53
+
* scaling
54
+
* tls
55
+
* tls-offload
56
+
* tls-handshake
57
+
* nfc
58
+
* 6lowpan
59
+
* 6pack
60
+
* arcnet-hardware
61
+
* arcnet
62
+
* atm
63
+
* ax25
64
+
* bonding
65
+
* cdc_mbim
66
+
* dccp
67
+
* dctcp
68
+
* devmem
69
+
* dns_resolver
70
+
* driver
71
+
* eql
72
+
* fib_trie
73
+
* filter
74
+
* generic-hdlc
75
+
* generic_netlink
76
+
* netlink_spec/index
77
+
* gen_stats
78
+
* gtp
79
+
* ila
80
+
* ioam6-sysctl
81
+
* ip_dynaddr
82
+
* ipsec
83
+
* ip-sysctl
84
+
* ipv6
85
+
* ipvlan
86
+
* ipvs-sysctl
87
+
* kcm
88
+
* l2tp
89
+
* lapb-module
90
+
* mac80211-injection
91
+
* mctp
92
+
* mpls-sysctl
93
+
* mptcp
94
+
* mptcp-sysctl
95
+
* multiqueue
96
+
* multi-pf-netdev
97
+
* napi
98
+
* net_cachelines/index
99
+
* netconsole
100
+
* netdev-features
101
+
* netdevices
102
+
* netfilter-sysctl
103
+
* netif-msg
104
+
* netmem
105
+
* nexthop-group-resilient
106
+
* nf_conntrack-sysctl
107
+
* nf_flowtable
108
+
* oa-tc6-framework
109
+
* openvswitch
110
+
* operstates
111
+
* packet_mmap
112
+
* phonet
113
+
* phy-link-topology
114
+
* pktgen
115
+
* plip
116
+
* ppp_generic
117
+
* proc_net_tcp
118
+
* pse-pd/index
119
+
* radiotap-headers
120
+
* rds
121
+
* regulatory
122
+
* representors
123
+
* rxrpc
124
+
* sctp
125
+
* secid
126
+
* seg6-sysctl
127
+
* skbuff
128
+
* smc-sysctl
129
+
* sriov
130
+
* statistics
131
+
* strparser
132
+
* switchdev
133
+
* sysfs-tagging
134
+
* tc-actions-env-rules
135
+
* tc-queue-filters
136
+
* tcp_ao
137
+
* tcp-thin
138
+
* team
139
+
* timestamping
140
+
* tipc
141
+
* tproxy
142
+
* tuntap
143
+
* udplite
144
+
* vrf
145
+
* vxlan
146
+
* x25
147
+
* x25-iface
148
+
* xfrm_device
149
+
* xfrm_proc
150
+
* xfrm_sync
151
+
* xfrm_sysctl
152
+
* xdp-rx-metadata
153
+
* xsk-tx-metadata
154
+
155
+
.. only:: subproject and html
156
+
157
+
Indices
158
+
=======
159
+
160
+
* :ref:`genindex`
+223
Documentation/translations/zh_CN/networking/msg_zerocopy.rst
+223
Documentation/translations/zh_CN/networking/msg_zerocopy.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
.. include:: ../disclaimer-zh_CN.rst
4
+
5
+
:Original: Documentation/networking/msg_zerocopy.rst
6
+
7
+
:翻译:
8
+
9
+
王亚鑫 Wang Yaxin <wang.yaxin@zte.com.cn>
10
+
11
+
:校译:
12
+
13
+
- 徐鑫 xu xin <xu.xin16@zte.com.cn>
14
+
- 何配林 He Peilin <he.peilin@zte.com.cn>
15
+
16
+
============
17
+
MSG_ZEROCOPY
18
+
============
19
+
20
+
简介
21
+
====
22
+
23
+
MSG_ZEROCOPY 标志用于启用套接字发送调用的免拷贝功能。该功能目前适用于 TCP、UDP 和 VSOCK
24
+
（使用 virtio 传输）套接字。
25
+
26
+
机遇与注意事项
27
+
--------------
28
+
29
+
在用户进程与内核之间拷贝大型缓冲区可能会消耗大量资源。Linux 支持多种免拷贝的接口，如sendfile
30
+
和 splice。MSG_ZEROCOPY 标志将底层的拷贝避免机制扩展到了常见的套接字发送调用中。
31
+
32
+
免拷贝并非毫无代价。在实现上，它通过页面固定（page pinning）将按字节拷贝的成本替换为页面统计
33
+
（page accounting）和完成通知的开销。因此，MSG_ZEROCOPY 通常仅在写入量超过大约 10 KB 时
34
+
才有效。
35
+
36
+
页面固定还会改变系统调用的语义。它会暂时在进程和网络堆栈之间共享缓冲区。与拷贝不同，进程在系统
37
+
调用返回后不能立即覆盖缓冲区，否则可能会修改正在传输中的数据。内核的完整性不会受到影响，但有缺
38
+
陷的程序可能会破坏自己的数据流。
39
+
40
+
当内核返回数据可以安全修改的通知时，进程才可以修改数据。因此，将现有应用程序转换为使用
41
+
MSG_ZEROCOPY 并非总是像简单地传递该标志那样容易。
42
+
43
+
更多信息
44
+
--------
45
+
46
+
本文档的大部分内容是来自于 netdev 2.1 上发表的一篇长篇论文。如需更深入的信息，请参阅该论文和
47
+
演讲，或者浏览 LWN.net 上的精彩报道，也可以直接阅读源码。
48
+
49
+
论文、幻灯片、视频：
50
+
https://netdevconf.org/2.1/session.html?debruijn
51
+
52
+
LWN 文章：
53
+
https://lwn.net/Articles/726917/
54
+
55
+
补丁集：
56
+
[PATCH net-next v4 0/9] socket sendmsg MSG_ZEROCOPY
57
+
https://lore.kernel.org/netdev/20170803202945.70750-1-willemdebruijn.kernel@gmail.com
58
+
59
+
接口
60
+
====
61
+
62
+
传递 MSG_ZEROCOPY 标志是启用免拷贝功能的最明显步骤，但并非唯一的步骤。
63
+
64
+
套接字设置
65
+
----------
66
+
67
+
当应用程序向 send 系统调用传递未定义的标志时，内核通常会宽容对待。默认情况下，它会简单地忽略
68
+
这些标志。为了避免为那些偶然传递此标志的遗留进程启用免拷贝模式，进程必须首先通过设置套接字选项
69
+
来表明意图：
70
+
71
+
::
72
+
73
+
if (setsockopt(fd, SOL_SOCKET, SO_ZEROCOPY, &one, sizeof(one)))
74
+
error(1, errno, "setsockopt zerocopy");
75
+
76
+
传输
77
+
----
78
+
79
+
对 send（或 sendto、sendmsg、sendmmsg）本身的改动非常简单。只需传递新的标志即可。
80
+
81
+
::
82
+
83
+
ret = send(fd, buf, sizeof(buf), MSG_ZEROCOPY);
84
+
85
+
如果零拷贝操作失败，将返回 -1，并设置 errno 为 ENOBUFS。这种情况可能发生在套接字超出其
86
+
optmem 限制，或者用户超出其锁定页面的 ulimit 时。
87
+
88
+
混合使用免拷贝和拷贝
89
+
~~~~~~~~~~~~~~~~~~~~
90
+
91
+
许多工作负载同时包含大型和小型缓冲区。由于对于小数据包来说，免拷贝的成本高于拷贝，因此该
92
+
功能是通过标志实现的。带有标志的调用和没有标志的调用可以安全地混合使用。
93
+
94
+
通知
95
+
----
96
+
97
+
当内核认为可以安全地重用之前传递的缓冲区时，它必须通知进程。完成通知在套接字的错误队列上
98
+
排队，类似于传输时间戳接口。
99
+
100
+
通知本身是一个简单的标量值。每个套接字都维护一个内部的无符号 32 位计数器。每次带有
101
+
MSG_ZEROCOPY 标志的 send 调用成功发送数据时，计数器都会增加。如果调用失败或长度为零，
102
+
则计数器不会增加。该计数器统计系统调用的调用次数，而不是字节数。在 UINT_MAX 次调用后，
103
+
计数器会循环。
104
+
105
+
通知接收
106
+
~~~~~~~~
107
+
108
+
下面的代码片段展示了 API 的使用。在最简单的情况下，每次 send 系统调用后，都会对错误队列
109
+
进行轮询和 recvmsg 调用。
110
+
111
+
从错误队列读取始终是一个非阻塞操作。poll 调用用于阻塞，直到出现错误。它会在其输出标志中
112
+
设置 POLLERR。该标志不需要在 events 字段中设置。错误会无条件地发出信号。
113
+
114
+
::
115
+
116
+
pfd.fd = fd;
117
+
pfd.events = 0;
118
+
if (poll(&pfd, 1, -1) != 1 || pfd.revents & POLLERR == 0)
119
+
error(1, errno, "poll");
120
+
121
+
ret = recvmsg(fd, &msg, MSG_ERRQUEUE);
122
+
if (ret == -1)
123
+
error(1, errno, "recvmsg");
124
+
125
+
read_notification(msg);
126
+
127
+
128
+
这个示例仅用于演示目的。在实际应用中，不等待通知，而是每隔几次 send 调用就进行一次非阻塞
129
+
读取会更高效。
130
+
131
+
零拷贝通知可以与其他套接字操作乱序处理。通常，拥有错误队列套接字会阻塞其他操作，直到错误
132
+
被读取。然而，零拷贝通知具有零错误代码，因此不会阻塞 send 和 recv 调用。
133
+
134
+
通知批处理
135
+
~~~~~~~~~~~~
136
+
137
+
可以使用 recvmmsg 调用来一次性读取多个未决的数据包。这通常不是必需的。在每条消息中，内核
138
+
返回的不是一个单一的值，而是一个范围。当错误队列上有一个通知正在等待接收时，它会将连续的通
139
+
知合并起来。
140
+
141
+
当一个新的通知即将被排队时，它会检查队列尾部的通知的范围是否可以扩展以包含新的值。如果是这
142
+
样，它会丢弃新的通知数据包，并增大未处理通知的范围上限值。
143
+
144
+
对于按顺序确认数据的协议（如 TCP），每个通知都可以合并到前一个通知中，因此在任何时候在等待
145
+
的通知都不会超过一个。
146
+
147
+
有序交付是常见的情况，但不能保证。在重传和套接字拆除时，通知可能会乱序到达。
148
+
149
+
通知解析
150
+
~~~~~~~~
151
+
152
+
下面的代码片段演示了如何解析控制消息：前面代码片段中的 read_notification() 调用。通知
153
+
以标准错误格式 sock_extended_err 编码。
154
+
155
+
控制数据中的级别和类型字段是协议族特定的，对于 TCP 或 UDP 套接字，分别为 IP_RECVERR 或
156
+
IPV6_RECVERR。对于 VSOCK 套接字，cmsg_level 为 SOL_VSOCK，cmsg_type 为 VSOCK_RECVERR。
157
+
158
+
错误来源是新的类型 SO_EE_ORIGIN_ZEROCOPY。如前所述，ee_errno 为零，以避免在套接字上
159
+
阻塞地读取和写入系统调用。
160
+
161
+
32 位通知范围编码为 [ee_info, ee_data]。这个范围是包含边界值的。除了下面讨论的 ee_code
162
+
字段外，结构中的其他字段应被视为未定义的。
163
+
164
+
::
165
+
166
+
struct sock_extended_err *serr;
167
+
struct cmsghdr *cm;
168
+
169
+
cm = CMSG_FIRSTHDR(msg);
170
+
if (cm->cmsg_level != SOL_IP &&
171
+
cm->cmsg_type != IP_RECVERR)
172
+
error(1, 0, "cmsg");
173
+
174
+
serr = (void *) CMSG_DATA(cm);
175
+
if (serr->ee_errno != 0 ||
176
+
serr->ee_origin != SO_EE_ORIGIN_ZEROCOPY)
177
+
error(1, 0, "serr");
178
+
179
+
printf("completed: %u..%u\n", serr->ee_info, serr->ee_data);
180
+
181
+
182
+
延迟拷贝
183
+
~~~~~~~~
184
+
185
+
传递标志 MSG_ZEROCOPY 是向内核发出的一个提示，让内核采用免拷贝的策略，同时也是一种约
186
+
定，即内核会对完成通知进行排队处理。但这并不保证拷贝操作一定会被省略。
187
+
188
+
拷贝避免不总是适用的。不支持分散/聚集 I/O 的设备无法发送由内核生成的协议头加上零拷贝用户
189
+
数据组成的数据包。数据包可能需要在协议栈底层转换为一份私有数据副本，例如用于计算校验和。
190
+
191
+
在所有这些情况下，当内核释放对共享页面的持有权时，它会返回一个完成通知。该通知可能在（已
192
+
拷贝）数据完全传输之前到达。因此。零拷贝完成通知并不是传输完成通知。
193
+
194
+
如果数据不在缓存中，延迟拷贝可能会比立即在系统调用中拷贝开销更大。进程还会因通知处理而产
195
+
生成本，但却没有带来任何好处。因此，内核会在返回时通过在 ee_code 字段中设置标志
196
+
SO_EE_CODE_ZEROCOPY_COPIED 来指示数据是否以拷贝的方式完成。进程可以利用这个信号，在
197
+
同一套接字上后续的请求中停止传递 MSG_ZEROCOPY 标志。
198
+
199
+
实现
200
+
====
201
+
202
+
环回
203
+
----
204
+
205
+
对于 TCP 和 UDP：
206
+
如果接收进程不读取其套接字，发送到本地套接字的数据可能会无限期排队。无限期的通知延迟是不
207
+
可接受的。因此，所有使用 MSG_ZEROCOPY 生成并环回到本地套接字的数据包都将产生延迟拷贝。
208
+
这包括环回到数据包套接字（例如，tcpdump）和 tun 设备。
209
+
210
+
对于 VSOCK：
211
+
发送到本地套接字的数据路径与非本地套接字相同。
212
+
213
+
测试
214
+
====
215
+
216
+
更具体的示例代码可以在内核源码的 tools/testing/selftests/net/msg_zerocopy.c 中找到。
217
+
218
+
要留意环回约束问题。该测试可以在一对主机之间进行。但如果是在本地的一对进程之间运行，例如当使用
219
+
msg_zerocopy.sh 脚本在跨命名空间的虚拟以太网（veth）对之间运行时，测试将不会显示出任何性能
220
+
提升。为了便于测试，可以通过让 skb_orphan_frags_rx 与 skb_orphan_frags 相同，来暂时放宽
221
+
环回限制。
222
+
223
+
对于 VSOCK 类型套接字的示例可以在 tools/testing/vsock/vsock_test_zerocopy.c 中找到。
+1
-1
MAINTAINERS
+1
-1
MAINTAINERS
···
5502
5502
5503
5503
CHINESE DOCUMENTATION
5504
5504
M: Alex Shi <alexs@kernel.org>
5505
-
M: Yanteng Si <siyanteng@loongson.cn>
5505
+
M: Yanteng Si <si.yanteng@linux.dev>
5506
5506
R: Dongliang Mu <dzm91@hust.edu.cn>
5507
5507
T: git git://git.kernel.org/pub/scm/linux/kernel/git/alexs/linux.git
5508
5508
S: Maintained