[PATCH 0/3] add three core api docs

[PATCH 0/3] add three core api docs

[Yanteng Si]

This patch add three core api docs.


Yanteng Si (3):
  docs/zh_CN: add core-api kernel-api.rst translation
  docs/zh_CN: add core-api printk-basics.rst translation
  docs/zh_CN: add core-api printk-formats.rst translation

 .../zh_CN/core-api/kernel-api.rst             | 433 +++++++++++++
 .../zh_CN/core-api/printk-basics.rst          | 118 ++++
 .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
 3 files changed, 1128 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/core-api/kernel-api.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/printk-basics.rst
 create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst

-- 
2.27.0

[PATCH 1/3] docs/zh_CN: add core-api kernel-api.rst translation

[Yanteng Si]

This patch translates Documentation/core-api/kernel-api.rst into Chinese.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 .../zh_CN/core-api/kernel-api.rst             | 433 ++++++++++++++++++
 1 file changed, 433 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/core-api/kernel-api.rst

diff --git a/Documentation/translations/zh_CN/core-api/kernel-api.rst b/Documentation/translations/zh_CN/core-api/kernel-api.rst
new file mode 100644
index 000000000000..fcd1d6392960
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/kernel-api.rst
@@ -0,0 +1,433 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: :doc:`../../../core-api/kernel-api`
+:Translator: Yanteng Si <siyanteng@loongson.cn>
+
+.. _cn_kernel-api.rst:
+
+
+============
+Linux内核API
+============
+
+
+列表管理函数
+============
+
+Todolist:
+
+   :internal:
+
+基本的C库函数
+=============
+
+在编写驱动程序时，一般不能使用C库中的例程。有些被认为是有用的函数，它
+们在下面被列出。这些函数的行为可能会与ANSI定义的函数略有不同，这些偏差
+会在文中注明。
+
+字符串转换
+----------
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :functions: kstrtol
+
+Todolist:
+
+   :functions: kstrtoul
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+字符串处理
+----------
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :functions: kstrdup kstrdup_const kstrndup kmemdup kmemdup_nul memdup_user
+               vmemdup_user strndup_user memdup_user_nul
+
+基本的内核库函数
+================
+
+Linux内核提供了很多基本的公用函数。
+
+位运算
+------
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :internal:
+
+位图运算
+--------
+
+Todolist:
+
+   :doc: 位图简介
+
+Todolist:
+
+   :doc: 声明位图
+
+Todolist:
+
+   :doc: 位图概述
+
+Todolist:
+
+   :doc: 位图位操作
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :internal:
+
+命令行解析
+----------
+
+Todolist:
+
+   :export:
+
+排序
+----
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+文本检索
+--------
+
+Todolist:
+
+   :doc: ts_intro
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :functions: textsearch_find textsearch_next \
+               textsearch_get_pattern textsearch_get_pattern_len
+
+Linux中的CRC和数学函数
+======================
+
+CRC函数
+-------
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+基数为2的对数和幂函数
+---------------------
+
+Todolist:
+
+   :internal:
+
+整数幂函数
+----------
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+除法函数
+--------
+
+Todolist:
+
+   :functions: do_div
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :functions: div_s64_rem div64_u64_rem div64_u64 div64_s64
+
+Todolist:
+
+   :export:
+
+UUID/GUID
+---------
+
+Todolist:
+
+   :export:
+
+核心IPC设备
+===========
+
+IPC公用程序
+-----------
+
+Todolist:
+
+   :internal:
+
+FIFO 缓冲区
+===========
+
+kfifo接口
+---------
+
+Todolist:
+
+   :internal:
+
+转发接口支持
+============
+
+转发接口支持旨在为工具和设备提供一种有效的机制，将大量数据从内核空间
+转发到用户空间。
+
+转发接口
+--------
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :internal:
+
+模块支持
+========
+
+模块加载
+--------
+
+Todolist:
+
+   :export:
+
+模块接口支持
+------------
+
+更多信息请参考文件kernel/module.c。
+
+硬件接口
+========
+
+DMA通道
+-------
+
+Todolist:
+
+   :export:
+
+资源管理
+--------
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :export:
+
+MTRR处理
+--------
+
+Todolist:
+
+   :export:
+
+安全框架
+========
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :export:
+
+审计接口
+========
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :internal:
+
+记账框架
+========
+
+Todolist:
+
+   :internal:
+
+块设备
+======
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :export:
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :internal:
+
+Todolist:
+
+   :export:
+
+字符设备
+========
+
+Todolist:
+
+   :export:
+
+时钟框架
+========
+
+时钟框架定义了编程接口，以支持系统时钟树的软件管理。该框架广泛用于系统级芯片（SOC）平
+台，以支持电源管理和各种可能需要自定义时钟速率的设备。请注意，这些 “时钟”与计时或实
+时时钟(RTC)无关，它们都有单独的框架。这些:c:type: `struct clk <clk>` 实例可用于管
+理例如96 MHz信号，该信号用于将位移入和移出外设或总线，或以其他方式触发系统硬件中的同
+步状态机转换。
+
+通过明确的软件时钟门控来支持电源管理：未使用的时钟被禁用，因此系统不会因为改变不在使用
+中的晶体管的状态而浪费电源。在某些系统中，这可能是由硬件时钟门控支持的，其中时钟被门控
+而不在软件中被禁用。芯片的部分，在供电但没有时钟的情况下，可能会保留其最后的状态。这种
+低功耗状态通常被称为*保留模式*。这种模式仍然会产生漏电流，特别是在电路几何结构较细的情
+况下，但对于CMOS电路来说，电源主要是通过时钟状态变化来使用的。
+
+电源感知驱动程序只有在其管理的设备处于活动使用状态时才会启用时钟。此外，系统睡眠状态通
+常根据哪些时钟域处于活动状态而有所不同：“待机”状态可能允许从多个活动域中唤醒，而
+"mem"（暂停到RAM）状态可能需要更全面地关闭来自高速PLL和振荡器的时钟，从而限制了可能
+的唤醒事件源的数量。驱动器的暂停方法可能需要注意目标睡眠状态的系统特定时钟约束。
+
+一些平台支持可编程时钟发生器。这些可以被各种外部芯片使用，如其他CPU、多媒体编解码器以
+及对接口时钟有严格要求的设备。
+
+Todolist:
+
+   :internal:
+
+同步原语
+========
+
+读/写同步机制(RCU)
+------------------
+
+Todolist:
\ No newline at end of file
-- 
2.27.0

[PATCH 2/3] docs/zh_CN: add core-api printk-basics.rst translation

[Yanteng Si]

This patch translates Documentation/core-api/printk-basics.rst into Chinese.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 .../zh_CN/core-api/printk-basics.rst          | 118 ++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/core-api/printk-basics.rst

diff --git a/Documentation/translations/zh_CN/core-api/printk-basics.rst b/Documentation/translations/zh_CN/core-api/printk-basics.rst
new file mode 100644
index 000000000000..056ca88604b2
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/printk-basics.rst
@@ -0,0 +1,118 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: :doc:`../../../core-api/printk-basics`
+:Translator: Yanteng Si <siyanteng@loongson.cn>
+
+.. _cn_printk-basics.rst:
+
+
+==================
+使用printk记录信息
+==================
+
+printk()是Linux内核中最广为人知的函数之一。它是我们打印信息的标准工具，通常也是追踪和调试
+的最基本方法。如果你熟悉printf(3)，你就能够知道printk()是基于它的，尽管它在功能上有一些不
+同之处。:
+
+  - printk() 信息可以指定日志级别。
+
+  - 格式字符串虽然与C99基本兼容，但并不遵循完全相同的规范。它有一些扩展和一些限制（没
+    有 ``%n`` 或浮点转换指定符）。参见:ref: `如何正确地获得printk格式指定符<printk-specifiers>` 。
+
+    所有的printk()消息都会被打印到内核日志缓冲区，这是一个通过/dev/kmsg输出到用户空间的环
+    形缓冲区。读取它的通常方法是使用 ``dmesg`` 。
+
+printk()的用法通常是这样的
+
+::
+
+  printk(KERN_INFO "Message: %s\n", arg);
+
+其中 ``KERN_INFO`` 是日志级别（注意，它与格式字符串连在一起，日志级别不是一个单独的参数）。
+可用的日志级别是：
+
+
++----------------+--------+-----------------------------------------------+
+| 名称           | 字符串 |  别名函数                                     |
++================+========+===============================================+
+| KERN_EMERG     | "0"    | pr_emerg()                                    |
++----------------+--------+-----------------------------------------------+
+| KERN_ALERT     | "1"    | pr_alert()                                    |
++----------------+--------+-----------------------------------------------+
+| KERN_CRIT      | "2"    | pr_crit()                                     |
++----------------+--------+-----------------------------------------------+
+| KERN_ERR       | "3"    | pr_err()                                      |
++----------------+--------+-----------------------------------------------+
+| KERN_WARNING   | "4"    | pr_warn()                                     |
++----------------+--------+-----------------------------------------------+
+| KERN_NOTICE    | "5"    | pr_notice()                                   |
++----------------+--------+-----------------------------------------------+
+| KERN_INFO      | "6"    | pr_info()                                     |
++----------------+--------+-----------------------------------------------+
+| KERN_DEBUG     | "7"    | pr_debug() and pr_devel() 如果定义了DEBUG     |
++----------------+--------+-----------------------------------------------+
+| KERN_DEFAULT   | ""     |                                               |
++----------------+--------+-----------------------------------------------+
+| KERN_CONT      | "c"    | pr_cont()                                     |
++----------------+--------+-----------------------------------------------+
+
+
+日志级别指定了一条消息的重要性。内核根据日志级别和当前 *console_loglevel* （一个内核变量）决
+定是否立即显示消息（将其打印到当前控制台）。如果消息的优先级比 *console_loglevel* 高（日志级
+别值较低），消息将被打印到控制台。
+
+如果省略了日志级别，则以 ``KERN_DEFAULT`` 级别打印消息。
+
+你可以用以下方法检查当前的 *console_loglevel* 。::
+
+  $ cat /proc/sys/kernel/printk
+  4        4        1        7
+
+结果显示了 *current*, *default*, *minimum* and *boot-time-default* 日志级别
+
+要改变当前的 console_loglevel，只需在 ``/proc/sys/kernel/printk`` 中写入所需的
+级别。例如，要打印所有的消息到控制台上::
+
+  # echo 8 > /proc/sys/kernel/printk
+
+另一种方式，使用 ``dmesg``
+
+::
+
+  # dmesg -n 5
+
+设置 console_loglevel 打印 KERN_WARNING (4) 或更严重的信息到控制台。更多信息参
+见 ``dmesg(1)`` 。
+
+作为printk()的替代方案，你可以使用 ``pr_*()`` 来记录日志。这个系列的宏在宏名中嵌入
+了日志级别。例如
+
+::
+
+  pr_info("Info message no. %d\n", msg_num);
+
+打印 ``KERN_INFO`` 信息。
+
+除了比等效的printk()调用更简洁之外，它们还可以通过pr_fmt()宏为格式字符串使用一个通用
+的定义。例如，在源文件的顶部（在任何 " ``#include`` " 指令之前）定义这样的内容。::
+
+  #define pr_fmt(fmt) "%s:%s: " fmt, KBUILD_MODNAME, __func__
+
+会在该文件中的每一条 pr_*() 消息前加上发起该消息的模块和函数名称。
+
+为了调试的目的，还有两个有条件编译的宏：
+pr_debug()和pr_devel()，除非定义了 ``DEBUG`` (或者在pr_debug()的情况下定义了
+``CONFIG_DYNAMIC_DEBUG`` )，否则它们会被编译。
+
+
+函数接口
+========
+
+Todolist:
+
+   :functions: printk
+
+
+   :functions: pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
+      pr_fmt pr_debug pr_devel pr_cont
-- 
2.27.0

[PATCH 3/3] docs/zh_CN: add core-api printk-formats.rst translation

[Yanteng Si]

This patch translates Documentation/core-api/printk-formats.rst into Chinese.

Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
---
 .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
 1 file changed, 577 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst

diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst
new file mode 100644
index 000000000000..8552bbb3c797
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst
@@ -0,0 +1,577 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: :doc:`../../../core-api/printk-formats`
+:Translator: Yanteng Si <siyanteng@loongson.cn>
+
+.. _cn_printk-formats.rst:
+
+
+==============================
+如何获得正确的printk格式说明符
+==============================
+
+.. _printk-specifiers:
+
+:作者: Randy Dunlap <rdunlap@infradead.org>
+:作者: Andrew Murray <amurray@mpc-data.co.uk>
+
+
+整数类型
+========
+
+::
+
+	        如果变量是Type，则使用printk格式说明符器。
+	        -----------------------------------------
+		char			%d or %x
+		unsigned char		%u or %x
+		short int		%d or %x
+		unsigned short int	%u or %x
+		int			%d or %x
+		unsigned int		%u or %x
+		long			%ld or %lx
+		unsigned long		%lu or %lx
+		long long		%lld or %llx
+		unsigned long long	%llu or %llx
+		size_t			%zu or %zx
+		ssize_t			%zd or %zx
+		s8			%d or %x
+		u8			%u or %x
+		s16			%d or %x
+		u16			%u or %x
+		s32			%d or %x
+		u32			%u or %x
+		s64			%lld or %llx
+		u64			%llu or %llx
+
+
+如果 <type> 的大小依赖于配置选项 (例如 sector_t, blkcnt_t) 或其大小依赖于架构
+(例如 tcflag_t)，则使用其可能的最大类型的格式说明符并显式强制转换为它。
+
+例如
+
+::
+
+	printk("test: sector number/total blocks: %llu/%llu\n",
+		(unsigned long long)sector, (unsigned long long)blockcount);
+
+提醒：sizeof()返回类型size_t。
+
+内核的printf不支持%n。浮点格式(%e, %f, %g, %a)也不被识别，原因很明显。使用任何不
+支持的说明符或长度限定符都会导致一个WARN和vsnprintf()的提前返回。
+
+指针类型
+========
+
+一个原始指针值可以用%p打印，它将在打印前对地址进行哈希处理。内核也支持扩展说明符来打印
+不同类型的指针。
+
+一些扩展说明符会打印给定地址上的数据，而不是打印地址本身。在这种情况下，以下错误信息可能
+会被打印出来，而不是无法访问的信息。::
+
+	(null)	 data on plain NULL address
+	(efault) data on invalid address
+	(einval) invalid data on a valid address
+
+简单的指针
+----------
+
+::
+
+	%p	abcdef12 or 00000000abcdef12
+
+没有指定扩展名的指针(即未加修饰的%p)会被哈希以防止泄露内核内存布局的信息。这样做的另一个
+好处是提供一个唯一的标识符。在64位机器上，前32位被清零。内核将打印 ``(ptrval)`` 直到它
+收集到足够的熵。如果你 *真* 想知道地址请看下面的%px。
+
+错误指针
+--------
+
+::
+
+	%pe	-ENOSPC
+
+用于打印错误指针(即IS_ERR()为真的指针)的符号错误名。不知道符号名的错误值会以十进制打印，
+而作为%pe参数传递的非ERR_PTR会被视为普通的%p。
+
+符号/函数指针
+-------------
+
+::
+
+	%pS	versatile_init+0x0/0x110
+	%ps	versatile_init
+	%pSR	versatile_init+0x9/0x110
+		(with __builtin_extract_return_addr() translation)
+	%pB	prev_fn_of_versatile_init+0x88/0x88
+
+
+``S`` 和 ``s`` 说明符用于打印符号格式的指针。它们的结果是符号名称带有(S)或不带有(s)偏移
+量。如果禁用KALLSYMS，则打印符号地址。
+
+``B`` 指定符的结果是带有偏移量的符号名，在打印堆栈回溯时应该使用。说明符将考虑编译器优化
+的影响，当使用尾部调用并使用noreturn GCC属性标记时，可能会发生这种优化。
+
+Probed Pointers from BPF / tracing
+----------------------------------
+
+::
+
+	%pks	kernel string
+	%pus	user string
+
+``k`` 和 ``u`` 指定符用于打印来自内核内存(k)或用户内存(u)的先前探测的内存。后面的 ``s`` 指
+定符的结果是打印一个字符串。对于直接在常规的vsnprintf()中使用时，(k)和(u)注释被忽略，但是，当
+在BPF的bpf_trace_printk()之外使用时，它会读取它所指向的内存，不会出现错误。
+
+内核指针
+--------
+
+::
+
+	%pK	01234567 or 0123456789abcdef
+
+用于打印应该对非特权用户隐藏的内核指针。%pK的行为取决于kptr_restrict sysctl--详见
+文档/admin-guide/sysctl/kernel.rst。
+
+未经修改的地址
+--------------
+
+::
+
+	%px	01234567 or 0123456789abcdef
+
+对于打印指针，当你 *真的* 想打印地址时。在用%px打印指针之前，请考虑你是否泄露了内核内
+存布局的敏感信息。%px在功能上等同于%lx（或%lu）。%px是首选，因为它更具有唯一的grep能
+力。如果将来我们需要修改内核处理打印指针的方式，我们将能更好地找到调用点。
+
+指针差异
+--------
+
+::
+
+	%td	2560
+	%tx	a00
+
+为了打印指针的差异，使用ptrdiff_t的%t修饰符。
+
+例如::
+
+	printk("test: difference between pointers: %td\n", ptr2 - ptr1);
+
+资源（Resources）结构体
+-----------------------
+
+::
+
+	%pr	[mem 0x60000000-0x6fffffff flags 0x2200] or
+		[mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
+	%pR	[mem 0x60000000-0x6fffffff pref] or
+		[mem 0x0000000060000000-0x000000006fffffff pref]
+
+用于打印结构资源。 ``R`` 和 ``r`` 说明符的结果是打印出的资源带有(R)或不带有(r)解码标志
+成员。
+
+通过引用传递。
+
+物理地址类型 phys_addr_t
+------------------------
+
+::
+
+	%pa[p]	0x01234567 or 0x0123456789abcdef
+
+用于打印phys_addr_t类型(以及它的衍生物，如resource_size_t)，该类型可以根据构建选项而
+变化，无论CPU数据路径的宽度如何。
+
+通过引用传递。
+
+DMA地址类型dma_addr_t
+---------------------
+
+::
+
+	%pad	0x01234567 or 0x0123456789abcdef
+
+用于打印dma_addr_t类型，该类型可以根据构建选项而变化，而不考虑CPU数据路径的宽度。
+
+通过引用传递。
+
+原始缓冲区为转义字符串
+----------------------
+
+::
+
+	%*pE[achnops]
+
+用于将原始缓冲区打印成转义字符串。对于以下缓冲区
+
+::
+
+		1b 62 20 5c 43 07 22 90 0d 5d
+
+几个例子显示了如何进行转换（不包括周围的引号）。
+
+::
+
+		%*pE		"\eb \C\a"\220\r]"
+		%*pEhp		"\x1bb \C\x07"\x90\x0d]"
+		%*pEa		"\e\142\040\\\103\a\042\220\r\135"
+
+转换规则是根据可选的标志组合来应用的(详见:c:func: `string_escape_mem` 内核文档):
+
+	- a - ESCAPE_ANY
+	- c - ESCAPE_SPECIAL
+	- h - ESCAPE_HEX
+	- n - ESCAPE_NULL
+	- o - ESCAPE_OCTAL
+	- p - ESCAPE_NP
+	- s - ESCAPE_SPACE
+
+默认情况下，使用 ESCAPE_ANY_NP。
+
+ESCAPE_ANY_NP是许多情况下的明智选择，特别是对于打印SSID。
+	
+如果字段宽度被省略，那么将只转义1个字节。
+
+原始缓冲区为十六进制字符串
+--------------------------
+
+::
+
+	%*ph	00 01 02  ...  3f
+	%*phC	00:01:02: ... :3f
+	%*phD	00-01-02- ... -3f
+	%*phN	000102 ... 3f
+
+对于打印小的缓冲区（最长64个字节），可以用一定的分隔符作为一个
+十六进制字符串。对于较大的缓冲区，可以考虑使用
+:c:func: `print_hex_dump` 。
+
+MAC/FDDI地址
+------------
+
+::
+
+	%pM	00:01:02:03:04:05
+	%pMR	05:04:03:02:01:00
+	%pMF	00-01-02-03-04-05
+	%pm	000102030405
+	%pmR	050403020100
+
+用于打印以十六进制表示的6字节MAC/FDDI地址。 ``M`` 和 ``m`` 说明符导致打印的
+地址有(M)或没有(m)字节分隔符。默认的字节分隔符是冒号（：）。
+
+对于FDDI地址，可以在 ``M`` 说明符之后使用 ``F`` 说明，以使用破折号(-)分隔符
+代替默认的分隔符。
+	
+对于蓝牙地址， ``R`` 说明符应使用在 ``M`` 说明符之后，以使用反转的字节顺序，适
+合于以小尾端顺序的蓝牙地址的肉眼可见的解析。
+	
+通过引用传递。
+
+IPv4地址
+--------
+
+::
+
+	%pI4	1.2.3.4
+	%pi4	001.002.003.004
+	%p[Ii]4[hnbl]
+
+用于打印IPv4点分隔的十进制地址。 ``I4`` 和 ``i4`` 说明符的结果是打印的地址
+有(i4)或没有(I4)前导零。
+
+附加的 ``h`` 、 ``n`` 、 ``b`` 和 ``l`` 说明符分别用于指定主机、网络、大
+尾端或小尾端地址。如果没有提供说明符，则使用默认的网络/大尾端顺序。
+	
+通过引用传递。
+
+IPv6 地址
+---------
+
+::
+
+	%pI6	0001:0002:0003:0004:0005:0006:0007:0008
+	%pi6	00010002000300040005000600070008
+	%pI6c	1:2:3:4:5:6:7:8
+
+用于打印IPv6网络顺序的16位十六进制地址。 ``I6`` 和 ``i6`` 说明符的结果是
+打印的地址有(I6)或没有(i6)分号。始终使用前导零。
+
+额外的 ``c`` 说明符可与 ``I`` 说明符一起使用，以打印压缩的IPv6地址，如下
+所述
+https://tools.ietf.org/html/rfc5952 
+	
+通过引用传递。
+
+IPv4/IPv6地址(generic, with port, flowinfo, scope)
+--------------------------------------------------
+
+::
+
+	%pIS	1.2.3.4		or 0001:0002:0003:0004:0005:0006:0007:0008
+	%piS	001.002.003.004	or 00010002000300040005000600070008
+	%pISc	1.2.3.4		or 1:2:3:4:5:6:7:8
+	%pISpc	1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345
+	%p[Ii]S[pfschnbl]
+
+用于打印一个IP地址，不需要区分它的类型是AF_INET还是AF_INET6。一个指向有效结构
+体sockaddr的指针，通过 ``IS`` 或 ``IS`` 指定，可以传递给这个格式说明符。
+
+附加的 ``p`` 、  ``f`` 和 ``s`` 说明符用于指定port(IPv4, IPv6)、
+flowinfo (IPv6)和sope(IPv6)。port有一个 ``:`` 前缀，flowinfo是 ``/`` 和
+范围是 ``%`` ，每个后面都跟着实际的值。
+	
+对于IPv6地址，如果指定了额外的指定符 ``c`` ，则使用
+https://tools.ietf.org/html/rfc5952描述的压缩IPv6地址。
+如https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
+所建议的，IPv6地址由'['，']'包围，以防止出现额外的说明符 ``p`` ， ``f`` 或 ``s`` 。
+	
+对于IPv4地址，也可以使用额外的 ``h`` ， ``n`` ， ``b`` 和 ``l`` 说
+明符，但对于IPv6地址则忽略。
+	
+通过引用传递。
+
+更多例子
+
+::
+
+	%pISfc		1.2.3.4		or [1:2:3:4:5:6:7:8]/123456789
+	%pISsc		1.2.3.4		or [1:2:3:4:5:6:7:8]%1234567890
+	%pISpfc		1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345/123456789
+
+UUID/GUID地址
+-------------
+
+::
+
+	%pUb	00010203-0405-0607-0809-0a0b0c0d0e0f
+	%pUB	00010203-0405-0607-0809-0A0B0C0D0E0F
+	%pUl	03020100-0504-0706-0809-0a0b0c0e0e0f
+	%pUL	03020100-0504-0706-0809-0A0B0C0E0E0F
+
+用于打印16字节的UUID/GUIDs地址。附加的 ``l`` , ``L`` , ``b`` 和 ``B`` 说明符用
+于指定小写(l)或大写(L)十六进制表示法中的小尾端顺序，以及小写(b)或大写(B)十六进制表
+示法中的大尾端顺序。
+
+如果没有使用额外的说明符，则将打印带有小写十六进制表示法的默认大端顺序。
+	
+通过引用传递。
+
+目录项（dentry）的名称
+----------------------
+
+::
+
+	%pd{,2,3,4}
+	%pD{,2,3,4}
+
+用于打印dentry名称；如果我们用 :c:func:`d_move` 和它比较，名称可能是新旧混合的，但
+不会oops。 %pd dentry比较安全，其相当于我们以前用的%s dentry->d_name.name，%pd<n>打
+印 ``n`` 最后的组件。 %pD对结构文件做同样的事情。
+
+
+通过引用传递。
+
+块设备（block_device）名称
+--------------------------
+
+::
+
+	%pg	sda, sda1 or loop0p1
+
+用于打印block_device指针的名称。
+
+va_format结构体
+---------------
+
+::
+
+	%pV
+
+用于打印结构体va_format。这些结构包含一个格式字符串
+和va_list如下
+
+::
+
+	struct va_format {
+		const char *fmt;
+		va_list *va;
+	};
+
+实现 "递归vsnprintf"。
+
+如果没有一些机制来验证格式字符串和va_list参数的正确性，请不要使用这个功能。
+	
+通过引用传递。
+
+设备树节点
+----------
+
+::
+
+	%pOF[fnpPcCF]
+
+
+用于打印设备树节点结构。默认行为相当于%pOFf。
+
+	- f - 设备节点全称
+	- n - 设备节点名
+	- p - 设备节点句柄
+	- P - 设备节点路径规范(名称+@单位)
+	- F - 设备节点标志
+	- c - 主要兼容字符串
+	- C - 全兼容字符串
+
+当使用多个参数时，分隔符是':'。
+
+例如
+
+::
+
+	%pOF	/foo/bar@0			- Node full name
+	%pOFf	/foo/bar@0			- Same as above
+	%pOFfp	/foo/bar@0:10			- Node full name + phandle
+	%pOFfcF	/foo/bar@0:foo,device:--P-	- Node full name +
+	                                          major compatible string +
+						  node flags
+							D - dynamic
+							d - detached
+							P - Populated
+							B - Populated bus
+
+通过引用传递。
+
+Fwnode handles
+--------------
+
+::
+
+	%pfw[fP]
+
+用于打印fwnode_handles的信息。默认情况下是打印完整的节点名称，包括路径。
+这些修饰符在功能上等同于上面的%pOF。
+
+	- f - 节点的全名，包括路径。
+	- P - 节点名称，包括地址（如果有的话）。
+
+例如 (ACPI)
+
+::
+
+	%pfwf	\_SB.PCI0.CIO2.port@1.endpoint@0	- Full node name
+	%pfwP	endpoint@0				- Node name
+
+例如 (OF)
+
+::
+
+	%pfwf	/ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name
+	%pfwP	endpoint				- Node name
+
+时间和日期
+----------
+
+::
+
+	%pt[RT]			YYYY-mm-ddTHH:MM:SS
+	%pt[RT]d		YYYY-mm-dd
+	%pt[RT]t		HH:MM:SS
+	%pt[RT][dt][r]
+
+用于打印日期和时间
+
+::
+
+	R  struct rtc_time structure
+	T  time64_t type
+
+以我们（人类）可读的格式。
+
+默认情况下，年将以1900为单位递增，月将以1为单位递增。 使用%pt[RT]r (raw)
+来抑制这种行为。
+	
+通过引用传递。
+
+clk结构体
+---------
+
+::
+
+	%pC	pll1
+	%pCn	pll1
+
+用于打印clk结构。%pC 和 %pCn 打印时钟的名称（通用时钟框架）或唯一的32位
+ID（传统时钟框架）。
+
+通过引用传递。
+
+位图及其衍生物，如cpumask和nodemask
+-----------------------------------
+
+::
+
+	%*pb	0779
+	%*pbl	0,3-6,8-10
+
+对于打印位图及其派生的cpumask和nodemask，%*pb输出以字段宽度为位数的位图，
+%*pbl输出以字段宽度为位数的范围列表。
+
+字段宽度用值传递，位图用引用传递。可以使用辅助宏cpumask_pr_args()和
+nodemask_pr_args()来方便打印cpumask和nodemask。
+
+标志位字段，如页标志、gfp_flags
+-------------------------------
+
+::
+
+	%pGp	referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff
+	%pGg	GFP_USER|GFP_DMA32|GFP_NOWARN
+	%pGv	read|exec|mayread|maywrite|mayexec|denywrite
+
+将flags位字段打印为构造值的符号常量集合。标志的类型由第三个字符给出。目前支持的
+是[p]age flags， [v]ma_flags(都期望 ``unsigned long *`` )和
+[g]fp_flags(期望 ``gfp_t *`` )。标志名称和打印顺序取决于特定的类型。
+
+注意，这种格式不应该直接用于跟踪点的:c:func: `TP_printk()` 部分。相反，应使
+用 <trace/events/mmflags.h>中的show_*_flags()函数。
+	
+通过引用传递。
+
+网络设备特性
+------------
+
+::
+
+	%pNF	0x000000000000c000
+
+用于打印netdev_features_t。
+
+通过引用传递。
+
+V4L2和DRM FourCC代码(像素格式)
+------------------------------
+
+::
+
+	%p4cc
+
+打印V4L2或DRM使用的FourCC代码，包括格式端序及其十六进制的数值。
+
+通过引用传递。
+
+例如
+
+::
+
+	%p4cc	BG12 little-endian (0x32314742)
+	%p4cc	Y10  little-endian (0x20303159)
+	%p4cc	NV12 big-endian (0xb231564e)
+
+谢谢
+====
+
+如果您添加了其他%p扩展，请在可行的情况下，用一个或多个测试用例扩展<lib/test_printf.c>。
+
+谢谢你的合作和关注。
-- 
2.27.0

