diff options
Diffstat (limited to 'Documentation/translations/zh_CN/admin-guide')
9 files changed, 2572 insertions, 5 deletions
diff --git a/Documentation/translations/zh_CN/admin-guide/README.rst b/Documentation/translations/zh_CN/admin-guide/README.rst new file mode 100644 index 000000000000..669a022f6817 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/README.rst @@ -0,0 +1,347 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/README.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +Linux内核5.x版本 <http://kernel.org/> +========================================= + +以下是Linux版本5的发行注记。仔细阅读它们， +它们会告诉你这些都是什么，解释如何安装内核，以及遇到问题时该如何做。 + +什么是Linux？ +--------------- + + Linux是Unix操作系统的克隆版本，由Linus Torvalds在一个松散的网络黑客 + （Hacker，无贬义）团队的帮助下从头开始编写。它旨在实现兼容POSIX和 + 单一UNIX规范。 + + 它具有在现代成熟的Unix中应当具有的所有功能，包括真正的多任务处理、虚拟内存、 + 共享库、按需加载、共享的写时拷贝（COW）可执行文件、恰当的内存管理以及包括 + IPv4和IPv6在内的复合网络栈。 + + Linux在GNU通用公共许可证，版本2（GNU GPLv2）下分发，详见随附的COPYING文件。 + +它能在什么样的硬件上运行？ +----------------------------- + + 虽然Linux最初是为32位的x86 PC机（386或更高版本）开发的，但今天它也能运行在 + （至少）Compaq Alpha AXP、Sun SPARC与UltraSPARC、Motorola 68000、PowerPC、 + PowerPC64、ARM、Hitachi SuperH、Cell、IBM S/390、MIPS、HP PA-RISC、Intel + IA-64、DEC VAX、AMD x86-64 Xtensa和ARC架构上。 + + Linux很容易移植到大多数通用的32位或64位体系架构，只要它们有一个分页内存管理 + 单元（PMMU）和一个移植的GNU C编译器（gcc；GNU Compiler Collection，GCC的一 + 部分）。Linux也被移植到许多没有PMMU的体系架构中，尽管功能显然受到了一定的 + 限制。 + Linux也被移植到了其自己上。现在可以将内核作为用户空间应用程序运行——这被 + 称为用户模式Linux（UML）。 + +文档 +----- +因特网上和书籍上都有大量的电子文档，既有Linux专属文档，也有与一般UNIX问题相关 +的文档。我建议在任何Linux FTP站点上查找LDP（Linux文档项目）书籍的文档子目录。 +本自述文件并不是关于系统的文档：有更好的可用资源。 + + - 因特网上和书籍上都有大量的（电子）文档，既有Linux专属文档，也有与普通 + UNIX问题相关的文档。我建议在任何有LDP（Linux文档项目）书籍的Linux FTP + 站点上查找文档子目录。本自述文件并不是关于系统的文档：有更好的可用资源。 + + - 文档/子目录中有各种自述文件：例如，这些文件通常包含一些特定驱动程序的 + 内核安装说明。请阅读 + :ref:`Documentation/process/changes.rst <changes>` 文件，它包含了升级内核 + 可能会导致的问题的相关信息。 + +安装内核源代码 +--------------- + + - 如果您要安装完整的源代码，请把内核tar档案包放在您有权限的目录中（例如您 + 的主目录）并将其解包:: + + xz -cd linux-5.x.tar.xz | tar xvf - + + 将“X”替换成最新内核的版本号。 + + 【不要】使用 /usr/src/linux 目录！这里有一组库头文件使用的内核头文件 + （通常是不完整的）。它们应该与库匹配，而不是被内核的变化搞得一团糟。 + + - 您还可以通过打补丁在5.x版本之间升级。补丁以xz格式分发。要通过打补丁进行 + 安装，请获取所有较新的补丁文件，进入内核源代码（linux-5.x）的目录并 + 执行:: + + xz -cd ../patch-5.x.xz | patch -p1 + + 请【按顺序】替换所有大于当前源代码树版本的“x”，这样就可以了。您可能想要 + 删除备份文件（文件名类似xxx~ 或 xxx.orig)，并确保没有失败的补丁（文件名 + 类似xxx# 或 xxx.rej）。如果有，不是你就是我犯了错误。 + + 与5.x内核的补丁不同，5.x.y内核（也称为稳定版内核）的补丁不是增量的，而是 + 直接应用于基本的5.x内核。例如，如果您的基本内核是5.0，并且希望应用5.0.3 + 补丁，则不应先应用5.0.1和5.0.2的补丁。类似地，如果您运行的是5.0.2内核， + 并且希望跳转到5.0.3，那么在应用5.0.3补丁之前，必须首先撤销5.0.2补丁 + （即patch -R）。更多关于这方面的内容，请阅读 + :ref:`Documentation/process/applying-patches.rst <applying_patches>` 。 + + 或者，脚本 patch-kernel 可以用来自动化这个过程。它能确定当前内核版本并 + 应用找到的所有补丁:: + + linux/scripts/patch-kernel linux + + 上面命令中的第一个参数是内核源代码的位置。补丁是在当前目录应用的，但是 + 可以将另一个目录指定为第二个参数。 + + - 确保没有过时的 .o 文件和依赖项:: + + cd linux + make mrproper + + 现在您应该已经正确安装了源代码。 + +软件要求 +--------- + + 编译和运行5.x内核需要各种软件包的最新版本。请参考 + :ref:`Documentation/process/changes.rst <changes>` + 来了解最低版本要求以及如何升级软件包。请注意，使用过旧版本的这些包可能会 + 导致很难追踪的间接错误，因此不要以为在生成或操作过程中出现明显问题时可以 + 只更新包。 + +为内核建立目录 +--------------- + + 编译内核时，默认情况下所有输出文件都将与内核源代码放在一起。使用 + ``make O=output/dir`` 选项可以为输出文件（包括 .config）指定备用位置。 + 例如:: + + kernel source code: /usr/src/linux-5.x + build directory: /home/name/build/kernel + + 要配置和构建内核，请使用:: + + cd /usr/src/linux-5.x + make O=/home/name/build/kernel menuconfig + make O=/home/name/build/kernel + sudo make O=/home/name/build/kernel modules_install install + + 请注意：如果使用了 ``O=output/dir`` 选项，那么它必须用于make的所有调用。 + +配置内核 +--------- + + 即使只升级一个小版本，也不要跳过此步骤。每个版本中都会添加新的配置选项， + 如果配置文件没有按预定设置，就会出现奇怪的问题。如果您想以最少的工作量 + 将现有配置升级到新版本，请使用 ``makeoldconfig`` ，它只会询问您新配置 + 选项的答案。 + + - 其他配置命令包括:: + + "make config" 纯文本界面。 + + "make menuconfig" 基于文本的彩色菜单、选项列表和对话框。 + + "make nconfig" 增强的基于文本的彩色菜单。 + + "make xconfig" 基于Qt的配置工具。 + + "make gconfig" 基于GTK+的配置工具。 + + "make oldconfig" 基于现有的 ./.config 文件选择所有选项，并询问 + 新配置选项。 + + "make olddefconfig" + 类似上一个，但不询问直接将新选项设置为默认值。 + + "make defconfig" 根据体系架构，使用arch/$arch/defconfig或 + arch/$arch/configs/${PLATFORM}_defconfig中的 + 默认选项值创建./.config文件。 + + "make ${PLATFORM}_defconfig" + 使用arch/$arch/configs/${PLATFORM}_defconfig中 + 的默认选项值创建一个./.config文件。 + 用“makehelp”来获取您体系架构中所有可用平台的列表。 + + "make allyesconfig" + 通过尽可能将选项值设置为“y”，创建一个 + ./.config文件。 + + "make allmodconfig" + 通过尽可能将选项值设置为“m”，创建一个 + ./.config文件。 + + "make allnoconfig" 通过尽可能将选项值设置为“n”，创建一个 + ./.config文件。 + + "make randconfig" 通过随机设置选项值来创建./.config文件。 + + "make localmodconfig" 基于当前配置和加载的模块（lsmod）创建配置。禁用 + 已加载的模块不需要的任何模块选项。 + + 要为另一台计算机创建localmodconfig，请将该计算机 + 的lsmod存储到一个文件中，并将其作为lsmod参数传入。 + + 此外，通过在参数LMC_KEEP中指定模块的路径，可以将 + 模块保留在某些文件夹或kconfig文件中。 + + target$ lsmod > /tmp/mylsmod + target$ scp /tmp/mylsmod host:/tmp + + host$ make LSMOD=/tmp/mylsmod \ + LMC_KEEP="drivers/usb:drivers/gpu:fs" \ + localmodconfig + + 上述方法在交叉编译时也适用。 + + "make localyesconfig" 与localmodconfig类似，只是它会将所有模块选项转换 + 为内置（=y）。你可以同时通过LMC_KEEP保留模块。 + + "make kvmconfig" 为kvm客体内核支持启用其他选项。 + + "make xenconfig" 为xen dom0客体内核支持启用其他选项。 + + "make tinyconfig" 配置尽可能小的内核。 + + 更多关于使用Linux内核配置工具的信息，见文档 + Documentation/kbuild/kconfig.rst。 + + - ``make config`` 注意事项: + + - 包含不必要的驱动程序会使内核变大，并且在某些情况下会导致问题： + 探测不存在的控制器卡可能会混淆其他控制器。 + + - 如果存在协处理器，则编译了数学仿真的内核仍将使用协处理器：在 + 这种情况下，数学仿真永远不会被使用。内核会稍微大一点，但不管 + 是否有数学协处理器，都可以在不同的机器上工作。 + + - “kernel hacking”配置细节通常会导致更大或更慢的内核（或两者 + 兼而有之），甚至可以通过配置一些例程来主动尝试破坏坏代码以发现 + 内核问题，从而降低内核的稳定性（kmalloc()）。因此，您可能应该 + 用于研究“开发”、“实验”或“调试”特性相关问题。 + +编译内核 +--------- + + - 确保您至少有gcc 4.9可用。 + 有关更多信息，请参阅 :ref:`Documentation/process/changes.rst <changes>` 。 + + 请注意，您仍然可以使用此内核运行a.out用户程序。 + + - 执行 ``make`` 来创建压缩内核映像。如果您安装了lilo以适配内核makefile， + 那么也可以进行 ``makeinstall`` ，但是您可能需要先检查特定的lilo设置。 + + 实际安装必须以root身份执行，但任何正常构建都不需要。 + 无须徒然使用root身份。 + + - 如果您将内核的任何部分配置为模块，那么还必须执行 ``make modules_install`` 。 + + - 详细的内核编译/生成输出： + + 通常，内核构建系统在相当安静的模式下运行（但不是完全安静）。但是有时您或 + 其他内核开发人员需要看到编译、链接或其他命令的执行过程。为此，可使用 + “verbose（详细）”构建模式。 + 向 ``make`` 命令传递 ``V=1`` 来实现，例如:: + + make V=1 all + + 如需构建系统也给出内个目标重建的愿意，请使用 ``V=2`` 。默认为 ``V=0`` 。 + + - 准备一个备份内核以防出错。对于开发版本尤其如此，因为每个新版本都包含 + 尚未调试的新代码。也要确保保留与该内核对应的模块的备份。如果要安装 + 与工作内核版本号相同的新内核，请在进行 ``make modules_install`` 安装 + 之前备份modules目录。 + + 或者，在编译之前，使用内核配置选项“LOCALVERSION”向常规内核版本附加 + 一个唯一的后缀。LOCALVERSION可以在“General Setup”菜单中设置。 + + - 为了引导新内核，您需要将内核映像（例如编译后的 + .../linux/arch/x86/boot/bzImage）复制到常规可引导内核的位置。 + + - 不再支持在没有LILO等启动装载程序帮助的情况下直接从软盘引导内核。 + + 如果从硬盘引导Linux，很可能使用LILO，它使用/etc/lilo.conf文件中 + 指定的内核映像文件。内核映像文件通常是/vmlinuz、/boot/vmlinuz、 + /bzImage或/boot/bzImage。使用新内核前，请保存旧映像的副本，并复制 + 新映像覆盖旧映像。然后您【必须重新运行LILO】来更新加载映射！否则， + 将无法启动新的内核映像。 + + 重新安装LILO通常需要运行/sbin/LILO。您可能希望编辑/etc/lilo.conf + 文件为旧内核映像指定一个条目（例如/vmlinux.old)防止新的不能正常 + 工作。有关更多信息，请参阅LILO文档。 + + 重新安装LILO之后，您应该就已经准备好了。关闭系统，重新启动，尽情 + 享受吧！ + + 如果需要更改内核映像中的默认根设备、视频模式等，请在适当的地方使用 + 启动装载程序的引导选项。无需重新编译内核即可更改这些参数。 + + - 使用新内核重新启动并享受它吧。 + +若遇到问题 +----------- + + - 如果您发现了一些可能由于内核缺陷所导致的问题，请检查MAINTAINERS（维护者） + 文件看看是否有人与令您遇到麻烦的内核部分相关。如果无人在此列出，那么第二 + 个最好的方案就是把它们发给我（torvalds@linux-foundation.org），也可能发送 + 到任何其他相关的邮件列表或新闻组。 + + - 在所有的缺陷报告中，【请】告诉我们您在说什么内核，如何复现问题，以及您的 + 设置是什么的（使用您的常识）。如果问题是新的，请告诉我；如果问题是旧的， + 请尝试告诉我您什么时候首次注意到它。 + + - 如果缺陷导致如下消息:: + + unable to handle kernel paging request at address C0000010 + Oops: 0002 + EIP: 0010:XXXXXXXX + eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx + esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx + ds: xxxx es: xxxx fs: xxxx gs: xxxx + Pid: xx, process nr: xx + xx xx xx xx xx xx xx xx xx xx + + 或者类似的内核调试信息显示在屏幕上或在系统日志里，请【如实】复制它。 + 可能对你来说转储（dump）看起来不可理解，但它确实包含可能有助于调试问题的 + 信息。转储上方的文本也很重要：它说明了内核转储代码的原因（在上面的示例中， + 是由于内核指针错误）。更多关于如何理解转储的信息，请参见 + Documentation/admin-guide/bug-hunting.rst。 + + - 如果使用 CONFIG_KALLSYMS 编译内核，则可以按原样发送转储，否则必须使用 + ``ksymoops`` 程序来理解转储（但通常首选使用CONFIG_KALLSYMS编译）。 + 此实用程序可从 + https://www.kernel.org/pub/linux/utils/kernel/ksymoops/ 下载。 + 或者，您可以手动执行转储查找： + + - 在调试像上面这样的转储时，如果您可以查找EIP值的含义，这将非常有帮助。 + 十六进制值本身对我或其他任何人都没有太大帮助：它会取决于特定的内核设置。 + 您应该做的是从EIP行获取十六进制值（忽略 ``0010:`` ），然后在内核名字列表 + 中查找它，以查看哪个内核函数包含有问题的地址。 + + 要找到内核函数名，您需要找到与显示症状的内核相关联的系统二进制文件。就是 + 文件“linux/vmlinux”。要提取名字列表并将其与内核崩溃中的EIP进行匹配， + 请执行:: + + nm vmlinux | sort | less + + 这将为您提供一个按升序排序的内核地址列表，从中很容易找到包含有问题的地址 + 的函数。请注意，内核调试消息提供的地址不一定与函数地址完全匹配（事实上， + 这是不可能的），因此您不能只“grep”列表：不过列表将为您提供每个内核函数 + 的起点，因此通过查找起始地址低于你正在搜索的地址，但后一个函数的高于的 + 函数，你会找到您想要的。实际上，在您的问题报告中加入一些“上下文”可能是 + 一个好主意，给出相关的上下几行。 + + 如果您由于某些原因无法完成上述操作（如您使用预编译的内核映像或类似的映像）， + 请尽可能多地告诉我您的相关设置信息，这会有所帮助。有关详细信息请阅读 + ‘Documentation/admin-guide/reporting-issues.rst’。 + + - 或者，您可以在正在运行的内核上使用gdb（只读的；即不能更改值或设置断点）。 + 为此，请首先使用-g编译内核；适当地编辑arch/x86/Makefile，然后执行 ``make + clean`` 。您还需要启用CONFIG_PROC_FS（通过 ``make config`` ）。 + + 使用新内核重新启动后，执行 ``gdb vmlinux /proc/kcore`` 。现在可以使用所有 + 普通的gdb命令。查找系统崩溃点的命令是 ``l *0xXXXXXXXX`` （将xxx替换为EIP + 值）。 + + 用gdb无法调试一个当前未运行的内核是由于gdb（错误地）忽略了编译内核的起始 + 偏移量。 diff --git a/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst b/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst new file mode 100644 index 000000000000..662eb5b46e84 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bug-bisect.rst @@ -0,0 +1,81 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/bug-bisect` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +二分（bisect）缺陷 ++++++++++++++++++++ + +（英文版）最后更新：2016年10月28日 + +引言 +===== + +始终尝试由来自kernel.org的源代码构建的最新内核。如果您没有信心这样做，请将 +错误报告给您的发行版供应商，而不是内核开发人员。 + +找到缺陷（bug）并不总是那么容易，不过仍然得去找。如果你找不到它，不要放弃。 +尽可能多的向相关维护人员报告您发现的信息。请参阅MAINTAINERS文件以了解您所 +关注的子系统的维护人员。 + +在提交错误报告之前，请阅读“Documentation/admin-guide/reporting-issues.rst”。 + +设备未出现（Devices not appearing） +==================================== + +这通常是由udev/systemd引起的。在将其归咎于内核之前先检查一下。 + +查找导致缺陷的补丁 +=================== + +使用 ``git`` 提供的工具可以很容易地找到缺陷，只要缺陷是可复现的。 + +操作步骤： + +- 从git源代码构建内核 +- 以此开始二分 [#f1]_:: + + $ git bisect start + +- 标记损坏的变更集:: + + $ git bisect bad [commit] + +- 标记正常工作的变更集:: + + $ git bisect good [commit] + +- 重新构建内核并测试 +- 使用以下任一与git bisect进行交互:: + + $ git bisect good + + 或:: + + $ git bisect bad + + 这取决于您测试的变更集上是否有缺陷 +- 在一些交互之后，git bisect将给出可能导致缺陷的变更集。 + +- 例如，如果您知道当前版本有问题，而4.8版本是正常的，则可以执行以下操作:: + + $ git bisect start + $ git bisect bad # Current version is bad + $ git bisect good v4.8 + + +.. [#f1] 您可以（可选地）在开始git bisect的时候提供good或bad参数 + ``git bisect start [BAD] [GOOD]`` + +如需进一步参考，请阅读： + +- ``git-bisect`` 的手册页 +- `Fighting regressions with git bisect（用git bisect解决回归） + <https://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html>`_ +- `Fully automated bisecting with "git bisect run"（使用git bisect run + 来全自动二分） <https://lwn.net/Articles/317154>`_ +- `Using Git bisect to figure out when brokenness was introduced + （使用Git二分来找出何时引入了错误） <http://webchick.net/node/99>`_ diff --git a/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst b/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst new file mode 100644 index 000000000000..decb9b26d2f1 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/bug-hunting.rst @@ -0,0 +1,340 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/bug-hunting` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +追踪缺陷 +========= + +内核错误报告通常附带如下堆栈转储:: + + ------------[ cut here ]------------ + WARNING: CPU: 1 PID: 28102 at kernel/module.c:1108 module_put+0x57/0x70 + Modules linked in: dvb_usb_gp8psk(-) dvb_usb dvb_core nvidia_drm(PO) nvidia_modeset(PO) snd_hda_codec_hdmi snd_hda_intel snd_hda_codec snd_hwdep snd_hda_core snd_pcm snd_timer snd soundcore nvidia(PO) [last unloaded: rc_core] + CPU: 1 PID: 28102 Comm: rmmod Tainted: P WC O 4.8.4-build.1 #1 + Hardware name: MSI MS-7309/MS-7309, BIOS V1.12 02/23/2009 + 00000000 c12ba080 00000000 00000000 c103ed6a c1616014 00000001 00006dc6 + c1615862 00000454 c109e8a7 c109e8a7 00000009 ffffffff 00000000 f13f6a10 + f5f5a600 c103ee33 00000009 00000000 00000000 c109e8a7 f80ca4d0 c109f617 + Call Trace: + [<c12ba080>] ? dump_stack+0x44/0x64 + [<c103ed6a>] ? __warn+0xfa/0x120 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c109e8a7>] ? module_put+0x57/0x70 + [<c103ee33>] ? warn_slowpath_null+0x23/0x30 + [<c109e8a7>] ? module_put+0x57/0x70 + [<f80ca4d0>] ? gp8psk_fe_set_frontend+0x460/0x460 [dvb_usb_gp8psk] + [<c109f617>] ? symbol_put_addr+0x27/0x50 + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + [<f80bb3bf>] ? dvb_usb_exit+0x2f/0xd0 [dvb_usb] + [<c13d03bc>] ? usb_disable_endpoint+0x7c/0xb0 + [<f80bb48a>] ? dvb_usb_device_exit+0x2a/0x50 [dvb_usb] + [<c13d2882>] ? usb_unbind_interface+0x62/0x250 + [<c136b514>] ? __pm_runtime_idle+0x44/0x70 + [<c13620d8>] ? __device_release_driver+0x78/0x120 + [<c1362907>] ? driver_detach+0x87/0x90 + [<c1361c48>] ? bus_remove_driver+0x38/0x90 + [<c13d1c18>] ? usb_deregister+0x58/0xb0 + [<c109fbb0>] ? SyS_delete_module+0x130/0x1f0 + [<c1055654>] ? task_work_run+0x64/0x80 + [<c1000fa5>] ? exit_to_usermode_loop+0x85/0x90 + [<c10013f0>] ? do_fast_syscall_32+0x80/0x130 + [<c1549f43>] ? sysenter_past_esp+0x40/0x6a + ---[ end trace 6ebc60ef3981792f ]--- + +这样的堆栈跟踪提供了足够的信息来识别内核源代码中发生错误的那一行。根据问题的 +严重性，它还可能包含 **“Oops”** 一词，比如:: + + BUG: unable to handle kernel NULL pointer dereference at (null) + IP: [<c06969d4>] iret_exc+0x7d0/0xa59 + *pdpt = 000000002258a001 *pde = 0000000000000000 + Oops: 0002 [#1] PREEMPT SMP + ... + +尽管有 **Oops** 或其他类型的堆栈跟踪，但通常需要找到出问题的行来识别和处理缺 +陷。在本章中，我们将参考“Oops”来了解需要分析的各种堆栈跟踪。 + +如果内核是用 ``CONFIG_DEBUG_INFO`` 编译的，那么可以使用文件： +`scripts/decode_stacktrace.sh` 。 + +链接的模块 +----------- + +受到污染或正在加载/卸载的模块用“（…）”标记，污染标志在 +`Documentation/admin-guide/tainted-kernels.rst` 文件中进行了描述，“正在被加 +载”用“+”标注，“正在被卸载”用“-”标注。 + + +Oops消息在哪？ +--------------- + +通常，Oops文本由klogd从内核缓冲区读取，然后交给 ``syslogd`` ，后者将其写入 +syslog文件，通常是 ``/var/log/messages`` （取决于 ``/etc/syslog.conf`` ）。 +在使用systemd的系统上，它也可以由 ``journald`` 守护进程存储，并通过运行 +``journalctl`` 命令进行访问。 + +有时 ``klogd`` 会挂掉，这种情况下您可以运行 ``dmesg > file`` 从内核缓冲区 +读取数据并保存它。或者您可以 ``cat /proc/kmsg > file`` ，但是您必须适时 +中断以停止传输，因为 ``kmsg`` 是一个“永无止境的文件”。 + +如果机器严重崩溃，无法输入命令或磁盘不可用，那还有三个选项： + +(1) 手动复制屏幕上的文本，并在机器重新启动后输入。很难受，但这是突然崩溃下 + 唯一的选择。或者你可以用数码相机拍下屏幕——虽然不那么好，但总比什么都没 + 有好。如果消息滚动超出控制台顶部，使用更高分辨率（例如 ``vga=791`` ） + 引导启动将允许您阅读更多文本。（警告：这需要 ``vesafb`` ，因此对“早期” + 的Oppses没有帮助） + +(2) 从串口终端启动（参见 + :ref:`Documentation/admin-guide/serial-console.rst <serial_console>` ）， + 在另一台机器上运行调制解调器然后用你喜欢的通信程序捕获输出。 + Minicom运行良好。 + +(3) 使用Kdump（参阅 Documentation/admin-guide/kdump/kdump.rst ），使用 + Documentation/admin-guide/kdump/gdbmacros.txt 中的dmesg gdbmacro从旧内存 + 中提取内核环形缓冲区。 + +找到缺陷位置 +------------- + +如果你能指出缺陷在内核源代码中的位置，则报告缺陷的效果会非常好。这有两种方法。 +通常来说使用 ``gdb`` 会比较容易，不过内核需要用调试信息来预编译。 + +gdb +^^^^ + +GNU 调试器（GNU debugger， ``gdb`` ）是从 ``vmlinux`` 文件中找出OOPS的确切 +文件和行号的最佳方法。 + +在使用 ``CONFIG_DEBUG_INFO`` 编译的内核上使用gdb效果最好。可通过运行以下命令 +进行设置:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + +在用 ``CONFIG_DEBUG_INFO`` 编译的内核上，你可以直接从OOPS复制EIP值:: + + EIP: 0060:[<c021e50e>] Not tainted VLI + +并使用GDB来将其翻译成可读形式:: + + $ gdb vmlinux + (gdb) l *0xc021e50e + +如果没有启用 ``CONFIG_DEBUG_INFO`` ，则使用OOPS的函数偏移:: + + EIP is at vt_ioctl+0xda8/0x1482 + +并在启用 ``CONFIG_DEBUG_INFO`` 的情况下重新编译内核:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + $ make vmlinux + $ gdb vmlinux + (gdb) l *vt_ioctl+0xda8 + 0x1888 is in vt_ioctl (drivers/tty/vt/vt_ioctl.c:293). + 288 { + 289 struct vc_data *vc = NULL; + 290 int ret = 0; + 291 + 292 console_lock(); + 293 if (VT_BUSY(vc_num)) + 294 ret = -EBUSY; + 295 else if (vc_num) + 296 vc = vc_deallocate(vc_num); + 297 console_unlock(); + +或者若您想要更详细的显示:: + + (gdb) p vt_ioctl + $1 = {int (struct tty_struct *, unsigned int, unsigned long)} 0xae0 <vt_ioctl> + (gdb) l *0xae0+0xda8 + +您也可以使用对象文件作为替代:: + + $ make drivers/tty/ + $ gdb drivers/tty/vt/vt_ioctl.o + (gdb) l *vt_ioctl+0xda8 + +如果你有调用跟踪，类似:: + + Call Trace: + [<ffffffff8802c8e9>] :jbd:log_wait_commit+0xa3/0xf5 + [<ffffffff810482d9>] autoremove_wake_function+0x0/0x2e + [<ffffffff8802770b>] :jbd:journal_stop+0x1be/0x1ee + ... + +这表明问题可能在 :jbd: 模块中。您可以在gdb中加载该模块并列出相关代码:: + + $ gdb fs/jbd/jbd.ko + (gdb) l *log_wait_commit+0xa3 + +.. note:: + + 您还可以对堆栈跟踪处的任何函数调用执行相同的操作，例如:: + + [<f80bc9ca>] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + + 上述调用发生的位置可以通过以下方式看到:: + + $ gdb drivers/media/usb/dvb-usb/dvb-usb.o + (gdb) l *dvb_usb_adapter_frontend_exit+0x3a + +objdump +^^^^^^^^ + +要调试内核，请使用objdump并从崩溃输出中查找十六进制偏移，以找到有效的代码/汇 +编行。如果没有调试符号，您将看到所示例程的汇编程序代码，但是如果内核有调试 +符号，C代码也将可见（调试符号可以在内核配置菜单的hacking项中启用）。例如:: + + $ objdump -r -S -l --disassemble net/dccp/ipv4.o + +.. note:: + + 您需要处于内核树的顶层以便此获得您的C文件。 + +如果您无法访问源代码，仍然可以使用以下方法调试一些崩溃转储（如Dave Miller的 +示例崩溃转储输出所示）:: + + EIP is at +0x14/0x4c0 + ... + Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 + 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 + <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 + + Put the bytes into a "foo.s" file like this: + + .text + .globl foo + foo: + .byte .... /* bytes from Code: part of OOPS dump */ + + Compile it with "gcc -c -o foo.o foo.s" then look at the output of + "objdump --disassemble foo.o". + + Output: + + ip_queue_xmit: + push %ebp + push %edi + push %esi + push %ebx + sub $0xbc, %esp + mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) + mov 0x8(%ebp), %ebx ! %ebx = skb->sk + mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt + +`scripts/decodecode` 文件可以用来自动完成大部分工作，这取决于正在调试的CPU +体系结构。 + +报告缺陷 +--------- + +一旦你通过定位缺陷找到了其发生的地方，你可以尝试自己修复它或者向上游报告它。 + +为了向上游报告，您应该找出用于开发受影响代码的邮件列表。这可以使用 ``get_maintainer.pl`` 。 + + +例如，您在gspca的sonixj.c文件中发现一个缺陷，则可以通过以下方法找到它的维护者:: + + $ ./scripts/get_maintainer.pl -f drivers/media/usb/gspca/sonixj.c + Hans Verkuil <hverkuil@xs4all.nl> (odd fixer:GSPCA USB WEBCAM DRIVER,commit_signer:1/1=100%) + Mauro Carvalho Chehab <mchehab@kernel.org> (maintainer:MEDIA INPUT INFRASTRUCTURE (V4L/DVB),commit_signer:1/1=100%) + Tejun Heo <tj@kernel.org> (commit_signer:1/1=100%) + Bhaktipriya Shridhar <bhaktipriya96@gmail.com> (commit_signer:1/1=100%,authored:1/1=100%,added_lines:4/4=100%,removed_lines:9/9=100%) + linux-media@vger.kernel.org (open list:GSPCA USB WEBCAM DRIVER) + linux-kernel@vger.kernel.org (open list) + +请注意它将指出： + +- 最后接触源代码的开发人员（如果这是在git树中完成的）。在上面的例子中是Tejun + 和Bhaktipriya（在这个特定的案例中，没有人真正参与这个文件的开发）； +- 驱动维护人员（Hans Verkuil）； +- 子系统维护人员（Mauro Carvalho Chehab）； +- 驱动程序和/或子系统邮件列表（linux-media@vger.kernel.org）； +- Linux内核邮件列表（linux-kernel@vger.kernel.org）。 + +通常，修复缺陷的最快方法是将它报告给用于开发相关代码的邮件列表（linux-media +ML），抄送驱动程序维护者（Hans）。 + +如果你完全不知道该把报告寄给谁，且 ``get_maintainer.pl`` 也没有提供任何有用 +的信息，请发送到linux-kernel@vger.kernel.org。 + +感谢您的帮助，这使Linux尽可能稳定:-) + +修复缺陷 +--------- + +如果你懂得编程，你不仅可以通过报告错误来帮助我们，还可以提供一个解决方案。 +毕竟，开源就是分享你的工作，你不想因为你的天才而被认可吗？ + +如果你决定这样做，请在制定解决方案后将其提交到上游。 + +请务必阅读 +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` ， +以帮助您的代码被接受。 + + +--------------------------------------------------------------------------- + +用 ``klogd`` 进行Oops跟踪的注意事项 +------------------------------------ + +为了帮助Linus和其他内核开发人员， ``klogd`` 对保护故障的处理提供了大量支持。 +为了完整支持地址解析，至少应该使用 ``sysklogd`` 包的1.3-pl3版本。 + +当发生保护故障时， ``klogd`` 守护进程会自动将内核日志消息中的重要地址转换为 +它们的等效符号。然后通过 ``klogd`` 使用的任何报告机制来转发这个已翻译的内核 +消息。保护错误消息可以直接从消息文件中剪切出来并转发给内核开发人员。 + +``klogd`` 执行两种类型的地址解析，静态翻译和动态翻译。静态翻译使用System.map +文件。为了进行静态转换， ``klogd`` 守护进程必须能够在守护进程初始化时找到系 +统映射文件。有关 ``klogd`` 如何搜索映射文件的信息，请参见klogd手册页。 + +当使用内核可加载模块时，动态地址转换非常重要。由于内核模块的内存是从内核的 +动态内存池中分配的，因此无论是模块的开头还是模块中的函数和符号都没有固定的 +位置。 + +内核支持系统调用，允许程序确定加载哪些模块及其在内存中的位置。klogd守护进程 +使用这些系统调用构建了一个符号表，可用于调试可加载内核模块中发生的保护错误。 + +klogd至少会提供产生保护故障的模块的名称。如果可加载模块的开发人员选择从模块 +导出符号信息，则可能会有其他可用的符号信息。 + +由于内核模块环境可以是动态的，因此当模块环境发生变化时，必须有一种通知 +``klogd`` 守护进程的机制。有一些可用的命令行选项允许klogd向当前正在执行的守 +护进程发出信号示意应该刷新符号信息。有关更多信息，请参阅 ``klogd`` 手册页。 + +sysklogd发行版附带了一个补丁，它修改了 ``modules-2.0.0`` 包，以便在加载或 +卸载模块时自动向klogd发送信号。应用此补丁基本上可无缝支持调试内核可加载模块 +发生的保护故障。 + +以下是 ``klogd`` 处理的可加载模块中的保护故障示例:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + +--------------------------------------------------------------------------- + +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst index 48bbd3ebad48..be835ec8e632 100644 --- a/Documentation/translations/zh_CN/admin-guide/index.rst +++ b/Documentation/translations/zh_CN/admin-guide/index.rst @@ -13,9 +13,13 @@ Linux 内核用户和管理员指南 这个初始部分包含总体信息，包括描述内核的README， 关于内核参数的文档等。 -Todolist: +.. toctree:: + :maxdepth: 1 README + +Todolist: + kernel-parameters devices sysctl/index @@ -28,16 +32,21 @@ Todolist: 下面的一组文档，针对的是试图跟踪问题和bug的用户。 -Todolist: +.. toctree:: + :maxdepth: 1 - reporting-bugs + reporting-issues security-bugs bug-hunting bug-bisect tainted-kernels + init + +Todolist: + + reporting-bugs ramoops dynamic-debug-howto - init kdump/index perf/index @@ -56,6 +65,7 @@ Todolist: clearing-warn-once cpu-load + unicode Todolist: @@ -111,7 +121,6 @@ Todolist: sysrq thunderbolt ufs - unicode vga-softcursor video-output xfs diff --git a/Documentation/translations/zh_CN/admin-guide/init.rst b/Documentation/translations/zh_CN/admin-guide/init.rst new file mode 100644 index 000000000000..fbaf6d97f86c --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/init.rst @@ -0,0 +1,54 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/init` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +解释“No working init found.”启动挂起消息 +========================================= + +:作者: + + Andreas Mohr <andi at lisas period de> + + Cristian Souza <cristianmsbr at gmail period com> + +本文档提供了加载初始化二进制（init binary）失败的一些高层级原因（大致按执行 +顺序列出）。 + +1) **无法挂载根文件系统Unable to mount root FS** ：请设置“debug”内核参数（在 + 引导加载程序bootloader配置文件或CONFIG_CMDLINE）以获取更详细的内核消息。 + +2) **初始化二进制不存在于根文件系统上init binary doesn't exist on rootfs** ： + 确保您的根文件系统类型正确（并且 ``root=`` 内核参数指向正确的分区）；拥有 + 所需的驱动程序，例如SCSI或USB等存储硬件；文件系统（ext3、jffs2等）是内建的 + （或者作为模块由initrd预加载）。 + +3) **控制台设备损坏Broken console device** ： ``console= setup`` 中可能存在 + 冲突 --> 初始控制台不可用（initial console unavailable）。例如，由于串行 + IRQ问题（如缺少基于中断的配置）导致的某些串行控制台不可靠。尝试使用不同的 + ``console= device`` 或像 ``netconsole=`` 。 + +4) **二进制存在但依赖项不可用Binary exists but dependencies not available** ： + 例如初始化二进制的必需库依赖项，像 ``/lib/ld-linux.so.2`` 丢失或损坏。使用 + ``readelf -d <INIT>|grep NEEDED`` 找出需要哪些库。 + +5) **无法加载二进制Binary cannot be loaded** ：请确保二进制的体系结构与您的 + 硬件匹配。例如i386不匹配x86_64，或者尝试在ARM硬件上加载x86。如果您尝试在 + 此处加载非二进制文件（shell脚本？），您应该确保脚本在其工作头（shebang + header）行 ``#!/...`` 中指定能正常工作的解释器（包括其库依赖项）。在处理 + 脚本之前，最好先测试一个简单的非脚本二进制文件，比如 ``/bin/sh`` ，并确认 + 它能成功执行。要了解更多信息，请将代码添加到 ``init/main.c`` 以显示 + kernel_execve()的返回值。 + +当您发现新的失败原因时，请扩展本解释（毕竟加载初始化二进制是一个 **关键** 且 +艰难的过渡步骤，需要尽可能无痛地进行），然后向LKML提交一个补丁。 + +待办事项： + +- 通过一个可以存储 ``kernel_execve()`` 结果值的结构体数组实现各种 + ``run_init_process()`` 调用，并在失败时通过迭代 **所有** 结果来记录一切 + （非常重要的可用性修复）。 +- 试着使实现本身在一般情况下更有帮助，例如在受影响的地方提供额外的错误消息。 diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst new file mode 100644 index 000000000000..6b4988da2c5a --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst @@ -0,0 +1,1335 @@ +.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) +.. + If you want to distribute this text under CC-BY-4.0 only, please use 'The + Linux kernel developers' for author attribution and link this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license. + +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/reporting-issues.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + + +报告问题 ++++++++++ + + +简明指南（亦即 太长不看） +========================== + +您面临的是否为同系列稳定版或长期支持内核的普通内核的回归？是否仍然受支持？ +请搜索 `LKML内核邮件列表 <https://lore.kernel.org/lkml/>`_ 和 +`Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ 存档中匹配的报告并 +加入讨论。如果找不到匹配的报告，请安装该系列的最新版本。如果它仍然出现问题， +报告给稳定版邮件列表（stable@vger.kernel.org）。 + +在所有其他情况下，请尽可能猜测是哪个内核部分导致了问题。查看MAINTAINERS文件， +了解开发人员希望如何得知问题，大多数情况下，报告问题都是通过电子邮件和抄送 +相关邮件列表进行的。检查报告目的地的存档中是否已有匹配的报告；也请搜索 +`LKML <https://lore.kernel.org/lkml/>`_ 和网络。如果找不到可加入的讨论，请 +安装 `最新的主线内核 <https://kernel.org/>`_ 。如果仍存在问题，请发送报告。 + +问题已经解决了，但是您希望看到它在一个仍然支持的稳定版或长期支持系列中得到 +解决？请安装其最新版本。如果它出现了问题，那么在主线中搜索修复它的更改，并 +检查是否正在回传（backporting）或者已放弃；如果两者都没有，那么可询问处理 +更改的人员。 + +**通用提醒** ：当安装和测试上述内核时，请确保它是普通的（即：没有补丁，也没 +有使用附加模块）。还要确保它是在一个正常的环境中构建和运行，并且在问题发生 +之前没有被污染（tainted）。 + +在编写报告时，要涵盖与问题相关的所有信息，如使用的内核和发行版。在碰见回归时， +尝试给出引入它的更改的提交ID，二分可以找到它。如果您同时面临Linux内核的多个 +问题，请分别报告每个问题。 + +一旦报告发出，请回答任何出现的问题，并尽可能地提供帮助。这包括通过不时重新 +测试新版本并发送状态更新来推动进展。 + + +如何向内核维护人员报告问题的逐步指南 +===================================== + +上面的简明指南概述了如何向Linux内核开发人员报告问题。对于已经熟悉向自由和开 +源软件（FLOSS）项目报告问题的人来说，这可能是他们所需要的全部内容。对于其他 +人，本部分更为详细，并一步一步地描述。为了便于阅读，它仍然尽量简洁，并省略 +了许多细节；这些在逐步指南后的参考章节中进行了描述，该章节更详细地解释了每 +个步骤。 + +注意：本节涉及的方面比简明指南多，顺序也稍有不同。这符合你的利益，以确保您 +尽早意识到看起来像Linux内核毛病的问题可能实际上是由其他原因引起的。这些步骤 +可以确保你最终不会觉得在这一过程中投入的时间是浪费： + + * 您是否面临硬件或软件供应商提供的Linux内核的问题？那么基本上您最好停止阅读 + 本文档，转而向您的供应商报告问题，除非您愿意自己安装最新的Linux版本。寻找 + 和解决问题往往需要后者。 + + * 使用您喜爱的网络搜索引擎对现有报告进行粗略搜索；此外，请检查 + `Linux内核邮件列表（LKML） <https://lore.kernel.org/lkml/>`_ 的存档。如果 + 找到匹配的报告，请加入讨论而不是发送新报告。 + + * 看看你正在处理的问题是否为回归问题、安全问题或非常严重的问题：这些都是需 + 要在接下来的一些步骤中特别处理的“高优先级问题”。 + + * 确保不是内核环境导致了您面临的问题。 + + * 创建一个新的备份，并将系统修复和恢复工具放在手边。 + + * 确保您的系统不会通过动态构建额外的内核模块来增强其内核，像DKMS这样的解决 + 方案可能在您不知情的情况下就在本地进行了这样的工作。 + + * 当问题发生时，检查您的内核是否被“污染”，因为使内核设置这个标志的事件可能 + 会导致您面临的问题。 + + * 粗略地写下如何重现这个问题。如果您同时处理多个问题，请为每个问题单独写注 + 释，并确保它们在新启动的系统上独立出现。这是必要的，因为每个问题都需要分 + 别报告给内核开发人员，除非它们严重纠缠在一起。 + + * 如果您正面临稳定版或长期支持版本线的回归（例如从5.10.4更新到5.10.5时出现 + 故障），请查看后文“报告稳定版和长期支持内核线的回归”小节。 + + * 定位可能引起问题的驱动程序或内核子系统。找出其开发人员期望的报告的方式和 + 位置。注意：大多数情况下不会是 bugzilla.kernel.org，因为问题通常需要通 + 过邮件发送给维护人员和公共邮件列表。 + + * 在缺陷追踪器或问题相关邮件列表的存档中彻底搜索可能与您的问题匹配的报告。 + 如果你发现了一些相关讨论，请加入讨论而不是发送新的报告。 + +在完成这些准备之后，你将进入主要部分： + + * 除非您已经在运行最新的“主线”Linux内核，否则最好在报告流程前安装它。在某些 + 情况下，使用最新的“稳定版”Linux进行测试和报告也是可以接受的替代方案；在 + 合并窗口期间，这实际上可能是最好的方法，但在开发阶段最好还是暂停几天。无论 + 你选择什么版本，最好使用“普通”构建。忽略这些建议会大大增加您的报告被拒绝 + 或忽略的风险。 + + * 确保您刚刚安装的内核在运行时不会“污染”自己。 + + * 在您刚刚安装的内核中复现这个问题。如果它没有出现，请查看下方只发生在 + 稳定版和长期支持内核的问题的说明。 + + * 优化你的笔记：试着找到并写出最直接的复现问题的方法。确保最终结果包含所有 + 重要的细节，同时让第一次听说的人容易阅读和理解。如果您在此过程中学到了一 + 些东西，请考虑再次搜索关于该问题的现有报告。 + + * 如果失败涉及“panic”、“Oops”、“warning”或“BUG”，请考虑解码内核日志以查找触 + 发错误的代码行。 + + * 如果您的问题是回归问题，请尽可能缩小引入问题时的范围。 + + * 通过详细描述问题来开始编写报告。记得包括以下条目：您为复现而安装的最新内 + 核版本、使用的Linux发行版以及关于如何复现该问题的说明。如果可能，将内核 + 构建配置（.config）和 ``dmesg`` 的输出放在网上的某个地方，并链接到它。包 + 含或上传所有其他可能相关的信息，如Oops的输出/截图或来自 ``lspci`` 的输出 + 。一旦你写完了这个主要部分，请在上方插入一个正常长度的段落快速概述问题和 + 影响。再在此之上添加一个简单描述问题的句子，以得到人们的阅读。现在给出一 + 个更短的描述性标题或主题。然后就可以像MAINTAINERS文件告诉你的那样发送或 + 提交报告了，除非你在处理一个“高优先级问题”：它们需要按照下面“高优先级问 + 题的特殊处理”所述特别关照。 + + * 等待别人的反应，继续推进事情，直到你能够接受这样或那样的结果。因此，请公 + 开和及时地回应任何询问。测试提出的修复。积极地测试：至少重新测试每个新主 + 线版本的首个候选版本（RC），并报告你的结果。如果出现拖延，就友好地提醒一 + 下。如果你没有得到任何帮助或者未能满意，请试着自己帮助自己。 + + +报告稳定版和长期支持内核线的回归 +---------------------------------- + +如果您发现了稳定版或长期支持内核版本线中的回归问题并按上述流程跳到这里，那么 +请阅读本小节。即例如您在从5.10.4更新到5.10.5时出现了问题（从5.9.15到5.10.5则 +不是）。开发人员希望尽快修复此类回归，因此有一个简化流程来报告它们： + + * 检查内核开发人员是否仍然维护你关心的Linux内核版本线：去 `kernel.org 的首页 + <https://kernel.org/>`_ ，确保此特定版本线的最新版没有“[EOL]”标记。 + + * 检查 `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ 中的现有报告。 + + * 从特定的版本线安装最新版本作为纯净内核。确保这个内核没有被污染，并且仍然 + 存在问题，因为问题可能已经在那里被修复了。如果您第一次发现供应商内核的问题， + 请检查已知最新版本的普通构建是否可以正常运行。 + + * 向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。大致 + 描述问题，并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常的版本。 + 然后等待进一步的指示。 + +下面的参考章节部分详细解释了这些步骤中的每一步。 + + +报告只发生在较旧内核版本线的问题 +---------------------------------- + +若您尝试了上述的最新主线内核，但未能在那里复现问题，那么本小节适用于您；以下 +流程有助于使问题在仍然支持的稳定版或长期支持版本线，或者定期基于最新稳定版或 +长期支持内核的供应商内核中得到修复。如果是这种情况，请执行以下步骤： + + * 请做好准备，接下来的几个步骤可能无法在旧版本中解决问题：修复可能太大或太 + 冒险，无法移植到那里。 + + * 执行前节“报告稳定版和长期支持内核线的回归”中的前三个步骤。 + + * 在Linux内核版本控制系统中搜索修复主线问题的更改，因为它的提交消息可能会 + 告诉你修复是否已经计划好了支持。如果你没有找到，搜索适当的邮件列表，寻找 + 讨论此类问题或同行评议可能修复的帖子；然后检查讨论是否认为修复不适合支持。 + 如果支持根本不被考虑，加入最新的讨论，询问是否有可能。 + + * 前面的步骤之一应该会给出一个解决方案。如果仍未能成功，请向可能引起问题的 + 子系统的维护人员询问建议；抄送特定子系统的邮件列表以及稳定版邮件列表 + +下面的参考章节部分详细解释了这些步骤中的每一步。 + + +参考章节：向内核维护者报告问题 +=============================== + +上面的详细指南简要地列出了所有主要步骤，这对大多数人来说应该足够了。但有时， +即使是有经验的用户也可能想知道如何实际执行这些步骤之一。这就是本节的目的， +因为它将提供关于上述每个步骤的更多细节。请将此作为参考文档：可以从头到尾 +阅读它。但它主要是为了浏览和查找如何实际执行这些步骤的详细信息。 + +在深入挖掘细节之前，我想先给你一些一般性建议： + + * Linux内核开发人员很清楚这个过程很复杂，比其他的FLOSS项目要求更多。我们很 + 希望让它更简单。但这需要在不同的地方以及一些基础设施上付诸努力，这些基础 + 设施需要持续的维护；尚未有人站出来做这些工作，所以目前情况就是这样。 + + * 与某些供应商签订的保证或支持合同并不能使您有权要求上游Linux内核社区的开 + 发人员进行修复：这样的合同完全在Linux内核、其开发社区和本文档的范围之外。 + 这就是为什么在这种情况下，你不能要求任何契约保证，即使开发人员处理的问 + 题对供应商有效。如果您想主张您的权利，使用供应商的支持渠道代替。当这样做 + 的时候，你可能想提出你希望看到这个问题在上游Linux内核中修复；可以这是确 + 保最终修复将被纳入所有Linux发行版的唯一方法来鼓励他们。 + + * 如果您从未向FLOSS项目报告过任何问题，那么您应该考虑阅读 `如何有效地报告 + 缺陷 <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_ ， `如何 + 以明智的方式提问 <http://www.catb.org/esr/faqs/smart-questions.html>`_ ， + 和 `如何提出好问题 <https://jvns.ca/blog/good-questions/>`_ 。 + +解决这些问题之后，可以在下面找到如何正确地向Linux内核报告问题的详细信息。 + + +确保您使用的是上游Linux内核 +---------------------------- + + *您是否面临硬件或软件供应商提供的Linux内核的问题？那么基本上您最好停止阅 + 读本文档，转而向您的供应商报告问题，除非您愿意自己安装最新的Linux版本。 + 寻找和解决问题往往需要后者。* + +与大多数程序员一样，Linux内核开发人员不喜欢花时间处理他们维护的源代码中根本 +不会发生的问题的报告。这只会浪费每个人的时间，尤其是你的时间。不幸的是，当 +涉及到内核时，这样的情况很容易发生，并且常常导致双方气馁。这是因为几乎所有预 +装在设备（台式机、笔记本电脑、智能手机、路由器等）上的Linux内核，以及大多数 +由Linux发行商提供的内核，都与由kernel.org发行的官方Linux内核相距甚远：从Linux +开发的角度来看，这些供应商提供的内核通常是古老的或者经过了大量修改，通常两点 +兼具。 + +大多数供应商内核都不适合用来向Linux内核开发人员报告问题：您在其中遇到的问题 +可能已经由Linux内核开发人员在数月或数年前修复；此外，供应商的修改和增强可能 +会导致您面临的问题，即使它们看起来很小或者完全不相关。这就是为什么您应该向 +供应商报告这些内核的问题。它的开发者应该查看报告，如果它是一个上游问题，直接 +于上游修复或将报告转发到那里。在实践中，这有时行不通。因此，您可能需要考虑 +通过自己安装最新的Linux内核内核来绕过供应商。如果如果您选择此方法，那么本指 +南后面的步骤将解释如何在排除了其他可能导致您的问题的原因后执行此操作。 + +注意前段使用的词语是“大多数”，因为有时候开发人员实际上愿意处理供应商内核出现 +的问题报告。他们是否这么做很大程度上取决于开发人员和相关问题。如果发行版只 +根据最近的Linux版本对内核进行了较小修改，那么机会就比较大；例如对于Debian +GNU/Linux Sid或Fedora Rawhide所提供的主线内核。一些开发人员还将接受基于最新 +稳定内核的发行版内核问题报告，只要它改动不大；例如Arch Linux、常规Fedora版本 +和openSUSE Turboweed。但是请记住，您最好使用主线Linux，并避免在此流程中使用 +稳定版内核，如“安装一个新的内核进行测试”一节中所详述。 + +当然，您可以忽略所有这些建议，并向上游Linux开发人员报告旧的或经过大量修改的 +供应商内核的问题。但是注意，这样的报告经常被拒绝或忽视，所以自行小心考虑一下。 +不过这还是比根本不报告问题要好：有时候这样的报告会直接或间接地帮助解决之后的 +问题。 + + +搜索现有报告（第一部分） +------------------------- + + *使用您喜爱的网络搜索引擎对现有报告进行粗略搜索；此外，请检查Linux内核 + 邮件列表（LKML）的存档。如果找到匹配的报告，请加入讨论而不是发送新报告。* + +报告一个别人已经提出的问题，对每个人来说都是浪费时间，尤其是作为报告人的你。 +所以彻底检查是否有人已经报告了这个问题，这对你自己是有利的。在流程中的这一步， +可以只执行一个粗略的搜索：一旦您知道您的问题需要报告到哪里，稍后的步骤将告诉 +您如何详细搜索。尽管如此，不要仓促完成这一步，它可以节省您的时间和减少麻烦。 + +只需先用你最喜欢的搜索引擎在互联网上搜索。然后再搜索Linux内核邮件列表（LKML） +存档。 + +如果搜索结果实在太多，可以考虑让你的搜索引擎将搜索时间范围限制在过去的一个 +月或一年。而且无论你在哪里搜索，一定要用恰当的搜索关键词；也要变化几次关键 +词。同时，试着从别人的角度看问题：这将帮助你想出其他的关键词。另外，一定不 +要同时使用过多的关键词。记住搜索时要同时尝试包含和不包含内核驱动程序的名称 +或受影响的硬件组件的名称等信息。但其确切的品牌名称（比如说“华硕红魔 Radeon +RX 5700 XT Gaming OC”）往往帮助不大，因为它太具体了。相反，尝试搜索术语，如 +型号（Radeon 5700 或 Radeon 5000）和核心代号（“Navi”或“Navi10”），以及包含 +和不包含其制造商（“AMD”）。 + +如果你发现了关于你的问题的现有报告，请加入讨论，因为你可能会提供有价值的额 +外信息。这一点很重要，即使是在修复程序已经准备好或处于最后阶段，因为开发人 +员可能会寻找能够提供额外信息或测试建议修复程序的人。跳到“发布报告后的责任” +一节，了解有关如何正确参与的细节。 + +注意，搜索 `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 网站可能 +也是一个好主意，因为这可能会提供有价值的见解或找到匹配的报告。如果您发现后者， +请记住：大多数子系统都希望在不同的位置报告，如下面“你需要将问题报告到何处” +一节中所述。因此本应处理这个问题的开发人员甚至可能不知道bugzilla的工单。所以 +请检查工单中的问题是否已经按照本文档所述得到报告，如果没有，请考虑这样做。 + +高优先级的问题？ +----------------- + + *看看你正在处理的问题是否是回归问题、安全问题或非常严重的问题：这些都是 + 需要在接下来的一些步骤中特别处理的“高优先级问题”。* + +Linus Torvalds和主要的Linux内核开发人员希望看到一些问题尽快得到解决，因此在 +报告过程中有一些“高优先级问题”的处理略有不同。有三种情况符合条件:回归、安全 +问题和非常严重的问题。 + +如果在旧版本的Linux内核中工作的东西不能在新版本的Linux内核中工作，或者某种 +程度上在新版本的Linux内核中工作得更差，那么你就需要处理“回归”。因此，当一个 +在Linux 5.7中表现良好的WiFi驱动程序在5.8中表现不佳或根本不能工作时，这是一 +种回归。如果应用程序在新的内核中出现不稳定的现象，这也是一种回归，这可能是 +由于内核和用户空间之间的接口（如procfs和sysfs）发生不兼容的更改造成的。显著 +的性能降低或功耗增加也可以称为回归。但是请记住:新内核需要使用与旧内核相似的 +配置来构建（参见下面如何实现这一点）。这是因为内核开发人员在实现新特性时有 +时无法避免不兼容性；但是为了避免回归，这些特性必须在构建配置期间显式地启用。 + +什么是安全问题留给您自己判断。在继续之前，请考虑阅读 +“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”， +因为它提供了如何最恰当地处理安全问题的额外细节。 + +当发生了完全无法接受的糟糕事情时，此问题就是一个“非常严重的问题”。例如， +Linux内核破坏了它处理的数据或损坏了它运行的硬件。当内核突然显示错误消息 +（“kernel panic”）并停止工作，或者根本没有任何停止信息时，您也在处理一个严重 +的问题。注意：不要混淆“panic”（内核停止自身的致命错误）和“Oops”（可恢复错误）， +因为显示后者之后内核仍然在运行。 + + +确保环境健康 +-------------- + + *确保不是内核所处环境导致了你所面临的问题。* + +看起来很像内核问题的问题有时是由构建或运行时环境引起的。很难完全排除这种问 +题，但你应该尽量减少这种问题： + + * 构建内核时，请使用经过验证的工具，因为编译器或二进制文件中的错误可能会导 + 致内核出现错误行为。 + + * 确保您的计算机组件在其设计规范内运行；这对处理器、内存和主板尤为重要。因 + 此，当面临潜在的内核问题时，停止低电压或超频。 + + * 尽量确保不是硬件故障导致了你的问题。例如，内存损坏会导致大量的问题，这些 + 问题会表现为看起来像内核问题。 + + * 如果你正在处理一个文件系统问题，你可能需要用 ``fsck`` 检查一下文件系统， + 因为它可能会以某种方式被损坏，从而导致无法预期的内核行为。 + + * 在处理回归问题时，要确保没有在更新内核的同时发生了其他变化。例如，这个问 + 题可能是由同时更新的其他软件引起的。也有可能是在你第一次重启进入新内核时， + 某个硬件巧合地坏了。更新系统 BIOS 或改变 BIOS 设置中的某些内容也会导致 + 一些看起来很像内核回归的问题。 + + +为紧急情况做好准备 +------------------- + + *创建一个全新的备份，并将系统修复和还原工具放在手边* + +我得提醒您，您正在和计算机打交道，计算机有时会出现意想不到的事情，尤其是当 +您折腾其操作系统的内核等关键部件时。而这就是你在这个过程中要做的事情。因此， +一定要创建一个全新的备份；还要确保你手头有修复或重装操作系统的所有工具， +以及恢复备份所需的一切。 + + +确保你的内核不会被增强 +------------------------ + + *确保您的系统不会通过动态构建额外的内核模块来增强其内核，像DKMS这样的解 + 决方案可能在您不知情的情况下就在本地进行了这样的工作。* + +如果内核以任何方式得到增强，那么问题报告被忽略或拒绝的风险就会急剧增加。这就 +是为什么您应该删除或禁用像akmods和DKMS这样的机制：这些机制会自动构建额外内核 +模块，例如当您安装新的Linux内核或第一次引导它时。也要记得同时删除他们可能安装 +的任何模块。然后重新启动再继续。 + +注意，你可能不知道你的系统正在使用这些解决方案之一：当你安装 Nvidia 专有图 +形驱动程序、VirtualBox 或其他需要 Linux 内核以外的模块支持的软件时，它们通 +常会静默设置。这就是为什么你可能需要卸载这些软件的软件包，以摆脱任何第三方 +内核模块。 + + +检查“污染”标志 +---------------- + + *当问题发生时，检查您的内核是否被“污染”，因为使内核设置这个标志的事件可 + 能会导致您面临的问题。* + +当某些可能会导致看起来完全不相关的后续错误的事情发生时，内核会用“污染 +（taint）”标志标记自己。如果您的内核受到污染，那么您面临的可能是这样的错误。 +因此在投入更多时间到这个过程中之前，尽早排除此情况可能对你有好处。这是这个 +步骤出现在这里的唯一原因，因为这个过程稍后会告诉您安装最新的主线内核；然后 +您将需要再次检查污染标志，因为当它出问题的时候内核报告会关注它。 + +在正在运行的系统上检查内核是否污染非常容易：如果 ``cat /proc/sys/kernel/tainted`` +返回“0”，那么内核没有被污染，一切正常。在某些情况下无法检查该文件；这就是 +为什么当内核报告内部问题（“kernel bug”）、可恢复错误（“kernel Oops”）或停止 +操作前不可恢复的错误（“kernel panic”）时，它也会提到污染状态。当其中一个错 +误发生时，查看打印的错误消息的顶部，搜索以“CPU:”开头的行。如果发现问题时内 +核未被污染，那么它应该以“Not infected”结束；如果你看到“Tainted:”且后跟一些 +空格和字母，那就被污染了。 + +如果你的内核被污染了，请阅读“Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst” +以找出原因。设法消除污染因素。通常是由以下三种因素之一引起的： + + 1. 发生了一个可恢复的错误（“kernel Oops”），内核污染了自己，因为内核知道在 + 此之后它可能会出现奇怪的行为错乱。在这种情况下，检查您的内核或系统日志， + 并寻找以下列文字开头的部分:: + + Oops: 0000 [#1] SMP + + 如方括号中的“#1”所示，这是自启动以来的第一次Oops。每个Oops和此后发生的 + 任何其他问题都可能是首个Oops的后续问题，即使这两个问题看起来完全不相关。 + 通过消除首个Oops的原因并在之后复现该问题，可以排除这种情况。有时仅仅 + 重新启动就足够了，有时更改配置后重新启动可以消除Oops。但是在这个流程中 + 不要花费太多时间在这一点上，因为引起Oops的原因可能已经在您稍后将按流程 + 安装的新Linux内核版本中修复了。 + + 2. 您的系统使用的软件安装了自己的内核模块，例如Nvidia的专有图形驱动程序或 + VirtualBox。当内核从外部源（即使它们是开源的）加载此类模块时，它会污染 + 自己：它们有时会在不相关的内核区域导致错误，从而可能导致您面临的问题。 + 因此，当您想要向Linux内核开发人员报告问题时，您必须阻止这些模块加载。 + 大多数情况下最简单的方法是：临时卸载这些软件，包括它们可能已经安装的任 + 何模块。之后重新启动。 + + 3. 当内核加载驻留在Linux内核源代码staging树中的模块时，它也会污染自身。这 + 是一个特殊的区域，代码（主要是驱动程序）还没有达到正常Linux内核的质量 + 标准。当您报告此种模块的问题时，内核受到污染显然是没有问题的；只需确保 + 问题模块是造成污染的唯一原因。如果问题发生在一个不相关的区域，重新启动 + 并通过指定 ``foo.blacklist=1`` 作为内核参数临时阻止该模块被加载（用有 + 问题的模块名替换“foo”）。 + + +记录如何重现问题 +------------------ + + *粗略地写下如何重现这个问题。如果您同时处理多个问题，请为每个问题单独写 + 注释，并确保它们在新启动的系统上独立出现。这是必要的，因为每个问题都需 + 要分别报告给内核开发人员，除非它们严重纠缠在一起。* + +如果你同时处理多个问题，必须分别报告每个问题，因为它们可能由不同的开发人员 +处理。在一份报告中描述多种问题，也会让其他人难以将其分开。因此只有在问题严 +重纠缠的情况下，才能将问题合并在一份报告中。 + +此外，在报告过程中，你必须测试该问题是否发生在其他内核版本上。因此，如果您 +知道如何在一个新启动的系统上快速重现问题，将使您的工作更加轻松。 + +注意：报告只发生过一次的问题往往是没有结果的，因为它们可能是由于宇宙辐射导 +致的位翻转。所以你应该尝试通过重现问题来排除这种情况，然后再继续。如果你有 +足够的经验来区分由于硬件故障引起的一次性错误和难以重现的罕见内核问题，可以 +忽略这个建议。 + + +稳定版或长期支持内核的回归？ +----------------------------- + + *如果您正面临稳定版或长期支持版本线的回归（例如从5.10.4更新到5.10.5时出现 + 故障），请查看后文“报告稳定版和长期支持内核线的回归”小节。* + +稳定版和长期支持内核版本线中的回归是Linux开发人员非常希望解决的问题，这样的 +问题甚至比主线开发分支中的回归更不应出现，因为它们会很快影响到很多人。开发人员 +希望尽快了解此类问题，因此有一个简化流程来报告这些问题。注意，使用更新内核版 +本线的回归（比如从5.9.15切换到5.10.5时出现故障）不符合条件。 + + +你需要将问题报告到何处 +------------------------ + + *定位可能引起问题的驱动程序或内核子系统。找出其开发人员期望的报告的方式 + 和位置。注意：大多数情况下不会是bugzilla.kernel.org，因为问题通常需要通 + 过邮件发送给维护人员和公共邮件列表。* + +将报告发送给合适的人是至关重要的，因为Linux内核是一个大项目，大多数开发人员 +只熟悉其中的一小部分。例如，相当多的程序员只关心一个驱动程序，比如一个WiFi +芯片驱动程序；它的开发人员可能对疏远的或不相关的“子系统”（如TCP堆栈、 +PCIe/PCI子系统、内存管理或文件系统）的内部知识了解很少或完全不了解。 + +问题在于：Linux内核缺少一个，可以简单地将问题归档并让需要了解它的开发人员了 +解它的，中心化缺陷跟踪器。这就是为什么你必须找到正确的途径来自己报告问题。 +您可以在脚本的帮助下做到这一点（见下文），但它主要针对的是内核开发人员和专 +家。对于其他人来说，MAINTAINERS（维护人员）文件是更好的选择。 + +如何阅读MAINTAINERS维护者文件 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +为了说明如何使用 :ref:`MAINTAINERS <maintainers>` 文件，让我们假设您的笔记 +本电脑中的WiFi在更新内核后突然出现了错误行为。这种情况下可能是WiFi驱动的问 +题。显然，它也可能由于驱动基于的某些代码，但除非你怀疑有这样的东西会附着在 +驱动程序上。如果真的是其他的问题，驱动程序的开发人员会让合适的人参与进来。 + +遗憾的是，没有通用且简单的办法来检查哪个代码驱动了特定硬件组件。 + +在WiFi驱动出现问题的情况下，你可能想查看 ``lspci -k`` 的输出，因为它列出了 +PCI/PCIe总线上的设备和驱动它的内核模块:: + + [user@something ~]$ lspci -k + [...] + 3a:00.0 Network controller: Qualcomm Atheros QCA6174 802.11ac Wireless Network Adapter (rev 32) + Subsystem: Bigfoot Networks, Inc. Device 1535 + Kernel driver in use: ath10k_pci + Kernel modules: ath10k_pci + [...] + +但如果你的WiFi芯片通过USB或其他内部总线连接，这种方法就行不通了。在这种情况 +下，您可能需要检查您的WiFi管理器或 ``ip link`` 的输出。寻找有问题的网络接口 +的名称，它可能类似于“wlp58s0”。此名称可以用来找到驱动它的模块:: + + [user@something ~]$ realpath --relative-to=/sys/module//sys/class/net/wlp58s0/device/driver/module + ath10k_pci + +如果这些技巧不能进一步帮助您，请尝试在网上搜索如何缩小相关驱动程序或子系统 +的范围。如果你不确定是哪一个：试着猜一下，即使你猜得不好，也会有人会帮助你 +的。 + +一旦您知道了相应的驱动程序或子系统，您就希望在MAINTAINERS文件中搜索它。如果 +是“ath10k_pci”，您不会找到任何东西，因为名称太具体了。有时你需要在网上寻找 +帮助；但在此之前，请尝试使用一个稍短或修改过的名称来搜索MAINTAINERS文件，因 +为这样你可能会发现类似这样的东西:: + + QUALCOMM ATHEROS ATH10K WIRELESS DRIVER + Mail: A. Some Human <shuman@example.com> + Mailing list: ath10k@lists.infradead.org + Status: Supported + Web-page: https://wireless.wiki.kernel.org/en/users/Drivers/ath10k + SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git + Files: drivers/net/wireless/ath/ath10k/ + +注意：如果您阅读在Linux源代码树的根目录中找到的原始维护者文件，则行描述将是 +缩写。例如，“Mail:（邮件）”将是“M:”，“Mailing list:（邮件列表）”将是“L”， +“Status:（状态）”将是“S:”。此文件顶部有一段解释了这些和其他缩写。 + +首先查看“Status”状态行。理想情况下，它应该得到“Supported（支持）”或 +“Maintained（维护）”。如果状态为“Obsolete（过时的）”，那么你在使用一些过时的 +方法，需要转换到新的解决方案上。有时候，只有在感到有动力时，才会有人为代码 +提供“Odd Fixes”。如果碰见“Orphan”，你就完全不走运了，因为再也没有人关心代码 +了，只剩下这些选项:准备好与问题共存，自己修复它，或者找一个愿意修复它的程序员。 + +检查状态后，寻找以“bug:”开头的一行：它将告诉你在哪里可以找到子系统特定的缺 +陷跟踪器来提交你的问题。上面的例子没有此行。大多数部分都是这样，因为 Linux +内核的开发完全是由邮件驱动的。很少有子系统使用缺陷跟踪器，且其中只有一部分 +依赖于 bugzilla.kernel.org。 + +在这种以及其他很多情况下，你必须寻找以“Mail:”开头的行。这些行提到了特定代码 +的维护者的名字和电子邮件地址。也可以查找以“Mailing list:”开头的行，它告诉你 +开发代码的公共邮件列表。你的报告之后需要通过邮件发到这些地址。另外，对于所有 +通过电子邮件发送的问题报告，一定要抄送 Linux Kernel Mailing List（LKML） +<linux-kernel@vger.kernel.org>。在以后通过邮件发送问题报告时，不要遗漏任何 +一个邮件列表!维护者都是大忙人，可能会把一些工作留给子系统特定列表上的其他开 +发者；而 LKML 很重要，因为需要一个可以找到所有问题报告的地方。 + + +借助脚本找到维护者 +~~~~~~~~~~~~~~~~~~~~ + +对于手头有Linux源码的人来说，有第二个可以找到合适的报告地点的选择：脚本 +“scripts/get_maintainer.pl”，它尝试找到所有要联系的人。它会查询MAINTAINERS +文件，并需要用相关源代码的路径来调用。对于编译成模块的驱动程序，经常可以用 +这样的命令找到:: + + $ modinfo ath10k_pci | grep filename | sed 's!/lib/modules/.*/kernel/!!; s!filename:!!; s!\.ko\(\|\.xz\)!!' + drivers/net/wireless/ath/ath10k/ath10k_pci.ko + +将其中的部分内容传递给脚本:: + + $ ./scripts/get_maintainer.pl -f drivers/net/wireless/ath/ath10k* + Some Human <shuman@example.com> (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + Another S. Human <asomehuman@example.com> (maintainer:NETWORKING DRIVERS) + ath10k@lists.infradead.org (open list:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + linux-wireless@vger.kernel.org (open list:NETWORKING DRIVERS (WIRELESS)) + netdev@vger.kernel.org (open list:NETWORKING DRIVERS) + linux-kernel@vger.kernel.org (open list) + +不要把你的报告发给所有的人。发送给维护者，脚本称之为“supporter:”；另外抄送 +代码最相关的邮件列表，以及 Linux 内核邮件列表（LKML）。在此例中，你需要将报 +告发送给 “Some Human <shuman@example.com>” ，并抄送 +“ath10k@lists.infradead.org”和“linux-kernel@vger.kernel.org”。 + +注意：如果你用 git 克隆了 Linux 源代码，你可能需要用--git 再次调用 +get_maintainer.pl。脚本会查看提交历史，以找到最近哪些人参与了相关代码的编写， +因为他们可能会提供帮助。但要小心使用这些结果，因为它很容易让你误入歧途。 +例如，这种情况常常会发生在很少被修改的地方（比如老旧的或未维护的驱动程序）： +有时这样的代码会在树级清理期间被根本不关心此驱动程序的开发者修改。 + + +搜索现有报告（第二部分） +-------------------------- + + *在缺陷追踪器或问题相关邮件列表的存档中彻底搜索可能与您的问题匹配的报告。 + 如果找到匹配的报告，请加入讨论而不是发送新报告。* + +如前所述：报告一个别人已经提出的问题，对每个人来说都是浪费时间，尤其是作为报告 +人的你。这就是为什么你应该再次搜索现有的报告。现在你已经知道问题需要报告到哪里。 +如果是邮件列表，那么一般在 `lore.kernel.org <https://lore.kernel.org/>`_ 可以 +找到相应存档。 + +但有些列表运行在其他地方。例如前面步骤中当例子的ath10k WiFi驱动程序就是这种 +情况。但是你通常可以在网上很容易地找到这些列表的档案。例如搜索“archive +ath10k@lists.infradead.org”，将引导您到ath10k邮件列表的信息页，该页面顶部链接 +到其 `列表存档 <https://lists.infradead.org/pipermail/ath10k/>`_ 。遗憾的是， +这个列表和其他一些列表缺乏搜索其存档的功能。在这种情况下可以使用常规的互联网 +搜索引擎，并添加类似“site:lists.infadead.org/pipermail/ath10k/”这 +样的搜索条件，这会把结果限制在该链接中的档案。 + +也请进一步搜索网络、LKML和bugzilla.kernel.org网站。 + +有关如何搜索以及在找到匹配报告时如何操作的详细信息，请参阅上面的“搜索现有报告 +（第一部分）”。 + +不要急着完成报告过程的这一步：花30到60分钟甚至更多的时间可以为你和其他人节省 / +减少相当多的时间和麻烦。 + + +安装一个新的内核进行测试 +-------------------------- + + *除非您已经在运行最新的“主线”Linux内核，否则最好在报告流程前安装它。在 + 某些情况下，使用最新的“稳定版”Linux进行测试和报告也是可以接受的替代方案； + 在合并窗口期间，这实际上可能是最好的方法，但在开发阶段最好还是暂停几天。 + 无论你选择什么版本，最好使用“普通”构建。忽略这些建议会大大增加您的报告 + 被拒绝或忽略的风险。* + +正如第一步的详细解释中所提到的：与大多数程序员一样，与大多数程序员一样，Linux +内核开发人员不喜欢花时间处理他们维护的源代码中根本不会发生的问题的报告。这只 +会浪费每个人的时间，尤其是你的时间。这就是为什么在报告问题之前，您必须先确认 +问题仍然存在于最新的上游代码中，这符合每个人的利益。您可以忽略此建议，但如前 +所述：这样做会极大地增加问题报告被拒绝或被忽略的风险。 + +内核“最新上游”的范围通常指： + + * 安装一个主线内核；最新的稳定版内核也可以是一个选择，但大多数时候都最好避免。 + 长期支持内核（有时称为“LTS内核”）不适合此流程。下一小节将更详细地解释所有 + 这些。 + + * 下一小节描述获取和安装这样一个内核的方法。它还指出了使用预编译内核是可以的， + 但普通的内核更好，这意味着：它是直接使用从 `kernel.org <https://kernel.org/>`_ + 获得的Linux源代码构建并且没有任何方式修改或增强。 + + +选择适合测试的版本 +~~~~~~~~~~~~~~~~~~~~ + +前往 `kernel.org <https://kernel.org/>`_ 来决定使用哪个版本。忽略那个写着 +“Latest release最新版本”的巨大黄色按钮，往下看有一个表格。在表格的顶部，你会 +看到一行以“mainline”开头的字样，大多数情况下它会指向一个版本号类似“5.8-rc2” +的预发布版本。如果是这样的话，你将需要使用这个主线内核进行测试。不要让“rc” +吓到你，这些“开发版内核”实际上非常可靠——而且你已经按照上面的指示做了备份， +不是吗？ + +大概每九到十周，“mainline”可能会给你指出一个版本号类似“5.7”的正式版本。如果 +碰见这种情况，请考虑暂停报告过程，直到下一个版本的第一个预发布（5.8-rc1）出 +现在 `kernel.org <https://kernel.org/>`_ 上。这是因为 Linux 的开发周期正在 +两周的“合并窗口”内。大部分的改动和所有干扰性的改动都会在这段时间内被合并到 +下一个版本中。在此期间使用主线是比较危险的。内核开发者通常也很忙，可能没有 +多余的时间来处理问题报告。这也是很有可能在合并窗口中应用了许多修改来修复你 +所面临的问题；这就是为什么你很快就得用一个新的内核版本重新测试，就像下面“发 +布报告后的责任”一节中所述的那样。 + +这就是为什么要等到合并窗口结束后才去做。但是如果你处理的是一些不应该等待的 +东西，则无需这样做。在这种情况下，可以考虑通过 git 获取最新的主线内核（见下 +文），或者使用 kernel.org 上提供的最新稳定版本。如果 mainline 因为某些原因 +不无法正常工作，那么使用它也是可以接受的。总的来说：用它来重现问题也比完全 +不报告问题要好。 + +最好避免在合并窗口外使用最新的稳定版内核，因为所有修复都必须首先应用于主线。 +这就是为什么检查最新的主线内核是如此重要：你希望看到在旧版本线修复的任何问题 +需要先在主线修复，然后才能得到回传，这可能需要几天或几周。另一个原因是：您 +希望的修复对于回传来说可能太难或太冒险；因此再次报告问题不太可能改变任何事情。 + +这些方面也部分表明了为什么长期支持内核（有时称为“LTS内核”）不适合报告流程： +它们与当前代码的距离太远。因此，先去测试主线，然后再按流程走：如果主线没有 +出现问题，流程将指导您如何在旧版本线中修复它。 + +如何获得新的 Linux 内核 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +你可以使用预编译或自编译的内核进行测试；如果你选择后者，可以使用 git 获取源 +代码，或者下载其 tar 存档包。 + +**使用预编译的内核** ：这往往是最快速、最简单、最安全的方法——尤其是在你不熟 +悉 Linux 内核的情况下。问题是：发行商或附加存储库提供的大多数版本都是从修改 +过的Linux源代码构建的。因此它们不是普通的，通常不适合于测试和问题报告：这些 +更改可能会导致您面临的问题或以某种方式影响问题。 + +但是如果您使用的是流行的Linux发行版，那么您就很幸运了：对于大部分的发行版， +您可以在网上找到包含最新主线或稳定版本Linux内核包的存储库。使用这些是完全可 +以的，只要从存储库的描述中确认它们是普通的或者至少接近普通。此外，请确保软件 +包包含kernel.org上提供的最新版本内核。如果这些软件包的时间超过一周，那么它们 +可能就不合适了，因为新的主线和稳定版内核通常至少每周发布一次。 + +请注意，您以后可能需要手动构建自己的内核：有时这是调试或测试修复程序所必需的， +如后文所述。还要注意，预编译的内核可能缺少在出现panic、Oops、warning或BUG时 +解码内核打印的消息所需的调试符号；如果您计划解码这些消息，最好自己编译内核 +（有关详细信息，请参阅本小节结尾和“解码失败信息”小节）。 + +**使用git** ：熟悉 git 的开发者和有经验的 Linux 用户通常最好直接从 +`kernel.org 上的官方开发仓库 +<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ +中获取最新的 Linux 内核源代码。这些很可能比最新的主线预发布版本更新一些。不 +用担心：它们和正式的预发布版本一样可靠，除非内核的开发周期目前正处于合并窗 +口中。不过即便如此，它们也是相当可靠的。 + +**常规方法** ：不熟悉 git 的人通常最好从 `kernel.org <https://kernel.org/>`_ +下载源码的tar 存档包。 + +如何实际构建一个内核并不在这里描述，因为许多网站已经解释了必要的步骤。如果 +你是新手，可以考虑按照那些建议使用 ``make localmodconfig`` 来做，它将尝试获 +取你当前内核的配置，然后根据你的系统进行一些调整。这样做并不能使编译出来的 +内核更好，但可以更快地编译。 + +注意：如果您正在处理来自内核的pannc、Oops、warning或BUG，请在配置内核时尝试 +启用 CONFIG_KALLSYMS 选项。此外，还可以启用 CONFIG_DEBUG_KERNEL 和 +CONFIG_DEBUG_INFO；后者是相关选项，但只有启用前者才能开启。请注意， +CONFIG_DEBUG_INFO 会需要更多储存空间来构建内核。但这是值得的，因为这些选项将 +允许您稍后精确定位触发问题的确切代码行。下面的“解码失败信息”一节对此进行了更 +详细的解释。 + +但请记住：始终记录遇到的问题，以防难以重现。发送未解码的报告总比不报告要好。 + + +检查“污染”标志 +---------------- + + *确保您刚刚安装的内核在运行时不会“污染”自己。* + +正如上面已经详细介绍过的：当发生一些可能会导致一些看起来完全不相关的后续错 +误的事情时，内核会设置一个“污染”标志。这就是为什么你需要检查你刚刚安装的内 +核是否有设置此标志。如果有的话，几乎在任何情况下你都需要在报告问题之前先消 +除它。详细的操作方法请看上面的章节。 + + +用新内核重现问题 +------------------ + + *在您刚刚安装的内核中复现这个问题。如果它没有出现，请查看下方只发生在 + 稳定版和长期支持内核的问题的说明。* + +检查这个问题是否发生在你刚刚安装的新 Linux 内核版本上。如果新内核已经修复了， +可以考虑使用此版本线，放弃报告问题。但是请记住，只要它没有在 `kernel.org +<https://kernel.org/>`_ 的稳定版和长期版（以及由这些版本衍生出来的厂商内核） +中得到修复，其他用户可能仍然会受到它的困扰。如果你喜欢使用其中的一个，或 +者只是想帮助它们的用户，请前往下面的“报告只发生在较旧内核版本线的问题”一节。 + + +优化复现问题的描述 +-------------------- + + *优化你的笔记：试着找到并写出最直接的复现问题的方法。确保最终结果包含所 + 有重要的细节，同时让第一次听说的人容易阅读和理解。如果您在此过程中学到 + 了一些东西，请考虑再次搜索关于该问题的现有报告。* + +过于复杂的报告会让别人很难理解。因此请尽量找到一个可以直接描述、易于以书面 +形式理解的再现方法。包含所有重要的细节，但同时也要尽量保持简短。 + +在这在前面的步骤中，你很可能已经了解了一些关于你所面临的问题的点。利用这些 +知识，再次搜索可以转而加入的现有报告。 + + +解码失败信息 +------------- + + *如果失败涉及“panic”、“Oops”、“warning”或“BUG”，请考虑解码内核日志以查找 + 触发错误的代码行。* + +当内核检测到内部问题时，它会记录一些有关已执行代码的信息。这使得在源代码中精 +确定位触发问题的行并显示如何调用它成为可能。但只有在配置内核时启用了 +CONFIG_DEBUG_INFO 和 CONFIG_KALLSYMS选项时，这种方法才起效。如果已启用此选项， +请考虑解码内核日志中的信息。这将使我们更容易理解是什么导致了“panic”、“Oops”、 +“warning”或“BUG”，从而增加了有人提供修复的几率。 + +解码可以通过Linux源代码树中的脚本来完成。如果您运行的内核是之前自己编译的， +这样这样调用它:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh ./linux-5.10.5/vmlinux + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +如果您运行的是打包好的普通内核，则可能需要安装带有调试符号的相应包。然后按以下 +方式调用脚本（如果发行版未打包，则可能需要从Linux源代码获取）:: + + [user@something ~]$ sudo dmesg | ./linux-5.10.5/scripts/decode_stacktrace.sh \ + /usr/lib/debug/lib/modules/5.10.10-4.1.x86_64/vmlinux /usr/src/kernels/5.10.10-4.1.x86_64/ + +脚本将解码如下的日志行，这些日志行显示内核在发生错误时正在执行的代码的地址:: + + [ 68.387301] RIP: 0010:test_module_init+0x5/0xffa [test_module] + +解码之后，这些行将变成这样:: + + [ 68.387301] RIP: 0010:test_module_init (/home/username/linux-5.10.5/test-module/test-module.c:16) test_module + +在本例中，执行的代码是从文件“~/linux-5.10.5/test-module/test-module.c”构建的， +错误出现在第16行的指令中。 + +该脚本也会如此解码以“Call trace”开头的部分中提到的地址，该部分显示出现问题的 +函数的路径。此外，脚本还会显示内核正在执行的代码部分的汇编输出。 + +注意，如果你没法做到这一点，只需跳过这一步，并在报告中说明原因。如果你幸运的 +话，可能无需解码。如果需要的话，也许有人会帮你做这件事情。还要注意，这只是解 +码内核堆栈跟踪的几种方法之一。有时需要采取不同的步骤来检索相关的详细信息。 +别担心，如果您碰到的情况需要这样做，开发人员会告诉您该怎么做。 + + +对回归的特别关照 +----------------- + + *如果您的问题是回归问题，请尽可能缩小引入问题时的范围。* + +Linux 首席开发者 Linus Torvalds 认为 Linux 内核永远不应恶化，这就是为什么他 +认为回归是不可接受的，并希望看到它们被迅速修复。这就是为什么引入了回归的改 +动导致的问题若无法通过其他方式快速解决，通常会被迅速撤销。因此，报告回归有 +点像“王炸”，会迅速得到修复。但要做到这一点，需要知道导致回归的变化。通常情 +况下，要由报告者来追查罪魁祸首，因为维护者往往没有时间或手头设置不便来自行 +重现它。 + +有一个叫做“二分”的过程可以来寻找变化，这在 +“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”文档中进行了详细 +的描述，这个过程通常需要你构建十到二十个内核镜像，每次都尝试在构建下一个镜像 +之前重现问题。是的，这需要花费一些时间，但不用担心，它比大多数人想象的要快得多。 +多亏了“binary search二进制搜索”，这将引导你在源代码管理系统中找到导致回归的提交。 +一旦你找到它，就在网上搜索其主题、提交ID和缩短的提交ID（提交ID的前12个字符）。 +如果有的话，这将引导您找到关于它的现有报告。 + +需要注意的是，二分法需要一点窍门，不是每个人都懂得诀窍，也需要相当多的努力， +不是每个人都愿意投入。尽管如此，还是强烈建议自己进行一次二分。如果你真的 +不能或者不想走这条路，至少要找出是哪个主线内核引入的回归。比如说从 5.5.15 +切换到 5.8.4 的时候出现了一些问题，那么至少可以尝试一下相近的所有的主线版本 +（5.6、5.7 和 5.8）来检查它是什么时候出现的。除非你想在一个稳定版或长期支持 +内核中找到一个回归，否则要避免测试那些编号有三段的版本（5.6.12、5.7.8），因 +为那会使结果难以解释，可能会让你的测试变得无用。一旦你找到了引入回归的主要 +版本，就可以放心地继续报告了。但请记住：在不知道罪魁祸首的情况下，开发人员 +是否能够提供帮助取决于手头的问题。有时他们可能会从报告中确认是什么出现了问 +题，并能修复它；有时他们可能无法提供帮助，除非你进行二分。 + +当处理回归问题时，请确保你所面临的问题真的是由内核引起的，而不是由其他东西 +引起的，如上文所述。 + +在整个过程中，请记住：只有当旧内核和新内核的配置相似时，问题才算回归。最好 +的方法是：把配置文件（``.config``）从旧的工作内核直接复制到你尝试的每个新内 +核版本。之后运行 ``make oldnoconfig`` 来调整它以适应新版本的需要，而不启用 +任何新的功能，因为那些功能也可能导致回归。 + + +撰写并发送报告 +--------------- + + *通过详细描述问题来开始编写报告。记得包括以下条目：您为复现而安装的最新 + 内核版本、使用的Linux发行版以及关于如何复现该问题的说明。如果可能，将内 + 核构建配置（.config）和 ``dmesg`` 的输出放在网上的某个地方，并链接到它。 + 包含或上传所有其他可能相关的信息，如Oops的输出/截图或来自 ``lspci`` + 的输出。一旦你写完了这个主要部分，请在上方插入一个正常长度的段落快速概 + 述问题和影响。再在此之上添加一个简单描述问题的句子，以得到人们的阅读。 + 现在给出一个更短的描述性标题或主题。然后就可以像MAINTAINERS文件告诉你的 + 那样发送或提交报告了，除非你在处理一个“高优先级问题”：它们需要按照下面 + “高优先级问题的特殊处理”所述特别关照。* + +现在你已经准备好了一切，是时候写你的报告了。上文前言中链接的三篇文档对如何 +写报告做了部分解释。这就是为什么本文将只提到一些基本的内容以及 Linux 内核特 +有的东西。 + +有一点是符合这两类的：你的报告中最关键的部分是标题/主题、第一句话和第一段。 +开发者经常会收到许多邮件。因此，他们往往只是花几秒钟的时间浏览一下邮件，然 +后再决定继续下一封或仔细查看。因此，你报告的开头越好，有人研究并帮助你的机 +会就越大。这就是为什么你应该暂时忽略他们，先写出详细的报告。;-) + +每份报告都应提及的事项 +~~~~~~~~~~~~~~~~~~~~~~~~ + +详细描述你的问题是如何发生在你安装的新纯净内核上的。试着包含你之前写的和优 +化过的分步说明，概述你和其他人如何重现这个问题；在极少数无法重现的情况下， +尽量描述你做了什么来触发它。 + +还应包括其他人为了解该问题及其环境而可能需要的所有相关信息。实际需要的东西 +在很大程度上取决于具体问题，但有些事项你总是应该包括在内： + + * ``cat /proc/version`` 的输出，其中包含 Linux 内核版本号和构建时的编译器。 + + * 机器正在运行的 Linux 发行版（ ``hostnamectl | grep “Operating System“`` ） + + * CPU 和操作系统的架构（ ``uname -mi`` ） + + * 如果您正在处理回归，并进行了二分，请提及导致回归的变更的主题和提交ID。 + +许多情况下，让读你报告的人多了解两件事也是明智之举： + + * 用于构建 Linux 内核的配置（“.config”文件） + + * 内核的信息，你从 ``dmesg`` 得到的信息写到一个文件里。确保它以像“Linux + version 5.8-1 (foobar@example.com) (gcc (GCC) 10.2.1, GNU ld version + 2.34) #1 SMP Mon Aug 3 14:54:37 UTC 2020”这样的行开始，如果没有，那么第 + 一次启动阶段的重要信息已经被丢弃了。在这种情况下，可以考虑使用 + ``journalctl -b 0 -k`` ；或者你也可以重启，重现这个问题，然后调用 + ``dmesg`` 。 + +这两个文件很大，所以直接把它们放到你的报告中是个坏主意。如果你是在缺陷跟踪 +器中提交问题，那么将它们附加到工单中。如果你通过邮件报告问题，不要用附件附 +上它们，因为那会使邮件变得太大，可以按下列之一做： + + * 将文件上传到某个公开的地方（你的网站，公共文件粘贴服务，在 + `bugzilla.kernel.org <https://bugzilla.kernel.org/>`_ 上创建的工单……）， + 并在你的报告中放上链接。理想情况下请使用允许这些文件保存很多年的地方，因 + 为它们可能在很多年后对别人有用；例如 5 年或 10 年后，一个开发者正在修改 + 一些代码，而这些代码正是为了修复你的问题。 + + * 把文件放在一边，然后说明你会在他人回复时再单独发送。只要记得报告发出去后， + 真正做到这一点就可以了。;-) + +提供这些东西可能是明智的 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +根据问题的不同，你可能需要提供更多的背景数据。这里有一些关于提供什么比较好 +的建议： + + * 如果你处理的是内核的“warning”、“OOPS”或“panic”，请包含它。如果你不能复制 + 粘贴它，试着用netconsole网络终端远程跟踪或者至少拍一张屏幕的照片。 + + * 如果问题可能与你的电脑硬件有关，请说明你使用的是什么系统。例如，如果你的 + 显卡有问题，请提及它的制造商，显卡的型号，以及使用的芯片。如果是笔记本电 + 脑，请提及它的型号名称，但尽量确保意义明确。例如“戴尔 XPS 13”就不很明确， + 因为它可能是 2012 年的那款，那款除了看起来和现在销售的没有什么不同之外， + 两者没有任何共同之处。因此，在这种情况下，要加上准确的型号，例如 2019 + 年内推出的 XPS 13 型号为“9380”或“7390”。像“联想 Thinkpad T590”这样的名字 + 也有些含糊不清：这款笔记本有带独立显卡和不带的子型号，所以要尽量找到准确 + 的型号名称或注明主要部件。 + + * 说明正在使用的相关软件。如果你在加载模块时遇到了问题，你要说明正在使用的 + kmod、systemd 和 udev 的版本。如果其中一个 DRM 驱动出现问题，你要说明 + libdrm 和 Mesa 的版本；还要说明你的 Wayland 合成器或 X-Server 及其驱动。 + 如果你有文件系统问题，请注明相应的文件系统实用程序的版本（e2fsprogs, + btrfs-progs, xfsprogs……）。 + + * 从内核中收集可能有用的额外信息。例如， ``lspci -nn`` 的输出可以帮助别人 + 识别你使用的硬件。如果你的硬件有问题，你甚至可以给出 ``sudo lspci -vvv`` + 的结果，因为它提供了组件是如何配置的信息。对于一些问题，可能最好包含 + ``/proc/cpuinfo`` ， ``/proc/ioports`` ， ``/proc/iomem`` ， + ``/proc/modules`` 或 ``/proc/scsi/scsi`` 等文件的内容。一些子系统还提 + 供了收集相关信息的工具。 ``alsa-info.sh`` `就是这样一个工具，它是音频/声 + 音子系统开发者提供的 <https://www.alsa-project.org/wiki/AlsaInfo>`_ 。 + +这些例子应该会给你一些知识点，让你知道附上什么数据可能是明智的，但你自己也 +要想一想，哪些数据对别人会有帮助。不要太担心忘记一些东西，因为开发人员会要 +求提供他们需要的额外细节。但从一开始就把所有重要的东西都提供出来，会增加别 +人仔细查看的机会。 + + +重要部分：报告的开头 +~~~~~~~~~~~~~~~~~~~~~~ + +现在你已经准备好了报告的详细部分，让我们进入最重要的部分：开头几句。现在到 +报告的最前面，在你刚才写的部分之前加上类似“The detailed description:”（详细 +描述）这样的内容，并在最前面插入两个新行。现在写一个正常长度的段落，大致概 +述这个问题。去掉所有枯燥的细节，把重点放在读者需要知道的关键部分，以让人了 +解这是怎么回事；如果你认为这个缺陷影响了很多用户，就提一下这点来吸引大家关 +注。 + +做好这一点后，在顶部再插入两行，写一句话的摘要，快速解释报告的内容。之后你 +要更加抽象，为报告写一个更短的主题/标题。 + +现在你已经写好了这部分，请花点时间来优化它，因为它是你的报告中最重要的部分： +很多人会先读这部分，然后才会决定是否值得花时间阅读其他部分。 + +现在就像 :ref:`MAINTAINERS <maintainers>` 维护者文件告诉你的那样发送或提交 +报告，除非它是前面概述的那些“高优先级问题”之一：在这种情况下，请先阅读下一 +小节，然后再发送报告。 + +高优先级问题的特殊处理 +~~~~~~~~~~~~~~~~~~~~~~~~ + +高优先级问题的报告需要特殊处理。 + +**非常严重的缺陷** ：确保在主题或工单标题以及第一段中明显标出 severeness +（非常严重的）。 + +**回归** ：如果问题是一个回归，请在邮件的主题或缺陷跟踪器的标题中添加 +[REGRESSION]。如果您没有进行二分，请至少注明您测试的最新主线版本（比如 5.7） +和出现问题的最新版本（比如 5.8）。如果您成功地进行了二分，请注明导致回归 +的提交ID和主题。也请添加该变更的作者到你的报告中；如果您需要将您的缺陷提交 +到缺陷跟踪器中，请将报告以私人邮件的形式转发给他，并注明报告提交地点。 + +**安全问题** ：对于这种问题，你将必须评估：如果细节被公开披露，是否会对其他 +用户产生短期风险。如果不会，只需按照所述继续报告问题。如果有此风险，你需要 +稍微调整一下报告流程。 + + * 如果 MAINTAINERS 文件指示您通过邮件报告问题，请不要抄送任何公共邮件列表。 + + * 如果你应该在缺陷跟踪器中提交问题，请确保将工单标记为“私有”或“安全问题”。 + 如果缺陷跟踪器没有提供保持报告私密性的方法，那就别想了，把你的报告以私人 + 邮件的形式发送给维护者吧。 + +在这两种情况下，都一定要将报告发到 MAINTAINERS 文件中“安全联络”部分列出的 +地址。理想的情况是在发送报告的时候直接抄送他们。如果您在缺陷跟踪器中提交了 +报告，请将报告的文本转发到这些地址；但请在报告的顶部加上注释，表明您提交了 +报告，并附上工单链接。 + +更多信息请参见“Documentation/translations/zh_CN/admin-guide/security-bugs.rst”。 + + +发布报告后的责任 +------------------ + + *等待别人的反应，继续推进事情，直到你能够接受这样或那样的结果。因此，请 + 公开和及时地回应任何询问。测试提出的修复。积极地测试：至少重新测试每个 + 新主线版本的首个候选版本（RC），并报告你的结果。如果出现拖延，就友好地 + 提醒一下。如果你没有得到任何帮助或者未能满意，请试着自己帮助自己。* + +如果你的报告非常优秀，而且你真的很幸运，那么某个开发者可能会立即发现导致问 +题的原因；然后他们可能会写一个补丁来修复、测试它，并直接发送给主线集成，同 +时标记它以便以后回溯到需要它的稳定版和长期支持内核。那么你需要做的就是回复 +一句“Thank you very much”（非常感谢），然后在发布后换上修复好的版本。 + +但这种理想状况很少发生。这就是为什么你把报告拿出来之后工作才开始。你要做的 +事情要视情况而定，但通常会是下面列出的事情。但在深入研究细节之前，这里有几 +件重要的事情，你需要记住这部分的过程。 + + +关于进一步互动的一般建议 +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**总是公开回复** ：当你在缺陷跟踪器中提交问题时，一定要在那里回复，不要私下 +联系任何开发者。对于邮件报告，在回复您收到的任何邮件时，总是使用“全部回复” +功能。这包括带有任何你可能想要添加到你的报告中的额外数据的邮件：进入邮件应 +用程序“已发送”文件夹，并在邮件上使用“全部回复”来回复报告。这种方法可以确保 +公共邮件列表和其他所有参与者都能及时了解情况；它还能保持邮件线程的完整性， +这对于邮件列表将所有相关邮件归为一类是非常重要的。 + +只有两种情况不适合在缺陷跟踪器或“全部回复”中发表评论： + + * 有人让你私下发东西。 + + * 你被告知要发送一些东西，但注意到其中包含需要保密的敏感信息。在这种情况下， + 可以私下发送给要求发送的开发者。但要在工单或邮件中注明你是这么做的，这 + 样其他人就知道你尊重了这个要求。 + +**在请求解释或帮助之前先研究一下** ：在这部分过程中，有人可能会告诉你用尚未 +掌握的技能做一些事情。例如你可能会被要求使用一些你从未听说过的测试工具；或 +者你可能会被要求在 Linux 内核源代码上应用一个补丁来测试它是否有帮助。在某些 +情况下，发个回复询问如何做就可以了。但在走这条路之前，尽量通过在互联网上搜 +索自行找到答案；或者考虑在其他地方询问建议。比如询问朋友，或者到你平时常去 +的聊天室或论坛发帖咨询。 + +**要有耐心** ：如果你真的很幸运，你可能会在几个小时内收到对你的报告的答复。 +但大多数情况下会花费更多的时间，因为维护者分散在全球各地，因此可能在不同的 +时区——在那里他们已经享受着远离键盘的夜晚。 + +一般来说，内核开发者需要一到五个工作日来回复报告。有时会花费更长的时间，因 +为他们可能正忙于合并窗口、其他工作、参加开发者会议，或者只是在享受一个漫长 +的暑假。 + +“高优先级的问题”（见上面的解释）例外：维护者应该尽快解决这些问题；这就是为 +什么你应该最多等待一个星期（如果是紧急的事情，则只需两天），然后再发送友好 +的提醒。 + +有时维护者可能没有及时回复；有时候可能会出现分歧，例如一个问题是否符合回归 +的条件。在这种情况下，在邮件列表上提出你的顾虑，并请求其他人公开或私下回复 +如何继续推进。如果失败了，可能应该让更高级别的维护者介入。如果是 WiFi 驱动， +那就是无线维护者；如果没有更高级别的维护者，或者其他一切努力都失败了，那 +这可能是一种罕见的、可以让 Linus Torvalds 参与进来的情况。 + +**主动测试** ：每当一个新的主线内核版本的第一个预发布版本（rc1）发布的时候， +去检查一下这个问题是否得到了解决，或者是否有什么重要的变化。在工单中或在 +回复报告的邮件中提及结果（确保所有参与讨论的人都被抄送）。这将表明你的承诺 +和你愿意帮忙。如果问题持续存在，它也会提醒开发者确保他们不会忘记它。其他一 +些不定期的重新测试（例如用rc3、rc5 和最终版本）也是一个好主意，但只有在相关 +的东西发生变化或者你正在写什么东西的时候才报告你的结果。 + +这些些常规的事情就不说了，我们来谈谈报告后如何帮助解决问题的细节。 + +查询和测试请求 +~~~~~~~~~~~~~~~ + +如果你的报告得到了回复则需履行以下责任： + +**检查与你打交道的人** ：大多数情况下，会是维护者或特定代码区域的开发人员对 +你的报告做出回应。但由于问题通常是公开报告的，所以回复的可能是任何人——包括 +那些想要帮忙的人，但最后可能会用他们的问题或请求引导你完全偏离轨道。这很少 +发生，但这是快速上网搜搜看你正在与谁互动是明智之举的许多原因之一。通过这样 +做，你也可以知道你的报告是否被正确的人听到，因为如果讨论没有导致满意的问题 +解决方案而淡出，之后可能需要提醒维护者（见下文）。 + +**查询数据** ：通常你会被要求测试一些东西或提供更多细节。尽快提供所要求的信 +息，因为你已经得到了可能会帮助你的人的注意，你等待的时间越长就有越可能失去 +关注；如果你不在数个工作日内提供信息，甚至可能出现这种结果。 + +**测试请求** ：当你被要求测试一个诊断补丁或可能的修复时，也要尽量及时测试。 +但要做得恰当，一定不要急于求成：混淆事情很容易发生，这会给所有人带来许多困 +惑。例如一个常见的错误是以为应用了一个带修复的建议补丁，但事实上并没有。即 +使是有经验的测试人员也会偶尔发生这样的事情，但当有修复的内核和没有修复的内 +核表现得一样时，他们大多时候会注意到。 + +当没有任何实质性进展时该怎么办 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +有些报告不会得到负有相关责任的 Linux 内核开发者的任何反应；或者围绕这个问题 +的讨论有所发展，但渐渐淡出，没有任何实质内容产出。 + +在这种情况下，要等两个星期（最好是三个星期）后再发出友好的提醒：也许当你的 +报告到达时，维护者刚刚离开键盘一段时间，或者有更重要的事情要处理。在写提醒 +信的时候，要善意地问一下，是否还需要你这边提供什么来让事情推进下去。如果报 +告是通过邮件发出来的，那就在邮件的第一行回复你的初始邮件（见上文），其中包 +括下方的原始报告的完整引用：这是少数几种情况下，这样的“TOFU”（Text Over, +Fullquote Under文字在上，完整引用在下）是正确的做法，因为这样所有的收件人都 +会以适当的顺序立即让细节到手头上来。 + +在提醒之后，再等三周的回复。如果你仍然没有得到适当的反馈，你首先应该重新考 +虑你的方法。你是否可能尝试接触了错误的人？是不是报告也许令人反感或者太混乱， +以至于人们决定完全远离它？排除这些因素的最好方法是：把报告给一两个熟悉 +FLOSS 问题报告的人看，询问他们的意见。同时征求他们关于如何继续推进的建议。 +这可能意味着：准备一份更好的报告，让这些人在你发出去之前对它进行审查。这样 +的方法完全可以；只需说明这是关于这个问题的第二份改进的报告，并附上第一份报 +告的链接。 + +如果报告是恰当的，你可以发送第二封提醒信；在其中询问为什么报告没有得到任何 +回复。第二封提醒邮件的好时机是在新 Linux 内核版本的首个预发布版本（'rc1'） +发布后不久，因为无论如何你都应该在那个时候重新测试并提供状态更新（见上文）。 + +如果第二次提醒的结果又在一周内没有任何反应，可以尝试联系上级维护者询问意见： +即使再忙的维护者在这时候也至少应该发过某种确认。 + +记住要做好失望的准备：理想状况下维护者最好对每一个问题报告做出回应，但他们 +只有义务解决之前列出的“高优先级问题”。所以，如果你得到的回复是“谢谢你的报告， +我目前有更重要的问题要处理，在可预见的未来没有时间去研究这个问题”，那请不 +要太沮丧。 + +也有可能在缺陷跟踪器或列表中进行了一些讨论之后，什么都没有发生，提醒也无助 +于激励大家进行修复。这种情况可能是毁灭性的，但在 Linux 内核开发中确实会发生。 +这些和其他得不到帮助的原因在本文结尾处的“为什么有些问题在被报告后没有得到 +任何回应或者仍然没有修复”中进行了解释。 + +如果你没有得到任何帮助或问题最终没有得到解决，不要沮丧：Linux 内核是 FLOSS， +因此你仍然可以自己帮助自己。例如，你可以试着找到其他受影响的人，和他们一 +起合作来解决这个问题。这样的团队可以一起准备一份新的报告，提到团队有多少人， +为什么你们认为这是应该得到解决的事情。也许你们还可以一起缩小确切原因或引 +入回归的变化，这往往会使修复更容易。而且如果运气好的话，团队中可能会有懂点 +编程的人，也许能写出一个修复方案。 + + + +“报告稳定版和长期支持内核线的回归”的参考 +------------------------------------------ + +本小节提供了在稳定版和长期支持内核线中面对回归时需要执行的步骤的详细信息。 + +确保特定版本线仍然受支持 +~~~~~~~~~~~~~~~~~~~~~~~~~ + + *检查内核开发人员是否仍然维护你关心的Linux内核版本线：去 kernel.org 的 + 首页，确保此特定版本线的最新版没有“[EOL]”标记。* + +大多数内核版本线只支持三个月左右，因为延长维护时间会带来相当多的工作。因此， +每年只会选择一个版本来支持至少两年（通常是六年）。这就是为什么你需要检查 +内核开发者是否还支持你关心的版本线。 + +注意，如果 `kernel.org <https://kernel.org/>`_ 在首页上列出了两个“稳定”版本， +你应该考虑切换到较新的版本，而忘掉较旧的版本：对它的支持可能很快就会结束。 +然后，它将被标记为“生命周期结束”（EOL）。达到这个程度的版本线仍然会在 +`kernel.org <https://kernel.org/>`_ 首页上被显示一两周，但不适合用于测试和 +报告。 + +搜索稳定版邮件列表 +~~~~~~~~~~~~~~~~~~~ + + *检查Linux稳定版邮件列表中的现有报告。* + +也许你所面临的问题已经被发现，并且已经或即将被修复。因此，请在 `Linux 稳定 +版邮件列表的档案 <https://lore.kernel.org/stable/>`_ 中搜索类似问题的报告。 +如果你找到任何匹配的问题，可以考虑加入讨论，除非修复工作已经完成并计划很快 +得到应用。 + +用最新版本复现问题 +~~~~~~~~~~~~~~~~~~~ + + *从特定的版本线安装最新版本作为纯净内核。确保这个内核没有被污染，并且仍 + 然存在问题，因为问题可能已经在那里被修复了。* + +在投入更多时间到这个过程中之前，你要检查这个问题是否在你关注的版本线的最新 +版本中已经得到了修复。这个内核需要是纯净的，在问题发生之前不应该被污染，正 +如上面已经在测试主线的过程中详细介绍过的一样。 + +您是否是第一次注意到供应商内核的回归？供应商的更改可能会发生变化。你需要重新 +检查排除来这个问题。当您从5.10.4-vendor.42更新到5.10.5-vendor.43时，记录损坏 +的信息。然后在测试了前一段中所述的最新5.10版本之后，检查Linux 5.10.4的普通版本 +是否也可以正常工作。如果问题在那里出现，那就不符合上游回归的条件，您需要切换 +回主逐步指南来报告问题。 + +报告回归 +~~~~~~~~~~ + + *向Linux稳定版邮件列表发送一个简短的问题报告(stable@vger.kernel.org)。 + 大致描述问题，并解释如何复现。讲清楚首个出现问题的版本和最后一个工作正常 + 的版本。然后等待进一步的指示。* + +当报告在稳定版或长期支持内核线内发生的回归（例如在从5.10.4更新到5.10.5时）， +一份简短的报告足以快速报告问题。因此只需要粗略的描述。 + +但是请注意，如果您能够指明引入问题的确切版本，这将对开发人员有很大帮助。因此 +如果有时间的话，请尝试使用普通内核找到该版本。让我们假设发行版发布Linux内核 +5.10.5到5.10.8的更新时发生了故障。那么按照上面的指示，去检查该版本线中的最新 +内核，比如5.10.9。如果问题出现，请尝试普通5.10.5，以确保供应商应用的补丁不会 +干扰。如果问题没有出现，那么尝试5.10.7，然后直到5.10.8或5.10.6（取决于结果） +找到第一个引入问题的版本。在报告中写明这一点，并指出5.10.9仍然存在故障。 + +前一段基本粗略地概述了“二分”方法。一旦报告出来，您可能会被要求做一个正确的 +报告，因为它允许精确地定位导致问题的确切更改（然后很容易被恢复以快速修复问题）。 +因此如果时间允许，考虑立即进行适当的二分。有关如何详细信息，请参阅“对回归的 +特别关照”部分和文档“Documentation/translations/zh_CN/admin-guide/bug-bisect.rst”。 + + +“报告仅在旧内核版本线中发生的问题”的参考 +---------------------------------------- + +本节详细介绍了如果无法用主线内核重现问题，但希望在旧版本线（又称稳定版内核和 +长期支持内核）中修复问题时需要采取的步骤。 + +有些修复太复杂 +~~~~~~~~~~~~~~~ + + *请做好准备，接下来的几个步骤可能无法在旧版本中解决问题：修复可能太大或 + 太冒险，无法移植到那里。* + +即使是微小的、看似明显的代码变化，有时也会带来新的、完全意想不到的问题。稳 +定版和长期支持内核的维护者非常清楚这一点，因此他们只对这些内核进行符合 +“Documentation/translations/zh_CN/process/stable-kernel-rules.rst”中所列出的 +规则的修改。 + +复杂或有风险的修改不符合条件，因此只能应用于主线。其他的修复很容易被回溯到 +最新的稳定版和长期支持内核，但是风险太大，无法集成到旧版内核中。所以要注意 +你所希望的修复可能是那些不会被回溯到你所关心的版本线的修复之一。在这种情况 +下，你将别无选择，要么忍受这个问题，要么切换到一个较新的 Linux 版本，除非你 +想自己把修复补丁应用到你的内核中。 + +通用准备 +~~~~~~~~~~ + + *执行上面“报告仅在旧内核版本线中发生的问题”一节中的前三个步骤。* + +您需要执行本指南另一节中已经描述的几个步骤。这些步骤将让您： + + * 检查内核开发人员是否仍然维护您关心的Linux内核版本行。 + + * 在Linux稳定邮件列表中搜索退出的报告。 + + * 检查最新版本。 + + +检查代码历史和搜索现有的讨论 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *在Linux内核版本控制系统中搜索修复主线问题的更改，因为它的提交消息可能 + 会告诉你修复是否已经计划好了支持。如果你没有找到，搜索适当的邮件列表， + 寻找讨论此类问题或同行评议可能修复的帖子；然后检查讨论是否认为修复不适 + 合支持。如果支持根本不被考虑，加入最新的讨论，询问是否有可能。* + +在许多情况下，你所处理的问题会发生在主线上，但已在主线上得到了解决。修正它 +的提交也需要被回溯才能解决这个问题。这就是为什么你要搜索它或任何相关讨论。 + + * 首先尝试在存放 Linux 内核源代码的 Git 仓库中找到修复。你可以通过 + `kernel.org 上的网页 + <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/>`_ + 或 `GitHub 上的镜像 <https://github.com/torvalds/linux>`_ 来实现；如果你 + 有一个本地克隆，你也可以在命令行用 ``git log --grep=<pattern>`` 来搜索。 + + 如果你找到了修复，请查看提交消息的尾部是否包含了类似这样的“稳定版标签”： + + Cc: <stable@vger.kernel.org> # 5.4+ + + 像上面这行，开发者标记了安全修复可以回传到 5.4 及以后的版本。大多数情况 + 下，它会在两周内被应用到那里，但有时需要更长的时间。 + + * 如果提交没有告诉你任何东西，或者你找不到修复，请再找找关于这个问题的讨论。 + 用你最喜欢的搜索引擎搜索网络，以及 `Linux kernel developers mailing + list 内核开发者邮件列表 <https://lore.kernel.org/lkml/>`_ 的档案。也可以 + 阅读上面的 `定位导致问题的内核区域` 一节，然后按照说明找到导致问题的子系 + 统：它的缺陷跟踪器或邮件列表存档中可能有你要找的答案。 + + * 如果你看到了一个计划的修复，请按上所述在版本控制系统中搜索它，因为提交可 + 能会告诉你是否可以进行回溯。 + + * 检查讨论中是否有任何迹象表明，该修复程序可能风险太大，无法回溯到你关心 + 的版本线。如果是这样的话，你必须忍受这个问题，或者切换到应用了修复的内 + 核版本线。 + + * 如果修复的问题未包含稳定版标签，并且没有讨论过回溯问题，请加入讨论：如 + 果合适的话，请提及你所面对的问题的版本，以及你希望看到它被修复。 + + +请求建议 +~~~~~~~~~ + + *前面的步骤之一应该会给出一个解决方案。如果仍未能成功，请向可能引起问题 + 的子系统的维护人员询问建议；抄送特定子系统的邮件列表以及稳定版邮件列表。* + +如果前面的三个步骤都没有让你更接近解决方案，那么只剩下一个选择：请求建议。 +在你发给可能是问题根源的子系统的维护者的邮件中这样做；抄送子系统的邮件列表 +以及稳定版邮件列表（stable@vger.kernel.org）。 + + +为什么有些问题在报告后没有任何回应或仍未解决？ +=============================================== + +当向 Linux 开发者报告问题时，要注意只有“高优先级的问题”（回归、安全问题、严 +重问题）才一定会得到解决。如果维护者或其他人都失败了，Linus Torvalds 他自己 +会确保这一点。他们和其他内核开发者也会解决很多其他问题。但是要知道，有时他 +们也会不能或不愿帮忙；有时甚至没有人发报告给他们。 + +最好的解释就是那些内核开发者常常是在业余时间为 Linux 内核做出贡献。内核中的 +不少驱动程序都是由这样的程序员编写的，往往只是因为他们想让自己的硬件可以在 +自己喜欢的操作系统上使用。 + +这些程序员大多数时候会很乐意修复别人报告的问题。但是没有人可以强迫他们这样 +做，因为他们是自愿贡献的。 + +还有一些情况下，这些开发者真的很想解决一个问题，但却不能解决：有时他们缺乏 +硬件编程文档来解决问题。这种情况往往由于公开的文档太简陋，或者驱动程序是通 +过逆向工程编写的。 + +业余开发者迟早也会不再关心某驱动。也许他们的测试硬件坏了，被更高级的玩意取 +代了，或者是太老了以至于只能在计算机博物馆里找到。有时开发者根本就不关心他 +们的代码和 Linux 了，因为在他们的生活中一些不同的东西变得更重要了。在某些情 +况下，没有人愿意接手维护者的工作——也没有人可以被强迫，因为对 Linux 内核的贡 +献是自愿的。然而被遗弃的驱动程序仍然存在于内核中：它们对人们仍然有用，删除 +它们可能导致回归。 + +对于那些为 Linux 内核工作而获得报酬的开发者来说，情况并没有什么不同。这些人 +现在贡献了大部分的变更。但是他们的雇主迟早也会停止关注他们的代码或者让程序 +员专注于其他事情。例如，硬件厂商主要通过销售新硬件来赚钱；因此，他们中的不 +少人并没有投入太多时间和精力来维护他们多年前就停止销售的东西的 Linux 内核驱 +动。企业级 Linux 发行商往往持续维护的时间比较长，但在新版本中往往会把对老旧 +和稀有硬件的支持放在一边，以限制范围。一旦公司抛弃了一些代码，往往由业余贡 +献者接手，但正如上面提到的：他们迟早也会放下代码。 + +优先级是一些问题没有被修复的另一个原因，因为维护者相当多的时候是被迫设置这 +些优先级的，因为在 Linux 上工作的时间是有限的。对于业余时间或者雇主给予他们 +的开发人员用于上游内核维护工作的时间也是如此。有时维护人员也会被报告淹没， +即使一个驱动程序几乎完美地工作。为了不被完全缠住，程序员可能别无选择，只能 +对问题报告进行优先级排序而拒绝其中的一些报告。 + +不过这些都不用太过担心，很多驱动都有积极的维护者，他们对尽可能多的解决问题 +相当感兴趣。 + + +结束语 +======= + +与其他免费/自由&开源软件（Free/Libre & Open Source Software，FLOSS）相比， +向 Linux 内核开发者报告问题是很难的：这个文档的长度和复杂性以及字里行间的内 +涵都说明了这一点。但目前就是这样了。这篇文字的主要作者希望通过记录现状来为 +以后改善这种状况打下一些基础。 diff --git a/Documentation/translations/zh_CN/admin-guide/security-bugs.rst b/Documentation/translations/zh_CN/admin-guide/security-bugs.rst new file mode 100644 index 000000000000..b8120391755d --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/security-bugs.rst @@ -0,0 +1,74 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/security-bugs` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +安全缺陷 +========= + +Linux内核开发人员非常重视安全性。因此我们想知道何时发现了安全漏洞，以便尽快 +修复和披露。请向Linux内核安全团队报告安全漏洞。 + +联络 +----- + +可以通过电子邮件<security@kernel.org>联系Linux内核安全团队。这是一个安全人员 +的私有列表，他们将帮助验证错误报告并开发和发布修复程序。如果您已经有了一个 +修复，请将其包含在您的报告中，这样可以大大加快进程。安全团队可能会从区域维护 +人员那里获得额外的帮助，以理解和修复安全漏洞。 + +与任何缺陷一样，提供的信息越多，诊断和修复就越容易。如果您不清楚哪些信息有用， +请查看“Documentation/translations/zh_CN/admin-guide/reporting-issues.rst”中 +概述的步骤。任何利用漏洞的攻击代码都非常有用，未经报告者同意不会对外发布，除 +非已经公开。 + +请尽可能发送无附件的纯文本电子邮件。如果所有的细节都藏在附件里，那么就很难对 +一个复杂的问题进行上下文引用的讨论。把它想象成一个 +:doc:`常规的补丁提交 <../process/submitting-patches>` （即使你还没有补丁）： +描述问题和影响，列出复现步骤，然后给出一个建议的解决方案，所有这些都是纯文本的。 + +披露和限制信息 +--------------- + +安全列表不是公开渠道。为此，请参见下面的协作。 + +一旦开发出了健壮的补丁，发布过程就开始了。对公开的缺陷的修复会立即发布。 + +尽管我们倾向于在未公开缺陷的修复可用时即发布补丁，但应报告者或受影响方的请求， +这可能会被推迟到发布过程开始后的7日内，如果根据缺陷的严重性需要更多的时间， +则可额外延长到14天。推迟发布修复的唯一有效原因是为了适应QA的逻辑和需要发布 +协调的大规模部署。 + +虽然可能与受信任的个人共享受限信息以开发修复，但未经报告者许可，此类信息不会 +与修复程序一起发布或发布在任何其他披露渠道上。这包括但不限于原始错误报告和 +后续讨论（如有）、漏洞、CVE信息或报告者的身份。 + +换句话说，我们唯一感兴趣的是修复缺陷。提交给安全列表的所有其他资料以及对报告 +的任何后续讨论，即使在解除限制之后，也将永久保密。 + +协调 +------ + +对敏感缺陷（例如那些可能导致权限提升的缺陷）的修复可能需要与私有邮件列表 +<linux-distros@vs.openwall.org>进行协调，以便分发供应商做好准备，在公开披露 +上游补丁时发布一个已修复的内核。发行版将需要一些时间来测试建议的补丁，通常 +会要求至少几天的限制，而供应商更新发布更倾向于周二至周四。若合适，安全团队 +可以协助这种协调，或者报告者可以从一开始就包括linux发行版。在这种情况下，请 +记住在电子邮件主题行前面加上“[vs]”，如linux发行版wiki中所述： +<http://oss-security.openwall.org/wiki/mailing-lists/distros#how-to-use-the-lists>。 + +CVE分配 +-------- + +安全团队通常不分配CVE，我们也不需要它们来进行报告或修复，因为这会使过程不必 +要的复杂化，并可能耽误缺陷处理。如果报告者希望在公开披露之前分配一个CVE编号， +他们需要联系上述的私有linux-distros列表。当在提供补丁之前已有这样的CVE编号时， +如报告者愿意，最好在提交消息中提及它。 + +保密协议 +--------- + +Linux内核安全团队不是一个正式的机构实体，因此无法签订任何保密协议。 diff --git a/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst b/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst new file mode 100644 index 000000000000..bc51d7cff9b0 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst @@ -0,0 +1,157 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: :doc:`../../../admin-guide/tainted-kernels` + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +受污染的内核 +------------- + +当发生一些在稍后调查问题时可能相关的事件时，内核会将自己标记为“受污染 +（tainted）”的。不用太过担心，大多数情况下运行受污染的内核没有问题；这些信息 +主要在有人想调查某个问题时才有意义的，因为问题的真正原因可能是导致内核受污染 +的事件。这就是为什么来自受污染内核的缺陷报告常常被开发人员忽略，因此请尝试用 +未受污染的内核重现问题。 + +请注意，即使在您消除导致污染的原因（亦即卸载专有内核模块）之后，内核仍将保持 +污染状态，以表示内核仍然不可信。这也是为什么内核在注意到内部问题（“kernel +bug”）、可恢复错误（“kernel oops”）或不可恢复错误（“kernel panic”）时会打印 +受污染状态，并将有关此的调试信息写入日志 ``dmesg`` 输出。也可以通过 +``/proc/`` 中的文件在运行时检查受污染的状态。 + + +BUG、Oops或Panics消息中的污染标志 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +在顶部以“CPU:”开头的一行中可以找到受污染的状态；内核是否受到污染和原因会显示 +在进程ID（“PID:”）和触发事件命令的缩写名称（“Comm:”）之后:: + + BUG: unable to handle kernel NULL pointer dereference at 0000000000000000 + Oops: 0002 [#1] SMP PTI + CPU: 0 PID: 4424 Comm: insmod Tainted: P W O 4.20.0-0.rc6.fc30 #1 + Hardware name: Red Hat KVM, BIOS 0.5.1 01/01/2011 + RIP: 0010:my_oops_init+0x13/0x1000 [kpanic] + [...] + +如果内核在事件发生时没有被污染，您将在那里看到“Not-tainted:”；如果被污染，那 +么它将是“Tainted:”以及字母或空格。在上面的例子中，它看起来是这样的:: + + Tainted: P W O + +下表解释了这些字符的含义。在本例中，由于加载了专有模块（ ``P`` ），出现了 +警告（ ``W`` ），并且加载了外部构建的模块（ ``O`` ），所以内核早些时候受到 +了污染。要解码其他字符，请使用下表。 + + +解码运行时的污染状态 +~~~~~~~~~~~~~~~~~~~~~ + +在运行时，您可以通过读取 ``cat /proc/sys/kernel/tainted`` 来查询受污染状态。 +如果返回 ``0`` ，则内核没有受到污染；任何其他数字都表示受到污染的原因。解码 +这个数字的最简单方法是使用脚本 ``tools/debugging/kernel-chktaint`` ，您的 +发行版可能会将其作为名为 ``linux-tools`` 或 ``kernel-tools`` 的包的一部分提 +供；如果没有，您可以从 +`git.kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/tools/debugging/kernel-chktaint>`_ +网站下载此脚本并用 ``sh kernel-chktaint`` 执行，它会在上面引用的日志中有类似 +语句的机器上打印这样的内容:: + + Kernel is Tainted for following reasons: + * Proprietary module was loaded (#0) + * Kernel issued warning (#9) + * Externally-built ('out-of-tree') module was loaded (#12) + See Documentation/admin-guide/tainted-kernels.rst in the Linux kernel or + https://www.kernel.org/doc/html/latest/admin-guide/tainted-kernels.html for + a more details explanation of the various taint flags. + Raw taint value as int/string: 4609/'P W O ' + +你也可以试着自己解码这个数字。如果内核被污染的原因只有一个，那么这很简单， +在本例中您可以通过下表找到数字。如果你需要解码有多个原因的数字，因为它是一 +个位域（bitfield），其中每个位表示一个特定类型的污染的存在或不存在，最好让 +前面提到的脚本来处理。但是如果您需要快速看一下，可以使用这个shell命令来检查 +设置了哪些位:: + + $ for i in $(seq 18); do echo $(($i-1)) $(($(cat /proc/sys/kernel/tainted)>>($i-1)&1));done + +污染状态代码表 +~~~~~~~~~~~~~~~ + +=== ===== ====== ======================================================== + 位 日志 数字 内核被污染的原因 +=== ===== ====== ======================================================== + 0 G/P 1 已加载专用模块 + 1 _/F 2 模块被强制加载 + 2 _/S 4 内核运行在不合规范的系统上 + 3 _/R 8 模块被强制卸载 + 4 _/M 16 处理器报告了机器检测异常（MCE） + 5 _/B 32 引用了错误的页或某些意外的页标志 + 6 _/U 64 用户空间应用程序请求的污染 + 7 _/D 128 内核最近死机了，即曾出现OOPS或BUG + 8 _/A 256 ACPI表被用户覆盖 + 9 _/W 512 内核发出警告 + 10 _/C 1024 已加载staging驱动程序 + 11 _/I 2048 已应用平台固件缺陷的解决方案 + 12 _/O 4096 已加载外部构建（“树外”）模块 + 13 _/E 8192 已加载未签名的模块 + 14 _/L 16384 发生软锁定 + 15 _/K 32768 内核已实时打补丁 + 16 _/X 65536 备用污染，为发行版定义并使用 + 17 _/T 131072 内核是用结构随机化插件构建的 +=== ===== ====== ======================================================== + +注：字符 ``_`` 表示空白，以便于阅读表。 + +污染的更详细解释 +~~~~~~~~~~~~~~~~~ + + 0) ``G`` 加载的所有模块都有GPL或兼容许可证， ``P`` 加载了任何专有模块。 + 没有MODULE_LICENSE（模块许可证）或MODULE_LICENSE未被insmod认可为GPL + 兼容的模块被认为是专有的。 + + + 1) ``F`` 任何模块被 ``insmod -f`` 强制加载， ``' '`` 所有模块正常加载。 + + 2) ``S`` 内核运行在不合规范的处理器或系统上：硬件已运行在不受支持的配置中， + 因此无法保证正确执行。内核将被污染，例如： + + - 在x86上：PAE是通过intel CPU（如Pentium M）上的forcepae强制执行的，这些 + CPU不报告PAE，但可能有功能实现，SMP内核在非官方支持的SMP Athlon CPU上 + 运行，MSR被暴露到用户空间中。 + - 在arm上：在某些CPU（如Keystone 2）上运行的内核，没有启用某些内核特性。 + - 在arm64上：CPU之间存在不匹配的硬件特性，引导加载程序以不同的模式引导CPU。 + - 某些驱动程序正在被用在不受支持的体系结构上（例如x86_64以外的其他系统 + 上的scsi/snic，非x86/x86_64/itanium上的scsi/ips，已经损坏了arm64上 + irqchip/irq-gic的固件设置…）。 + + 3) ``R`` 模块被 ``rmmod -f`` 强制卸载， ``' '`` 所有模块都正常卸载。 + + 4) ``M`` 任何处理器报告了机器检测异常， ``' '`` 未发生机器检测异常。 + + 5) ``B`` 页面释放函数发现错误的页面引用或某些意外的页面标志。这表示硬件问题 + 或内核错误；日志中应该有其他信息指示发生此污染的原因。 + + 6) ``U`` 用户或用户应用程序特意请求设置受污染标志，否则应为 ``' '`` 。 + + 7) ``D`` 内核最近死机了，即出现了OOPS或BUG。 + + 8) ``A`` ACPI表被重写。 + + 9) ``W`` 内核之前已发出过警告（尽管有些警告可能会设置更具体的污染标志）。 + + 10) ``C`` 已加载staging驱动程序。 + + 11) ``I`` 内核正在处理平台固件（BIOS或类似软件）中的严重错误。 + + 12) ``O`` 已加载外部构建（“树外”）模块。 + + 13) ``E`` 在支持模块签名的内核中加载了未签名的模块。 + + 14) ``L`` 系统上先前发生过软锁定。 + + 15) ``K`` 内核已经实时打了补丁。 + + 16) ``X`` 备用污染，由Linux发行版定义和使用。 + + 17) ``T`` 内核构建时使用了randstruct插件，它可以有意生成非常不寻常的内核结构 + 布局（甚至是性能病态的布局），这在调试时非常有用。于构建时设置。 diff --git a/Documentation/translations/zh_CN/admin-guide/unicode.rst b/Documentation/translations/zh_CN/admin-guide/unicode.rst new file mode 100644 index 000000000000..b0b08d2b6eb7 --- /dev/null +++ b/Documentation/translations/zh_CN/admin-guide/unicode.rst @@ -0,0 +1,170 @@ +.. include:: ../disclaimer-zh_CN.rst + +:Original: Documentation/admin-guide/unicode.rst + +:译者: + + 吴想成 Wu XiangCheng <bobwxc@email.cn> + +Unicode（统一码）支持 +====================== + + （英文版）上次更新：2005-01-17，版本号 1.4 + +此文档由H. Peter Anvin <unicode@lanana.org>管理，是Linux注册名称与编号管理局 +（Linux Assigned Names And Numbers Authority，LANANA）项目的一部分。 +现行版本请见： + + http://www.lanana.org/docs/unicode/admin-guide/unicode.rst + +简介 +----- + +Linux内核代码已被重写以使用Unicode来将字符映射到字体。下载一个Unicode到字体 +（Unicode-to-font）表，八位字符集与UTF-8模式都将改用此字体来显示。 + +这微妙地改变了八位字符表的语义。现在的四个字符表是： + +=============== =============================== ================ +映射代号 映射名称 Escape代码 (G0) +=============== =============================== ================ +LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B +GRAF_MAP DEC VT100 pseudographics ESC ( 0 +IBMPC_MAP IBM code page 437 ESC ( U +USER_MAP User defined ESC ( K +=============== =============================== ================ + +特别是 ESC ( U 不再是“直通字体”，因为字体可能与IBM字符集完全不同。 +例如，即使加载了一个Latin-1字体，也允许使用块图形（block graphics）。 + +请注意，尽管这些代码与ISO 2022类似，但这些代码及其用途都与ISO 2022不匹配； +Linux有两个八位代码（G0和G1），而ISO 2022有四个七位代码（G0-G3）。 + +根据Unicode标准/ISO 10646，U+F000到U+F8FF被保留用于操作系统范围内的分配 +（Unicode标准将其称为“团体区域（Corporate Zone）”，因为这对于Linux是不准确 +的，所以我们称之为“Linux区域”）。选择U+F000作为起点，因为它允许直接映射 +区域以2的大倍数开始（以防需要1024或2048个字符的字体）。这就留下U+E000到 +U+EFFF作为最终用户区。 + +[v1.2]：Unicodes范围从U+F000到U+F7FF已经被硬编码为直接映射到加载的字体， +绕过了翻译表。用户定义的映射现在默认为U+F000到U+F0FF，模拟前述行为。实际上， +此范围可能较短；例如，vgacon只能处理256字符（U+F000..U+F0FF）或512字符 +（U+F000..U+F1FF）字体。 + +Linux 区域中定义的实际字符 +--------------------------- + +此外，还定义了Unicode 1.1.4中不存在的以下字符；这些字符由DEC VT图形映射使用。 +[v1.2]此用法已过时，不应再使用；请参见下文。 + +====== ====================================== +U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 +U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 +U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 +U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 +====== ====================================== + +DEC VT220使用6x10字符矩阵，这些字符在DEC VT图形字符集中形成一个平滑的过渡。 +我省略了扫描5行，因为它也被用作块图形字符，因此被编码为U+2500 FORMS LIGHT +HORIZONTAL。 + +[v1.3]：这些字符已正式添加到Unicode 3.2.0中；它们在U+23BA、U+23BB、U+23BC、 +U+23BD处添加。Linux现在使用新值。 + +[v1.2]：添加了以下字符来表示常见的键盘符号，这些符号不太可能被添加到Unicode +中，因为它们非常讨厌地取决于特定供应商。当然，这是糟糕设计的一个好例子。 + +====== ====================================== +U+F810 KEYBOARD SYMBOL FLYING FLAG +U+F811 KEYBOARD SYMBOL PULLDOWN MENU +U+F812 KEYBOARD SYMBOL OPEN APPLE +U+F813 KEYBOARD SYMBOL SOLID APPLE +====== ====================================== + +克林贡（Klingon）语支持 +------------------------ + +1996年，Linux是世界上第一个添加对人工语言克林贡支持的操作系统，克林贡是由 +Marc Okrand为《星际迷航》电视连续剧创造的。这种编码后来被征募Unicode注册表 +（ConScript Unicode Registry，CSUR）采用，并建议（但最终被拒绝）纳入Unicode +平面一。不过，它仍然是Linux区域中的Linux/CSUR私有分配。 + +这种编码已经得到克林贡语言研究所（Klingon Language Institute）的认可。 +有关更多信息，请联系他们： + + http://www.kli.org/ + +由于Linux CZ开头部分的字符大多是dingbats/symbols/forms类型，而且这是一种 +语言，因此根据标准Unicode惯例，我将它放置在16单元的边界上。 + +.. note:: + + 这个范围现在由征募Unicode注册表正式管理。规范性引用文件为： + + https://www.evertype.com/standards/csur/klingon.html + +克林贡语有一个26个字符的字母表，一个10位数的位置数字书写系统，从左到右 +，从上到下书写。 + +克林贡字母的几种字形已经被提出。但是由于这组符号看起来始终是一致的，只有实际 +的形状不同，因此按照标准Unicode惯例，这些差异被认为是字体变体。 + +====== ======================================================= +U+F8D0 KLINGON LETTER A +U+F8D1 KLINGON LETTER B +U+F8D2 KLINGON LETTER CH +U+F8D3 KLINGON LETTER D +U+F8D4 KLINGON LETTER E +U+F8D5 KLINGON LETTER GH +U+F8D6 KLINGON LETTER H +U+F8D7 KLINGON LETTER I +U+F8D8 KLINGON LETTER J +U+F8D9 KLINGON LETTER L +U+F8DA KLINGON LETTER M +U+F8DB KLINGON LETTER N +U+F8DC KLINGON LETTER NG +U+F8DD KLINGON LETTER O +U+F8DE KLINGON LETTER P +U+F8DF KLINGON LETTER Q + - Written <q> in standard Okrand Latin transliteration +U+F8E0 KLINGON LETTER QH + - Written <Q> in standard Okrand Latin transliteration +U+F8E1 KLINGON LETTER R +U+F8E2 KLINGON LETTER S +U+F8E3 KLINGON LETTER T +U+F8E4 KLINGON LETTER TLH +U+F8E5 KLINGON LETTER U +U+F8E6 KLINGON LETTER V +U+F8E7 KLINGON LETTER W +U+F8E8 KLINGON LETTER Y +U+F8E9 KLINGON LETTER GLOTTAL STOP + +U+F8F0 KLINGON DIGIT ZERO +U+F8F1 KLINGON DIGIT ONE +U+F8F2 KLINGON DIGIT TWO +U+F8F3 KLINGON DIGIT THREE +U+F8F4 KLINGON DIGIT FOUR +U+F8F5 KLINGON DIGIT FIVE +U+F8F6 KLINGON DIGIT SIX +U+F8F7 KLINGON DIGIT SEVEN +U+F8F8 KLINGON DIGIT EIGHT +U+F8F9 KLINGON DIGIT NINE + +U+F8FD KLINGON COMMA +U+F8FE KLINGON FULL STOP +U+F8FF KLINGON SYMBOL FOR EMPIRE +====== ======================================================= + +其他虚构和人工字母 +------------------- + +自从分配了克林贡Linux Unicode块之后，John Cowan <jcowan@reutershealth.com> +和 Michael Everson <everson@evertype.com> 建立了一个虚构和人工字母的注册表。 +征募Unicode注册表请访问： + + https://www.evertype.com/standards/csur/ + +所使用的范围位于最终用户区域的低端，因此无法进行规范化分配，但建议希望对虚构 +字母进行编码的人员使用这些代码，以实现互操作性。对于克林贡语，CSUR采用了Linux +编码。CSUR的人正在推动将Tengwar和Cirth添加到Unicode平面一；将克林贡添加到 +Unicode平面一被拒绝，因此上述编码仍然是官方的。 |