Re: [PATCH] docs/zh_CN: Add dev-tools/kcov Chinese translation

Alex Shi
2024-04-24T03:04:44Z

On 4/23/24 10:23 PM, Haoyang Liu wrote:
> Translate dev-tools/kcov into Chinese and add it in
> dev-tools/zh_CN/index.rst.
>
> Signed-off-by: Haoyang Liu <tttturtleruss@hust.edu.cn>
> Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
> ---
> .../translations/zh_CN/dev-tools/index.rst | 2 +-
> .../translations/zh_CN/dev-tools/kcov.rst | 359 ++++++++++++++++++
> 2 files changed, 360 insertions(+), 1 deletion(-)
> create mode 100644 Documentation/translations/zh_CN/dev-tools/kcov.rst
>
> diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst
> index 51e5b3e724c1..fa900f5beb68 100644
> --- a/Documentation/translations/zh_CN/dev-tools/index.rst
> +++ b/Documentation/translations/zh_CN/dev-tools/index.rst
> @@ -22,6 +22,7 @@ Documentation/translations/zh_CN/dev-tools/testing-overview.rst
> sparse
> gcov
> kasan
> + kcov
> ubsan
> kmemleak
> gdb-kernel-debugging
> @@ -29,7 +30,6 @@ Documentation/translations/zh_CN/dev-tools/testing-overview.rst
> Todolist:
>
> - coccinelle
> - - kcov
> - kcsan
> - kfence
> - kgdb
> diff --git a/Documentation/translations/zh_CN/dev-tools/kcov.rst b/Documentation/translations/zh_CN/dev-tools/kcov.rst
> new file mode 100644
> index 000000000000..629154df7121
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/dev-tools/kcov.rst
> @@ -0,0 +1,359 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. include:: ../disclaimer-zh_CN.rst
> +
> +:Original: Documentation/dev-tools/kcov.rst
> +:Translator: 刘浩阳 Haoyang Liu <tttturtleruss@hust.edu.cn>
> +
> +KCOV: 用于模糊测试的代码覆盖率
> +==============================
> +
> +KCOV 以一种适用于覆盖率引导的模糊测试的形式收集和暴露内核代码覆盖率信息。
> +一个正在运行的内核的覆盖率数据可以通过 ``kcov`` 调试文件导出。覆盖率的收集是基
> +于任务启用的，因此 KCOV 可以精确捕获单个系统调用的覆盖率。
> +
> +要注意的是 KCOV 不是为了收集尽可能多的覆盖率数据。而是为了收集相对稳定的覆盖率
> +，这是系统调用输入的函数。为了完成这个目标，它不收集软硬中断的覆盖率（除非移除
> +覆盖率收集被启用，见下文）以及内核中固有的不确定部分的覆盖率（如调度器，锁定）
> +
> +除了收集代码覆盖率，KCOV 还收集操作数比较的覆盖率。见 "操作数比较收集" 一节
> +查看详细信息。
> +
> +除了从系统调用处理器收集覆盖率数据，KCOV 还从后台内核或软中断任务中执行的内核
> +被标注的部分收集覆盖率。见 "远程覆盖率收集" 一节查看详细信息。
> +
> +先决条件
> +--------
> +
> +KCOV 依赖编译器插桩，要求 GCC 6.1.0 及更高版本或者内核支持的任意版本的 Clang。
> +
> +收集操作数比较的覆盖率需要 GCC 8+ 或者 Clang。
> +
> +为了启用 KCOV，需要使用如下参数配置内核::
> +
> + CONFIG_KCOV=y
> +
> +为了启用操作数比较覆盖率的收集，使用如下参数::

“比较操作数” 看起来更好一些， 而不是"操作数比较"

> +
> + CONFIG_KCOV_ENABLE_COMPARISONS=y
> +
> +覆盖率数据只会在调试文件系统被挂载后才可以获取::
> +
> + mount -t debugfs none /sys/kernel/debug
> +
> +覆盖率收集
> +----------
> +
> +下面的程序演示了如何使用 KCOV 在一个测试程序中收集单个系统调用的覆盖率：
> +
> +.. code-block:: c
> +
> + #include <stdio.h>
> + #include <stddef.h>
> + #include <stdint.h>
> + #include <stdlib.h>
> + #include <sys/types.h>
> + #include <sys/stat.h>
> + #include <sys/ioctl.h>
> + #include <sys/mman.h>
> + #include <unistd.h>
> + #include <fcntl.h>
> + #include <linux/types.h>
> +
> + #define KCOV_INIT_TRACE _IOR('c', 1, unsigned long)
> + #define KCOV_ENABLE _IO('c', 100)
> + #define KCOV_DISABLE _IO('c', 101)
> + #define COVER_SIZE (64<<10)
> +
> + #define KCOV_TRACE_PC 0
> + #define KCOV_TRACE_CMP 1
> +
> + int main(int argc, char **argv)
> + {
> + int fd;
> + unsigned long *cover, n, i;
> +
> + /* 单个文件描述符允许
> + * 在单线程上收集覆盖率。
> + */
> + fd = open("/sys/kernel/debug/kcov", O_RDWR);
> + if (fd == -1)
> + perror("open"), exit(1);
> + /* 设置跟踪模式和跟踪大小。 */
> + if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE))
> + perror("ioctl"), exit(1);
> + /* 映射内核空间和用户空间共享的缓冲区。 */
> + cover = (unsigned long*)mmap(NULL, COVER_SIZE * sizeof(unsigned long),
> + PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
> + if ((void*)cover == MAP_FAILED)
> + perror("mmap"), exit(1);
> + /* 在当前线程中启用覆盖率收集。 */
> + if (ioctl(fd, KCOV_ENABLE, KCOV_TRACE_PC))
> + perror("ioctl"), exit(1);
> + /* 在调用 ioctl() 之后重置覆盖率。 */
> + __atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED);
> + /* 调用目标系统调用。 */
> + read(-1, NULL, 0);
> + /* 读取收集到的 PC 的数目。 */
> + n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED);
> + for (i = 0; i < n; i++)
> + printf("0x%lx\n", cover[i + 1]);
> + /* 在当前线程上禁用覆盖率收集。在这之后
> + * 可以在其他线程上收集覆盖率
> + */
> + if (ioctl(fd, KCOV_DISABLE, 0))
> + perror("ioctl"), exit(1);
> + /* 释放资源 */
> + if (munmap(cover, COVER_SIZE * sizeof(unsigned long)))
> + perror("munmap"), exit(1);
> + if (close(fd))
> + perror("close"), exit(1);
> + return 0;
> + }
> +
> +在使用 ``addr2line`` 传输后，程序输出应该如下所示::
> +
> + SyS_read
> + fs/read_write.c:562
> + __fdget_pos
> + fs/file.c:774
> + __fget_light
> + fs/file.c:746
> + __fget_light
> + fs/file.c:750
> + __fget_light
> + fs/file.c:760
> + __fdget_pos
> + fs/file.c:784
> + SyS_read
> + fs/read_write.c:562
> +
> +如果一个程序需要从多个线程收集覆盖率（独立地）。那么每个线程都需要单独打开
> +``/sys/kernel/debug/kcov``。
> +
> +接口的细粒度允许高效的创建测试进程。即，一个父进程打开了
> +``/sys/kernel/debug/kcov``，启用了追踪模式，映射了覆盖率缓冲区，然后在一个循
> +环中创建了子进程。这个子进程只需要启用覆盖率收集即可（当一个线程退出时将自动禁
> +用覆盖率收集）。
> +
> +操作数比较收集

ditto

others LGTM

Reviewed-by: Alex Shi <alexs@kernel.org>