Re: [PATCH 1/3] docs/zh_CN: add core-api kernel-api.rst translation

[Matthew Wilcox]

On Mon, Apr 19, 2021 at 09:10:55PM +0800, Yanteng Si wrote:
> This patch translates Documentation/core-api/kernel-api.rst into Chinese.

I don't speak one word of Chinese, but this can't be right?

> +列表管理函数
> +============
> +
> +Todolist:
> +
> +   :internal:

The corresponding section in English is:

List Management Functions
=========================

.. kernel-doc:: include/linux/list.h
   :internal:

and surely you need a '.. kernel-doc' to have the ':internal:' make sense?

Then, I wonder how useful it is to bring kernel-doc written in English
into a Chinese document?  Wouldn't we be better off admitting that we
don't provide Chinese documentation for kernel APIs and referring to
the English documents?

(I would love nothing more than to provide Chinese documentation for
kernel APIs, but we don't have any kind of system for providing that
today)

Re: [PATCH 1/3] docs/zh_CN: add core-api kernel-api.rst translation

[Wu X.C.]

On Mon, Apr 19, 2021 at 02:35:26PM +0100, Matthew Wilcox wrote:
> On Mon, Apr 19, 2021 at 09:10:55PM +0800, Yanteng Si wrote:
> > This patch translates Documentation/core-api/kernel-api.rst into Chinese.
> 
> I don't speak one word of Chinese, but this can't be right?
> 
> > +列表管理函数
> > +============
> > +
> > +Todolist:
> > +
> > +   :internal:
> 
> The corresponding section in English is:
> 
> List Management Functions
> =========================
> 
> .. kernel-doc:: include/linux/list.h
>    :internal:
> 
> and surely you need a '.. kernel-doc' to have the ':internal:' make sense?

Yes, Matthew is right. 
You need to call kernel-doc to generate related docs.

> 
> Then, I wonder how useful it is to bring kernel-doc written in English
> into a Chinese document?  Wouldn't we be better off admitting that we
> don't provide Chinese documentation for kernel APIs and referring to
> the English documents?
> 
> (I would love nothing more than to provide Chinese documentation for
> kernel APIs, but we don't have any kind of system for providing that
> today)

Emm, I think, for the completeness of translation, it is worth.

But I want to know if the extra call to kernel-doc will significant
increase docs build time? If yes, I support add links to En rather than
simply put ..kernel-doc.

Thanks,
Wu.

Re: [PATCH 2/3] docs/zh_CN: add core-api printk-basics.rst translation

[Wu X.C.]

On Mon, Apr 19, 2021 at 09:10:56PM +0800, Yanteng Si wrote:
> This patch translates Documentation/core-api/printk-basics.rst into Chinese.
> 
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
>  .../zh_CN/core-api/printk-basics.rst          | 118 ++++++++++++++++++
>  1 file changed, 118 insertions(+)
>  create mode 100644 Documentation/translations/zh_CN/core-api/printk-basics.rst
> 
> diff --git a/Documentation/translations/zh_CN/core-api/printk-basics.rst b/Documentation/translations/zh_CN/core-api/printk-basics.rst
> new file mode 100644
> index 000000000000..056ca88604b2
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/printk-basics.rst
> @@ -0,0 +1,118 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: :doc:`../../../core-api/printk-basics`

As Cerbot suggested, better to use 
:Original: Documentation/core-api/printk-basics.rst

> +:Translator: Yanteng Si <siyanteng@loongson.cn>
> +
> +.. _cn_printk-basics.rst:
> +
> +
> +==================
> +使用printk记录信息
> +==================

建议仔细推敲本文所有 message 翻译
信息 or 消息
不一定要统一
消息 for one sentence, short information
信息 for a long, whole information

> +
> +printk()是Linux内核中最广为人知的函数之一。它是我们打印信息的标准工具，通常也是追踪和调试
> +的最基本方法。如果你熟悉printf(3)，你就能够知道printk()是基于它的，尽管它在功能上有一些不
> +同之处。:

remove 。

> +
> +  - printk() 信息可以指定日志级别。
> +
> +  - 格式字符串虽然与C99基本兼容，但并不遵循完全相同的规范。它有一些扩展和一些限制（没
> +    有 ``%n`` 或浮点转换指定符）。参见:ref: `如何正确地获得printk格式指定符<printk-specifiers>` 。
> +

wrong indent next paragraph

> +    所有的printk()消息都会被打印到内核日志缓冲区，这是一个通过/dev/kmsg输出到用户空间的环
> +    形缓冲区。读取它的通常方法是使用 ``dmesg`` 。
> +
> +printk()的用法通常是这样的
> +
> +::

Please make a test when "::" after texts and at the begin of a line.
Do you find the ':' ?

> +
> +  printk(KERN_INFO "Message: %s\n", arg);
> +
> +其中 ``KERN_INFO`` 是日志级别（注意，它与格式字符串连在一起，日志级别不是一个单独的参数）。
> +可用的日志级别是：
> +
> +
> ++----------------+--------+-----------------------------------------------+
> +| 名称           | 字符串 |  别名函数                                     |
> ++================+========+===============================================+
> +| KERN_EMERG     | "0"    | pr_emerg()                                    |
> ++----------------+--------+-----------------------------------------------+
> +| KERN_ALERT     | "1"    | pr_alert()                                    |
> ++----------------+--------+-----------------------------------------------+
> +| KERN_CRIT      | "2"    | pr_crit()                                     |
> ++----------------+--------+-----------------------------------------------+
> +| KERN_ERR       | "3"    | pr_err()                                      |
> ++----------------+--------+-----------------------------------------------+
> +| KERN_WARNING   | "4"    | pr_warn()                                     |
> ++----------------+--------+-----------------------------------------------+
> +| KERN_NOTICE    | "5"    | pr_notice()                                   |
> ++----------------+--------+-----------------------------------------------+
> +| KERN_INFO      | "6"    | pr_info()                                     |
> ++----------------+--------+-----------------------------------------------+
> +| KERN_DEBUG     | "7"    | pr_debug() and pr_devel() 如果定义了DEBUG     |

better
（若定义了DEBUG）

> ++----------------+--------+-----------------------------------------------+
> +| KERN_DEFAULT   | ""     |                                               |
> ++----------------+--------+-----------------------------------------------+
> +| KERN_CONT      | "c"    | pr_cont()                                     |
> ++----------------+--------+-----------------------------------------------+
> +
> +
> +日志级别指定了一条消息的重要性。内核根据日志级别和当前 *console_loglevel* （一个内核变量）决
> +定是否立即显示消息（将其打印到当前控制台）。如果消息的优先级比 *console_loglevel* 高（日志级
> +别值较低），消息将被打印到控制台。
> +
> +如果省略了日志级别，则以 ``KERN_DEFAULT`` 级别打印消息。
> +
> +你可以用以下方法检查当前的 *console_loglevel* 。::

remove 。

> +
> +  $ cat /proc/sys/kernel/printk
> +  4        4        1        7
> +
> +结果显示了 *current*, *default*, *minimum* and *boot-time-default* 日志级别

and -> 和

> +
> +要改变当前的 console_loglevel，只需在 ``/proc/sys/kernel/printk`` 中写入所需的
> +级别。例如，要打印所有的消息到控制台上::
> +
> +  # echo 8 > /proc/sys/kernel/printk
> +
> +另一种方式，使用 ``dmesg``
> +
> +::
   ^^

> +
> +  # dmesg -n 5
> +
> +设置 console_loglevel 打印 KERN_WARNING (4) 或更严重的信息到控制台。更多信息参
> +见 ``dmesg(1)`` 。
> +
> +作为printk()的替代方案，你可以使用 ``pr_*()`` 来记录日志。这个系列的宏在宏名中嵌入

``pr_*()`` 别名来记录日志

> +了日志级别。例如
> +
> +::
   ^^

> +
> +  pr_info("Info message no. %d\n", msg_num);
> +
> +打印 ``KERN_INFO`` 信息。
> +
> +除了比等效的printk()调用更简洁之外，它们还可以通过pr_fmt()宏为格式字符串使用一个通用
> +的定义。例如，在源文件的顶部（在任何 " ``#include`` " 指令之前）定义这样的内容。::

remove " "

> +
> +  #define pr_fmt(fmt) "%s:%s: " fmt, KBUILD_MODNAME, __func__
> +
> +会在该文件中的每一条 pr_*() 消息前加上发起该消息的模块和函数名称。
> +
> +为了调试的目的，还有两个有条件编译的宏：
           ^^^^^^  
为了调试，还有

> +pr_debug()和pr_devel()，除非定义了 ``DEBUG`` (或者在pr_debug()的情况下定义了
> +``CONFIG_DYNAMIC_DEBUG`` )，否则它们会被编译。
> +
> +
> +函数接口

reference

> +========
> +
> +Todolist:
> +
> +   :functions: printk
> +
> +
> +   :functions: pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
> +      pr_fmt pr_debug pr_devel pr_cont

Simply use original text, this is a kernel-doc 

> -- 
> 2.27.0

Thanks,
Wu X.C.

Re: [PATCH 3/3] docs/zh_CN: add core-api printk-formats.rst translation

[Wu X.C.]

On Mon, Apr 19, 2021 at 09:10:57PM +0800, Yanteng Si wrote:
> This patch translates Documentation/core-api/printk-formats.rst into Chinese.
> 
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
>  .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
>  1 file changed, 577 insertions(+)
>  create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst
> 
> diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> new file mode 100644
> index 000000000000..8552bbb3c797
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> @@ -0,0 +1,577 @@
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: :doc:`../../../core-api/printk-formats`
> +:Translator: Yanteng Si <siyanteng@loongson.cn>
> +
> +.. _cn_printk-formats.rst:
> +
> +
> +==============================
> +如何获得正确的printk格式说明符
> +==============================
> +
> +.. _printk-specifiers:

重复标签

> +
> +:作者: Randy Dunlap <rdunlap@infradead.org>
> +:作者: Andrew Murray <amurray@mpc-data.co.uk>
> +
> +
> +整数类型
> +========
> +
> +::
> +
> +	        如果变量是Type，则使用printk格式说明符器。

		若变量类型为		则使用printk格式说明符

> +	        -----------------------------------------
> +		char			%d or %x
> +		unsigned char		%u or %x
> +		short int		%d or %x
> +		unsigned short int	%u or %x
> +		int			%d or %x
> +		unsigned int		%u or %x
> +		long			%ld or %lx
> +		unsigned long		%lu or %lx
> +		long long		%lld or %llx
> +		unsigned long long	%llu or %llx
> +		size_t			%zu or %zx
> +		ssize_t			%zd or %zx
> +		s8			%d or %x
> +		u8			%u or %x
> +		s16			%d or %x
> +		u16			%u or %x
> +		s32			%d or %x
> +		u32			%u or %x
> +		s64			%lld or %llx
> +		u64			%llu or %llx
> +

s/or/或/

Emmm, let convert this to a table?
It looks not clear... Seems also need to fix origin file.

> +
> +如果 <type> 的大小依赖于配置选项 (例如 sector_t, blkcnt_t) 或其大小依赖于架构
> +(例如 tcflag_t)，则使用其可能的最大类型的格式说明符并显式强制转换为它。
> +
> +例如
> +
> +::
> +
> +	printk("test: sector number/total blocks: %llu/%llu\n",
> +		(unsigned long long)sector, (unsigned long long)blockcount);
> +
> +提醒：sizeof()返回类型size_t。
> +
> +内核的printf不支持%n。浮点格式(%e, %f, %g, %a)也不被识别，原因很明显。使用任何不
> +支持的说明符或长度限定符都会导致一个WARN和vsnprintf()的提前返回。
> +
> +指针类型
> +========
> +
> +一个原始指针值可以用%p打印，它将在打印前对地址进行哈希处理。内核也支持扩展说明符来打印
> +不同类型的指针。
> +
> +一些扩展说明符会打印给定地址上的数据，而不是打印地址本身。在这种情况下，以下错误信息可能
> +会被打印出来，而不是无法访问的信息。::

remove 。

> +
> +	(null)	 data on plain NULL address
> +	(efault) data on invalid address
> +	(einval) invalid data on a valid address
> +
> +简单的指针

普通指针？

> +----------
> +
> +::
> +
> +	%p	abcdef12 or 00000000abcdef12
> +
> +没有指定扩展名的指针(即未加修饰的%p)会被哈希以防止泄露内核内存布局的信息。这样做的另一个
> +好处是提供一个唯一的标识符。在64位机器上，前32位被清零。内核将打印 ``(ptrval)`` 直到它
> +收集到足够的熵。如果你 *真* 想知道地址请看下面的%px。
> +

Missed two paragraph in linux-next

> +错误指针
> +--------
> +
> +::
> +
> +	%pe	-ENOSPC
> +
> +用于打印错误指针(即IS_ERR()为真的指针)的符号错误名。不知道符号名的错误值会以十进制打印，
> +而作为%pe参数传递的非ERR_PTR会被视为普通的%p。
> +
> +符号/函数指针
> +-------------
> +
> +::
> +
> +	%pS	versatile_init+0x0/0x110
> +	%ps	versatile_init
> +	%pSR	versatile_init+0x9/0x110
> +		(with __builtin_extract_return_addr() translation)
> +	%pB	prev_fn_of_versatile_init+0x88/0x88
> +
> +
> +``S`` 和 ``s`` 说明符用于打印符号格式的指针。它们的结果是符号名称带有(S)或不带有(s)偏移
> +量。如果禁用KALLSYMS，则打印符号地址。
> +
> +``B`` 指定符的结果是带有偏移量的符号名，在打印堆栈回溯时应该使用。说明符将考虑编译器优化
         ^^^^^^

> +的影响，当使用尾部调用并使用noreturn GCC属性标记时，可能会发生这种优化。
> +
> +Probed Pointers from BPF / tracing

need translate

> +----------------------------------
> +
> +::
> +
> +	%pks	kernel string
> +	%pus	user string
> +
> +``k`` 和 ``u`` 指定符用于打印来自内核内存(k)或用户内存(u)的先前探测的内存。后面的 ``s`` 指
> +定符的结果是打印一个字符串。对于直接在常规的vsnprintf()中使用时，(k)和(u)注释被忽略，但是，当
> +在BPF的bpf_trace_printk()之外使用时，它会读取它所指向的内存，不会出现错误。
> +
> +内核指针
> +--------
> +
> +::
> +
> +	%pK	01234567 or 0123456789abcdef
> +
> +用于打印应该对非特权用户隐藏的内核指针。%pK的行为取决于kptr_restrict sysctl--详见

——

> +文档/admin-guide/sysctl/kernel.rst。

Documentation/admin-guide/sysctl/kernel.rst

> +
> +未经修改的地址
> +--------------
> +
> +::
> +
> +	%px	01234567 or 0123456789abcdef
> +
> +对于打印指针，当你 *真的* 想打印地址时。在用%px打印指针之前，请考虑你是否泄露了内核内
> +存布局的敏感信息。%px在功能上等同于%lx（或%lu）。%px是首选，因为它更具有唯一的grep能

在grep查找时更唯一？

