diff options
Diffstat (limited to 'Documentation/translations/zh_CN')
23 files changed, 1976 insertions, 108 deletions
diff --git a/Documentation/translations/zh_CN/dev-tools/gcov.rst b/Documentation/translations/zh_CN/dev-tools/gcov.rst index 3158c9da1318..ea8f94852f41 100644 --- a/Documentation/translations/zh_CN/dev-tools/gcov.rst +++ b/Documentation/translations/zh_CN/dev-tools/gcov.rst @@ -120,7 +120,7 @@ gcov的内核分析插桩支持内核的编译和运行是在同一台机器上 如果内核编译和运行是不同的机器，那么需要额外的准备工作，这取决于gcov工具 是在哪里使用的: -.. _gcov-test_zh: +.. _gcov-test_zh_CN: a) 若gcov运行在测试机上 @@ -140,7 +140,7 @@ a) 若gcov运行在测试机上 如果文件是软链接，需要替换成真正的目录文件（这是由make的当前工作 目录变量CURDIR引起的）。 -.. _gcov-build_zh: +.. _gcov-build_zh_CN: b) 若gcov运行在编译机上 @@ -205,7 +205,7 @@ kconfig会根据编译工具链的检查自动选择合适的gcov格式。 -------------------------- 用于在编译机上收集覆盖率元文件的示例脚本 -（见 :ref:`编译机和测试机分离 a. <gcov-test_zh>` ） +（见 :ref:`编译机和测试机分离 a. <gcov-test_zh_CN>` ） .. code-block:: sh @@ -238,7 +238,7 @@ kconfig会根据编译工具链的检查自动选择合适的gcov格式。 ------------------------- 用于在测试机上收集覆盖率数据文件的示例脚本 -（见 :ref:`编译机和测试机分离 b. <gcov-build_zh>` ） +（见 :ref:`编译机和测试机分离 b. <gcov-build_zh_CN>` ） .. code-block:: sh diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rst index 6a8c637c0be1..7b37194217b0 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 kcov kcsan + kmsan gcov kasan ubsan @@ -32,7 +33,6 @@ Todolist: - checkpatch - coccinelle - - kmsan - kfence - kgdb - kselftest diff --git a/Documentation/translations/zh_CN/dev-tools/kmsan.rst b/Documentation/translations/zh_CN/dev-tools/kmsan.rst new file mode 100644 index 000000000000..b1ddb47bd6c4 --- /dev/null +++ b/Documentation/translations/zh_CN/dev-tools/kmsan.rst @@ -0,0 +1,392 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/dev-tools/kmsan.rst +:Translator: 刘浩阳 Haoyang Liu <tttturtleruss@hust.edu.cn> + +======================= +内核内存消毒剂（KMSAN） +======================= + +KMSAN 是一个动态错误检测器，旨在查找未初始化值的使用。它基于编译器插桩，类似于用 +户空间的 `MemorySanitizer tool`_。 + +需要注意的是 KMSAN 并不适合生产环境，因为它会大幅增加内核内存占用并降低系统运行速度。 + +使用方法 +======== + +构建内核 +-------- + +要构建带有 KMSAN 的内核，你需要一个较新的 Clang (14.0.6+)。 +请参阅 `LLVM documentation`_ 了解如何构建 Clang。 + +现在配置并构建一个启用 CONFIG_KMSAN 的内核。 + +示例报告 +-------- + +以下是一个 KMSAN 报告的示例:: + + ===================================================== + BUG: KMSAN: uninit-value in test_uninit_kmsan_check_memory+0x1be/0x380 [kmsan_test] + test_uninit_kmsan_check_memory+0x1be/0x380 mm/kmsan/kmsan_test.c:273 + kunit_run_case_internal lib/kunit/test.c:333 + kunit_try_run_case+0x206/0x420 lib/kunit/test.c:374 + kunit_generic_run_threadfn_adapter+0x6d/0xc0 lib/kunit/try-catch.c:28 + kthread+0x721/0x850 kernel/kthread.c:327 + ret_from_fork+0x1f/0x30 ??:? + + Uninit was stored to memory at: + do_uninit_local_array+0xfa/0x110 mm/kmsan/kmsan_test.c:260 + test_uninit_kmsan_check_memory+0x1a2/0x380 mm/kmsan/kmsan_test.c:271 + kunit_run_case_internal lib/kunit/test.c:333 + kunit_try_run_case+0x206/0x420 lib/kunit/test.c:374 + kunit_generic_run_threadfn_adapter+0x6d/0xc0 lib/kunit/try-catch.c:28 + kthread+0x721/0x850 kernel/kthread.c:327 + ret_from_fork+0x1f/0x30 ??:? + + Local variable uninit created at: + do_uninit_local_array+0x4a/0x110 mm/kmsan/kmsan_test.c:256 + test_uninit_kmsan_check_memory+0x1a2/0x380 mm/kmsan/kmsan_test.c:271 + + Bytes 4-7 of 8 are uninitialized + Memory access of size 8 starts at ffff888083fe3da0 + + CPU: 0 PID: 6731 Comm: kunit_try_catch Tainted: G B E 5.16.0-rc3+ #104 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014 + ===================================================== + +报告指出本地变量 ``uninit`` 在 ``do_uninit_local_array()`` 中未初始化。 +第三个堆栈跟踪对应于该变量创建的位置。 + +第一个堆栈跟踪显示了未初始化值的使用位置（在 +``test_uninit_kmsan_check_memory()``）。 +工具显示了局部变量中未初始化的字节及其被复制到其他内存位置前的堆栈。 + +KMSAN 会在以下情况下报告未初始化的值 ``v``: + + - 在条件判断中，例如 ``if (v) { ... }``； + - 在索引或指针解引用中，例如 ``array[v]`` 或 ``*v``； + - 当它被复制到用户空间或硬件时，例如 ``copy_to_user(..., &v, ...)``； + - 当它作为函数参数传递，并且启用 ``CONFIG_KMSAN_CHECK_PARAM_RETVAL`` 时（见下文）。 + +这些情况（除了复制数据到用户空间或硬件外，这是一个安全问题）被视为 C11 标准下的未定义行为。 + +禁用插桩 +-------- + +可以用 ``__no_kmsan_checks`` 标记函数。这样，KMSAN 会忽略该函数中的未初始化值， +并将其输出标记为已初始化。如此，用户不会收到与该函数相关的 KMSAN 报告。 + +KMSAN 还支持 ``__no_sanitize_memory`` 函数属性。KMSAN 不会对拥有该属性的函数进行 +插桩，这在我们不希望编译器干扰某些底层代码（例如标记为 ``noinstr`` 的代码，该 +代码隐式添加了 ``__no_sanitize_memory``）时可能很有用。 + +然而，这会有代价：此类函数的栈分配将具有不正确的影子/初始值，可能导致误报。来 +自非插桩代码的函数也可能接收到不正确的元数据。 + + +作为经验之谈，避免显式使用 ``__no_sanitize_memory``。 + +也可以通过 Makefile 禁用 KMSAN 对某个文件（例如 main.o）的作用:: + + KMSAN_SANITIZE_main.o := n + +或者对整个目录:: + + KMSAN_SANITIZE := n + +将其应用到文件或目录中的每个函数。大多数用户不会需要 KMSAN_SANITIZE， +除非他们的代码被 KMSAN 破坏（例如在早期启动时运行的代码）。 + +还可以通过调用 ``kmsan_disable_current()`` 和 ``kmsan_enable_current()`` +暂时对当前任务禁用 KMSAN 检查。每个 ``kmsan_enable_current()`` 必须在 +``kmsan_disable_current()`` 之后调用；这些调用对可以嵌套。在调用时需要注意保持 +嵌套区域简短，并且尽可能使用其他方法禁用插桩。 + +支持 +==== + +为了使用 KMSAN，内核必须使用 Clang 构建，到目前为止，Clang 是唯一支持 KMSAN +的编译器。内核插桩过程基于用户空间的 `MemorySanitizer tool`_。 + +目前运行时库仅支持 x86_64 架构。 + +KMSAN 的工作原理 +================ + +KMSAN 阴影内存 +-------------- + +KMSAN 将一个元数据字节（也称为阴影字节）与每个内核内存字节关联。仅当内核内存字节 +的相应位未初始化时，阴影字节中的一个比特位才会被设置。将内存标记为未初始化（即 +将其阴影字节设置为 ``0xff``）称为中毒，将其标记为已初始化（将阴影字节设置为 +``0x00``）称为解毒。 + +当在栈上分配新变量时，默认情况下它会中毒，这由编译器插入的插桩代码完成（除非它 +是立即初始化的栈变量）。任何未使用 ``__GFP_ZERO`` 的堆分配也会中毒。 + +编译器插桩还跟踪阴影值在代码中的使用。当需要时，插桩代码会调用 ``mm/kmsan/`` 中 +的运行时库以持久化阴影值。 + +基本或复合类型的阴影值是长度相同的字节数组。当常量值写入内存时，该内存会被解毒 +。当从内存读取值时，其阴影内存也会被获取，并传递到所有使用该值的操作中。对于每 +个需要一个或多个值的指令，编译器会生成代码根据这些值及其阴影来计算结果的阴影。 + + +示例:: + + int a = 0xff; // i.e. 0x000000ff + int b; + int c = a | b; + +在这种情况下， ``a`` 的阴影为 ``0``， ``b`` 的阴影为 ``0xffffffff``， +``c`` 的阴影为 ``0xffffff00``。这意味着 ``c`` 的高三个字节未初始化，而低字节已 +初始化。 + +起源跟踪 +-------- + +每四字节的内核内存都有一个所谓的源点与之映射。这个源点描述了在程序执行中，未初 +始化值的创建点。每个源点都与完整的分配栈（对于堆分配的内存）或包含未初始化变 +量的函数（对于局部变量）相关联。 + +当一个未初始化的变量在栈或堆上分配时，会创建一个新的源点值，并将该变量的初始值 +填充为这个值。当从内存中读取一个值时，其初始值也会被读取并与阴影一起保留。对于 +每个接受一个或多个值的指令，结果的源点是与任何未初始化输入相对应的源点之一。如 +果一个污染值被写入内存，其起源也会被写入相应的存储中。 + +示例 1:: + + int a = 42; + int b; + int c = a + b; + +在这种情况下， ``b`` 的源点是在函数入口时生成的，并在加法结果写入内存之前存储到 +``c`` 的源点中。 + +如果几个变量共享相同的源点地址，则它们被存储在同一个四字节块中。在这种情况下， +对任何变量的每次写入都会更新所有变量的源点。在这种情况下我们必须牺牲精度，因 +为为单独的位（甚至字节）存储源点成本过高。 + +示例 2:: + + int combine(short a, short b) { + union ret_t { + int i; + short s[2]; + } ret; + ret.s[0] = a; + ret.s[1] = b; + return ret.i; + } + +如果 ``a`` 已初始化而 ``b`` 未初始化，则结果的阴影为 0xffff0000，结果的源点为 +``b`` 的源点。 ``ret.s[0]`` 会有相同的起源，但它不会被使用，因为该变量已初始化。 + +如果两个函数参数都未初始化，则只保留第二个参数的源点。 + +源点链 +~~~~~~ + +为了便于调试，KMSAN 在每次将未初始化值存储到内存时都会创建一个新的源点。新的源点 +引用了其创建栈以及值的前一个起源。这可能导致内存消耗增加，因此我们在运行时限制 +了源点链的长度。 + +Clang 插桩 API +-------------- + +Clang 插桩通过在内核代码中插入定义在 ``mm/kmsan/instrumentation.c`` 中的函数调用 +来实现。 + + +阴影操作 +~~~~~~~~ + +对于每次内存访问，编译器都会发出一个函数调用，该函数返回一对指针，指向给定内存 +的阴影和原始地址:: + + typedef struct { + void *shadow, *origin; + } shadow_origin_ptr_t + + shadow_origin_ptr_t __msan_metadata_ptr_for_load_{1,2,4,8}(void *addr) + shadow_origin_ptr_t __msan_metadata_ptr_for_store_{1,2,4,8}(void *addr) + shadow_origin_ptr_t __msan_metadata_ptr_for_load_n(void *addr, uintptr_t size) + shadow_origin_ptr_t __msan_metadata_ptr_for_store_n(void *addr, uintptr_t size) + +函数名依赖于内存访问的大小。 + +编译器确保对于每个加载的值，其阴影和原始值都从内存中读取。当一个值存储到内存时 +，其阴影和原始值也会通过元数据指针进行存储。 + +处理局部变量 +~~~~~~~~~~~~ + +一个特殊的函数用于为局部变量创建一个新的原始值，并将该变量的原始值设置为该值:: + + void __msan_poison_alloca(void *addr, uintptr_t size, char *descr) + +访问每个任务数据 +~~~~~~~~~~~~~~~~ + +在每个插桩函数的开始处，KMSAN 插入一个对 ``__msan_get_context_state()`` 的调用 +:: + + kmsan_context_state *__msan_get_context_state(void) + +``kmsan_context_state`` 在 ``include/linux/kmsan.h`` 中声明:: + + struct kmsan_context_state { + char param_tls[KMSAN_PARAM_SIZE]; + char retval_tls[KMSAN_RETVAL_SIZE]; + char va_arg_tls[KMSAN_PARAM_SIZE]; + char va_arg_origin_tls[KMSAN_PARAM_SIZE]; + u64 va_arg_overflow_size_tls; + char param_origin_tls[KMSAN_PARAM_SIZE]; + depot_stack_handle_t retval_origin_tls; + }; + +KMSAN 使用此结构体在插桩函数之间传递参数阴影和原始值（除非立刻通过 + ``CONFIG_KMSAN_CHECK_PARAM_RETVAL`` 检查参数）。 + +将未初始化的值传递给函数 +~~~~~~~~~~~~~~~~~~~~~~~~ + +Clang 的 MemorySanitizer 插桩有一个选项 ``-fsanitize-memory-param-retval``，该 +选项使编译器检查按值传递的函数参数，以及函数返回值。 + +该选项由 ``CONFIG_KMSAN_CHECK_PARAM_RETVAL`` 控制，默认启用以便 KMSAN 更早报告 +未初始化的值。有关更多细节，请参考 `LKML discussion`_。 + +由于 LLVM 中的实现检查的方式（它们仅应用于标记为 ``noundef`` 的参数），并不是所 +有参数都能保证被检查，因此我们不能放弃 ``kmsan_context_state`` 中的元数据存储 +。 + +字符串函数 +~~~~~~~~~~~ + +编译器将对 ``memcpy()``/``memmove()``/``memset()`` 的调用替换为以下函数。这些函 +数在数据结构初始化或复制时也会被调用，确保阴影和原始值与数据一起复制:: + + void *__msan_memcpy(void *dst, void *src, uintptr_t n) + void *__msan_memmove(void *dst, void *src, uintptr_t n) + void *__msan_memset(void *dst, int c, uintptr_t n) + +错误报告 +~~~~~~~~ + +对于每个值的使用，编译器发出一个阴影检查，在值中毒的情况下调用 +``__msan_warning()``:: + + void __msan_warning(u32 origin) + +``__msan_warning()`` 使 KMSAN 运行时打印错误报告。 + +内联汇编插桩 +~~~~~~~~~~~~ + +KMSAN 对每个内联汇编输出进行插桩，调用:: + + void __msan_instrument_asm_store(void *addr, uintptr_t size) + +，该函数解除内存区域的污染。 + +这种方法可能会掩盖某些错误，但也有助于避免许多位操作、原子操作等中的假阳性。 + +有时传递给内联汇编的指针不指向有效内存。在这种情况下，它们在运行时被忽略。 + + +运行时库 +-------- + +代码位于 ``mm/kmsan/``。 + +每个任务 KMSAN 状态 +~~~~~~~~~~~~~~~~~~~ + +每个 task_struct 都有一个关联的 KMSAN 任务状态，它保存 KMSAN +上下文（见上文）和一个每个任务计数器以禁止 KMSAN 报告:: + + struct kmsan_context { + ... + unsigned int depth; + struct kmsan_context_state cstate; + ... + } + + struct task_struct { + ... + struct kmsan_context kmsan; + ... + } + +KMSAN 上下文 +~~~~~~~~~~~~ + +在内核任务上下文中运行时，KMSAN 使用 ``current->kmsan.cstate`` 来 +保存函数参数和返回值的元数据。 + +但在内核运行于中断、softirq 或 NMI 上下文中， ``current`` 不可用时， +KMSAN 切换到每 CPU 中断状态:: + + DEFINE_PER_CPU(struct kmsan_ctx, kmsan_percpu_ctx); + +元数据分配 +~~~~~~~~~~ + +内核中有多个地方存储元数据。 + +1. 每个 ``struct page`` 实例包含两个指向其影子和内存页面的指针 +:: + + struct page { + ... + struct page *shadow, *origin; + ... + }; + +在启动时，内核为每个可用的内核页面分配影子和源页面。这是在内核地址空间已经碎片 +化时后完成的，完成的相当晚，因此普通数据页面可能与元数据页面任意交错。 + +这意味着通常两个相邻的内存页面，它们的影子/源页面可能不是连续的。因此，如果内存 +访问跨越内存块的边界，访问影子/源内存可能会破坏其他页面或从中读取错误的值。 + +实际上，由相同 ``alloc_pages()`` 调用返回的连续内存页面将具有连续的元数据，而 +如果这些页面属于两个不同的分配，它们的元数据页面可能会被碎片化。 + +对于内核数据（ ``.data``、 ``.bss`` 等）和每 CPU 内存区域，也没有对元数据连续 +性的保证。 + +在 ``__msan_metadata_ptr_for_XXX_YYY()`` 遇到两个页面之间的 +非连续元数据边界时，它返回指向假影子/源区域的指针:: + + char dummy_load_page[PAGE_SIZE] __attribute__((aligned(PAGE_SIZE))); + char dummy_store_page[PAGE_SIZE] __attribute__((aligned(PAGE_SIZE))); + +``dummy_load_page`` 被初始化为零，因此读取它始终返回零。对 ``dummy_store_page`` 的 +所有写入都被忽略。 + +2. 对于 vmalloc 内存和模块，内存范围、影子和源之间有一个直接映射。KMSAN 将 +vmalloc 区域缩小了 3/4，仅使前四分之一可用于 ``vmalloc()``。vmalloc +区域的第二个四分之一包含第一个四分之一的影子内存，第三个四分之一保存源。第四个 +四分之一的小部分包含内核模块的影子和源。有关更多详细信息，请参阅 +``arch/x86/include/asm/pgtable_64_types.h``。 + +当一系列页面映射到一个连续的虚拟内存空间时，它们的影子和源页面也以连续区域的方 +式映射。 + +参考文献 +======== + +E. Stepanov, K. Serebryany. `MemorySanitizer: fast detector of uninitialized +memory use in C++ +<https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/43308.pdf>`_. +In Proceedings of CGO 2015. + +.. _MemorySanitizer tool: https://clang.llvm.org/docs/MemorySanitizer.html +.. _LLVM documentation: https://llvm.org/docs/GettingStarted.html +.. _LKML discussion: https://lore.kernel.org/all/20220614144853.3693273-1-glider@google.com/ diff --git a/Documentation/translations/zh_CN/glossary.rst b/Documentation/translations/zh_CN/glossary.rst index 24f094df97cd..5975b0426f3d 100644 --- a/Documentation/translations/zh_CN/glossary.rst +++ b/Documentation/translations/zh_CN/glossary.rst @@ -34,3 +34,4 @@ * semaphores: 信号量。 * spinlock: 自旋锁。 * watermark: 水位，一般指页表的消耗水平。 +* PTE: 页表项。（Page Table Entry） diff --git a/Documentation/translations/zh_CN/kbuild/index.rst b/Documentation/translations/zh_CN/kbuild/index.rst index b51655d981f6..3f9ab52fa5bb 100644 --- a/Documentation/translations/zh_CN/kbuild/index.rst +++ b/Documentation/translations/zh_CN/kbuild/index.rst @@ -12,20 +12,21 @@ .. toctree:: :maxdepth: 1 + kconfig headers_install gcc-plugins + kbuild + reproducible-builds + llvm TODO: - kconfig-language - kconfig-macro-language -- kbuild -- kconfig - makefiles - modules - issues -- reproducible-builds -- llvm + .. only:: subproject and html diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/translations/zh_CN/kbuild/kbuild.rst new file mode 100644 index 000000000000..e5e2aebe1ebc --- /dev/null +++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst @@ -0,0 +1,304 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kbuild/kbuild.rst +:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn> + +====== +Kbuild +====== + + +输出文件 +======== + +modules.order +------------- +该文件记录模块在 Makefile 中出现的顺序。modprobe 使用该文件来确定性 +解析匹配多个模块的别名。 + +modules.builtin +--------------- +该文件列出了所有内置到内核中的模块。modprobe 使用该文件来避免尝试加载 +内置模块时出错。 + +modules.builtin.modinfo +----------------------- +该文件包含所有内置模块的 modinfo。与单独模块的 modinfo 不同，所有字段 +都带有模块名称前缀。 + +modules.builtin.ranges +---------------------- +该文件包含所有内核内置模块的地址偏移范围（每个 ELF 节）。结合 System.map +文件，它可以用来将模块名称与符号关联起来。 + +环境变量 +======== + +KCPPFLAGS +--------- +在预处理时传递的额外选项。kbuild 进行所有预处理（包括构建 C 文件和汇编文件） +时，都会使用这些预处理选项。 + +KAFLAGS +------- +传递给汇编器的额外选项（适用于内置模块和外部模块）。 + +AFLAGS_MODULE +------------- +外部模块的额外汇编选项。 + +AFLAGS_KERNEL +------------- +内置模块的额外汇编选项。 + +KCFLAGS +------- +传递给 C 编译器的额外选项（适用于内置模块和外部模块）。 + +KRUSTFLAGS +---------- +传递给 Rust 编译器的额外选项（适用于内置模块和外部模块）。 + +CFLAGS_KERNEL +------------- +在编译内置代码时，传递给 $(CC) 的额外选项。 + +CFLAGS_MODULE +------------- +编译外部模块时，传递给 $(CC) 的额外模块特定选项。 + +RUSTFLAGS_KERNEL +---------------- +在编译内置代码时，传递给 $(RUSTC) 的额外选项。 + +RUSTFLAGS_MODULE +---------------- +用于 $(RUSTC) 的额外模块特定选项。 + +LDFLAGS_MODULE +-------------- +用于 $(LD) 链接模块时的额外选项。 + +HOSTCFLAGS +---------- +在构建主机程序时传递给 $(HOSTCC) 的额外标志。 + +HOSTCXXFLAGS +------------ +在构建主机程序时传递给 $(HOSTCXX) 的额外标志。 + +HOSTRUSTFLAGS +------------- +在构建主机程序时传递给 $(HOSTRUSTC) 的额外标志。 + +HOSTLDFLAGS +----------- +链接主机程序时传递的额外选项。 + +HOSTLDLIBS +---------- +在构建主机程序时链接的额外库。 + +.. _zh_cn_userkbuildflags: + +USERCFLAGS +---------- +用于 $(CC) 编译用户程序（userprogs）时的额外选项。 + +USERLDFLAGS +----------- +用于 $(LD) 链接用户程序时的额外选项。用户程序（userprogs）是使用 CC 链接的， +因此 $(USERLDFLAGS) 应该根据需要包含 "-Wl," 前缀。 + +KBUILD_KCONFIG +-------------- +将顶级 Kconfig 文件设置为此环境变量的值。默认名称为 "Kconfig"。 + +KBUILD_VERBOSE +-------------- +设置 kbuild 的详细程度。可以分配与 "V=..." 相同的值。 + +有关完整列表，请参见 `make help`。 + +设置 "V=..." 优先于 KBUILD_VERBOSE。 + +KBUILD_EXTMOD +------------- +在构建外部模块时设置内核源代码的搜索目录。 + +设置 "M=..." 优先于 KBUILD_EXTMOD。 + +KBUILD_OUTPUT +------------- +指定内核构建的输出目录。 + +在单独的构建目录中为预构建内核构建外部模块时，这个变量也可以指向内核输出目录。请注意， +这并不指定外部模块本身的输出目录。 + +输出目录也可以使用 "O=..." 指定。 + +设置 "O=..." 优先于 KBUILD_OUTPUT。 + +KBUILD_EXTRA_WARN +----------------- +指定额外的构建检查。也可以通过在命令行传递 "W=..." 来设置相同的值。 + +请参阅 `make help` 了解支持的值列表。 + +设置 "W=..." 优先于 KBUILD_EXTRA_WARN。 + +KBUILD_DEBARCH +-------------- +对于 deb-pkg 目标，允许覆盖 deb-pkg 部署的正常启发式方法。通常 deb-pkg 尝试根据 +UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确的架构。KBUILD_DEBARCH +的值假定（不检查）为有效的 Debian 架构。 + +KDOCFLAGS +--------- +指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看 +scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。 + +ARCH +---- +设置 ARCH 为要构建的架构。 + +在大多数情况下，架构的名称与 arch/ 目录中的子目录名称相同。 + +但某些架构（如 x86 和 sparc）有别名。 + +- x86: i386 表示 32 位，x86_64 表示 64 位 +- parisc: parisc64 表示 64 位 +- sparc: sparc32 表示 32 位，sparc64 表示 64 位 + +CROSS_COMPILE +------------- +指定 binutils 文件名的可选固定部分。CROSS_COMPILE 可以是文件名的一部分或完整路径。 + +在某些设置中，CROSS_COMPILE 也用于 ccache。 + +CF +-- +用于 sparse 的额外选项。 + +CF 通常在命令行中如下所示使用:: + + make CF=-Wbitwise C=2 + +INSTALL_PATH +------------ +INSTALL_PATH 指定放置更新后的内核和系统映像的路径。默认值是 /boot，但你可以设置 +为其他值。 + +INSTALLKERNEL +------------- +使用 "make install" 时调用的安装脚本。 +默认名称是 "installkernel"。 + +该脚本将会以以下参数调用： + + - $1 - 内核版本 + - $2 - 内核映像文件 + - $3 - 内核映射文件 + - $4 - 默认安装路径（如果为空，则使用根目录） + +"make install" 的实现是架构特定的，可能与上述有所不同。 + +提供 INSTALLKERNEL 以便在交叉编译内核时可以指定自定义安装程序。 + +MODLIB +------ +指定模块的安装位置。 +默认值为:: + + $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE) + +该值可以被覆盖，在这种情况下将忽略默认值。 + +INSTALL_MOD_PATH +---------------- +INSTALL_MOD_PATH 指定了模块目录重定位时 MODLIB 的前缀，通常由构建根 +（build roots）所需。它没有在 makefile 中定义，但如果需要，可以作为 +参数传递给 make。 + +INSTALL_MOD_STRIP +----------------- +如果 INSTALL_MOD_STRIP 被定义，内核模块在安装后会被剥离。如果 +INSTALL_MOD_STRIP 的值为 '1'，则会使用默认选项 --strip-debug。否则， +INSTALL_MOD_STRIP 的值将作为 strip 命令的选项。 + +INSTALL_HDR_PATH +---------------- +INSTALL_HDR_PATH 指定了执行 "make headers_*" 时，用户空间头文件的安装位置。 + +默认值为:: + + $(objtree)/usr + +$(objtree) 是保存输出文件的目录。 +输出目录通常使用命令行中的 "O=..." 进行设置。 + +该值可以被覆盖，在这种情况下将忽略默认值。 + +INSTALL_DTBS_PATH +----------------- +INSTALL_DTBS_PATH 指定了设备树二进制文件的安装位置，通常由构建根（build roots）所需。 +它没有在 makefile 中定义，但如果需要，可以作为参数传递给 make。 + +KBUILD_ABS_SRCTREE +-------------------------------------------------- +Kbuild 在可能的情况下使用相对路径指向源代码树。例如，在源代码树中构建时，源代码树路径是 +'.'。 + +设置该标志请求 Kbuild 使用源代码树的绝对路径。 +在某些情况下这是有用的，例如在生成带有绝对路径条目的标签文件时等。 + +KBUILD_SIGN_PIN +--------------- +当签署内核模块时，如果私钥需要密码或 PIN，此变量允许将密码或 PIN 传递给 sign-file 工具。 + +KBUILD_MODPOST_WARN +------------------- +KBUILD_MODPOST_WARN 可以设置为在最终模块链接阶段出现未定义符号时避免错误。它将这些错误 +转为警告。 + +KBUILD_MODPOST_NOFINAL +---------------------- +KBUILD_MODPOST_NOFINAL 可以设置为跳过模块的最终链接。这仅在加速编译测试时有用。 + +KBUILD_EXTRA_SYMBOLS +-------------------- +用于依赖其他模块符号的模块。详见 modules.rst。 + +ALLSOURCE_ARCHS +--------------- +对于 tags/TAGS/cscope 目标，可以指定包含在数据库中的多个架构，用空格分隔。例如:: + + $ make ALLSOURCE_ARCHS="x86 mips arm" tags + +要获取所有可用架构，也可以指定 all。例如:: + + $ make ALLSOURCE_ARCHS=all tags + +IGNORE_DIRS +----------- +对于 tags/TAGS/cscope 目标，可以选择不包含在数据库中的目录，用空格分隔。例如:: + + $ make IGNORE_DIRS="drivers/gpu/drm/radeon tools" cscope + +KBUILD_BUILD_TIMESTAMP +---------------------- +将该环境变量设置为日期字符串，可以覆盖在 UTS_VERSION 定义中使用的时间戳 +（运行内核时的 uname -v）。该值必须是一个可以传递给 date -d 的字符串。默认值是 +内核构建某个时刻的 date 命令输出。 + +KBUILD_BUILD_USER, KBUILD_BUILD_HOST +------------------------------------ +这两个变量允许覆盖启动时显示的 user@host 字符串以及 /proc/version 中的信息。 +默认值分别是 whoami 和 host 命令的输出。 + +LLVM +---- +如果该变量设置为 1，Kbuild 将使用 Clang 和 LLVM 工具，而不是 GCC 和 GNU +binutils 来构建内核。 diff --git a/Documentation/translations/zh_CN/kbuild/kconfig.rst b/Documentation/translations/zh_CN/kbuild/kconfig.rst new file mode 100644 index 000000000000..3b06d8913dbf --- /dev/null +++ b/Documentation/translations/zh_CN/kbuild/kconfig.rst @@ -0,0 +1,259 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kbuild/kconfig.rst +:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn> + +================ +配置目标和编辑器 +================ + +本文件包含使用 ``make *config`` 的一些帮助。 + +使用 ``make help`` 列出所有可能的配置目标。 + +xconfig（'qconf'）、menuconfig（'mconf'）和 nconfig（'nconf'）程序也包含 +内嵌的帮助文本。请务必查看这些帮助文本以获取导航、搜索和其他帮助信息。 + +gconfig（'gconf'）程序的帮助文本较少。 + + +通用信息 +======== + +新的内核版本通常会引入新的配置符号。更重要的是，新的内核版本可能会重命名配置符号。 +当这种情况发生时，使用之前正常工作的 .config 文件并运行 "make oldconfig" +不一定会生成一个可正常工作的新内核，因此，你可能需要查看哪些新的内核符号被引入。 + +要查看新配置符号的列表，请使用:: + + cp user/some/old.config .config + make listnewconfig + +配置程序将列出所有新配置符号，每行一个。 + +或者，你可以使用暴力破解方法:: + + make oldconfig + scripts/diffconfig .config.old .config | less + + +环境变量 +======== + +``*config`` 的环境变量： + +``KCONFIG_CONFIG`` + 该环境变量可用于指定一个默认的内核配置文件名，以覆盖默认的 ".config"。 + +``KCONFIG_DEFCONFIG_LIST`` + 该环境变量指定了一个配置文件列表，当 .config 不存在时，这些文件可用作基础配置。 + 列表中的条目以空格分隔，只有第一个存在的文件会被使用。 + +``KCONFIG_OVERWRITECONFIG`` + 如果该环境变量被设置，当 .config 是指向其他位置的符号链接时，Kconfig 不会 + 破坏符号链接。 + +``KCONFIG_WARN_UNKNOWN_SYMBOLS`` + 该环境变量使 Kconfig 对配置输入中所有无法识别的符号发出警告。 + +``KCONFIG_WERROR`` + 如果该环境变量被设置，Kconfig 将所有警告视为错误。 + +``CONFIG_`` + 如果该环境变量被设置，Kconfig 将在保存配置时，为所有符号添加其值作为前缀， + 而不是使用默认值。 + +``{allyes/allmod/allno/rand}config`` 的环境变量： + +``KCONFIG_ALLCONFIG`` + allyesconfig/allmodconfig/allnoconfig/randconfig 这些变体也可以使用环境 + 变量 KCONFIG_ALLCONFIG 作为标志或包含用户要求设置为特定值的配置符号的文件名。 + 如果 KCONFIG_ALLCONFIG 未指定文件名，即 KCONFIG_ALLCONFIG == "" 或 + KCONFIG_ALLCONFIG == "1"，则 ``make *config`` 将查找名为 + "all{yes/mod/no/def/random}.config" 的文件（对应于所使用的 ``*config`` + 命令）以强制符号值。如果找不到此文件，它会查找名为 "all.config" 的文件以包含 + 强制值。 + + 这可以创建“微型”配置（miniconfig）或自定义配置文件，其中仅包含感兴趣的配置符号。 + 然后，内核配置系统将生成完整的 .config 文件，包括 miniconfig 文件中的符号。 + + ``KCONFIG_ALLCONFIG`` 文件包含许多预设配置符号（通常是所有符号的子集）。 + 这些变量设置仍需遵守正常的依赖性检查。 + + 示例:: + + KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig + + 或:: + + KCONFIG_ALLCONFIG=mini.config make allnoconfig + + 或:: + + make KCONFIG_ALLCONFIG=mini.config allnoconfig + + 这些示例将禁用大多数配置选项（allnoconfig），但启用或禁用 miniconfig 文件 + 中显式列出的选项。 + +``randconfig`` 的环境变量： + +``KCONFIG_SEED`` + 如果你想调试 kconfig 解析器/前端的行为，你可以将此变量设置整数值，用于初始化 + 随机数生成器。如果未设置，将使用当前时间。 + +``KCONFIG_PROBABILITY`` + 该变量可用于倾斜概率分布。此变量可不设置或设置为空，或设置为以下三种不同格式： + + ======================= ================== ===================== + KCONFIG_PROBABILITY y:n 分配 y:m:n 分配 + ======================= ================== ===================== + 未设置或设置为空 50 : 50 33 : 33 : 34 + N N : 100-N N/2 : N/2 : 100-N + [1] N:M N+M : 100-(N+M) N : M : 100-(N+M) + [2] N:M:L N : 100-N M : L : 100-(M+L) + ======================= ================== ===================== + +其中 N、M 和 L 是范围在 [0,100] 内的整数（以十进制表示），并且需满足： + + [1] N+M 的范围在 [0,100] 之间 + + [2] M+L 的范围在 [0,100] 之间 + +示例:: + + KCONFIG_PROBABILITY=10 + 10% 的布尔值将设置为 'y'，90% 设置为 'n' + 5% 的三态值将设置为 'y'，5% 设置为 'm'，90% 设置为 'n' + KCONFIG_PROBABILITY=15:25 + 40% 的布尔值将设置为 'y'，60% 设置为 'n' + 15% 的三态值将设置为 'y'，25% 设置为 'm'，60% 设置为 'n' + KCONFIG_PROBABILITY=10:15:15 + 10% 的布尔值将设置为 'y'，90% 设置为 'n' + 15% 的三态值将设置为 'y'，15% 设置为 'm'，70% 设置为 'n' + +``syncconfig`` 的环境变量： + +``KCONFIG_NOSILENTUPDATE`` + 如果该变量非空，它将阻止静默的内核配置更新（需要明确更新）。 + +``KCONFIG_AUTOCONFIG`` + 该环境变量可以设置为 "auto.conf" 文件的路径和名称。默认值为 + "include/config/auto.conf"。 + +``KCONFIG_AUTOHEADER`` + 该环境变量可以设置为 "autoconf.h" 头文件的路径和名称。默认值为 + "include/generated/autoconf.h"。 + +menuconfig +========== + +在 menuconfig 中搜索： + + 搜索功能会搜索内核配置符号名称，因此你必须知道欲搜索内容的大致名称。 + + 示例:: + + /hotplug + 这会列出所有包含 "hotplug" 的配置符号，例如，HOTPLUG_CPU， + MEMORY_HOTPLUG。 + + 若需要搜索帮助，输入 / 后跟 TAB-TAB（高亮显示 <Help>）并按回车键。 + 这说明你还可以在搜索字符串中使用正则表达式（regex），所以如果你对 + MEMORY_HOTPLUG 不感兴趣，你可以尝试:: + + /^hotplug + + 在搜索时，符号将按以下顺序排序： + + - 首先，完全匹配的符号，按字母顺序排列（完全匹配是指搜索与符号名称完全匹配）； + - 然后是其他匹配项，按字母顺序排列。 + + 例如，^ATH.K 匹配:: + + ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG + [...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...] + + 其中只有 ATH5K 和 ATH9K 完全匹配，因此它们排在前面（按字母顺序）， + 接下来是其他符号，同样按字母顺序排列。 + + 在此菜单中，按下以 (#) 为前缀的键将直接跳转到该位置。退出此新菜单后， + 你将返回当前的搜索结果。 + +'menuconfig' 的用户界面选项： + +``MENUCONFIG_COLOR`` + 可以使用变量 MENUCONFIG_COLOR 选择不同的配色主题。使用以下命令选择主题:: + + make MENUCONFIG_COLOR=<theme> menuconfig + + 可用的主题有:: + + - mono => 选择适合单色显示器的颜色 + - blackbg => 选择具有黑色背景的配色方案 + - classic => 经典外观，蓝色背景 + - bluetitle => 经典外观的 LCD 友好版本（默认） + +``MENUCONFIG_MODE`` + 此模式会将所有子菜单显示为一个大树状结构。 + + 示例:: + + make MENUCONFIG_MODE=single_menu menuconfig + +nconfig +======= + +nconfig 是一个替代的基于文本的配置工具。它在终端（窗口）底部列出功能键，用于执行 +命令。除非你在数据输入窗口中，否则你也可以直接使用相应的数字键来执行命令。例如，你 +可以直接按 6，而非 F6 进行保存。 + +使用 F1 获取全局帮助或 F3 打开简短帮助菜单。 + +在 nconfig 中搜索： + + 你可以在菜单项“提示”字符串中或配置符号中进行搜索。 + + 使用 / 开始在菜单项中搜索。这不支持正则表达式。使用 <Down> 或 <Up> + 分别为下一个命中项和上一个命中项。使用 <Esc> 退出搜索模式。 + + F8（SymSearch）在配置符号中搜索给定的字符串或正则表达式（regex）。 + + 在 SymSearch 中，按下 (#) 前缀的键会直接跳转到该位置。退出该新菜单后， + 你将返回到当前的搜索结果。 + +环境变量： + +``NCONFIG_MODE`` + 此模式会将所有子菜单显示为一个大型树结构。 + + 示例:: + + make NCONFIG_MODE=single_menu nconfig + +xconfig +======= + +在 xconfig 中搜索： + + 搜索功能会搜索内核配置符号名称，因此你必须知道欲搜索内容的大致名称。 + + 示例:: + + Ctrl-F hotplug + + 或:: + + 菜单：File, Search, hotplug + + 列出所有符号名称中包含 "hotplug" 的配置符号项。在此搜索对话框中， + 你可以更改任何未灰显条目的配置设置。你还可以输入不同的搜索字符串， + 而无需返回主菜单。 + +gconfig +======= + +在 gconfig 中搜索： + + gconfig 中没有搜索命令。然而，gconfig 具有几种不同的查看选择、模式和选项。 diff --git a/Documentation/translations/zh_CN/kbuild/llvm.rst b/Documentation/translations/zh_CN/kbuild/llvm.rst new file mode 100644 index 000000000000..f87e0181d8e7 --- /dev/null +++ b/Documentation/translations/zh_CN/kbuild/llvm.rst @@ -0,0 +1,203 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kbuild/llvm.rst +:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn> + +========================== +使用 Clang/LLVM 构建 Linux +========================== + +本文档介绍如何使用 Clang 和 LLVM 工具构建 Linux 内核。 + +关于 +---- + +Linux 内核传统上一直使用 GNU 工具链（如 GCC 和 binutils）进行编译。持续的工作使得 +`Clang <https://clang.llvm.org/>`_ 和 `LLVM <https://llvm.org/>`_ 工具可 +作为可行的替代品。一些发行版，如 `Android <https://www.android.com/>`_、 +`ChromeOS <https://www.chromium.org/chromium-os>`_、`OpenMandriva +<https://www.openmandriva.org/>`_ 和 `Chimera Linux +<https://chimera-linux.org/>`_ 使用 Clang 编译的内核。谷歌和 Meta 的数据中心 +集群也运行由 Clang 编译的内核。 + +`LLVM 是由 C++ 对象实现的工具链组件集合 <https://www.aosabook.org/en/llvm.html>`_。 +Clang 是 LLVM 的前端，支持 C 语言和内核所需的 GNU C 扩展，其发音为 "klang"，而非 +"see-lang"。 + +使用 LLVM 构建 +-------------- + +通过以下命令调用 ``make``:: + + make LLVM=1 + +为主机目标进行编译。对于交叉编译:: + + make LLVM=1 ARCH=arm64 + +LLVM= 参数 +---------- + +LLVM 有 GNU binutils 工具的替代品。这些工具可以单独启用。以下是支持的 make 变量 +完整列表:: + + make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \ + OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ + HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld + +``LLVM=1`` 扩展为上述命令。 + +如果你的 LLVM 工具不在 PATH 中，你可以使用以斜杠结尾的 LLVM 变量提供它们的位置:: + + make LLVM=/path/to/llvm/ + +这将使用 ``/path/to/llvm/clang``、``/path/to/llvm/ld.lld`` 等工具。也可以 +使用以下命令:: + + PATH=/path/to/llvm:$PATH make LLVM=1 + +如果你的 LLVM 工具带有版本后缀，并且你希望测试该特定版本而非无后缀的可执行文件， +类似于 ``LLVM=1``，你可以使用 ``LLVM`` 变量传递该后缀:: + + make LLVM=-14 + +这将使用 ``clang-14``、``ld.lld-14`` 等工具。为了支持带有版本后缀的树外路径组合， +我们建议:: + + PATH=/path/to/llvm/:$PATH make LLVM=-14 + +``LLVM=0`` 与省略 ``LLVM`` 完全不同，它将表现得像 ``LLVM=1``。如果你只希望使用 +某些 LLVM 工具，请使用它们各自的 make 变量。 + +在通过不同命令配置和构建时，应为每次调用 ``make`` 设置相同的 ``LLVM=`` 值。如果 +运行的脚本最终会调用 ``make``，则还应将 ``LLVM=`` 设置为环境变量。 + +交叉编译 +-------- + +单个 Clang 编译器二进制文件（及其对应的 LLVM 工具）通常会包含所有支持的后端，这可以 +简化交叉编译，尤其是使用 ``LLVM=1`` 时。如果仅使用 LLVM 工具，``CROSS_COMPILE`` +或目标三元组前缀就变得不必要。示例:: + + make LLVM=1 ARCH=arm64 + +作为混合 LLVM 和 GNU 工具的示例，对于像 ``ARCH=s390`` 这样目前尚不支持 +``ld.lld`` 或 ``llvm-objcopy`` 的目标，你可以通过以下方式调用 ``make``:: + + make LLVM=1 ARCH=s390 LD=s390x-linux-gnu-ld.bfd \ + OBJCOPY=s390x-linux-gnu-objcopy + +此示例将调用 ``s390x-linux-gnu-ld.bfd`` 作为链接器和 +``s390x-linux-gnu-objcopy``，因此请确保它们在你的 ``$PATH`` 中。 + +当 ``LLVM=1`` 未设置时，``CROSS_COMPILE`` 不会用于给 Clang 编译器二进制文件 +（或相应的 LLVM 工具）添加前缀，而 GNU 工具则需要这样做。 + +LLVM_IAS= 参数 +-------------- + +Clang 可以编译汇编代码。你可以传递 ``LLVM_IAS=0`` 禁用此行为，使 Clang 调用 +相应的非集成汇编器。示例:: + + make LLVM=1 LLVM_IAS=0 + +在交叉编译时，你需要使用 ``CROSS_COMPILE`` 与 ``LLVM_IAS=0``，从而设置 +``--prefix=`` 使得编译器可以对应的非集成汇编器（通常，在面向另一种架构时， +你不想使用系统汇编器）。例如:: + + make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_COMPILE=arm-linux-gnueabi- + +Ccache +------ + +``ccache`` 可以与 ``clang`` 一起使用，以改善后续构建（尽管在不同构建之间 +KBUILD_BUILD_TIMESTAMP_ 应设置为同一确定值，以避免 100% 的缓存未命中， +详见 Reproducible_builds_ 获取更多信息）:: + + KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang" + +.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp +.. _Reproducible_builds: reproducible-builds.html#timestamps + +支持的架构 +---------- + +LLVM 并不支持 Linux 内核所有可支持的架构，同样，即使 LLVM 支持某一架构，也并不意味着在 +该架构下内核可以正常构建或工作。以下是当前 ``CC=clang`` 或 ``LLVM=1`` 支持的架构总结。 +支持级别对应于 MAINTAINERS 文件中的 "S" 值。如果某个架构未列出，则表示 LLVM 不支持它 +或存在已知问题。使用最新的稳定版 LLVM 或甚至开发版本通常会得到最佳结果。一个架构的 +``defconfig`` 通常预期能够良好工作，但某些配置可能存在尚未发现的问题。欢迎在以下 +问题跟踪器中提交错误报告！ + +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 + + * - 架构 + - 支持级别 + - ``make`` 命令 + * - arm + - 支持 + - ``LLVM=1`` + * - arm64 + - 支持 + - ``LLVM=1`` + * - hexagon + - 维护 + - ``LLVM=1`` + * - loongarch + - 维护 + - ``LLVM=1`` + * - mips + - 维护 + - ``LLVM=1`` + * - powerpc + - 维护 + - ``LLVM=1`` + * - riscv + - 支持 + - ``LLVM=1`` + * - s390 + - 维护 + - ``LLVM=1`` （LLVM >= 18.1.0），``CC=clang`` （LLVM < 18.1.0） + * - um (用户模式) + - 维护 + - ``LLVM=1`` + * - x86 + - 支持 + - ``LLVM=1`` + +获取帮助 +-------- + +- `网站 <https://clangbuiltlinux.github.io/>`_ +- `邮件列表 <https://lore.kernel.org/llvm/>`_: <llvm@lists.linux.dev> +- `旧邮件列表档案 <https://groups.google.com/g/clang-built-linux>`_ +- `问题跟踪器 <https://github.com/ClangBuiltLinux/linux/issues>`_ +- IRC: #clangbuiltlinux 在 irc.libera.chat +- `Telegram <https://t.me/ClangBuiltLinux>`_: @ClangBuiltLinux +- `维基 <https://github.com/ClangBuiltLinux/linux/wiki>`_ +- `初学者问题 <https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_ + +.. _zh_cn_getting_llvm: + +获取 LLVM +--------- + +我们在 `kernel.org <https://kernel.org/pub/tools/llvm/>`_ 提供预编译的稳定版 LLVM。 +这些版本已经针对 Linux 内核构建，使用配置文件数据进行优化。相较于其他发行版中的 LLVM，它们应该 +能提高内核构建效率。 + +以下是一些有助于从源代码构建 LLVM 或通过发行版的包管理器获取 LLVM 的链接。 + +- https://releases.llvm.org/download.html +- https://github.com/llvm/llvm-project +- https://llvm.org/docs/GettingStarted.html +- https://llvm.org/docs/CMake.html +- https://apt.llvm.org/ +- https://www.archlinux.org/packages/extra/x86_64/llvm/ +- https://github.com/ClangBuiltLinux/tc-build +- https://github.com/ClangBuiltLinux/linux/wiki/Building-Clang-from-source +- https://android.googlesource.com/platform/prebuilts/clang/host/linux-x86/ diff --git a/Documentation/translations/zh_CN/kbuild/reproducible-builds.rst b/Documentation/translations/zh_CN/kbuild/reproducible-builds.rst new file mode 100644 index 000000000000..5f27ebf2fbfc --- /dev/null +++ b/Documentation/translations/zh_CN/kbuild/reproducible-builds.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/kbuild/reproducible-builds.rst + +:Translator: 慕冬亮 Dongliang Mu <dzm91@hust.edu.cn> + +============ +可重现的构建 +============ + +通常希望使用相同工具集构建相同源代码是可重现的，即，输出始终完全相同。这使得能够验证 +二进制分发或嵌入式系统的构建基础设施未被篡改。这样也更容易验证源代码或工具的更改不会 +影响最终生成的二进制文件。 + +`可重现构建项目`_ 提供了有关该主题的更多信息。本文档涵盖了构建内核可能不可重现的 +各种原因，以及如何避免这些问题。 + +时间戳 +------ + +内核在三个地方嵌入时间戳： + +* 通过 ``uname()`` 显示与包含在 ``/proc/version`` 中的版本字符串 + +* initramfs 中的文件时间戳 + +* 如果启动 ``CONFIG_IKHEADERS``，内核或相应模块中嵌入的内核头文件的时间戳， + 通过 ``/sys/kernel/kheaders.tar.xz`` 显示 + +默认情况下，时间戳为当前时间或内核头文件的修改时间。这个内容必须使用 +`KBUILD_BUILD_TIMESTAMP`_ 变量进行覆盖。如果你从某个 git 提交进行构建， +可以使用其提交日期。 + +内核 *不* 使用 ``__DATE__`` 和 ``__TIME__`` 宏，并在使用这些宏时启用警告。 +如果你合并的外部代码使用这些宏，则必须通过设置 `SOURCE_DATE_EPOCH`_ 环境 +变量来覆盖它们对应的时间戳。 + +用户，主机 +---------- + +内核在 ``/proc/version`` 中嵌入构建用户和主机名。必须使用 +`KBUILD_BUILD_USER 和 KBUILD_BUILD_HOST`_ 变量来覆盖这些设置。如果 +您从某个 git 提交进行构建，可以使用其提交者地址。 + +绝对文件名 +---------- + +当内核在树外构建时，调试信息可能包括源文件的绝对文件名。这些信息必须通过在 +`KCFLAGS`_ 变量中包含 ``-fdebug-prefix-map`` 选项来覆盖。 + +根据使用的编译器，``__FILE__`` 宏在树外构建中也可能扩展为绝对文件名。Kbuild +自动使用 ``-fmacro-prefix-map`` 选项来防止这种情况，前提是它被支持。 + +可重现构建网站提供了有关这些 `prefix-map 选项`_ 的更多信息。 + +在源包中的生成文件 +------------------ + +在 ``tools/`` 子目录下，一些程序的构建过程并不完全支持树外构建。这可能导致后续 +使用如 ``make rpm-pkg`` 构建的源码包包含生成的文件。在构建源码包之前，您应该通过 +运行 ``make mrproper`` 或 ``git clean -d -f -x`` 来确保源码树是干净的。 + +模块签名 +-------- + +如果你启用 ``CONFIG_MODULE_SIG_ALL``，默认行为是为每次构建生成不同的临时密钥， +从而导致模块不可重现。然而，将签名密钥包含在源代码中显然会违背签名模块的目的。 + +一种方法是将构建过程分为几个部分，以便不可重现的部分可以作为源处理： + +1. 生成一个持久的签名密钥。将该密钥的证书添加到内核源代码中。 + +2. 将 ``CONFIG_SYSTEM_TRUSTED_KEYS`` 符号设置为包括签名密钥的证书，将 +``CONFIG_MODULE_SIG_KEY`` 设置为空字符串，并禁用 ``CONFIG_MODULE_SIG_ALL``。 +最后，构建内核和模块。 + +3. 为模块创建分离的签名，并将它们作为源发布。 + +4. 附加模块签名并进行第二次构建。这可以重建模块，或使用步骤 2 的输出。 + +结构随机化 +---------- + +如果你启用 ``CONFIG_RANDSTRUCT``，则需要在 ``scripts/basic/randstruct.seed`` +中预生成随机种子，以便每次构建都使用相同的值。有关详细信息，请参见 +``scripts/gen-randstruct-seed.sh``。 + +调试信息冲突 +------------ + +这并非是个不可重现性的问题，而是生成的文件 *过于* 可重现的问题。 + +一旦你设置了所有必要的变量来开展可重现构建，vDSO 的调试信息可能即使对于不同的内核版 +本也是相同的。这会导致不同内核版本的调试信息软件包之间发生文件冲突。 + +为了避免这种情况，你可以通过在 vDSO 中包含一个任意的 salt 字符串，使其对于不同的 +内核版本是不同的。这种机制由 Kconfig 符号 ``CONFIG_BUILD_SALT`` 指定。 + +Git +--- + +未提交的更改或 Git 中的不同提交 ID 也可能导致不同的编译结果。例如，在执行 +``git reset HEAD^`` 后，即使代码相同，编译期间生成的 +``include/config/kernel.release`` 也会不同，导致最终生成的二进制文件也不尽相同。 +有关详细信息，请参见 ``scripts/setlocalversion``。 + +.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp +.. _KBUILD_BUILD_USER 和 KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host +.. _KCFLAGS: kbuild.html#kcflags +.. _prefix-map 选项: https://reproducible-builds.org/docs/build-path/ +.. _可重现构建项目: https://reproducible-builds.org/ +.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/ diff --git a/Documentation/translations/zh_CN/mm/active_mm.rst b/Documentation/translations/zh_CN/mm/active_mm.rst index c2816f523bd7..b3352668c4c8 100644 --- a/Documentation/translations/zh_CN/mm/active_mm.rst +++ b/Documentation/translations/zh_CN/mm/active_mm.rst @@ -13,6 +13,11 @@ Active MM ========= +注意，在配置了 CONFIG_MMU_LAZY_TLB_REFCOUNT=n 的内核中，mm_count 引用计数 +可能不再包括“懒惰”用户（运行任务中 ->active_mm == mm && ->mm == NULL）。 +获取和释放这些懒惰引用必须使用 mmgrab_lazy_tlb() 和 mmdrop_lazy_tlb() 这 +两个辅助函数，它们抽象了这个配置选项。 + 这是一封linux之父回复开发者的一封邮件，所以翻译时我尽量保持邮件格式的完整。 :: diff --git a/Documentation/translations/zh_CN/mm/damon/faq.rst b/Documentation/translations/zh_CN/mm/damon/faq.rst index de4be417494a..234d63f4f072 100644 --- a/Documentation/translations/zh_CN/mm/damon/faq.rst +++ b/Documentation/translations/zh_CN/mm/damon/faq.rst @@ -13,23 +13,6 @@ 常见问题 ======== -为什么是一个新的子系统，而不是扩展perf或其他用户空间工具？ -========================================================== - -首先，因为它需要尽可能的轻量级，以便可以在线使用，所以应该避免任何不必要的开销，如内核-用户 -空间的上下文切换成本。第二，DAMON的目标是被包括内核在内的其他程序所使用。因此，对特定工具 -（如perf）的依赖性是不可取的。这就是DAMON在内核空间实现的两个最大的原因。 - - -“闲置页面跟踪” 或 “perf mem” 可以替代DAMON吗？ -============================================== - -闲置页跟踪是物理地址空间访问检查的一个低层次的原始方法。“perf mem”也是类似的，尽管它可以 -使用采样来减少开销。另一方面，DAMON是一个更高层次的框架，用于监控各种地址空间。它专注于内 -存管理优化，并提供复杂的精度/开销处理机制。因此，“空闲页面跟踪” 和 “perf mem” 可以提供 -DAMON输出的一个子集，但不能替代DAMON。 - - DAMON是否只支持虚拟内存？ ========================= diff --git a/Documentation/translations/zh_CN/mm/hmm.rst b/Documentation/translations/zh_CN/mm/hmm.rst index babbbe756c0f..0669f947d0bc 100644 --- a/Documentation/translations/zh_CN/mm/hmm.rst +++ b/Documentation/translations/zh_CN/mm/hmm.rst @@ -129,13 +129,7 @@ struct page可以与现有的 mm 机制进行最简单、最干净的集成。 int hmm_range_fault(struct hmm_range *range); 如果请求写访问，它将在丢失或只读条目上触发缺页异常（见下文）。缺页异常使用通用的 mm 缺 -页异常代码路径，就像 CPU 缺页异常一样。 - -这两个函数都将 CPU 页表条目复制到它们的 pfns 数组参数中。该数组中的每个条目对应于虚拟 -范围中的一个地址。HMM 提供了一组标志来帮助驱动程序识别特殊的 CPU 页表项。 - -在 sync_cpu_device_pagetables() 回调中锁定是驱动程序必须尊重的最重要的方面，以保 -持事物正确同步。使用模式是:: +页异常代码路径，就像 CPU 缺页异常一样。使用模式是:: int driver_populate_range(...) { diff --git a/Documentation/translations/zh_CN/mm/index.rst b/Documentation/translations/zh_CN/mm/index.rst index b950dd118be7..c8726bce8f74 100644 --- a/Documentation/translations/zh_CN/mm/index.rst +++ b/Documentation/translations/zh_CN/mm/index.rst @@ -53,6 +53,8 @@ Linux内存管理文档 page_migration page_owner page_table_check + page_tables + physical_memory remap_file_pages split_page_table_lock vmalloced-kernel-stacks diff --git a/Documentation/translations/zh_CN/mm/overcommit-accounting.rst b/Documentation/translations/zh_CN/mm/overcommit-accounting.rst index d8452d8b7fbb..f136a8b81859 100644 --- a/Documentation/translations/zh_CN/mm/overcommit-accounting.rst +++ b/Documentation/translations/zh_CN/mm/overcommit-accounting.rst @@ -16,8 +16,7 @@ Linux内核支持下列超量使用处理模式 0 启发式超量使用处理。拒绝明显的地址空间超量使用。用于一个典型的系统。 - 它确保严重的疯狂分配失败，同时允许超量使用以减少swap的使用。在这种模式下， - 允许root分配稍多的内存。这是默认的。 + 它确保严重的疯狂分配失败，同时允许超量使用以减少swap的使用。这是默认的。 1 总是超量使用。适用于一些科学应用。经典的例子是使用稀疏数组的代码，只是依赖 几乎完全由零页组成的虚拟内存 diff --git a/Documentation/translations/zh_CN/mm/page_owner.rst b/Documentation/translations/zh_CN/mm/page_owner.rst index b72a972271d9..c0d1ca4b9695 100644 --- a/Documentation/translations/zh_CN/mm/page_owner.rst +++ b/Documentation/translations/zh_CN/mm/page_owner.rst @@ -26,6 +26,9 @@ page owner是用来追踪谁分配的每一个页面。它可以用来调试内 页面所有者也可以用于各种目的。例如，可以通过每个页面的gfp标志信息获得精确的碎片 统计。如果启用了page owner，它就已经实现并激活了。我们非常欢迎其他用途。 +它也可以用来显示所有的栈以及它们当前分配的基础页面数，这让我们能够快速了解内存的 +使用情况，而无需浏览所有页面并匹配分配和释放操作。 + page owner在默认情况下是禁用的。所以，如果你想使用它，你需要在你的启动cmdline 中加入"page_owner=on"。如果内核是用page owner构建的，并且由于没有启用启动 选项而在运行时禁用page owner，那么运行时的开销是很小的。如果在运行时禁用，它不 @@ -60,6 +63,49 @@ page owner在默认情况下是禁用的。所以，如果你想使用它，你 4) 分析来自页面所有者的信息:: + cat /sys/kernel/debug/page_owner_stacks/show_stacks > stacks.txt + cat stacks.txt + post_alloc_hook+0x177/0x1a0 + get_page_from_freelist+0xd01/0xd80 + __alloc_pages+0x39e/0x7e0 + allocate_slab+0xbc/0x3f0 + ___slab_alloc+0x528/0x8a0 + kmem_cache_alloc+0x224/0x3b0 + sk_prot_alloc+0x58/0x1a0 + sk_alloc+0x32/0x4f0 + inet_create+0x427/0xb50 + __sock_create+0x2e4/0x650 + inet_ctl_sock_create+0x30/0x180 + igmp_net_init+0xc1/0x130 + ops_init+0x167/0x410 + setup_net+0x304/0xa60 + copy_net_ns+0x29b/0x4a0 + create_new_namespaces+0x4a1/0x820 + nr_base_pages: 16 + ... + ... + echo 7000 > /sys/kernel/debug/page_owner_stacks/count_threshold + cat /sys/kernel/debug/page_owner_stacks/show_stacks> stacks_7000.txt + cat stacks_7000.txt + post_alloc_hook+0x177/0x1a0 + get_page_from_freelist+0xd01/0xd80 + __alloc_pages+0x39e/0x7e0 + alloc_pages_mpol+0x22e/0x490 + folio_alloc+0xd5/0x110 + filemap_alloc_folio+0x78/0x230 + page_cache_ra_order+0x287/0x6f0 + filemap_get_pages+0x517/0x1160 + filemap_read+0x304/0x9f0 + xfs_file_buffered_read+0xe6/0x1d0 [xfs] + xfs_file_read_iter+0x1f0/0x380 [xfs] + __kernel_read+0x3b9/0x730 + kernel_read_file+0x309/0x4d0 + __do_sys_finit_module+0x381/0x730 + do_syscall_64+0x8d/0x150 + entry_SYSCALL_64_after_hwframe+0x62/0x6a + nr_base_pages: 20824 + ... + cat /sys/kernel/debug/page_owner > page_owner_full.txt ./page_owner_sort page_owner_full.txt sorted_page_owner.txt diff --git a/Documentation/translations/zh_CN/mm/page_table_check.rst b/Documentation/translations/zh_CN/mm/page_table_check.rst index e8077310a76c..dc34570dceff 100644 --- a/Documentation/translations/zh_CN/mm/page_table_check.rst +++ b/Documentation/translations/zh_CN/mm/page_table_check.rst @@ -54,3 +54,16 @@ 可以选择用PAGE_TABLE_CHECK_ENFORCED来构建内核，以便在没有额外的内核参数的情况下获得页表 支持。 + +实现注意事项 +============ + +我们特意决定不使用 VMA 信息，以避免依赖于 MM 状态（除了有限的 “struct page” 信息）。页表检查 +独立于 Linux-MM 状态机，它验证用户可访问的页面不会被错误地共享。 + +PAGE_TABLE_CHECK 依赖于 EXCLUSIVE_SYSTEM_RAM。原因在于，若没有 EXCLUSIVE_SYSTEM_RAM， +用户被允许通过 /dev/mem 将任意物理内存区域映射到用户空间。同时，页面可能在映射到用户空间期间 +改变自己的属性（例如，从匿名页面变为命名页面），导致页表检查检测到“损坏”。 + +即使有 EXCLUSIVE_SYSTEM_RAM，I/O 页面可能仍然被允许通过 /dev/mem 映射。然而，这些页面始终 +被视为命名页面，所以它们不会破坏页表检查中使用的逻辑。 diff --git a/Documentation/translations/zh_CN/mm/page_tables.rst b/Documentation/translations/zh_CN/mm/page_tables.rst new file mode 100644 index 000000000000..c9f750fc5298 --- /dev/null +++ b/Documentation/translations/zh_CN/mm/page_tables.rst @@ -0,0 +1,221 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/page_tables.rst + +:翻译: + + 张鹏宇 Pengyu Zhang <zpenya1314@gmail.com> + +:校译: + +==== +页表 +==== + +分页虚拟内存是随虚拟内存的概念一起于 1962 年在 Ferranti Atlas 计算机上被提出的， +这是第一台有分页虚拟内存的计算机。随着时间推移，这个特性被迁移到更新的计算机上， +并且成为所有类 Unix 系统实际的特性。在 1985 年，这个特性被包含在了英特尔 80386 +中，也就是运行 Linux 1.0 的CPU。 + +页表将 CPU 看到的虚拟地址映射到外部内存总线上看到的物理地址。 + +Linux 将页表定义为一个分级结构，目前有五级。对于支持的每种架构，其代码会根据硬件 +限制对这个层级结构进行映射。 + +虚拟地址对应的物理地址通常由底层物理页帧引用。 **页帧号(page frame number,pfn)** +是页的物理地址（在外部内存总线看到的地址）除以 `PAGE_SIZE` 得到的值。 + +物理内存地址 0 对应 *pfn 0*，而最大的 pfn 对应处理器外部地址总线所能寻址物理地址 +的最后一页。 + +在页粒度为 4KB 且地址范围为32位的情况下，pfn 0 对应地址0x00000000，pfn 1 对应 +地址0x00001000，pfn 2 对应地址 0x00002000，以此类推，直到 pfn 0xfffff 对应 +0xfffff000。如果页粒度为 16KB，则 pfn 分别对应地址 0x00004000、0x00008000 +... 0xffffc000，pfn 的范围从 0 到 0x3ffff。 + +如你所见，对于 4KB 页面粒度，页基址使用地址的 12-31 位，这就是为什么在这种情况下 +`PAGE_SHIFT` 被定义为 12，并且 `PAGE_SIZE` 通常由页偏移定义，为 `(1 << PAGE_SHIFT)`。 + +随着内存容量的增加，久而久之层级结构逐渐加深。Linux 最初使用 4KB 页面和一个名为 +`swapper_pg_dir` 的页表，该页表拥有 1024 个表项(entries)，覆盖 4MB 的内存， +事实上Torvald 的第一台计算机正好就有 4MB 物理内存。表项在这张表中被称为 *PTE*:s +- 页表项(page table entries)。 + +软件页表层级结构反映了页表硬件已经变得分层化的事实，而这种分层化的目的是为了节省 +页表内存并加快地址映射速度。 + +当然，人们可以想象一张拥有大量表项的单一线性的页表将整个内存分为一个个页。而且， +这样的页表会非常稀疏，因为虚拟内存中大部分位置通常是未使用的。通过页表分层，虚拟 +内存中的大量空洞不会浪费宝贵的页表内存，因为只需要在上层页表中将大块的区域标记为 +未映射即可。 + +另外，在现代处理器中，上层页表项可以直接指向一个物理地址范围，这使得单个上层 +页表项可以连续映射几兆字节甚至几千兆字节的内存范围，从而快捷地实现虚拟地址到 +物理地址的映射：当你找到一个像这样的大型映射范围时，无需在层级结构中进一步遍历。 + +页表的层级结构目前发展为如下所示:: + + +-----+ + | PGD | + +-----+ + | + | +-----+ + +-->| P4D | + +-----+ + | + | +-----+ + +-->| PUD | + +-----+ + | + | +-----+ + +-->| PMD | + +-----+ + | + | +-----+ + +-->| PTE | + +-----+ + + +不同页表层级的符号含义从最底层开始如下： + +- **pte**, `pte_t`, `pteval_t` = **页表项** - 前面提到过。*pte* 是一个由 + `PTRS_PER_PTE` 个 `pteval_t` 类型元素组成的数组，每个元素将一个虚拟内存页 + 映射到一个物理内存页。体系结构定义了 `pteval_t` 的大小和内容。 + + 一个典型的例子是 `pteval_t` 是一个 32 或者 64 位的值，其中高位是 **pfn**， + 而低位则一些特定体系架构相关的位，如内存保护。 + + 这个 **表项(entry)** 有点令人困惑，因为在 Linux 1.0 中它确实指的是单层顶级 + 页表中的单个页表项，但在首次引入二级页表时，它被重新定义为映射元素的数组。 + 因此，*pte* 现在指的是最底层的页 *表*，而不是一个页表 *项*。 + +- **pmd**, `pmd_t`, `pmdval_t` = **页中间目录(Page Middle Directory)**, + 位于 *pte* 之上的层级结构，包含 `PTRS_PER_PMD` 个指向 *pte* 的引用。 + +- **pud**, `pud_t`, `pudval_t` = **页上级目录(Page Upper Directory)** + 是在其他层级之后引入的，用于处理四级页表。它可能未被使用，或者像我们稍后 + 讨论的那样被“折叠”。 + +- **p4d**, `p4d_t`, `p4dval_t` = **页四级目录(Page Level 4 Directory)** + 是在 *pud* 之后用于处理五级页表引入的。至此，显然需要用数字来替代 *pgd*、 + *pmd*、*pud* 等目录层级的名称，不能再继续使用临时的命名方式。这个目录层级 + 只在实际拥有五级页表的系统上使用，否则它会被折叠。 + +- **pgd**, `pgd_t`, `pgdval_t` = **页全局目录(Page Global Directory)** - + Linux 内核用于处理内核内存的 *PGD* 主页表仍然位于 `swapper_pg_dir`。 + 但系统中的每个用户空间进程也有自己的内存上下文，因此也有自己的 *pgd*， + 它位于 `struct mm_struct` 中，而 `struct mm_struct` 又在每个 `struct task_struct` + 中有引用。所以，任务（进程）存在一个形式为 `struct mm_struct` 的内存上下文， + 而这个结构体中有一个指向指向相应的页全局目录 `struct pgt_t *pgd` 指针。 + +重申一下：页表层级结构中的每一层都是一个 *指针数组*，所以 *pgd* 包含 `PTRS_PER_PGD` +个指向下一层的指针，*p4d* 包含 `PTRS_PER_P4D` 个指向 *pud* 项的指针，依此类推。 +每一层的指针数量由体系结构定义。:: + + PMD + --> +-----+ PTE + | ptr |-------> +-----+ + | ptr |- | ptr |-------> PAGE + | ptr | \ | ptr | + | ptr | \ ... + | ... | \ + | ptr | \ PTE + +-----+ +----> +-----+ + | ptr |-------> PAGE + | ptr | + ... + +页表折叠 +======== + +如果架构不使用所有的页表层级，那么这些层级可以被 *折叠*，也就是说被跳过。在 +访问下一层时，所有在页表上执行的操作都会在编译时增强，以跳过这一层。 + +与架构无关的页表处理代码（例如虚拟内存管理器）需要编写得能够遍历当前的所有五个 +层级。对于特定架构的代码，也应优先采用这种风格，以便对未来的变化具有更好的适应性。 + +MMU，TLB 和缺页异常 +=================== + +`内存管理单元(MMU)` 是处理虚拟地址到物理地址转换的硬件组件。它可能会使用相对较小 +的硬件缓存，如 `转换后备缓冲区(TLB)` 和 `页遍历缓存`，以加快这些地址翻译过程。 + +当 CPU 访存时，它会向 MMU 提供一个虚拟地址。MMU 会首先检查 TLB 或者页遍历缓存 +（在支持的架构上）是否存在对应的转换结果。如果没有，MMU 会通过遍历来确定物理地址 +并且建立映射。 + +当页面被写入时，该页的脏位会被设置（即打开）。每个内存页面都有相关的权限位和脏位。 +后者表明这个页自从被加载到内存以来是否被修改。 + +如果没有任何阻碍，物理内存到头来可以被任意访问并且对物理帧进行请求的操作。 + +MMU 无法找到某些转换有多种原因。有可能是 CPU 试图去访问当前进程没有权限访问的 +内存，或者因为访问的数据还不在物理内存中。 + +当这些情况发生时，MMU 会触发缺页异常，这是一种异常类型，用于通知 CPU 暂停当前 +执行并运行一个特殊的函数去处理这些异常。 + +缺页异常有一些常见且预期的原因。这些因素是由称为“懒加载”和“写时复制”的进程管理 +优化技术来触发的。缺页异常也可能发生在当页帧被交换到持久存储（交换分区或者文件） +并从其物理地址移出时。 + +这些技术提高了内存效率，减少了延迟，并且最小化了空间占用。本文档不会深入讨论 +“懒加载”和“写时复制”的细节，因为这些的主题属于进程地址管理范畴，超出了本文范围。 + +交换技术和前面提到的其他技术不同，因为它是在压力过大下情况下减少内存消耗的一种 +迫不得已的手段，因此是不受欢迎的。 + +交换不适用于由内核逻辑地址映射的内存。这些地址是内核虚拟地址空间的子集，直接映射 +一段连续的物理内存。对于提供的任意逻辑地址，它的物理地址可以通过对偏移量进行简单 +的算数运算来确定。对逻辑地址的访问很快，因为这避免了复杂的页表查找，但代价是这些 +内存不能被驱逐或置换。 + +如果内核无法为必须存在于物理帧中的数据腾出空间，那么它会调用内存不足(out-of-memory, +OOM)杀手，通过杀掉低优先级的进程来腾出空间，直到内存压力下降到安全阈值之下。 + +另外，代码漏洞或指示 CPU 访问的精心制作的恶意地址也可能导致缺页异常。一个进程的 +线程可以利用指令来访问不属于其地址空间的（非共享）内存，或者试图执行写入只读位置 +的指令。 + +如果上述情况发生在用户态，内核会向当前线程发送 `段错误` (SIGSEGV)信号。该信号 +通常导致线程及其所属的进程终止。 + +本文将简化并概述 Linux 内核如何处理这些缺页中断、创建表和表项、检查内存是否存在， +以及当内存不存在时，如何请求从持久存储或其他设备加载数据，并更新 MMU 及其缓存。 + +最初的步骤依赖于架构。大多是架构跳转到 `do_page_fault()`，而 x86 中断处理程序是由 +`DEFINE_IDTENTRY_RAW_ERRORCODE()` 宏定义的，该宏调用 `handle_page_fault()`。 + +无论调用路径如何，所有架构最终都会调用 `handle_mm_fault()`，该函数通常会调用 +`__handle_mm_fault()` 来执行实际分配页表的任务。 + +如果不幸无法调用 `__handle_mm_fault()` 则意味着虚拟地址指向了无权访问的物理 +内存区域（至少对于当前上下文如此）。这种情况会导致内核向该进程发送上述的 SIGSEGV +信号，并引发前面提到的后果。 + +这些用于查找偏移量的函数名称通常以 `*_offset()` 结尾，其中“\*”可以是 pgd，p4d， +pud，pmd 或者 pte；而分配相应层级页表的函数名称是 `*_alloc`，它们按照上述命名 +约定以对应页表层级的类型命名。 + +页表遍历可能在中间或者上层结束(PMD，PUD)。 + +Linux 支持比通常 4KB 更大的页面（即所谓的 `巨页`）。当使用这种较大的页面时，没有 +必要使用更低层的页表项(PTE)。巨页通常包含 2MB 到 1GB 的大块连续物理区域，分别由 +PMD 和 PUD 页表项映射。 + +巨页带来许多好处，如减少 TLB 压力，减少页表开销，提高内存分配效率，以及改善 +特定工作负载的性能。然而，这些好处也伴随着权衡，如内存浪费和分配难度增加。 + +在遍历和分配的最后，如果没有返回错误，`__handle_mm_fault()` 最终调用 `handle_pte_fault()` +通过 `do_fault()` 执行 `do_read_fault()`、 `do_cow_fault()` 和 `do_shared_fault()`。 +“read”，“cow”和“shared”分别暗示了它处理错误的类型和原因。 + +实际的工作流程实现是非常复杂的。其设计允许 Linux 根据每种架构的特定特性处理缺页 +异常，同时仍然共享一个通用的整体结构。 + +为了总结 Linux 如何处理缺页中断的概述，需要补充的是，缺页异常处理程序可以通过 +`pagefault_disable()` 和 `pagefault_enable()` 分别禁用和启用。 + +许多代码路径使用了这两个函数，因为它们需要禁止陷入缺页异常处理程序，主要是为了 +防止死锁。 diff --git a/Documentation/translations/zh_CN/mm/physical_memory.rst b/Documentation/translations/zh_CN/mm/physical_memory.rst new file mode 100644 index 000000000000..4594d15cefec --- /dev/null +++ b/Documentation/translations/zh_CN/mm/physical_memory.rst @@ -0,0 +1,356 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/mm/physical_memory.rst + +:翻译: + + 王亚鑫 Yaxin Wang <wang.yaxin@zte.com.cn> + +======== +物理内存 +======== + +Linux可用于多种架构，因此需要一个与架构无关的抽象来表示物理内存。本章描述 +了管理运行系统中物理内存的结构。 + +第一个与内存管理相关的主要概念是 `非一致性内存访问(NUMA) +<https://en.wikipedia.org/wiki/Non-uniform_memory_access>` + +在多核和多插槽机器中，内存可能被组织成不同的存储区，这些存储区根据与处理器 +的距离“不同”而有不同的访问开销。例如，可能为每个CPU分配内存存储区，或者为 +外围设备在附近分配一个非常适合DMA的内存存储区。 + +每个存储区被称为一个节点，节点在Linux中表示为 ``struct pglist_data``， +即使是在UMA架构中也是这样表示。该结构总是通过 ``pg_data_t`` 来引用。特 +定节点的 ``pg_data_t`` 结构体可以通过NODE_DATA(nid)引用，其中nid被称 +为该节点的ID。 + +对于非一致性内存访问（NUMA）架构，节点数据结构在引导时由特定于架构的代码早 +期分配。通常，这些结构在其所在的内存区上本地分配。对于一致性内存访问（UMA） +架构，只使用一个静态的 ``pg_data_t`` 结构体，称为 ``contig_page_data``。 +节点将会在 :ref:`节点 <nodes>` 章节中进一步讨论。 + +整个物理内存被划分为一个或多个被称为区域的块，这些区域表示内存的范围。这 +些范围通常由访问内存的架构限制来决定。在节点内，与特定区域对应的内存范围 +由 ``struct zone`` 结构体描述，该结构被定义为 ``zone_t``，每种区域都 +属于以下描述类型的一种。 + +* ``ZONE_DMA`` 和 ``ZONE_DMA32`` 在历史上代表适用于DMA的内存，这些 + 内存由那些不能访问所有可寻址内存的外设访问。多年来，已经有了更好、更稳 + 固的接口来获取满足特定DMA需求的内存（这些接口由 + Documentation/core-api/dma-api.rst 文档描述），但是 ``ZONE_DMA`` + 和 ``ZONE_DMA32`` 仍然表示访问受限的内存范围。 + +取决于架构的不同，这两种区域可以在构建时通过关闭 ``CONFIG_ZONE_DMA`` 和 +``CONFIG_ZONE_DMA32`` 配置选项来禁用。一些64位的平台可能需要这两种区域， +因为他们支持具有不同DMA寻址限制的外设。 + +* ``ZONE_NORMAL`` 是普通内存的区域，这种内存可以被内核随时访问。如果DMA + 设备支持将数据传输到所有可寻址的内存区域，那么可在该区域的页面上执行DMA + 操作。``ZONE_NORMAL`` 总是开启的。 + +* ``ZONE_HIGHMEM`` 是指那些没有在内核页表中永久映射的物理内存部分。该区 + 域的内存只能通过临时映射被内核访问。该区域只在某些32位架构上可用，并且是 + 通过 ``CONFIG_HIGHMEM`` 选项开启。 + +* ``ZONE_MOVABLE`` 是指可访问的普通内存区域，就像 ``ZONE_NORMAL`` + 一样。不同之处在于 ``ZONE_MOVABLE`` 中的大多数页面内容是可移动的。 + 这意味着这些页面的虚拟地址不会改变，但它们的内容可能会在不同的物理页面 + 之间移动。通常，在内存热插拔期间填充 ``ZONE_MOVABLE``，在启动时也可 + 以使用 ``kernelcore``、``movablecore`` 和 ``movable_node`` + 这些内核命令行参数来填充。更多详细信息，请参阅内核文档 + Documentation/mm/page_migration.rst 和 + Documentation/admin-guide/mm/memory-hotplug.rst。 + +* ``ZONE_DEVICE`` 表示位于持久性内存（PMEM）和图形处理单元（GPU） + 等设备上的内存。它与RAM区域类型有不同的特性，并且它的存在是为了提供 + :ref:`struct page<Pages>` 结构和内存映射服务，以便设备驱动程序能 + 识别物理地址范围。``ZONE_DEVICE`` 通过 ``CONFIG_ZONE_DEVICE`` + 选项开启。 + +需要注意的是，许多内核操作只能使用 ``ZONE_NORMAL`` 来执行，因此它是 +性能最关键区域。区域在 :ref:`区域 <zones>` 章节中有更详细的讨论。 + +节点和区域范围之间的关系由固件报告的物理内存映射决定，另外也由内存寻址 +的架构约束以及内核命令行中的某些参数决定。 + +例如，在具有2GB RAM的x86统一内存架构（UMA）机器上运行32位内核时，整 +个内存将位于节点0，并且将有三个区域： ``ZONE_DMA``、 ``ZONE_NORMAL`` +和 ``ZONE_HIGHMEM``:: + + 0 2G + +-------------------------------------------------------------+ + | node 0 | + +-------------------------------------------------------------+ + + 0 16M 896M 2G + +----------+-----------------------+--------------------------+ + | ZONE_DMA | ZONE_NORMAL | ZONE_HIGHMEM | + +----------+-----------------------+--------------------------+ + + +在内核构建时关闭 ``ZONE_DMA`` 开启 ``ZONE_DMA32``，并且具有16GB +RAM平均分配在两个节点上的arm64机器上，使用 ``movablecore=80%`` 参数 +启动时，``ZONE_DMA32``、``ZONE_NORMAL`` 和 ``ZONE_MOVABLE`` +位于节点0，而 ``ZONE_NORMAL`` 和 ``ZONE_MOVABLE`` 位于节点1:: + + + 1G 9G 17G + +--------------------------------+ +--------------------------+ + | node 0 | | node 1 | + +--------------------------------+ +--------------------------+ + + 1G 4G 4200M 9G 9320M 17G + +---------+----------+-----------+ +------------+-------------+ + | DMA32 | NORMAL | MOVABLE | | NORMAL | MOVABLE | + +---------+----------+-----------+ +------------+-------------+ + + +内存存储区可能位于交错的节点。在下面的例子中，一台x86机器有16GB的RAM分 +布在4个内存存储区上，偶数编号的内存存储区属于节点0，奇数编号的内存条属于 +节点1:: + + 0 4G 8G 12G 16G + +-------------+ +-------------+ +-------------+ +-------------+ + | node 0 | | node 1 | | node 0 | | node 1 | + +-------------+ +-------------+ +-------------+ +-------------+ + + 0 16M 4G + +-----+-------+ +-------------+ +-------------+ +-------------+ + | DMA | DMA32 | | NORMAL | | NORMAL | | NORMAL | + +-----+-------+ +-------------+ +-------------+ +-------------+ + +在这种情况下，节点0将覆盖从0到12GB的内存范围，而节点1将覆盖从4GB到16GB +的内存范围。 + +.. _nodes_zh_CN: + +节点 +==== + +正如我们所提到的，内存中的每个节点由 ``pg_data_t`` 描述，通过 +``struct pglist_data`` 结构体的类型定义。在分配页面时，默认情况下，Linux +使用节点本地分配策略，从离当前运行CPU的最近节点分配内存。由于进程倾向于在同 +一个CPU上运行，很可能会使用当前节点的内存。分配策略可以由用户控制，如内核文 +档 Documentation/admin-guide/mm/numa_memory_policy.rst 中所述。 + +大多数NUMA（非统一内存访问）架构维护了一个指向节点结构的指针数组。这些实际 +的结构在启动过程中的早期被分配，这时特定于架构的代码解析了固件报告的物理内 +存映射。节点初始化的大部分工作是在由free_area_init()实现的启动过程之后 +完成，该函数在后面的小节 :ref:`初始化 <initialization>` 中有详细描述。 + +除了节点结构，内核还维护了一个名为 ``node_states`` 的 ``nodemask_t`` +位掩码数组。这个数组中的每个位掩码代表一组特定属性的节点，这些属性由 +``enum node_states`` 定义，定义如下： + +``N_POSSIBLE`` +节点可能在某个时刻上线。 + +``N_ONLINE`` +节点已经上线。 + +``N_NORMAL_MEMORY`` +节点拥有普通内存。 + +``N_HIGH_MEMORY`` +节点拥有普通或高端内存。当关闭 ``CONFIG_HIGHMEM`` 配置时， +也可以称为 ``N_NORMAL_MEMORY``。 + +``N_MEMORY`` +节点拥有（普通、高端、可移动）内存。 + +``N_CPU`` +节点拥有一个或多个CPU。 + +对于具有上述属性的每个节点，``node_states[<property>]`` +掩码中对应于节点ID的位会被置位。 + +例如，对于具有常规内存和CPU的节点2，第二个bit将被设置:: + + node_states[N_POSSIBLE] + node_states[N_ONLINE] + node_states[N_NORMAL_MEMORY] + node_states[N_HIGH_MEMORY] + node_states[N_MEMORY] + node_states[N_CPU] + +有关使用节点掩码（nodemasks）可能进行的各种操作，请参考 +``include/linux/nodemask.h``。 + +除此之外，节点掩码（nodemasks）提供用于遍历节点的宏，即 +``for_each_node()`` 和 ``for_each_online_node()``。 + +例如，要为每个在线节点调用函数 foo()，可以这样操作:: + + for_each_online_node(nid) { + pg_data_t *pgdat = NODE_DATA(nid); + + foo(pgdat); + } + +节点数据结构 +------------ + +节点结构 ``struct pglist_data`` 在 ``include/linux/mmzone.h`` +中声明。这里我们将简要描述这个结构体的字段： + +通用字段 +~~~~~~~~ + +``node_zones`` +表示该节点的区域列表。并非所有区域都可能被填充，但这是 +完整的列表。它被该节点的node_zonelists以及其它节点的 +node_zonelists引用。 + +``node_zonelists`` +表示所有节点中所有区域的列表。此列表定义了分配内存时首选的区域 +顺序。``node_zonelists`` 在核心内存管理结构初始化期间， +由 ``mm/page_alloc.c`` 中的 ``build_zonelists()`` +函数设置。 + +``nr_zones`` +表示此节点中已填充区域的数量。 + +``node_mem_map`` +对于使用FLATMEM内存模型的UMA系统，0号节点的 ``node_mem_map`` +表示每个物理帧的struct pages数组。 + +``node_page_ext`` +对于使用FLATMEM内存模型的UMA系统，0号节点的 ``node_page_ext`` +是struct pages的扩展数组。只有在构建时开启了 ``CONFIG_PAGE_EXTENSION`` +选项的内核中才可用。 + +``node_start_pfn`` +表示此节点中起始页面帧的页面帧号。 + +``node_present_pages`` +表示此节点中存在的物理页面的总数。 + +``node_spanned_pages`` +表示包括空洞在内的物理页面范围的总大小。 + +``node_size_lock`` +一个保护定义节点范围字段的锁。仅在开启了 ``CONFIG_MEMORY_HOTPLUG`` 或 +``CONFIG_DEFERRED_STRUCT_PAGE_INIT`` 配置选项中的某一个时才定义。提 +供了 ``pgdat_resize_lock()`` 和 ``pgdat_resize_unlock()`` 用来操作 +``node_size_lock``，而无需检查 ``CONFIG_MEMORY_HOTPLUG`` 或 +``CONFIG_DEFERRED_STRUCT_PAGE_INIT`` 选项。 + +``node_id`` +节点的节点ID（NID），从0开始。 + +``totalreserve_pages`` +这是每个节点保留的页面，这些页面不可用于用户空间分配。 + +``first_deferred_pfn`` +如果大型机器上的内存初始化被推迟，那么第一个PFN（页帧号）是需要初始化的。 +在开启了 ``CONFIG_DEFERRED_STRUCT_PAGE_INIT`` 选项时定义。 + +``deferred_split_queue`` +每个节点的大页队列，这些大页的拆分被推迟了。仅在开启了 ``CONFIG_TRANSPARENT_HUGEPAGE`` +配置选项时定义。 + +``__lruvec`` +每个节点的lruvec持有LRU（最近最少使用）列表和相关参数。仅在禁用了内存 +控制组（cgroups）时使用。它不应该直接访问，而应该使用 ``mem_cgroup_lruvec()`` +来查找lruvecs。 + +回收控制 +~~~~~~~~ + +另见内核文档 Documentation/mm/page_reclaim.rst 文件。 + +``kswapd`` +每个节点的kswapd内核线程实例。 + +``kswapd_wait``, ``pfmemalloc_wait``, ``reclaim_wait`` +同步内存回收任务的工作队列。 + +``nr_writeback_throttled`` +等待写回脏页时，被限制的任务数量。 + +``kswapd_order`` +控制kswapd尝试回收的order。 + +``kswapd_highest_zoneidx`` +kswapd线程可以回收的最高区域索引。 + +``kswapd_failures`` +kswapd无法回收任何页面的运行次数。 + +``min_unmapped_pages`` +无法回收的未映射文件支持的最小页面数量。由 ``vm.min_unmapped_ratio`` +系统控制台（sysctl）参数决定。在开启 ``CONFIG_NUMA`` 配置时定义。 + +``min_slab_pages`` +无法回收的SLAB页面的最少数量。由 ``vm.min_slab_ratio`` 系统控制台 +（sysctl）参数决定。在开启 ``CONFIG_NUMA`` 时定义。 + +``flags`` +控制回收行为的标志位。 + +内存压缩控制 +~~~~~~~~~~~~ + +``kcompactd_max_order`` +kcompactd应尝试实现的页面order。 + +``kcompactd_highest_zoneidx`` +kcompactd可以压缩的最高区域索引。 + +``kcompactd_wait`` +同步内存压缩任务的工作队列。 + +``kcompactd`` +每个节点的kcompactd内核线程实例。 + +``proactive_compact_trigger`` +决定是否使用主动压缩。由 ``vm.compaction_proactiveness`` 系统控 +制台（sysctl）参数控制。 + +统计信息 +~~~~~~~~ + +``per_cpu_nodestats`` +表示节点的Per-CPU虚拟内存统计信息。 + +``vm_stat`` +表示节点的虚拟内存统计数据。 + +.. _zones_zh_CN: + +区域 +==== + +.. admonition:: Stub + + 本节内容不完整。请列出并描述相应的字段。 + +.. _pages_zh_CN: + +页 +==== + +.. admonition:: Stub + + 本节内容不完整。请列出并描述相应的字段。 + +.. _folios_zh_CN: + +页码 +==== + +.. admonition:: Stub + + 本节内容不完整。请列出并描述相应的字段。 + +.. _initialization_zh_CN: + +初始化 +====== + +.. admonition:: Stub + + 本节内容不完整。请列出并描述相应的字段。 diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst index 6a469e1c7deb..6c83a8f40310 100644 --- a/Documentation/translations/zh_CN/process/5.Posting.rst +++ b/Documentation/translations/zh_CN/process/5.Posting.rst @@ -146,10 +146,6 @@ - 补丁本身，采用统一的（“-u”）补丁格式。使用“-p”选项来diff将使函数名与 更改相关联，从而使结果补丁更容易被其他人读取。 -您应该避免在补丁中包括与更改不相关文件（例如，构建过程生成的文件或编辑器 -备份文件）。文档目录中的“dontdiff”文件在这方面有帮助；使用“-X”选项将 -其传递给diff。 - 上面提到的标签（tag）用于描述各种开发人员如何与这个补丁的开发相关联。 :ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>` 文档中对它们进行了详细描述；下面是一个简短的总结。每一行的格式如下： diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 10b9cb4f6a65..0484d0c65c25 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -560,17 +560,6 @@ Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 * with beginning and ending almost-blank lines. */ -对于在 net/ 和 drivers/net/ 的文件，首选的长 (多行) 注释风格有些不同。 - -.. code-block:: c - - /* The preferred comment style for files in net/ and drivers/net - * looks like this. - * - * It is nearly the same as the generally preferred comment style, - * but there is no initial almost-blank line. - */ - 注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行 应只声明一个数据 (不要使用逗号来一次声明多个数据)。这样你就有空间来为每个数据 写一段小注释来解释它们的用途了。 diff --git a/Documentation/translations/zh_CN/process/email-clients.rst b/Documentation/translations/zh_CN/process/email-clients.rst index 34d51cdadc7b..a70393089df3 100644 --- a/Documentation/translations/zh_CN/process/email-clients.rst +++ b/Documentation/translations/zh_CN/process/email-clients.rst @@ -197,7 +197,7 @@ Mutt不自带编辑器，所以不管你使用什么编辑器，不自动断行 Mutt 是高度可配置的。 这里是个使用mutt通过 Gmail 发送的补丁的最小配置:: # .muttrc - # ================ IMAP ==================== + # ================ IMAP ==================== set imap_user = 'yourusername@gmail.com' set imap_pass = 'yourpassword' set spoolfile = imaps://imap.gmail.com/INBOX @@ -325,3 +325,10 @@ Gmail网页客户端自动地把制表符转换为空格。 另一个问题是Gmail还会把任何含有非ASCII的字符的消息改用base64编码，如欧洲人的 名字。 +HacKerMaiL (TUI) +**************** + +HacKerMaiL (hkml) 是一个基于公共收件箱的简单邮件管理工具，它不需要订阅邮件列表。 +该工具由 DAMON 维护者开发和维护，旨在支持 DAMON 和通用内核子系统的基本开发工作 +流程。详细信息可参考 HacKerMaiL 的 README 文件 +(https://github.com/sjp38/hackermail/blob/master/README.md)。 diff --git a/Documentation/translations/zh_CN/process/programming-language.rst b/Documentation/translations/zh_CN/process/programming-language.rst index fabdc338dbfb..95aa4829d78f 100644 --- a/Documentation/translations/zh_CN/process/programming-language.rst +++ b/Documentation/translations/zh_CN/process/programming-language.rst @@ -3,25 +3,22 @@ :Original: :ref:`Documentation/process/programming-language.rst <programming_language>` :Translator: Alex Shi <alex.shi@linux.alibaba.com> -.. _cn_programming_language: - 程序设计语言 ============ -内核是用C语言 :ref:`c-language <cn_c-language>` 编写的。更准确地说，内核通常是用 :ref:`gcc <cn_gcc>` -在 ``-std=gnu11`` :ref:`gcc-c-dialect-options <cn_gcc-c-dialect-options>` 下编译的：ISO C11的 GNU 方言 - -这种方言包含对语言 :ref:`gnu-extensions <cn_gnu-extensions>` 的许多扩展，当然，它们许多都在内核中使用。 +内核是用 C 编程语言编写的 [zh_cn_c-language]_。更准确地说，内核通常使用 ``gcc`` [zh_cn_gcc]_ 编译， +并且使用 ``-std=gnu11`` [zh_cn_gcc-c-dialect-options]_：这是 ISO C11 的 GNU 方言。 +``clang`` [zh_cn_clang]_ 也得到了支持，详见文档： +:ref:`使用 Clang/LLVM 构建 Linux <kbuild_llvm>`。 -对于一些体系结构，有一些使用 :ref:`clang <cn_clang>` 和 :ref:`icc <cn_icc>` 编译内核 -的支持，尽管在编写此文档时还没有完成，仍需要第三方补丁。 +这种方言包含对 C 语言的许多扩展 [zh_cn_gnu-extensions]_，当然，它们许多都在内核中使用。 属性 ---- -在整个内核中使用的一个常见扩展是属性（attributes） :ref:`gcc-attribute-syntax <cn_gcc-attribute-syntax>` +在整个内核中使用的一个常见扩展是属性（attributes） [zh_cn_gcc-attribute-syntax]_。 属性允许将实现定义的语义引入语言实体（如变量、函数或类型），而无需对语言进行 -重大的语法更改（例如添加新关键字） :ref:`n2049 <cn_n2049>` +重大的语法更改（例如添加新关键字） [zh_cn_n2049]_。 在某些情况下，属性是可选的（即不支持这些属性的编译器仍然应该生成正确的代码， 即使其速度较慢或执行的编译时检查/诊断次数不够） @@ -30,42 +27,27 @@ ``__attribute__((__pure__))`` ），以检测可以使用哪些关键字和/或缩短代码, 具体 请参阅 ``include/linux/compiler_attributes.h`` -.. _cn_c-language: - -c-language - http://www.open-std.org/jtc1/sc22/wg14/www/standards - -.. _cn_gcc: - -gcc - https://gcc.gnu.org - -.. _cn_clang: - -clang - https://clang.llvm.org - -.. _cn_icc: - -icc - https://software.intel.com/en-us/c-compilers - -.. _cn_gcc-c-dialect-options: - -c-dialect-options - https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html - -.. _cn_gnu-extensions: - -gnu-extensions - https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html - -.. _cn_gcc-attribute-syntax: - -gcc-attribute-syntax - https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html - -.. _cn_n2049: +Rust +---- -n2049 - http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf +内核对 Rust 编程语言 [zh_cn_rust-language]_ 的支持是实验性的，并且可以通过配置选项 +``CONFIG_RUST`` 来启用。Rust 代码使用 ``rustc`` [zh_cn_rustc]_ 编译器在 +``--edition=2021`` [zh_cn_rust-editions]_ 选项下进行编译。版本（Editions）是一种 +在语言中引入非后向兼容的小型变更的方式。 + +除此之外，内核中还使用了一些不稳定的特性 [zh_cn_rust-unstable-features]_。这些不稳定 +的特性将来可能会发生变化，因此，一个重要的目标是达到仅使用稳定特性的程度。 + +具体请参阅 Documentation/rust/index.rst + +.. [zh_cn_c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards +.. [zh_cn_gcc] https://gcc.gnu.org +.. [zh_cn_clang] https://clang.llvm.org +.. [zh_cn_gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html +.. [zh_cn_gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html +.. [zh_cn_gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html +.. [zh_cn_n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf +.. [zh_cn_rust-language] https://www.rust-lang.org +.. [zh_cn_rustc] https://doc.rust-lang.org/rustc/ +.. [zh_cn_rust-editions] https://doc.rust-lang.org/edition-guide/editions/ +.. [zh_cn_rust-unstable-features] https://github.com/Rust-for-Linux/linux/issues/2 diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index 7ca16bda3709..f7ae584a439e 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -105,7 +105,7 @@ xyzzy do frotz”或“[I]changed xyzzy to do frotz”，就好像你在命令 当链接到邮件列表存档时，请首选lore.kernel.org邮件存档服务。用邮件中的 ``Message-ID`` 头（去掉尖括号）可以创建链接URL。例如:: - Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/ + Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI 请检查该链接以确保可用且指向正确的邮件。 @@ -195,11 +195,8 @@ scripts/get_maintainer.pl在这个步骤中非常有用。如果您找不到正 在MAINTAINERS文件中查找子系统特定的列表；您的补丁可能会在那里得到更多的关注。 不过，请不要发送垃圾邮件到无关的列表。 -许多与内核相关的列表托管在vger.kernel.org上；您可以在 -http://vger.kernel.org/vger-lists.html 上找到它们的列表。不过，也有与内核相关 -的列表托管在其他地方。 - -不要一次发送超过15个补丁到vger邮件列表！！！！ +许多与内核相关的列表托管在 kernel.org 上；您可以在 https://subspace.kernel.org +上找到它们的列表。不过，也有与内核相关的列表托管在其他地方。 Linus Torvalds是决定改动能否进入 Linux 内核的最终裁决者。他的邮件地址是 torvalds@linux-foundation.org 。他收到的邮件很多，所以一般来说最好 **别** @@ -621,6 +618,13 @@ Fixes: 指示补丁修复了之前提交的一个问题。它可以便于确定 的工作所基于的树的提交哈希。你应该在封面邮件或系列的第一个补丁中添加它，它应 该放在 ``---`` 行的下面或所有其他内容之后，即只在你的电子邮件签名之前。 +工具 +---- + +这个过程的许多技术方面可以使用 b4 自动完成，其文档可在 +https://b4.docs.kernel.org/en/latest/ 查看。该工具可帮助处理诸如追踪依赖项、运行 +checkpatch 以及格式化和发送邮件等事务。 + 参考文献 -------- @@ -643,9 +647,6 @@ Greg Kroah-Hartman，“如何惹恼内核子系统维护人员” <http://www.kroah.com/log/linux/maintainer-06.html> -不！！！别再发巨型补丁炸弹给linux-kernel@vger.kernel.org的人们了！ - <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net> - 内核 Documentation/translations/zh_CN/process/coding-style.rst Linus Torvalds关于标准补丁格式的邮件 |