> +力。如果将来我们需要修改内核处理打印指针的方式，我们将能更好地找到调用点。

Missed a paragraph in linux-next

> +
> +指针差异
> +--------
> +
> +::
> +
> +	%td	2560
> +	%tx	a00
> +
> +为了打印指针的差异，使用ptrdiff_t的%t修饰符。
> +
> +例如::
> +
> +	printk("test: difference between pointers: %td\n", ptr2 - ptr1);
> +
> +资源（Resources）结构体
> +-----------------------
> +
> +::
> +
> +	%pr	[mem 0x60000000-0x6fffffff flags 0x2200] or
> +		[mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
> +	%pR	[mem 0x60000000-0x6fffffff pref] or
> +		[mem 0x0000000060000000-0x000000006fffffff pref]
> +
> +用于打印结构资源。 ``R`` 和 ``r`` 说明符的结果是打印出的资源带有(R)或不带有(r)解码标志
           ^^^^^^^^

> +成员。
> +
> +通过引用传递。
> +
> +物理地址类型 phys_addr_t
> +------------------------
> +
> +::
> +
> +	%pa[p]	0x01234567 or 0x0123456789abcdef
> +
> +用于打印phys_addr_t类型(以及它的衍生物，如resource_size_t)，该类型可以根据构建选项而
（）                      ^                                 ^
> +变化，无论CPU数据路径的宽度如何。
> +
> +通过引用传递。
> +
> +DMA地址类型dma_addr_t
> +---------------------
> +
> +::
> +
> +	%pad	0x01234567 or 0x0123456789abcdef
> +
> +用于打印dma_addr_t类型，该类型可以根据构建选项而变化，而不考虑CPU数据路径的宽度。
> +
> +通过引用传递。
> +
> +原始缓冲区为转义字符串
> +----------------------
> +
> +::
> +
> +	%*pE[achnops]
> +
> +用于将原始缓冲区打印成转义字符串。对于以下缓冲区
> +
> +::
> +
> +		1b 62 20 5c 43 07 22 90 0d 5d
> +
> +几个例子显示了如何进行转换（不包括周围的引号）。

以下几个例子展示了如何进行转换（不包括两端引号）。

> +
> +::
   ^^
> +
> +		%*pE		"\eb \C\a"\220\r]"
> +		%*pEhp		"\x1bb \C\x07"\x90\x0d]"
> +		%*pEa		"\e\142\040\\\103\a\042\220\r\135"
> +
> +转换规则是根据可选的标志组合来应用的(详见:c:func: `string_escape_mem` 内核文档):
                                                    ^
                                                    remove a space
> +
> +	- a - ESCAPE_ANY
> +	- c - ESCAPE_SPECIAL
> +	- h - ESCAPE_HEX
> +	- n - ESCAPE_NULL
> +	- o - ESCAPE_OCTAL
> +	- p - ESCAPE_NP
> +	- s - ESCAPE_SPACE
> +
> +默认情况下，使用 ESCAPE_ANY_NP。
> +
> +ESCAPE_ANY_NP是许多情况下的明智选择，特别是对于打印SSID。
> +	
   ^^^^
there is a tab

> +如果字段宽度被省略，那么将只转义1个字节。
> +
> +原始缓冲区为十六进制字符串
> +--------------------------
> +
> +::
> +
> +	%*ph	00 01 02  ...  3f
> +	%*phC	00:01:02: ... :3f
> +	%*phD	00-01-02- ... -3f
> +	%*phN	000102 ... 3f
> +
> +对于打印小的缓冲区（最长64个字节），可以用一定的分隔符作为一个
> +十六进制字符串。对于较大的缓冲区，可以考虑使用
> +:c:func: `print_hex_dump` 。
           ^

> +
> +MAC/FDDI地址
> +------------
> +
> +::
> +
> +	%pM	00:01:02:03:04:05
> +	%pMR	05:04:03:02:01:00
> +	%pMF	00-01-02-03-04-05
> +	%pm	000102030405
> +	%pmR	050403020100
> +
> +用于打印以十六进制表示的6字节MAC/FDDI地址。 ``M`` 和 ``m`` 说明符导致打印的
> +地址有(M)或没有(m)字节分隔符。默认的字节分隔符是冒号（：）。
> +
> +对于FDDI地址，可以在 ``M`` 说明符之后使用 ``F`` 说明，以使用破折号(-)分隔符

连字符，这不是破折号
https://sspai.com/post/45516

> +代替默认的分隔符。
> +	
   ^^^
   remove tab
> +对于蓝牙地址， ``R`` 说明符应使用在 ``M`` 说明符之后，以使用反转的字节顺序，适
> +合于以小尾端顺序的蓝牙地址的肉眼可见的解析。
> +	
   ^^^^
   remove tab
> +通过引用传递。
> +
> +IPv4地址
> +--------
> +
> +::
> +
> +	%pI4	1.2.3.4
> +	%pi4	001.002.003.004
> +	%p[Ii]4[hnbl]
> +
> +用于打印IPv4点分隔的十进制地址。 ``I4`` 和 ``i4`` 说明符的结果是打印的地址
> +有(i4)或没有(I4)前导零。
> +
> +附加的 ``h`` 、 ``n`` 、 ``b`` 和 ``l`` 说明符分别用于指定主机、网络、大
> +尾端或小尾端地址。如果没有提供说明符，则使用默认的网络/大尾端顺序。
> +	
   ^^^
   remove tab
> +通过引用传递。
> +
> +IPv6 地址
> +---------
> +
> +::
> +
> +	%pI6	0001:0002:0003:0004:0005:0006:0007:0008
> +	%pi6	00010002000300040005000600070008
> +	%pI6c	1:2:3:4:5:6:7:8
> +
> +用于打印IPv6网络顺序的16位十六进制地址。 ``I6`` 和 ``i6`` 说明符的结果是
> +打印的地址有(I6)或没有(i6)分号。始终使用前导零。
> +
> +额外的 ``c`` 说明符可与 ``I`` 说明符一起使用，以打印压缩的IPv6地址，如下
> +所述
> +https://tools.ietf.org/html/rfc5952 
> +	

如https://sspai.com/post/45516所述

> +通过引用传递。
> +
> +IPv4/IPv6地址(generic, with port, flowinfo, scope)
> +--------------------------------------------------
> +
> +::
> +
> +	%pIS	1.2.3.4		or 0001:0002:0003:0004:0005:0006:0007:0008
> +	%piS	001.002.003.004	or 00010002000300040005000600070008
> +	%pISc	1.2.3.4		or 1:2:3:4:5:6:7:8
> +	%pISpc	1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345
> +	%p[Ii]S[pfschnbl]
> +
> +用于打印一个IP地址，不需要区分它的类型是AF_INET还是AF_INET6。一个指向有效结构
> +体sockaddr的指针，通过 ``IS`` 或 ``IS`` 指定，可以传递给这个格式说明符。
> +
> +附加的 ``p`` 、  ``f`` 和 ``s`` 说明符用于指定port(IPv4, IPv6)、
> +flowinfo (IPv6)和sope(IPv6)。port有一个 ``:`` 前缀，flowinfo是 ``/`` 和
> +范围是 ``%`` ，每个后面都跟着实际的值。
> +	
   ^^^
> +对于IPv6地址，如果指定了额外的指定符 ``c`` ，则使用
> +https://tools.ietf.org/html/rfc5952描述的压缩IPv6地址。
> +如https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
> +所建议的，IPv6地址由'['，']'包围，以防止出现额外的说明符 ``p`` ， ``f`` 或 ``s`` 。
> +	
   ^^^
> +对于IPv4地址，也可以使用额外的 ``h`` ， ``n`` ， ``b`` 和 ``l`` 说
> +明符，但对于IPv6地址则忽略。
> +	
   ^^^
> +通过引用传递。
> +
> +更多例子
> +
> +::
> +
> +	%pISfc		1.2.3.4		or [1:2:3:4:5:6:7:8]/123456789
> +	%pISsc		1.2.3.4		or [1:2:3:4:5:6:7:8]%1234567890
> +	%pISpfc		1.2.3.4:12345	or [1:2:3:4:5:6:7:8]:12345/123456789
> +
> +UUID/GUID地址
> +-------------
> +
> +::
> +
> +	%pUb	00010203-0405-0607-0809-0a0b0c0d0e0f
> +	%pUB	00010203-0405-0607-0809-0A0B0C0D0E0F
> +	%pUl	03020100-0504-0706-0809-0a0b0c0e0e0f
> +	%pUL	03020100-0504-0706-0809-0A0B0C0E0E0F
> +
> +用于打印16字节的UUID/GUIDs地址。附加的 ``l`` , ``L`` , ``b`` 和 ``B`` 说明符用
> +于指定小写(l)或大写(L)十六进制表示法中的小尾端顺序，以及小写(b)或大写(B)十六进制表
> +示法中的大尾端顺序。
> +
> +如果没有使用额外的说明符，则将打印带有小写十六进制表示法的默认大端顺序。
> +	
   ^^^
> +通过引用传递。
> +
> +目录项（dentry）的名称
> +----------------------
> +
> +::
> +
> +	%pd{,2,3,4}
> +	%pD{,2,3,4}
> +
> +用于打印dentry名称；如果我们用 :c:func:`d_move` 和它比较，名称可能是新旧混合的，但
> +不会oops。 %pd dentry比较安全，其相当于我们以前用的%s dentry->d_name.name，%pd<n>打
> +印 ``n`` 最后的组件。 %pD对结构文件做同样的事情。
> +
> +
> +通过引用传递。
> +
> +块设备（block_device）名称
> +--------------------------
> +
> +::
> +
> +	%pg	sda, sda1 or loop0p1
> +
> +用于打印block_device指针的名称。
> +
> +va_format结构体
> +---------------
> +
> +::
> +
> +	%pV
> +
> +用于打印结构体va_format。这些结构包含一个格式字符串
> +和va_list如下
> +
> +::
> +
> +	struct va_format {
> +		const char *fmt;
> +		va_list *va;
> +	};
> +
> +实现 "递归vsnprintf"。
> +
> +如果没有一些机制来验证格式字符串和va_list参数的正确性，请不要使用这个功能。
> +	
   ^^^
> +通过引用传递。
> +
> +设备树节点
> +----------
> +
> +::
> +
> +	%pOF[fnpPcCF]
> +
> +
> +用于打印设备树节点结构。默认行为相当于%pOFf。
> +
> +	- f - 设备节点全称
> +	- n - 设备节点名
> +	- p - 设备节点句柄
> +	- P - 设备节点路径规范(名称+@单位)
> +	- F - 设备节点标志
> +	- c - 主要兼容字符串
> +	- C - 全兼容字符串
> +
> +当使用多个参数时，分隔符是':'。
> +
> +例如
> +
> +::
> +
> +	%pOF	/foo/bar@0			- Node full name
> +	%pOFf	/foo/bar@0			- Same as above
> +	%pOFfp	/foo/bar@0:10			- Node full name + phandle
> +	%pOFfcF	/foo/bar@0:foo,device:--P-	- Node full name +
> +	                                          major compatible string +
> +						  node flags
> +							D - dynamic
> +							d - detached
> +							P - Populated
> +							B - Populated bus
> +
> +通过引用传递。
> +
> +Fwnode handles
> +--------------
> +
> +::
> +
> +	%pfw[fP]
> +
> +用于打印fwnode_handles的信息。默认情况下是打印完整的节点名称，包括路径。
> +这些修饰符在功能上等同于上面的%pOF。
> +
> +	- f - 节点的全名，包括路径。
> +	- P - 节点名称，包括地址（如果有的话）。
> +
> +例如 (ACPI)
> +
> +::
> +
> +	%pfwf	\_SB.PCI0.CIO2.port@1.endpoint@0	- Full node name
> +	%pfwP	endpoint@0				- Node name
> +
> +例如 (OF)
> +
> +::
> +
> +	%pfwf	/ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name
> +	%pfwP	endpoint				- Node name
> +
> +时间和日期
> +----------
> +
> +::
> +
> +	%pt[RT]			YYYY-mm-ddTHH:MM:SS
> +	%pt[RT]d		YYYY-mm-dd
> +	%pt[RT]t		HH:MM:SS
> +	%pt[RT][dt][r]
> +
> +用于打印日期和时间
> +
> +::
> +
> +	R  struct rtc_time structure
> +	T  time64_t type
> +
> +以我们（人类）可读的格式。
> +
> +默认情况下，年将以1900为单位递增，月将以1为单位递增。 使用%pt[RT]r (raw)
> +来抑制这种行为。
> +	
   ^^^
> +通过引用传递。
> +
> +clk结构体
> +---------
> +
> +::
> +
> +	%pC	pll1
> +	%pCn	pll1
> +
> +用于打印clk结构。%pC 和 %pCn 打印时钟的名称（通用时钟框架）或唯一的32位
> +ID（传统时钟框架）。
> +
> +通过引用传递。
> +
> +位图及其衍生物，如cpumask和nodemask
> +-----------------------------------
> +
> +::
> +
> +	%*pb	0779
> +	%*pbl	0,3-6,8-10
> +
> +对于打印位图及其派生的cpumask和nodemask，%*pb输出以字段宽度为位数的位图，
括注 bitmap ?
> +%*pbl输出以字段宽度为位数的范围列表。
> +
> +字段宽度用值传递，位图用引用传递。可以使用辅助宏cpumask_pr_args()和
> +nodemask_pr_args()来方便打印cpumask和nodemask。
> +
> +标志位字段，如页标志、gfp_flags
> +-------------------------------
> +
> +::
> +
> +	%pGp	referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff
> +	%pGg	GFP_USER|GFP_DMA32|GFP_NOWARN
> +	%pGv	read|exec|mayread|maywrite|mayexec|denywrite
> +
> +将flags位字段打印为构造值的符号常量集合。标志的类型由第三个字符给出。目前支持的
> +是[p]age flags， [v]ma_flags(都期望 ``unsigned long *`` )和
> +[g]fp_flags(期望 ``gfp_t *`` )。标志名称和打印顺序取决于特定的类型。
> +
> +注意，这种格式不应该直接用于跟踪点的:c:func: `TP_printk()` 部分。相反，应使
                                               ^
> +用 <trace/events/mmflags.h>中的show_*_flags()函数。
> +	
   ^^^
> +通过引用传递。
> +
> +网络设备特性
> +------------
> +
> +::
> +
> +	%pNF	0x000000000000c000
> +
> +用于打印netdev_features_t。
> +
> +通过引用传递。
> +
> +V4L2和DRM FourCC代码(像素格式)
> +------------------------------
> +
> +::
> +
> +	%p4cc
> +
> +打印V4L2或DRM使用的FourCC代码，包括格式端序及其十六进制的数值。
> +
> +通过引用传递。
> +
> +例如
> +
> +::
> +
> +	%p4cc	BG12 little-endian (0x32314742)
> +	%p4cc	Y10  little-endian (0x20303159)
> +	%p4cc	NV12 big-endian (0xb231564e)
> +
> +谢谢
> +====
> +
> +如果您添加了其他%p扩展，请在可行的情况下，用一个或多个测试用例扩展<lib/test_printf.c>。
> +
> +谢谢你的合作和关注。
> -- 
> 2.27.0

Thanks,
Wu X.C.

Re: [PATCH 0/3] add three core api docs

[Jonathan Corbet]

Yanteng Si <siyanteng@loongson.cn> writes:

> This patch add three core api docs.
>
>
> Yanteng Si (3):
>   docs/zh_CN: add core-api kernel-api.rst translation
>   docs/zh_CN: add core-api printk-basics.rst translation
>   docs/zh_CN: add core-api printk-formats.rst translation
>
>  .../zh_CN/core-api/kernel-api.rst             | 433 +++++++++++++
>  .../zh_CN/core-api/printk-basics.rst          | 118 ++++
>  .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
>  3 files changed, 1128 insertions(+)
>  create mode 100644 Documentation/translations/zh_CN/core-api/kernel-api.rst
>  create mode 100644 Documentation/translations/zh_CN/core-api/printk-basics.rst
>  create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst

Please, don't forget to add these files to index.rst.  This suggests to
me that you haven't tried a docs build; please always do that too.

Thanks,

jon

Re: [PATCH 0/3] add three core api docs

[teng sterling]

Jonathan Corbet <corbet@lwn.net> 于2021年4月21日周三 上午6:04写道：
>
> Yanteng Si <siyanteng@loongson.cn> writes:
>
> > This patch add three core api docs.
> >
> >
> > Yanteng Si (3):
> >   docs/zh_CN: add core-api kernel-api.rst translation
> >   docs/zh_CN: add core-api printk-basics.rst translation
> >   docs/zh_CN: add core-api printk-formats.rst translation
> >
> >  .../zh_CN/core-api/kernel-api.rst             | 433 +++++++++++++
> >  .../zh_CN/core-api/printk-basics.rst          | 118 ++++
> >  .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
> >  3 files changed, 1128 insertions(+)
> >  create mode 100644 Documentation/translations/zh_CN/core-api/kernel-api.rst
> >  create mode 100644 Documentation/translations/zh_CN/core-api/printk-basics.rst
> >  create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst
>
> Please, don't forget to add these files to index.rst.  This suggests to
> me that you haven't tried a docs build; please always do that too.

Hi jonathan,

OK！I add indexs when I test every time, but this time the indexs are
based on the
previous set, so I'm worried that repeated commits will cause
conflicts. I will add them to v2.

and next time :
when I add a new file, I will do the associated index.rst changes in
the same patch.

BTW. My other gmail mailbox may be broken, the mail can't be sent,
please don't be surprised if you receive two identical emails.


Thanks,

Yanteng

Re: [PATCH 3/3] docs/zh_CN: add core-api printk-formats.rst translation

[teng sterling]

Wu X.C. <bobwxc@email.cn> 于2021年4月20日周二 下午1:28写道：
On Mon, Apr 19, 2021 at 09:10:57PM +0800, Yanteng Si wrote:
> This patch translates Documentation/core-api/printk-formats.rst into Chinese.
>
> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> ---
>  .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
>  1 file changed, 577 insertions(+)
>  create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst
>
> diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> new file mode 100644
> index 000000000000..8552bbb3c797
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> @@ -0,0 +1,577 @@
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: :doc:`../../../core-api/printk-formats`
> +:Translator: Yanteng Si <siyanteng@loongson.cn>
> +
> +.. _cn_printk-formats.rst:
> +
> +
> +==============================
> +如何获得正确的printk格式说明符
> +==============================
> +
> +.. _printk-specifiers:

重复标签

OK! del > +
> +:作者: Randy Dunlap <rdunlap@infradead.org>
> +:作者: Andrew Murray <amurray@mpc-data.co.uk>
> +
> +
> +整数类型
> +========
> +
> +::
> +
> +             如果变量是Type，则使用printk格式说明符器。

                若变量类型为          则使用printk格式说明符
OK!
> +             -----------------------------------------
> +             char                    %d or %x
> +             unsigned char           %u or %x
> +             short int               %d or %x
> +             unsigned short int      %u or %x
> +             int                     %d or %x
> +             unsigned int            %u or %x
> +             long                    %ld or %lx
> +             unsigned long           %lu or %lx
> +             long long               %lld or %llx
> +             unsigned long long      %llu or %llx
> +             size_t                  %zu or %zx
> +             ssize_t                 %zd or %zx
> +             s8                      %d or %x
> +             u8                      %u or %x
> +             s16                     %d or %x
> +             u16                     %u or %x
> +             s32                     %d or %x
> +             u32                     %u or %x
> +             s64                     %lld or %llx
> +             u64                     %llu or %llx
> +

s/or/或/
OK！
Emmm, let convert this to a table?
It looks not clear... Seems also need to fix origin file.
Let's do it later ：）
> +
> +如果 <type> 的大小依赖于配置选项 (例如 sector_t, blkcnt_t) 或其大小依赖于架构
> +(例如 tcflag_t)，则使用其可能的最大类型的格式说明符并显式强制转换为它。
> +
> +例如
> +
> +::
> +
> +     printk("test: sector number/total blocks: %llu/%llu\n",
> +             (unsigned long long)sector, (unsigned long long)blockcount);
> +
> +提醒：sizeof()返回类型size_t。
> +
> +内核的printf不支持%n。浮点格式(%e, %f, %g, %a)也不被识别，原因很明显。使用任何不
> +支持的说明符或长度限定符都会导致一个WARN和vsnprintf()的提前返回。
> +
> +指针类型
> +========
> +
> +一个原始指针值可以用%p打印，它将在打印前对地址进行哈希处理。内核也支持扩展说明符来打印
> +不同类型的指针。
> +
> +一些扩展说明符会打印给定地址上的数据，而不是打印地址本身。在这种情况下，以下错误信息可能
> +会被打印出来，而不是无法访问的信息。::

remove 。
OK！
> +
> +     (null)   data on plain NULL address
> +     (efault) data on invalid address
> +     (einval) invalid data on a valid address
> +
> +简单的指针

普通指针？
OK！
> +----------
> +
> +::
> +
> +     %p      abcdef12 or 00000000abcdef12
> +
> +没有指定扩展名的指针(即未加修饰的%p)会被哈希以防止泄露内核内存布局的信息。这样做的另一个
> +好处是提供一个唯一的标识符。在64位机器上，前32位被清零。内核将打印 ``(ptrval)`` 直到它
> +收集到足够的熵。如果你 *真* 想知道地址请看下面的%px。
> +

Missed two paragraph in linux-next
OK！ +没有指定扩展名的指针（即没有修饰符的%p）被散列（hash），以防止内核内存布局信息的泄露。这+样还有一个额外的好处，就是提供一个唯一的标识符。在64位机器上，前32位被清零。内核将打+印
``(ptrval)`` ，直到它收集到足够的熵。++如果可能的话，使用专门的修饰符，如%pS或%pB（如下所述），以避免打印一个必须事后解释的非哈+希地址。如果不可能，而且打印地址的目的是为调试提供更多的信息，使用%p，并在调试过程中+用
``no_hash_pointers`` 参数启动内核，这将打印所有未修改的%p地址。如果你 *真的*
想知+道未修改的地址，请看下面的%px。++如果（也只有在）你将地址作为虚拟文件的内容打印出来，例如在procfs或sysfs中（使用+seq_printf()，而不是printk()）由用户空间进程读取，使用下面描述的%pK修饰符，不+要用%p或%px。
> +错误指针
> +--------
> +
> +::
> +
> +     %pe     -ENOSPC
> +
> +用于打印错误指针(即IS_ERR()为真的指针)的符号错误名。不知道符号名的错误值会以十进制打印，
> +而作为%pe参数传递的非ERR_PTR会被视为普通的%p。
> +
> +符号/函数指针
> +-------------
> +
> +::
> +
> +     %pS     versatile_init+0x0/0x110
> +     %ps     versatile_init
> +     %pSR    versatile_init+0x9/0x110
> +             (with __builtin_extract_return_addr() translation)
> +     %pB     prev_fn_of_versatile_init+0x88/0x88
> +
> +
> +``S`` 和 ``s`` 说明符用于打印符号格式的指针。它们的结果是符号名称带有(S)或不带有(s)偏移
> +量。如果禁用KALLSYMS，则打印符号地址。
> +
> +``B`` 指定符的结果是带有偏移量的符号名，在打印堆栈回溯时应该使用。说明符将考虑编译器优化
         ^^^^^^
OK！
> +的影响，当使用尾部调用并使用noreturn GCC属性标记时，可能会发生这种优化。
> +
> +Probed Pointers from BPF / tracing

need translate
OK 来自BPF / tracing追踪的探查指针
> +----------------------------------
> +
> +::
> +
> +     %pks    kernel string
> +     %pus    user string
> +
> +``k`` 和 ``u`` 指定符用于打印来自内核内存(k)或用户内存(u)的先前探测的内存。后面的 ``s`` 指
> +定符的结果是打印一个字符串。对于直接在常规的vsnprintf()中使用时，(k)和(u)注释被忽略，但是，当
> +在BPF的bpf_trace_printk()之外使用时，它会读取它所指向的内存，不会出现错误。
> +
> +内核指针
> +--------
> +
> +::
> +
> +     %pK     01234567 or 0123456789abcdef
> +
> +用于打印应该对非特权用户隐藏的内核指针。%pK的行为取决于kptr_restrict sysctl--详见

——
OK！
> +文档/admin-guide/sysctl/kernel.rst。

OMG！ I'm so stupid。Documentation/admin-guide/sysctl/kernel.rst OK！
> +
> +未经修改的地址
> +--------------
> +
> +::
> +
> +     %px     01234567 or 0123456789abcdef
> +
> +对于打印指针，当你 *真的* 想打印地址时。在用%px打印指针之前，请考虑你是否泄露了内核内
> +存布局的敏感信息。%px在功能上等同于%lx（或%lu）。%px是首选，因为它更具有唯一的grep能

在grep查找时更唯一？
OK！
> +力。如果将来我们需要修改内核处理打印指针的方式，我们将能更好地找到调用点。

Missed a paragraph in linux-next
OK! +在使用%px之前，请考虑使用%p并在调试过程中启用' ' no_hash_pointer '
'内核参数是否足+够(参见上面的%p描述)。%px的一个有效场景可能是在panic发生之前立即打印信息，这样无论如何+都可以防止任何敏感信息被利用，使用%px就不需要用no_hash_pointer来重现panic。
> +
> +指针差异
> +--------
> +
> +::
> +
> +     %td     2560
> +     %tx     a00
> +
> +为了打印指针的差异，使用ptrdiff_t的%t修饰符。
> +
> +例如::
> +
> +     printk("test: difference between pointers: %td\n", ptr2 - ptr1);
> +
> +资源（Resources）结构体
> +-----------------------
> +
> +::
> +
> +     %pr     [mem 0x60000000-0x6fffffff flags 0x2200] or
> +             [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
> +     %pR     [mem 0x60000000-0x6fffffff pref] or
> +             [mem 0x0000000060000000-0x000000006fffffff pref]
> +
> +用于打印结构资源。 ``R`` 和 ``r`` 说明符的结果是打印出的资源带有(R)或不带有(r)解码标志
           ^^^^^^^^
OK!
> +成员。
> +
> +通过引用传递。
> +
> +物理地址类型 phys_addr_t
> +------------------------
> +
> +::
> +
> +     %pa[p]  0x01234567 or 0x0123456789abcdef
> +
> +用于打印phys_addr_t类型(以及它的衍生物，如resource_size_t)，该类型可以根据构建选项而
（）                      ^                                 ^
OK！ > +变化，无论CPU数据路径的宽度如何。
> +
> +通过引用传递。
> +
> +DMA地址类型dma_addr_t
> +---------------------
> +
> +::
> +
> +     %pad    0x01234567 or 0x0123456789abcdef
> +
> +用于打印dma_addr_t类型，该类型可以根据构建选项而变化，而不考虑CPU数据路径的宽度。
> +
> +通过引用传递。
> +
> +原始缓冲区为转义字符串
> +----------------------
> +
> +::
> +
> +     %*pE[achnops]
> +
> +用于将原始缓冲区打印成转义字符串。对于以下缓冲区
> +
> +::
> +
> +             1b 62 20 5c 43 07 22 90 0d 5d
> +
> +几个例子显示了如何进行转换（不包括周围的引号）。

以下几个例子展示了如何进行转换（不包括两端引号）。
OK！
> +
> +::
OK！    ^^
> +
> +             %*pE            "\eb \C\a"\220\r]"
> +             %*pEhp          "\x1bb \C\x07"\x90\x0d]"
> +             %*pEa           "\e\142\040\\\103\a\042\220\r\135"
> +
> +转换规则是根据可选的标志组合来应用的(详见:c:func: `string_escape_mem` 内核文档):
                                                    ^
                                                    remove a space
OK！ > +
> +     - a - ESCAPE_ANY
> +     - c - ESCAPE_SPECIAL
> +     - h - ESCAPE_HEX
> +     - n - ESCAPE_NULL
> +     - o - ESCAPE_OCTAL
> +     - p - ESCAPE_NP
> +     - s - ESCAPE_SPACE
> +
> +默认情况下，使用 ESCAPE_ANY_NP。
> +
> +ESCAPE_ANY_NP是许多情况下的明智选择，特别是对于打印SSID。
> +
   ^^^^
there is a tab
OK！ del
> +如果字段宽度被省略，那么将只转义1个字节。
> +
> +原始缓冲区为十六进制字符串
> +--------------------------
> +
> +::
> +
> +     %*ph    00 01 02  ...  3f
> +     %*phC   00:01:02: ... :3f
> +     %*phD   00-01-02- ... -3f
> +     %*phN   000102 ... 3f
> +
> +对于打印小的缓冲区（最长64个字节），可以用一定的分隔符作为一个
> +十六进制字符串。对于较大的缓冲区，可以考虑使用
> +:c:func: `print_hex_dump` 。
           ^
OK！
> +
> +MAC/FDDI地址
> +------------
> +
> +::
> +
> +     %pM     00:01:02:03:04:05
> +     %pMR    05:04:03:02:01:00
> +     %pMF    00-01-02-03-04-05
> +     %pm     000102030405
> +     %pmR    050403020100
> +
> +用于打印以十六进制表示的6字节MAC/FDDI地址。 ``M`` 和 ``m`` 说明符导致打印的
> +地址有(M)或没有(m)字节分隔符。默认的字节分隔符是冒号（：）。
> +
> +对于FDDI地址，可以在 ``M`` 说明符之后使用 ``F`` 说明，以使用破折号(-)分隔符

连字符，这不是破折号
https://sspai.com/post/45516OK！

> +代替默认的分隔符。
> +
   ^^^
   remove tab
OK！ > +对于蓝牙地址， ``R`` 说明符应使用在 ``M`` 说明符之后，以使用反转的字节顺序，适
> +合于以小尾端顺序的蓝牙地址的肉眼可见的解析。
> +
   ^^^^
   remove tab
OK！ > +通过引用传递。
> +
> +IPv4地址
> +--------
> +
> +::
> +
> +     %pI4    1.2.3.4
> +     %pi4    001.002.003.004
> +     %p[Ii]4[hnbl]
> +
> +用于打印IPv4点分隔的十进制地址。 ``I4`` 和 ``i4`` 说明符的结果是打印的地址
> +有(i4)或没有(I4)前导零。
> +
> +附加的 ``h`` 、 ``n`` 、 ``b`` 和 ``l`` 说明符分别用于指定主机、网络、大
> +尾端或小尾端地址。如果没有提供说明符，则使用默认的网络/大尾端顺序。
> +
   ^^^
   remove tab
OK！ > +通过引用传递。
> +
> +IPv6 地址
> +---------
> +
> +::
> +
> +     %pI6    0001:0002:0003:0004:0005:0006:0007:0008
> +     %pi6    00010002000300040005000600070008
> +     %pI6c   1:2:3:4:5:6:7:8
> +
> +用于打印IPv6网络顺序的16位十六进制地址。 ``I6`` 和 ``i6`` 说明符的结果是
> +打印的地址有(I6)或没有(i6)分号。始终使用前导零。
> +
> +额外的 ``c`` 说明符可与 ``I`` 说明符一起使用，以打印压缩的IPv6地址，如下
> +所述
> +https://tools.ietf.org/html/rfc5952
> +

如https://sspai.com/post/45516所述

OK！ > +通过引用传递。
> +
> +IPv4/IPv6地址(generic, with port, flowinfo, scope)
> +--------------------------------------------------
> +
> +::
> +
> +     %pIS    1.2.3.4         or 0001:0002:0003:0004:0005:0006:0007:0008
> +     %piS    001.002.003.004 or 00010002000300040005000600070008
> +     %pISc   1.2.3.4         or 1:2:3:4:5:6:7:8
> +     %pISpc  1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345
> +     %p[Ii]S[pfschnbl]
> +
> +用于打印一个IP地址，不需要区分它的类型是AF_INET还是AF_INET6。一个指向有效结构
> +体sockaddr的指针，通过 ``IS`` 或 ``IS`` 指定，可以传递给这个格式说明符。
> +
> +附加的 ``p`` 、  ``f`` 和 ``s`` 说明符用于指定port(IPv4, IPv6)、
> +flowinfo (IPv6)和sope(IPv6)。port有一个 ``:`` 前缀，flowinfo是 ``/`` 和
> +范围是 ``%`` ，每个后面都跟着实际的值。
> +
   ^^^
OK！ > +对于IPv6地址，如果指定了额外的指定符 ``c`` ，则使用
> +https://tools.ietf.org/html/rfc5952描述的压缩IPv6地址。
> +如https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
> +所建议的，IPv6地址由'['，']'包围，以防止出现额外的说明符 ``p`` ， ``f`` 或 ``s`` 。
> +
   ^^^
OK！ > +对于IPv4地址，也可以使用额外的 ``h`` ， ``n`` ， ``b`` 和 ``l`` 说
> +明符，但对于IPv6地址则忽略。
> +
   ^^^
OK！ > +通过引用传递。
> +
> +更多例子
> +
> +::
> +
> +     %pISfc          1.2.3.4         or [1:2:3:4:5:6:7:8]/123456789
> +     %pISsc          1.2.3.4         or [1:2:3:4:5:6:7:8]%1234567890
> +     %pISpfc         1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345/123456789
> +
> +UUID/GUID地址
> +-------------
> +
> +::
> +
> +     %pUb    00010203-0405-0607-0809-0a0b0c0d0e0f
> +     %pUB    00010203-0405-0607-0809-0A0B0C0D0E0F
> +     %pUl    03020100-0504-0706-0809-0a0b0c0e0e0f
> +     %pUL    03020100-0504-0706-0809-0A0B0C0E0E0F
> +
> +用于打印16字节的UUID/GUIDs地址。附加的 ``l`` , ``L`` , ``b`` 和 ``B`` 说明符用
> +于指定小写(l)或大写(L)十六进制表示法中的小尾端顺序，以及小写(b)或大写(B)十六进制表
> +示法中的大尾端顺序。
> +
> +如果没有使用额外的说明符，则将打印带有小写十六进制表示法的默认大端顺序。
> +
   ^^^
OK！ > +通过引用传递。
> +
> +目录项（dentry）的名称
> +----------------------
> +
> +::
> +
> +     %pd{,2,3,4}
> +     %pD{,2,3,4}
> +
> +用于打印dentry名称；如果我们用 :c:func:`d_move` 和它比较，名称可能是新旧混合的，但
> +不会oops。 %pd dentry比较安全，其相当于我们以前用的%s dentry->d_name.name，%pd<n>打
> +印 ``n`` 最后的组件。 %pD对结构文件做同样的事情。
> +
> +
> +通过引用传递。
> +
> +块设备（block_device）名称
> +--------------------------
> +
> +::
> +
> +     %pg     sda, sda1 or loop0p1
> +
> +用于打印block_device指针的名称。
> +
> +va_format结构体
> +---------------
> +
> +::
> +
> +     %pV
> +
> +用于打印结构体va_format。这些结构包含一个格式字符串
> +和va_list如下
> +
> +::
> +
> +     struct va_format {
> +             const char *fmt;
> +             va_list *va;
> +     };
> +
> +实现 "递归vsnprintf"。
> +
> +如果没有一些机制来验证格式字符串和va_list参数的正确性，请不要使用这个功能。
> +
   ^^^
OK！ > +通过引用传递。
> +
> +设备树节点
> +----------
> +
> +::
> +
> +     %pOF[fnpPcCF]
> +
> +
> +用于打印设备树节点结构。默认行为相当于%pOFf。
> +
> +     - f - 设备节点全称
> +     - n - 设备节点名
> +     - p - 设备节点句柄
> +     - P - 设备节点路径规范(名称+@单位)
> +     - F - 设备节点标志
> +     - c - 主要兼容字符串
> +     - C - 全兼容字符串
> +
> +当使用多个参数时，分隔符是':'。
> +
> +例如
> +
> +::
> +
> +     %pOF    /foo/bar@0                      - Node full name
> +     %pOFf   /foo/bar@0                      - Same as above
> +     %pOFfp  /foo/bar@0:10                   - Node full name + phandle
> +     %pOFfcF /foo/bar@0:foo,device:--P-      - Node full name +
> +                                               major compatible string +
> +                                               node flags
> +                                                     D - dynamic
> +                                                     d - detached
> +                                                     P - Populated
> +                                                     B - Populated bus
> +
> +通过引用传递。
> +
> +Fwnode handles
> +--------------
> +
> +::
> +
> +     %pfw[fP]
> +
> +用于打印fwnode_handles的信息。默认情况下是打印完整的节点名称，包括路径。
> +这些修饰符在功能上等同于上面的%pOF。
> +
> +     - f - 节点的全名，包括路径。
> +     - P - 节点名称，包括地址（如果有的话）。
> +
> +例如 (ACPI)
> +
> +::
> +
> +     %pfwf   \_SB.PCI0.CIO2.port@1.endpoint@0        - Full node name
> +     %pfwP   endpoint@0                              - Node name
> +
> +例如 (OF)
> +
> +::
> +
> +     %pfwf   /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name
> +     %pfwP   endpoint                                - Node name
> +
> +时间和日期
> +----------
> +
> +::
> +
> +     %pt[RT]                 YYYY-mm-ddTHH:MM:SS
> +     %pt[RT]d                YYYY-mm-dd
> +     %pt[RT]t                HH:MM:SS
> +     %pt[RT][dt][r]
> +
> +用于打印日期和时间
> +
> +::
> +
> +     R  struct rtc_time structure
> +     T  time64_t type
> +
> +以我们（人类）可读的格式。
> +
> +默认情况下，年将以1900为单位递增，月将以1为单位递增。 使用%pt[RT]r (raw)
> +来抑制这种行为。
> +
   ^^^
OK！ > +通过引用传递。
> +
> +clk结构体
> +---------
> +
> +::
> +
> +     %pC     pll1
> +     %pCn    pll1
> +
> +用于打印clk结构。%pC 和 %pCn 打印时钟的名称（通用时钟框架）或唯一的32位
> +ID（传统时钟框架）。
> +
> +通过引用传递。
> +
> +位图及其衍生物，如cpumask和nodemask
> +-----------------------------------
> +
> +::
> +
> +     %*pb    0779
> +     %*pbl   0,3-6,8-10
> +
> +对于打印位图及其派生的cpumask和nodemask，%*pb输出以字段宽度为位数的位图，
括注 bitmap ?
OK， 对于打印位图（bitmap）> +%*pbl输出以字段宽度为位数的范围列表。
> +
> +字段宽度用值传递，位图用引用传递。可以使用辅助宏cpumask_pr_args()和
> +nodemask_pr_args()来方便打印cpumask和nodemask。
> +
> +标志位字段，如页标志、gfp_flags
> +-------------------------------
> +
> +::
> +
> +     %pGp    referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff
> +     %pGg    GFP_USER|GFP_DMA32|GFP_NOWARN
> +     %pGv    read|exec|mayread|maywrite|mayexec|denywrite
> +
> +将flags位字段打印为构造值的符号常量集合。标志的类型由第三个字符给出。目前支持的
> +是[p]age flags， [v]ma_flags(都期望 ``unsigned long *`` )和
> +[g]fp_flags(期望 ``gfp_t *`` )。标志名称和打印顺序取决于特定的类型。
> +
> +注意，这种格式不应该直接用于跟踪点的:c:func: `TP_printk()` 部分。相反，应使
                                               ^
OK！ > +用 <trace/events/mmflags.h>中的show_*_flags()函数。
> +
   ^^^
OK！
> +通过引用传递。
> +
> +网络设备特性
> +------------
> +
> +::
> +
> +     %pNF    0x000000000000c000
> +
> +用于打印netdev_features_t。
> +
> +通过引用传递。
> +
> +V4L2和DRM FourCC代码(像素格式)
> +------------------------------
> +
> +::
> +
> +     %p4cc
> +
> +打印V4L2或DRM使用的FourCC代码，包括格式端序及其十六进制的数值。
> +
> +通过引用传递。
> +
> +例如
> +
> +::
> +
> +     %p4cc   BG12 little-endian (0x32314742)
> +     %p4cc   Y10  little-endian (0x20303159)
> +     %p4cc   NV12 big-endian (0xb231564e)
> +
> +谢谢
> +====
> +
> +如果您添加了其他%p扩展，请在可行的情况下，用一个或多个测试用例扩展<lib/test_printf.c>。
> +
> +谢谢你的合作和关注。
> --
> 2.27.0

Thanks,
Wu X.C.

Thank you for your review.

Thanks，

Yanteng

Re: [PATCH 3/3] docs/zh_CN: add core-api printk-formats.rst translation

[Wu X.C.]

On Wed, Apr 21, 2021 at 03:15:40PM +0800, teng sterling wrote:
> Wu X.C. <bobwxc@email.cn> 于2021年4月20日周二 下午1:28写道：
> On Mon, Apr 19, 2021 at 09:10:57PM +0800, Yanteng Si wrote:
> > This patch translates Documentation/core-api/printk-formats.rst into Chinese.
> >
> > Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> > ---
> >  .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
> >  1 file changed, 577 insertions(+)
> >  create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst
> >
> > diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> > new file mode 100644
> > index 000000000000..8552bbb3c797
> > --- /dev/null
> > +++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst
[...]
> > +
> > +用于打印IPv6网络顺序的16位十六进制地址。 ``I6`` 和 ``i6`` 说明符的结果是
> > +打印的地址有(I6)或没有(i6)分号。始终使用前导零。
> > +
> > +额外的 ``c`` 说明符可与 ``I`` 说明符一起使用，以打印压缩的IPv6地址，如下
> > +所述
> > +https://tools.ietf.org/html/rfc5952
> > +
> 
> 如https://sspai.com/post/45516所述
> 
> OK！ 

Oh, here I wrote a wrong link.
Should be

	如https://tools.ietf.org/html/rfc5952所述

Sorry for the inconvience!

Wu

Re: [PATCH 3/3] docs/zh_CN: add core-api printk-formats.rst translation

[teng sterling]

Wu X.C. <bobwxc@email.cn> 于2021年4月21日周三 下午4:12写道：
>
> On Wed, Apr 21, 2021 at 03:15:40PM +0800, teng sterling wrote:
> > Wu X.C. <bobwxc@email.cn> 于2021年4月20日周二 下午1:28写道：
> > On Mon, Apr 19, 2021 at 09:10:57PM +0800, Yanteng Si wrote:
> > > This patch translates Documentation/core-api/printk-formats.rst into Chinese.
> > >
> > > Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> > > ---
> > >  .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
> > >  1 file changed, 577 insertions(+)
> > >  create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst
> > >
> > > diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> > > new file mode 100644
> > > index 000000000000..8552bbb3c797
> > > --- /dev/null
> > > +++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> [...]
> > > +
> > > +用于打印IPv6网络顺序的16位十六进制地址。 ``I6`` 和 ``i6`` 说明符的结果是
> > > +打印的地址有(I6)或没有(i6)分号。始终使用前导零。
> > > +
> > > +额外的 ``c`` 说明符可与 ``I`` 说明符一起使用，以打印压缩的IPv6地址，如下
> > > +所述
> > > +https://tools.ietf.org/html/rfc5952
> > > +
> >
> > 如https://sspai.com/post/45516所述
> >
> > OK！
>
> Oh, here I wrote a wrong link.
> Should be
>
>         如https://tools.ietf.org/html/rfc5952所述

Fortunately, I didn't copy and paste.   ~>_<~
>
> Sorry for the inconvience!
>
> Wu
>

Re: [PATCH 3/3] docs/zh_CN: add core-api printk-formats.rst translation

[teng sterling]

Hi all

sorry, There are some new modify.

teng sterling <sterlingteng@gmail.com> 于2021年4月21日周三 下午3:15写道：
>
> Wu X.C. <bobwxc@email.cn> 于2021年4月20日周二 下午1:28写道：
> On Mon, Apr 19, 2021 at 09:10:57PM +0800, Yanteng Si wrote:
> > This patch translates Documentation/core-api/printk-formats.rst into Chinese.
> >
> > Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> > ---
> >  .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
> >  1 file changed, 577 insertions(+)
> >  create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst
> >
> > diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> > new file mode 100644
> > index 000000000000..8552bbb3c797
> > --- /dev/null
> > +++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> > @@ -0,0 +1,577 @@
> > +.. include:: ../disclaimer-zh_CN.rst
> > +
> > +:Original: :doc:`../../../core-api/printk-formats`
> > +:Translator: Yanteng Si <siyanteng@loongson.cn>
> > +
> > +.. _cn_printk-formats.rst:
> > +
> > +
> > +==============================
> > +如何获得正确的printk格式说明符
> > +==============================
> > +
> > +.. _printk-specifiers:
>
> 重复标签
>
> OK! del > +
> > +:作者: Randy Dunlap <rdunlap@infradead.org>
> > +:作者: Andrew Murray <amurray@mpc-data.co.uk>
> > +
> > +
> > +整数类型
> > +========
> > +
> > +::
> > +
> > +             如果变量是Type，则使用printk格式说明符器。
>
>                 若变量类型为          则使用printk格式说明符
> OK!
> > +             -----------------------------------------
> > +             char                    %d or %x
> > +             unsigned char           %u or %x
> > +             short int               %d or %x
> > +             unsigned short int      %u or %x
> > +             int                     %d or %x
> > +             unsigned int            %u or %x
> > +             long                    %ld or %lx
> > +             unsigned long           %lu or %lx
> > +             long long               %lld or %llx
> > +             unsigned long long      %llu or %llx
> > +             size_t                  %zu or %zx
> > +             ssize_t                 %zd or %zx
> > +             s8                      %d or %x
> > +             u8                      %u or %x
> > +             s16                     %d or %x
> > +             u16                     %u or %x
> > +             s32                     %d or %x
> > +             u32                     %u or %x
> > +             s64                     %lld or %llx
> > +             u64                     %llu or %llx
> > +
>
> s/or/或/
> OK！
> Emmm, let convert this to a table?
> It looks not clear... Seems also need to fix origin file.
> Let's do it later ：）
> > +
> > +如果 <type> 的大小依赖于配置选项 (例如 sector_t, blkcnt_t) 或其大小依赖于架构
> > +(例如 tcflag_t)，则使用其可能的最大类型的格式说明符并显式强制转换为它。
> > +
> > +例如
> > +
> > +::
> > +
> > +     printk("test: sector number/total blocks: %llu/%llu\n",
> > +             (unsigned long long)sector, (unsigned long long)blockcount);
> > +
> > +提醒：sizeof()返回类型size_t。
> > +
> > +内核的printf不支持%n。浮点格式(%e, %f, %g, %a)也不被识别，原因很明显。使用任何不
> > +支持的说明符或长度限定符都会导致一个WARN和vsnprintf()的提前返回。
> > +
> > +指针类型
> > +========
> > +
> > +一个原始指针值可以用%p打印，它将在打印前对地址进行哈希处理。内核也支持扩展说明符来打印
> > +不同类型的指针。
> > +
> > +一些扩展说明符会打印给定地址上的数据，而不是打印地址本身。在这种情况下，以下错误信息可能
> > +会被打印出来，而不是无法访问的信息。::
>
> remove 。
> OK！
> > +
> > +     (null)   data on plain NULL address
> > +     (efault) data on invalid address
> > +     (einval) invalid data on a valid address
> > +
> > +简单的指针
>
> 普通指针？
> OK！
> > +----------
> > +
> > +::
> > +
> > +     %p      abcdef12 or 00000000abcdef12
> > +
> > +没有指定扩展名的指针(即未加修饰的%p)会被哈希以防止泄露内核内存布局的信息。这样做的另一个
> > +好处是提供一个唯一的标识符。在64位机器上，前32位被清零。内核将打印 ``(ptrval)`` 直到它
> > +收集到足够的熵。如果你 *真* 想知道地址请看下面的%px。
> > +
>
> Missed two paragraph in linux-next
> OK！ +没有指定扩展名的指针（即没有修饰符的%p）被散列（hash），以防止内核内存布局信息的泄露。这+样还有一个额外的好处，就是提供一个唯一的标识符。在64位机器上，前32位被清零。内核将打+印
> ``(ptrval)`` ，直到它收集到足够的熵。++如果可能的话，使用专门的修饰符，如%pS或%pB（如下所述），以避免打印一个必须事后解释的非哈+希地址。如果不可能，而且打印地址的目的是为调试提供更多的信息，使用%p，并在调试过程中+用
> ``no_hash_pointers`` 参数启动内核，这将打印所有未修改的%p地址。如果你 *真的*
> 想知+道未修改的地址，请看下面的%px。++如果（也只有在）你将地址作为虚拟文件的内容打印出来，例如在procfs或sysfs中（使用+seq_printf()，而不是printk()）由用户空间进程读取，使用下面描述的%pK修饰符，不+要用%p或%px。
> > +错误指针
> > +--------
> > +
> > +::
> > +
> > +     %pe     -ENOSPC
> > +
> > +用于打印错误指针(即IS_ERR()为真的指针)的符号错误名。不知道符号名的错误值会以十进制打印，
> > +而作为%pe参数传递的非ERR_PTR会被视为普通的%p。
> > +
> > +符号/函数指针
> > +-------------
> > +
> > +::
> > +
> > +     %pS     versatile_init+0x0/0x110
> > +     %ps     versatile_init
> > +     %pSR    versatile_init+0x9/0x110
> > +             (with __builtin_extract_return_addr() translation)
> > +     %pB     prev_fn_of_versatile_init+0x88/0x88
> > +
> > +
> > +``S`` 和 ``s`` 说明符用于打印符号格式的指针。它们的结果是符号名称带有(S)或不带有(s)偏移
> > +量。如果禁用KALLSYMS，则打印符号地址。
> > +
> > +``B`` 指定符的结果是带有偏移量的符号名，在打印堆栈回溯时应该使用。说明符将考虑编译器优化
>          ^^^^^^
> OK！
> > +的影响，当使用尾部调用并使用noreturn GCC属性标记时，可能会发生这种优化。
> > +
> > +Probed Pointers from BPF / tracing
>
> need translate
> OK 来自BPF / tracing追踪的探查指针
> > +----------------------------------
> > +
> > +::
> > +
> > +     %pks    kernel string
> > +     %pus    user string
> > +
> > +``k`` 和 ``u`` 指定符用于打印来自内核内存(k)或用户内存(u)的先前探测的内存。后面的 ``s`` 指
> > +定符的结果是打印一个字符串。对于直接在常规的vsnprintf()中使用时，(k)和(u)注释被忽略，但是，当
> > +在BPF的bpf_trace_printk()之外使用时，它会读取它所指向的内存，不会出现错误。
> > +
> > +内核指针
> > +--------
> > +
> > +::
> > +
> > +     %pK     01234567 or 0123456789abcdef
> > +
> > +用于打印应该对非特权用户隐藏的内核指针。%pK的行为取决于kptr_restrict sysctl--详见
>
> ——
> OK！
> > +文档/admin-guide/sysctl/kernel.rst。
>
> OMG！ I'm so stupid。Documentation/admin-guide/sysctl/kernel.rst OK！
> > +
> > +未经修改的地址
> > +--------------
> > +
> > +::
> > +
> > +     %px     01234567 or 0123456789abcdef
> > +
> > +对于打印指针，当你 *真的* 想打印地址时。在用%px打印指针之前，请考虑你是否泄露了内核内
> > +存布局的敏感信息。%px在功能上等同于%lx（或%lu）。%px是首选，因为它更具有唯一的grep能
>
> 在grep查找时更唯一？
> OK！
> > +力。如果将来我们需要修改内核处理打印指针的方式，我们将能更好地找到调用点。
>
> Missed a paragraph in linux-next
> OK! +在使用%px之前，请考虑使用%p并在调试过程中启用' ' no_hash_pointer '
> '内核参数是否足+够(参见上面的%p描述)。%px的一个有效场景可能是在panic发生之前立即打印信息，这样无论如何+都可以防止任何敏感信息被利用，使用%px就不需要用no_hash_pointer来重现panic。
> > +
> > +指针差异
> > +--------
> > +
> > +::
> > +
> > +     %td     2560
> > +     %tx     a00
> > +
> > +为了打印指针的差异，使用ptrdiff_t的%t修饰符。
> > +
> > +例如::
> > +
> > +     printk("test: difference between pointers: %td\n", ptr2 - ptr1);
> > +
> > +资源（Resources）结构体
结构体资源（Resources）

> > +-----------------------
> > +
> > +::
> > +
> > +     %pr     [mem 0x60000000-0x6fffffff flags 0x2200] or
> > +             [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
> > +     %pR     [mem 0x60000000-0x6fffffff pref] or
> > +             [mem 0x0000000060000000-0x000000006fffffff pref]
> > +
> > +用于打印结构资源。 ``R`` 和 ``r`` 说明符的结果是打印出的资源带有(R)或不带有(r)解码标志
打印结构体资源
>            ^^^^^^^^
> OK!
> > +成员。
> > +
> > +通过引用传递。
> > +
> > +物理地址类型 phys_addr_t
> > +------------------------
> > +
> > +::
> > +
> > +     %pa[p]  0x01234567 or 0x0123456789abcdef
> > +
> > +用于打印phys_addr_t类型(以及它的衍生物，如resource_size_t)，该类型可以根据构建选项而
> （）                      ^                                 ^
> OK！ > +变化，无论CPU数据路径的宽度如何。
> > +
> > +通过引用传递。
> > +
> > +DMA地址类型dma_addr_t
> > +---------------------
> > +
> > +::
> > +
> > +     %pad    0x01234567 or 0x0123456789abcdef
> > +
> > +用于打印dma_addr_t类型，该类型可以根据构建选项而变化，而不考虑CPU数据路径的宽度。
> > +
> > +通过引用传递。
> > +
> > +原始缓冲区为转义字符串
> > +----------------------
> > +
> > +::
> > +
> > +     %*pE[achnops]
> > +
> > +用于将原始缓冲区打印成转义字符串。对于以下缓冲区
> > +
> > +::
> > +
> > +             1b 62 20 5c 43 07 22 90 0d 5d
> > +
> > +几个例子显示了如何进行转换（不包括周围的引号）。
>
> 以下几个例子展示了如何进行转换（不包括两端引号）。
> OK！
> > +
> > +::
> OK！    ^^
> > +
> > +             %*pE            "\eb \C\a"\220\r]"
> > +             %*pEhp          "\x1bb \C\x07"\x90\x0d]"
> > +             %*pEa           "\e\142\040\\\103\a\042\220\r\135"
> > +
> > +转换规则是根据可选的标志组合来应用的(详见:c:func: `string_escape_mem` 内核文档):
>                                                     ^
>                                                     remove a space
> OK！ > +
> > +     - a - ESCAPE_ANY
> > +     - c - ESCAPE_SPECIAL
> > +     - h - ESCAPE_HEX
> > +     - n - ESCAPE_NULL
> > +     - o - ESCAPE_OCTAL
> > +     - p - ESCAPE_NP
> > +     - s - ESCAPE_SPACE
> > +
> > +默认情况下，使用 ESCAPE_ANY_NP。
> > +
> > +ESCAPE_ANY_NP是许多情况下的明智选择，特别是对于打印SSID。
> > +
>    ^^^^
> there is a tab
> OK！ del
> > +如果字段宽度被省略，那么将只转义1个字节。
> > +
> > +原始缓冲区为十六进制字符串
> > +--------------------------
> > +
> > +::
> > +
> > +     %*ph    00 01 02  ...  3f
> > +     %*phC   00:01:02: ... :3f
> > +     %*phD   00-01-02- ... -3f
> > +     %*phN   000102 ... 3f
> > +
> > +对于打印小的缓冲区（最长64个字节），可以用一定的分隔符作为一个
> > +十六进制字符串。对于较大的缓冲区，可以考虑使用
> > +:c:func: `print_hex_dump` 。
>            ^
> OK！
> > +
> > +MAC/FDDI地址
> > +------------
> > +
> > +::
> > +
> > +     %pM     00:01:02:03:04:05
> > +     %pMR    05:04:03:02:01:00
> > +     %pMF    00-01-02-03-04-05
> > +     %pm     000102030405
> > +     %pmR    050403020100
> > +
> > +用于打印以十六进制表示的6字节MAC/FDDI地址。 ``M`` 和 ``m`` 说明符导致打印的
> > +地址有(M)或没有(m)字节分隔符。默认的字节分隔符是冒号（：）。
> > +
> > +对于FDDI地址，可以在 ``M`` 说明符之后使用 ``F`` 说明，以使用破折号(-)分隔符
>
> 连字符，这不是破折号
> https://sspai.com/post/45516OK！
>
> > +代替默认的分隔符。
> > +
>    ^^^
>    remove tab
> OK！ > +对于蓝牙地址， ``R`` 说明符应使用在 ``M`` 说明符之后，以使用反转的字节顺序，适
> > +合于以小尾端顺序的蓝牙地址的肉眼可见的解析。
> > +
>    ^^^^
>    remove tab
> OK！ > +通过引用传递。
> > +
> > +IPv4地址
> > +--------
> > +
> > +::
> > +
> > +     %pI4    1.2.3.4
> > +     %pi4    001.002.003.004
> > +     %p[Ii]4[hnbl]
> > +
> > +用于打印IPv4点分隔的十进制地址。 ``I4`` 和 ``i4`` 说明符的结果是打印的地址
> > +有(i4)或没有(I4)前导零。
> > +
> > +附加的 ``h`` 、 ``n`` 、 ``b`` 和 ``l`` 说明符分别用于指定主机、网络、大
> > +尾端或小尾端地址。如果没有提供说明符，则使用默认的网络/大尾端顺序。
> > +
>    ^^^
>    remove tab
> OK！ > +通过引用传递。
> > +
> > +IPv6 地址
> > +---------
> > +
> > +::
> > +
> > +     %pI6    0001:0002:0003:0004:0005:0006:0007:0008
> > +     %pi6    00010002000300040005000600070008
> > +     %pI6c   1:2:3:4:5:6:7:8
> > +
> > +用于打印IPv6网络顺序的16位十六进制地址。 ``I6`` 和 ``i6`` 说明符的结果是
> > +打印的地址有(I6)或没有(i6)分号。始终使用前导零。
> > +
> > +额外的 ``c`` 说明符可与 ``I`` 说明符一起使用，以打印压缩的IPv6地址，如下
> > +所述
> > +https://tools.ietf.org/html/rfc5952
> > +
>
> 如https://sspai.com/post/45516所述
>
> OK！ > +通过引用传递。
> > +
> > +IPv4/IPv6地址(generic, with port, flowinfo, scope)
> > +--------------------------------------------------
> > +
> > +::
> > +
> > +     %pIS    1.2.3.4         or 0001:0002:0003:0004:0005:0006:0007:0008
> > +     %piS    001.002.003.004 or 00010002000300040005000600070008
> > +     %pISc   1.2.3.4         or 1:2:3:4:5:6:7:8
> > +     %pISpc  1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345
> > +     %p[Ii]S[pfschnbl]
> > +
> > +用于打印一个IP地址，不需要区分它的类型是AF_INET还是AF_INET6。一个指向有效结构
> > +体sockaddr的指针，通过 ``IS`` 或 ``IS`` 指定，可以传递给这个格式说明符。
> > +
> > +附加的 ``p`` 、  ``f`` 和 ``s`` 说明符用于指定port(IPv4, IPv6)、
> > +flowinfo (IPv6)和sope(IPv6)。port有一个 ``:`` 前缀，flowinfo是 ``/`` 和
> > +范围是 ``%`` ，每个后面都跟着实际的值。
> > +
>    ^^^
> OK！ > +对于IPv6地址，如果指定了额外的指定符 ``c`` ，则使用
> > +https://tools.ietf.org/html/rfc5952描述的压缩IPv6地址。
> > +如https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
> > +所建议的，IPv6地址由'['，']'包围，以防止出现额外的说明符 ``p`` ， ``f`` 或 ``s`` 。
> > +
>    ^^^
> OK！ > +对于IPv4地址，也可以使用额外的 ``h`` ， ``n`` ， ``b`` 和 ``l`` 说
> > +明符，但对于IPv6地址则忽略。
> > +
>    ^^^
> OK！ > +通过引用传递。
> > +
> > +更多例子
> > +
> > +::
> > +
> > +     %pISfc          1.2.3.4         or [1:2:3:4:5:6:7:8]/123456789
> > +     %pISsc          1.2.3.4         or [1:2:3:4:5:6:7:8]%1234567890
> > +     %pISpfc         1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345/123456789
> > +
> > +UUID/GUID地址
> > +-------------
> > +
> > +::
> > +
> > +     %pUb    00010203-0405-0607-0809-0a0b0c0d0e0f
> > +     %pUB    00010203-0405-0607-0809-0A0B0C0D0E0F
> > +     %pUl    03020100-0504-0706-0809-0a0b0c0e0e0f
> > +     %pUL    03020100-0504-0706-0809-0A0B0C0E0E0F
> > +
> > +用于打印16字节的UUID/GUIDs地址。附加的 ``l`` , ``L`` , ``b`` 和 ``B`` 说明符用
> > +于指定小写(l)或大写(L)十六进制表示法中的小尾端顺序，以及小写(b)或大写(B)十六进制表
> > +示法中的大尾端顺序。
> > +
> > +如果没有使用额外的说明符，则将打印带有小写十六进制表示法的默认大端顺序。
> > +
>    ^^^
> OK！ > +通过引用传递。
> > +
> > +目录项（dentry）的名称
> > +----------------------
> > +
> > +::
> > +
> > +     %pd{,2,3,4}
> > +     %pD{,2,3,4}
> > +
> > +用于打印dentry名称；如果我们用 :c:func:`d_move` 和它比较，名称可能是新旧混合的，但
> > +不会oops。 %pd dentry比较安全，其相当于我们以前用的%s dentry->d_name.name，%pd<n>打
> > +印 ``n`` 最后的组件。 %pD对结构文件做同样的事情。
> > +
> > +
> > +通过引用传递。
> > +
> > +块设备（block_device）名称
> > +--------------------------
> > +
> > +::
> > +
> > +     %pg     sda, sda1 or loop0p1
> > +
> > +用于打印block_device指针的名称。
> > +
> > +va_format结构体
> > +---------------
> > +
> > +::
> > +
> > +     %pV
> > +
> > +用于打印结构体va_format。这些结构包含一个格式字符串
> > +和va_list如下
> > +
> > +::
> > +
> > +     struct va_format {
> > +             const char *fmt;
> > +             va_list *va;
> > +     };
> > +
> > +实现 "递归vsnprintf"。
> > +
> > +如果没有一些机制来验证格式字符串和va_list参数的正确性，请不要使用这个功能。
> > +
>    ^^^
> OK！ > +通过引用传递。
> > +
> > +设备树节点
> > +----------
> > +
> > +::
> > +
> > +     %pOF[fnpPcCF]
> > +
> > +
> > +用于打印设备树节点结构。默认行为相当于%pOFf。
> > +
> > +     - f - 设备节点全称
> > +     - n - 设备节点名
> > +     - p - 设备节点句柄
> > +     - P - 设备节点路径规范(名称+@单位)
> > +     - F - 设备节点标志
> > +     - c - 主要兼容字符串
> > +     - C - 全兼容字符串
> > +
> > +当使用多个参数时，分隔符是':'。
> > +
> > +例如
> > +
> > +::
> > +
> > +     %pOF    /foo/bar@0                      - Node full name
> > +     %pOFf   /foo/bar@0                      - Same as above
> > +     %pOFfp  /foo/bar@0:10                   - Node full name + phandle
> > +     %pOFfcF /foo/bar@0:foo,device:--P-      - Node full name +
> > +                                               major compatible string +
> > +                                               node flags
> > +                                                     D - dynamic
> > +                                                     d - detached
> > +                                                     P - Populated
> > +                                                     B - Populated bus
> > +
> > +通过引用传递。
> > +
> > +Fwnode handles
> > +--------------
> > +
> > +::
> > +
> > +     %pfw[fP]
> > +
> > +用于打印fwnode_handles的信息。默认情况下是打印完整的节点名称，包括路径。
> > +这些修饰符在功能上等同于上面的%pOF。
> > +
> > +     - f - 节点的全名，包括路径。
> > +     - P - 节点名称，包括地址（如果有的话）。
> > +
> > +例如 (ACPI)
> > +
> > +::
> > +
> > +     %pfwf   \_SB.PCI0.CIO2.port@1.endpoint@0        - Full node name
> > +     %pfwP   endpoint@0                              - Node name
> > +
> > +例如 (OF)
> > +
> > +::
> > +
> > +     %pfwf   /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name
> > +     %pfwP   endpoint                                - Node name
> > +
> > +时间和日期
> > +----------
> > +
> > +::
> > +
> > +     %pt[RT]                 YYYY-mm-ddTHH:MM:SS
> > +     %pt[RT]d                YYYY-mm-dd
> > +     %pt[RT]t                HH:MM:SS
> > +     %pt[RT][dt][r]
> > +
> > +用于打印日期和时间
> > +
> > +::
> > +
> > +     R  struct rtc_time structure
> > +     T  time64_t type
> > +
> > +以我们（人类）可读的格式。
> > +
> > +默认情况下，年将以1900为单位递增，月将以1为单位递增。 使用%pt[RT]r (raw)
> > +来抑制这种行为。
> > +
>    ^^^
> OK！ > +通过引用传递。
> > +
> > +clk结构体
> > +---------
> > +
> > +::
> > +
> > +     %pC     pll1
> > +     %pCn    pll1
> > +
> > +用于打印clk结构。%pC 和 %pCn 打印时钟的名称（通用时钟框架）或唯一的32位
> > +ID（传统时钟框架）。
> > +
> > +通过引用传递。
> > +
> > +位图及其衍生物，如cpumask和nodemask
> > +-----------------------------------
> > +
> > +::
> > +
> > +     %*pb    0779
> > +     %*pbl   0,3-6,8-10
> > +
> > +对于打印位图及其派生的cpumask和nodemask，%*pb输出以字段宽度为位数的位图，
> 括注 bitmap ?
> OK， 对于打印位图（bitmap）> +%*pbl输出以字段宽度为位数的范围列表。
> > +
> > +字段宽度用值传递，位图用引用传递。可以使用辅助宏cpumask_pr_args()和
> > +nodemask_pr_args()来方便打印cpumask和nodemask。
> > +
> > +标志位字段，如页标志、gfp_flags
> > +-------------------------------
> > +
> > +::
> > +
> > +     %pGp    referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff
> > +     %pGg    GFP_USER|GFP_DMA32|GFP_NOWARN
> > +     %pGv    read|exec|mayread|maywrite|mayexec|denywrite
> > +
> > +将flags位字段打印为构造值的符号常量集合。标志的类型由第三个字符给出。目前支持的
> > +是[p]age flags， [v]ma_flags(都期望 ``unsigned long *`` )和
> > +[g]fp_flags(期望 ``gfp_t *`` )。标志名称和打印顺序取决于特定的类型。
> > +
> > +注意，这种格式不应该直接用于跟踪点的:c:func: `TP_printk()` 部分。相反，应使
>                                                ^
> OK！ > +用 <trace/events/mmflags.h>中的show_*_flags()函数。
> > +
>    ^^^
> OK！
> > +通过引用传递。
> > +
> > +网络设备特性
> > +------------
> > +
> > +::
> > +
> > +     %pNF    0x000000000000c000
> > +
> > +用于打印netdev_features_t。
> > +
> > +通过引用传递。
> > +
> > +V4L2和DRM FourCC代码(像素格式)
> > +------------------------------
> > +
> > +::
> > +
> > +     %p4cc
> > +
> > +打印V4L2或DRM使用的FourCC代码，包括格式端序及其十六进制的数值。
> > +
> > +通过引用传递。
> > +
> > +例如
> > +
> > +::
> > +
> > +     %p4cc   BG12 little-endian (0x32314742)
> > +     %p4cc   Y10  little-endian (0x20303159)
> > +     %p4cc   NV12 big-endian (0xb231564e)
> > +
> > +谢谢
> > +====
> > +
> > +如果您添加了其他%p扩展，请在可行的情况下，用一个或多个测试用例扩展<lib/test_printf.c>。
> > +
> > +谢谢你的合作和关注。
> > --
> > 2.27.0
>
> Thanks,
> Wu X.C.
>
> Thank you for your review.
>
> Thanks，
>
> Yanteng

Thanks,

yanteng

Re: [PATCH 3/3] docs/zh_CN: add core-api printk-formats.rst translation

[Wu X.C.]

On Fri, Apr 23, 2021 at 11:22:48PM +0800, teng sterling wrote:
> Hi all
> 
> sorry, There are some new modify.
> 
> teng sterling <sterlingteng@gmail.com> 于2021年4月21日周三 下午3:15写道：
> >
> > Wu X.C. <bobwxc@email.cn> 于2021年4月20日周二 下午1:28写道：
> > On Mon, Apr 19, 2021 at 09:10:57PM +0800, Yanteng Si wrote:
> > > This patch translates Documentation/core-api/printk-formats.rst into Chinese.
> > >
> > > Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> > > ---
> > >  .../zh_CN/core-api/printk-formats.rst         | 577 ++++++++++++++++++
> > >  1 file changed, 577 insertions(+)
> > >  create mode 100644 Documentation/translations/zh_CN/core-api/printk-formats.rst
> > >
> > > diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> > > new file mode 100644
> > > index 000000000000..8552bbb3c797
> > > --- /dev/null
> > > +++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst
> > > +
[...]
> > > +资源（Resources）结构体
> 结构体资源（Resources）
> 
> > > +-----------------------
> > > +
> > > +::
> > > +
> > > +     %pr     [mem 0x60000000-0x6fffffff flags 0x2200] or
> > > +             [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
> > > +     %pR     [mem 0x60000000-0x6fffffff pref] or
> > > +             [mem 0x0000000060000000-0x000000006fffffff pref]
> > > +
> > > +用于打印结构资源。 ``R`` 和 ``r`` 说明符的结果是打印出的资源带有(R)或不带有(r)解码标志
> 打印结构体资源
> >            ^^^^^^^^
> > OK!

Aye.

Wu X.C.

Re: [PATCH 1/3] docs/zh_CN: add core-api kernel-api.rst translation

[Alex Shi]

On 2021/4/19 下午9:35, Matthew Wilcox wrote:
> On Mon, Apr 19, 2021 at 09:10:55PM +0800, Yanteng Si wrote:
>> This patch translates Documentation/core-api/kernel-api.rst into Chinese.
> 
> I don't speak one word of Chinese, but this can't be right?
> 
>> +列表管理函数
>> +============
>> +
>> +Todolist:
>> +
>> +   :internal:
> 
> The corresponding section in English is:
> 
> List Management Functions
> =========================
> 
> .. kernel-doc:: include/linux/list.h
>    :internal:
> 
> and surely you need a '.. kernel-doc' to have the ':internal:' make sense?
> 
> Then, I wonder how useful it is to bring kernel-doc written in English
> into a Chinese document?  Wouldn't we be better off admitting that we
> don't provide Chinese documentation for kernel APIs and referring to
> the English documents?
> 
> (I would love nothing more than to provide Chinese documentation for
> kernel APIs, but we don't have any kind of system for providing that
> today)
> 

I wouldn't reject the Chinese version of kernel-api, but a bit concern
of the subtle of the doc could be kept in translation. It would be a
big challenge. :)

Thanks
Alex

Re: [PATCH 1/3] docs/zh_CN: add core-api kernel-api.rst translation

[Matthew Wilcox]

On Fri, Apr 30, 2021 at 07:06:08PM +0800, Alex Shi wrote:
> On 2021/4/19 下午9:35, Matthew Wilcox wrote:
> > and surely you need a '.. kernel-doc' to have the ':internal:' make sense?
> > 
> > Then, I wonder how useful it is to bring kernel-doc written in English
> > into a Chinese document?  Wouldn't we be better off admitting that we
> > don't provide Chinese documentation for kernel APIs and referring to
> > the English documents?
> > 
> > (I would love nothing more than to provide Chinese documentation for
> > kernel APIs, but we don't have any kind of system for providing that
> > today)
> > 
> 
> I wouldn't reject the Chinese version of kernel-api, but a bit concern
> of the subtle of the doc could be kept in translation. It would be a
> big challenge. :)

That's a big challenge, to be sure, but logistically, where would we
keep it?

A concrete example, we have:

Documentation/core-api/xarray.rst

which has
.. kernel-doc:: lib/xarray.c

which contains:

/**
 * xas_load() - Load an entry from the XArray (advanced).
 * @xas: XArray operation state.
 *
...
 */

So where do we put the Chinese translations?  The kernel-doc is
adjacent to the function to "encourage" C programmers to keep
the documentation up to date when they change the function.
Do we also put the Chinese text in xarray.c?  Do we have a magic
Documentation/translations/zh_CN/lib/xarray.c which contains the
translations of the kernel-doc in lib/xarray.c?  Do we then have tooling
which notices that the inline documentation in lib/xarray.c has changed
and notifies the translator to keep it up-to-date?

Re: [PATCH 1/3] docs/zh_CN: add core-api kernel-api.rst translation

[Alex Shi]

On 2021/4/30 下午8:34, Matthew Wilcox wrote:
> On Fri, Apr 30, 2021 at 07:06:08PM +0800, Alex Shi wrote:
>> On 2021/4/19 下午9:35, Matthew Wilcox wrote:
>>> and surely you need a '.. kernel-doc' to have the ':internal:' make sense?
>>>
>>> Then, I wonder how useful it is to bring kernel-doc written in English
>>> into a Chinese document?  Wouldn't we be better off admitting that we
>>> don't provide Chinese documentation for kernel APIs and referring to
>>> the English documents?
>>>
>>> (I would love nothing more than to provide Chinese documentation for
>>> kernel APIs, but we don't have any kind of system for providing that
>>> today)
>>>
>>
>> I wouldn't reject the Chinese version of kernel-api, but a bit concern
>> of the subtle of the doc could be kept in translation. It would be a
>> big challenge. :)
> 
> That's a big challenge, to be sure, but logistically, where would we
> keep it?

Hi Willy,

Good question!

I have the same concern with you at the first look. But after check the
translation. I don't feel that bad. Correct Chinese version could be
read much faster and no misleading problem.

> 
> A concrete example, we have:
> 
> Documentation/core-api/xarray.rst
> 
> which has
> .. kernel-doc:: lib/xarray.c

It's a good example, I guess most descriptions in xarray.rst could be
translated for a quick reference.
On other side, Yes there do need a boundary, that would be the
real code, like lib/xarray.c. Guess we'd better stop there.


BTW, 
As to the original/translation version issue, We'd better to written
down the original commit ID in translation commit or doc properly. Then
we know the sync up time.

Thanks
Alex
 
> 
> which contains:
> 
> /**
>  * xas_load() - Load an entry from the XArray (advanced).
>  * @xas: XArray operation state.
>  *
> ...
>  */
> 
> So where do we put the Chinese translations?  The kernel-doc is
> adjacent to the function to "encourage" C programmers to keep
> the documentation up to date when they change the function.
> Do we also put the Chinese text in xarray.c?  Do we have a magic
> Documentation/translations/zh_CN/lib/xarray.c which contains the
> translations of the kernel-doc in lib/xarray.c?  Do we then have tooling
> which notices that the inline documentation in lib/xarray.c has changed
> and notifies the translator to keep it up-to-date?
>