From 2c3c1048746a4622d8c89a29670120dc8fab93c4 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 20:49:45 +0200 Subject: Adding upstream version 6.1.76. Signed-off-by: Daniel Baumann --- Documentation/translations/zh_TW/IRQ.txt | 41 + .../translations/zh_TW/admin-guide/README.rst | 351 +++++ .../translations/zh_TW/admin-guide/bug-bisect.rst | 85 ++ .../translations/zh_TW/admin-guide/bug-hunting.rst | 344 +++++ .../zh_TW/admin-guide/clearing-warn-once.rst | 16 + .../translations/zh_TW/admin-guide/cpu-load.rst | 112 ++ .../translations/zh_TW/admin-guide/index.rst | 135 ++ .../translations/zh_TW/admin-guide/init.rst | 58 + .../zh_TW/admin-guide/reporting-issues.rst | 1337 ++++++++++++++++++++ .../zh_TW/admin-guide/security-bugs.rst | 78 ++ .../zh_TW/admin-guide/tainted-kernels.rst | 161 +++ .../translations/zh_TW/admin-guide/unicode.rst | 174 +++ Documentation/translations/zh_TW/arm64/amu.rst | 104 ++ Documentation/translations/zh_TW/arm64/booting.txt | 251 ++++ .../translations/zh_TW/arm64/elf_hwcaps.rst | 244 ++++ .../translations/zh_TW/arm64/hugetlbpage.rst | 49 + Documentation/translations/zh_TW/arm64/index.rst | 23 + .../zh_TW/arm64/legacy_instructions.txt | 77 ++ Documentation/translations/zh_TW/arm64/memory.txt | 119 ++ Documentation/translations/zh_TW/arm64/perf.rst | 88 ++ .../translations/zh_TW/arm64/silicon-errata.txt | 79 ++ .../translations/zh_TW/arm64/tagged-pointers.txt | 57 + Documentation/translations/zh_TW/cpu-freq/core.rst | 108 ++ .../translations/zh_TW/cpu-freq/cpu-drivers.rst | 256 ++++ .../translations/zh_TW/cpu-freq/cpufreq-stats.rst | 132 ++ .../translations/zh_TW/cpu-freq/index.rst | 47 + .../translations/zh_TW/disclaimer-zh_TW.rst | 11 + .../translations/zh_TW/filesystems/debugfs.rst | 224 ++++ .../translations/zh_TW/filesystems/index.rst | 31 + .../translations/zh_TW/filesystems/sysfs.txt | 377 ++++++ .../translations/zh_TW/filesystems/tmpfs.rst | 148 +++ .../translations/zh_TW/filesystems/virtiofs.rst | 61 + Documentation/translations/zh_TW/gpio.txt | 651 ++++++++++ Documentation/translations/zh_TW/index.rst | 177 +++ Documentation/translations/zh_TW/io_ordering.txt | 68 + .../translations/zh_TW/process/1.Intro.rst | 199 +++ .../translations/zh_TW/process/2.Process.rst | 369 ++++++ .../translations/zh_TW/process/3.Early-stage.rst | 172 +++ .../translations/zh_TW/process/4.Coding.rst | 297 +++++ .../translations/zh_TW/process/5.Posting.rst | 250 ++++ .../translations/zh_TW/process/6.Followthrough.rst | 156 +++ .../zh_TW/process/7.AdvancedTopics.rst | 137 ++ .../translations/zh_TW/process/8.Conclusion.rst | 73 ++ .../process/code-of-conduct-interpretation.rst | 112 ++ .../translations/zh_TW/process/code-of-conduct.rst | 76 ++ .../translations/zh_TW/process/coding-style.rst | 958 ++++++++++++++ .../zh_TW/process/development-process.rst | 30 + .../translations/zh_TW/process/email-clients.rst | 252 ++++ .../zh_TW/process/embargoed-hardware-issues.rst | 232 ++++ Documentation/translations/zh_TW/process/howto.rst | 499 ++++++++ Documentation/translations/zh_TW/process/index.rst | 66 + .../zh_TW/process/kernel-driver-statement.rst | 203 +++ .../zh_TW/process/kernel-enforcement-statement.rst | 155 +++ .../translations/zh_TW/process/license-rules.rst | 374 ++++++ .../translations/zh_TW/process/magic-number.rst | 77 ++ .../zh_TW/process/management-style.rst | 211 +++ .../zh_TW/process/programming-language.rst | 75 ++ .../zh_TW/process/stable-api-nonsense.rst | 159 +++ .../zh_TW/process/stable-kernel-rules.rst | 68 + .../zh_TW/process/submit-checklist.rst | 109 ++ .../zh_TW/process/submitting-patches.rst | 660 ++++++++++ .../zh_TW/process/volatile-considered-harmful.rst | 110 ++ Documentation/translations/zh_TW/sparse.txt | 91 ++ 63 files changed, 12444 insertions(+) create mode 100644 Documentation/translations/zh_TW/IRQ.txt create mode 100644 Documentation/translations/zh_TW/admin-guide/README.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/bug-bisect.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/bug-hunting.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/cpu-load.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/index.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/init.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/reporting-issues.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/security-bugs.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst create mode 100644 Documentation/translations/zh_TW/admin-guide/unicode.rst create mode 100644 Documentation/translations/zh_TW/arm64/amu.rst create mode 100644 Documentation/translations/zh_TW/arm64/booting.txt create mode 100644 Documentation/translations/zh_TW/arm64/elf_hwcaps.rst create mode 100644 Documentation/translations/zh_TW/arm64/hugetlbpage.rst create mode 100644 Documentation/translations/zh_TW/arm64/index.rst create mode 100644 Documentation/translations/zh_TW/arm64/legacy_instructions.txt create mode 100644 Documentation/translations/zh_TW/arm64/memory.txt create mode 100644 Documentation/translations/zh_TW/arm64/perf.rst create mode 100644 Documentation/translations/zh_TW/arm64/silicon-errata.txt create mode 100644 Documentation/translations/zh_TW/arm64/tagged-pointers.txt create mode 100644 Documentation/translations/zh_TW/cpu-freq/core.rst create mode 100644 Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst create mode 100644 Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst create mode 100644 Documentation/translations/zh_TW/cpu-freq/index.rst create mode 100644 Documentation/translations/zh_TW/disclaimer-zh_TW.rst create mode 100644 Documentation/translations/zh_TW/filesystems/debugfs.rst create mode 100644 Documentation/translations/zh_TW/filesystems/index.rst create mode 100644 Documentation/translations/zh_TW/filesystems/sysfs.txt create mode 100644 Documentation/translations/zh_TW/filesystems/tmpfs.rst create mode 100644 Documentation/translations/zh_TW/filesystems/virtiofs.rst create mode 100644 Documentation/translations/zh_TW/gpio.txt create mode 100644 Documentation/translations/zh_TW/index.rst create mode 100644 Documentation/translations/zh_TW/io_ordering.txt create mode 100644 Documentation/translations/zh_TW/process/1.Intro.rst create mode 100644 Documentation/translations/zh_TW/process/2.Process.rst create mode 100644 Documentation/translations/zh_TW/process/3.Early-stage.rst create mode 100644 Documentation/translations/zh_TW/process/4.Coding.rst create mode 100644 Documentation/translations/zh_TW/process/5.Posting.rst create mode 100644 Documentation/translations/zh_TW/process/6.Followthrough.rst create mode 100644 Documentation/translations/zh_TW/process/7.AdvancedTopics.rst create mode 100644 Documentation/translations/zh_TW/process/8.Conclusion.rst create mode 100644 Documentation/translations/zh_TW/process/code-of-conduct-interpretation.rst create mode 100644 Documentation/translations/zh_TW/process/code-of-conduct.rst create mode 100644 Documentation/translations/zh_TW/process/coding-style.rst create mode 100644 Documentation/translations/zh_TW/process/development-process.rst create mode 100644 Documentation/translations/zh_TW/process/email-clients.rst create mode 100644 Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst create mode 100644 Documentation/translations/zh_TW/process/howto.rst create mode 100644 Documentation/translations/zh_TW/process/index.rst create mode 100644 Documentation/translations/zh_TW/process/kernel-driver-statement.rst create mode 100644 Documentation/translations/zh_TW/process/kernel-enforcement-statement.rst create mode 100644 Documentation/translations/zh_TW/process/license-rules.rst create mode 100644 Documentation/translations/zh_TW/process/magic-number.rst create mode 100644 Documentation/translations/zh_TW/process/management-style.rst create mode 100644 Documentation/translations/zh_TW/process/programming-language.rst create mode 100644 Documentation/translations/zh_TW/process/stable-api-nonsense.rst create mode 100644 Documentation/translations/zh_TW/process/stable-kernel-rules.rst create mode 100644 Documentation/translations/zh_TW/process/submit-checklist.rst create mode 100644 Documentation/translations/zh_TW/process/submitting-patches.rst create mode 100644 Documentation/translations/zh_TW/process/volatile-considered-harmful.rst create mode 100644 Documentation/translations/zh_TW/sparse.txt (limited to 'Documentation/translations/zh_TW') diff --git a/Documentation/translations/zh_TW/IRQ.txt b/Documentation/translations/zh_TW/IRQ.txt new file mode 100644 index 000000000..73d435a0d --- /dev/null +++ b/Documentation/translations/zh_TW/IRQ.txt @@ -0,0 +1,41 @@ +Chinese translated version of Documentation/core-api/irq/index.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Eric W. Biederman +Traditional Chinese maintainer: Hu Haowen +--------------------------------------------------------------------- +Documentation/core-api/irq/index.rst 的繁體中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向繁體中文版維護者求助。如果本翻譯更新不及時或 +者翻譯存在問題，請聯繫繁體中文版維護者。 + +英文版維護者： Eric W. Biederman +繁體中文版維護者： 胡皓文 Hu Haowen +繁體中文版翻譯者： 胡皓文 Hu Haowen +繁體中文版校譯者： 胡皓文 Hu Haowen + + +以下爲正文 +--------------------------------------------------------------------- +何爲 IRQ? + +一個 IRQ 是來自某個設備的一個中斷請求。目前，它們可以來自一個硬體引腳， +或來自一個數據包。多個設備可能連接到同個硬體引腳，從而共享一個 IRQ。 + +一個 IRQ 編號是用於告知硬體中斷源的內核標識。通常情況下，這是一個 +全局 irq_desc 數組的索引，但是除了在 linux/interrupt.h 中的實現， +具體的細節是體系結構特定的。 + +一個 IRQ 編號是設備上某個可能的中斷源的枚舉。通常情況下，枚舉的編號是 +該引腳在系統內中斷控制器的所有輸入引腳中的編號。對於 ISA 總線中的情況， +枚舉的是在兩個 i8259 中斷控制器中 16 個輸入引腳。 + +架構可以對 IRQ 編號指定額外的含義，在硬體涉及任何手工配置的情況下， +是被提倡的。ISA 的 IRQ 是一個分配這類額外含義的典型例子。 + diff --git a/Documentation/translations/zh_TW/admin-guide/README.rst b/Documentation/translations/zh_TW/admin-guide/README.rst new file mode 100644 index 000000000..6ce97edba --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/README.rst @@ -0,0 +1,351 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/README.rst + +:譯者: + + 吳想成 Wu XiangCheng + 胡皓文 Hu Haowen + +Linux內核5.x版本 +========================================= + +以下是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 ` 文件，它包含了升級內核 + 可能會導致的問題的相關信息。 + +安裝內核原始碼 +--------------- + + - 如果您要安裝完整的原始碼，請把內核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 ` 。 + + 或者，腳本 patch-kernel 可以用來自動化這個過程。它能確定當前內核版本並 + 應用找到的所有補丁:: + + linux/scripts/patch-kernel linux + + 上面命令中的第一個參數是內核原始碼的位置。補丁是在當前目錄應用的，但是 + 可以將另一個目錄指定爲第二個參數。 + + - 確保沒有過時的 .o 文件和依賴項:: + + cd linux + make mrproper + + 現在您應該已經正確安裝了原始碼。 + +軟體要求 +--------- + + 編譯和運行5.x內核需要各種軟體包的最新版本。請參考 + :ref:`Documentation/process/changes.rst ` + 來了解最低版本要求以及如何升級軟體包。請注意，使用過舊版本的這些包可能會 + 導致很難追蹤的間接錯誤，因此不要以爲在生成或操作過程中出現明顯問題時可以 + 只更新包。 + +爲內核建立目錄 +--------------- + + 編譯內核時，默認情況下所有輸出文件都將與內核原始碼放在一起。使用 + ``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 5.1可用。 + 有關更多信息，請參閱 :ref:`Documentation/process/changes.rst ` 。 + + 請注意，您仍然可以使用此內核運行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_TW/admin-guide/bug-bisect.rst b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst new file mode 100644 index 000000000..41a39aebb --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/bug-bisect.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/bug-bisect` + +:譯者: + + 吳想成 Wu XiangCheng + 胡皓文 Hu Haowen + +二分（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解決回歸） + `_ +- `Fully automated bisecting with "git bisect run"（使用git bisect run + 來全自動二分） `_ +- `Using Git bisect to figure out when brokenness was introduced + （使用Git二分來找出何時引入了錯誤） `_ + diff --git a/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst new file mode 100644 index 000000000..4d813aec7 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/bug-hunting.rst @@ -0,0 +1,344 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/bug-hunting` + +:譯者: + + 吳想成 Wu XiangCheng + 胡皓文 Hu Haowen + +追蹤缺陷 +========= + +內核錯誤報告通常附帶如下堆棧轉儲:: + + ------------[ 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: + [] ? dump_stack+0x44/0x64 + [] ? __warn+0xfa/0x120 + [] ? module_put+0x57/0x70 + [] ? module_put+0x57/0x70 + [] ? warn_slowpath_null+0x23/0x30 + [] ? module_put+0x57/0x70 + [] ? gp8psk_fe_set_frontend+0x460/0x460 [dvb_usb_gp8psk] + [] ? symbol_put_addr+0x27/0x50 + [] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + [] ? dvb_usb_exit+0x2f/0xd0 [dvb_usb] + [] ? usb_disable_endpoint+0x7c/0xb0 + [] ? dvb_usb_device_exit+0x2a/0x50 [dvb_usb] + [] ? usb_unbind_interface+0x62/0x250 + [] ? __pm_runtime_idle+0x44/0x70 + [] ? __device_release_driver+0x78/0x120 + [] ? driver_detach+0x87/0x90 + [] ? bus_remove_driver+0x38/0x90 + [] ? usb_deregister+0x58/0xb0 + [] ? SyS_delete_module+0x130/0x1f0 + [] ? task_work_run+0x64/0x80 + [] ? exit_to_usermode_loop+0x85/0x90 + [] ? do_fast_syscall_32+0x80/0x130 + [] ? sysenter_past_esp+0x40/0x6a + ---[ end trace 6ebc60ef3981792f ]--- + +這樣的堆棧跟蹤提供了足夠的信息來識別內核原始碼中發生錯誤的那一行。根據問題的 +嚴重性，它還可能包含 **「Oops」** 一詞，比如:: + + BUG: unable to handle kernel NULL pointer dereference at (null) + IP: [] 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 ` ）， + 在另一台機器上運行數據機然後用你喜歡的通信程序捕獲輸出。 + 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:[] 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 + (gdb) l *0xae0+0xda8 + +您也可以使用對象文件作爲替代:: + + $ make drivers/tty/ + $ gdb drivers/tty/vt/vt_ioctl.o + (gdb) l *vt_ioctl+0xda8 + +如果你有調用跟蹤，類似:: + + Call Trace: + [] :jbd:log_wait_commit+0xa3/0xf5 + [] autoremove_wake_function+0x0/0x2e + [] :jbd:journal_stop+0x1be/0x1ee + ... + +這表明問題可能在 :jbd: 模塊中。您可以在gdb中加載該模塊並列出相關代碼:: + + $ gdb fs/jbd/jbd.ko + (gdb) l *log_wait_commit+0xa3 + +.. note:: + + 您還可以對堆棧跟蹤處的任何函數調用執行相同的操作，例如:: + + [] ? 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 (odd fixer:GSPCA USB WEBCAM DRIVER,commit_signer:1/1=100%) + Mauro Carvalho Chehab (maintainer:MEDIA INPUT INFRASTRUCTURE (V4L/DVB),commit_signer:1/1=100%) + Tejun Heo (commit_signer:1/1=100%) + Bhaktipriya Shridhar (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 ` ， +以幫助您的代碼被接受。 + + +--------------------------------------------------------------------------- + +用 ``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_TW/admin-guide/clearing-warn-once.rst b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst new file mode 100644 index 000000000..bdc1a2204 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Translator: 胡皓文 Hu Haowen + +清除 WARN_ONCE +-------------- + +WARN_ONCE / WARN_ON_ONCE / printk_once 僅僅列印一次消息. + +echo 1 > /sys/kernel/debug/clear_warn_once + +可以清除這種狀態並且再次允許列印一次告警信息，這對於運行測試集後重現問題 +很有用。 + diff --git a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst new file mode 100644 index 000000000..be087cef1 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst @@ -0,0 +1,112 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Translator: 胡皓文 Hu Haowen + +======== +CPU 負載 +======== + +Linux通過``/proc/stat``和``/proc/uptime``導出各種信息，用戶空間工具 +如top(1)使用這些信息計算系統花費在某個特定狀態的平均時間。 +例如： + + $ iostat + Linux 2.6.18.3-exp (linmac) 02/20/2007 + + avg-cpu: %user %nice %system %iowait %steal %idle + 10.01 0.00 2.92 5.44 0.00 81.63 + + ... + +這裡系統認爲在默認採樣周期內有10.01%的時間工作在用戶空間，2.92%的時 +間用在系統空間，總體上有81.63%的時間是空閒的。 + +大多數情況下``/proc/stat``的信息幾乎真實反映了系統信息，然而，由於內 +核採集這些數據的方式/時間的特點，有時這些信息根本不可靠。 + +那麼這些信息是如何被搜集的呢？每當時間中斷觸發時，內核查看此刻運行的 +進程類型，並增加與此類型/狀態進程對應的計數器的值。這種方法的問題是 +在兩次時間中斷之間系統（進程）能夠在多種狀態之間切換多次，而計數器只 +增加最後一種狀態下的計數。 + +舉例 +--- + +假設系統有一個進程以如下方式周期性地占用cpu:: + + 兩個時鐘中斷之間的時間線 + |-----------------------| + ^ ^ + |_ 開始運行 | + |_ 開始睡眠 + （很快會被喚醒） + +在上面的情況下，根據``/proc/stat``的信息（由於當系統處於空閒狀態時， +時間中斷經常會發生）系統的負載將會是0 + +大家能夠想像內核的這種行爲會發生在許多情況下，這將導致``/proc/stat`` +中存在相當古怪的信息:: + + /* gcc -o hog smallhog.c */ + #include + #include + #include + #include + #define HIST 10 + + static volatile sig_atomic_t stop; + + static void sighandler (int signr) + { + (void) signr; + stop = 1; + } + static unsigned long hog (unsigned long niters) + { + stop = 0; + while (!stop && --niters); + return niters; + } + int main (void) + { + int i; + struct itimerval it = { .it_interval = { .tv_sec = 0, .tv_usec = 1 }, + .it_value = { .tv_sec = 0, .tv_usec = 1 } }; + sigset_t set; + unsigned long v[HIST]; + double tmp = 0.0; + unsigned long n; + signal (SIGALRM, &sighandler); + setitimer (ITIMER_REAL, &it, NULL); + + hog (ULONG_MAX); + for (i = 0; i < HIST; ++i) v[i] = ULONG_MAX - hog (ULONG_MAX); + for (i = 0; i < HIST; ++i) tmp += v[i]; + tmp /= HIST; + n = tmp - (tmp / 3.0); + + sigemptyset (&set); + sigaddset (&set, SIGALRM); + + for (;;) { + hog (n); + sigwait (&set, &i); + } + return 0; + } + + +參考 +--- + +- https://lore.kernel.org/r/loom.20070212T063225-663@post.gmane.org +- Documentation/filesystems/proc.rst (1.8) + + +謝謝 +--- + +Con Kolivas, Pavel Machek + diff --git a/Documentation/translations/zh_TW/admin-guide/index.rst b/Documentation/translations/zh_TW/admin-guide/index.rst new file mode 100644 index 000000000..293c20245 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/index.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/index` +:Translator: 胡皓文 Hu Haowen + +Linux 內核用戶和管理員指南 +========================== + +下面是一組隨時間添加到內核中的面向用戶的文檔的集合。到目前爲止，還沒有一個 +整體的順序或組織 - 這些材料不是一個單一的，連貫的文件！幸運的話，情況會隨著 +時間的推移而迅速改善。 + +這個初始部分包含總體信息，包括描述內核的README， 關於內核參數的文檔等。 + +.. toctree:: + :maxdepth: 1 + + README + +Todolist: + + kernel-parameters + devices + sysctl/index + +本節介紹CPU漏洞及其緩解措施。 + +Todolist: + + hw-vuln/index + +下面的一組文檔，針對的是試圖跟蹤問題和bug的用戶。 + +.. toctree:: + :maxdepth: 1 + + reporting-issues + security-bugs + bug-hunting + bug-bisect + tainted-kernels + init + +Todolist: + + reporting-bugs + ramoops + dynamic-debug-howto + kdump/index + perf/index + +這是應用程式開發人員感興趣的章節的開始。可以在這裡找到涵蓋內核ABI各個 +方面的文檔。 + +Todolist: + + sysfs-rules + +本手冊的其餘部分包括各種指南，介紹如何根據您的喜好配置內核的特定行爲。 + + +.. toctree:: + :maxdepth: 1 + + clearing-warn-once + cpu-load + unicode + +Todolist: + + acpi/index + aoe/index + auxdisplay/index + bcache + binderfs + binfmt-misc + blockdev/index + bootconfig + braille-console + btmrvl + cgroup-v1/index + cgroup-v2 + cifs/index + cputopology + dell_rbu + device-mapper/index + edid + efi-stub + ext4 + nfs/index + gpio/index + highuid + hw_random + initrd + iostats + java + jfs + kernel-per-CPU-kthreads + laptops/index + lcd-panel-cgram + ldm + lockup-watchdogs + LSM/index + md + media/index + mm/index + module-signing + mono + namespaces/index + numastat + parport + perf-security + pm/index + pnp + rapidio + ras + rtc + serial-console + svga + sysrq + thunderbolt + ufs + vga-softcursor + video-output + xfs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/translations/zh_TW/admin-guide/init.rst b/Documentation/translations/zh_TW/admin-guide/init.rst new file mode 100644 index 000000000..32cdf1349 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/init.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/init` + +:譯者: + + 吳想成 Wu XiangCheng + 胡皓文 Hu Haowen + +解釋「No working init found.」啓動掛起消息 +========================================== + +:作者: + + Andreas Mohr + + Cristian Souza + +本文檔提供了加載初始化二進位（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 |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_TW/admin-guide/reporting-issues.rst b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst new file mode 100644 index 000000000..27638e199 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/reporting-issues.rst @@ -0,0 +1,1337 @@ +.. 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_TW.rst + +:Original: Documentation/admin-guide/reporting-issues.rst + +:譯者: + + 吳想成 Wu XiangCheng + 胡皓文 Hu Haowen + + +報告問題 ++++++++++ + + +簡明指南（亦即 太長不看） +========================== + +您面臨的是否爲同系列穩定版或長期支持內核的普通內核的回歸？是否仍然受支持？ +請搜索 `LKML內核郵件列表 `_ 和 +`Linux穩定版郵件列表 `_ 存檔中匹配的報告並 +加入討論。如果找不到匹配的報告，請安裝該系列的最新版本。如果它仍然出現問題， +報告給穩定版郵件列表（stable@vger.kernel.org）。 + +在所有其他情況下，請儘可能猜測是哪個內核部分導致了問題。查看MAINTAINERS文件， +了解開發人員希望如何得知問題，大多數情況下，報告問題都是通過電子郵件和抄送 +相關郵件列表進行的。檢查報告目的地的存檔中是否已有匹配的報告；也請搜索 +`LKML `_ 和網絡。如果找不到可加入的討論，請 +安裝 `最新的主線內核 `_ 。如果仍存在問題，請發送報告。 + +問題已經解決了，但是您希望看到它在一個仍然支持的穩定版或長期支持系列中得到 +解決？請安裝其最新版本。如果它出現了問題，那麼在主線中搜索修復它的更改，並 +檢查是否正在回傳（backporting）或者已放棄；如果兩者都沒有，那麼可詢問處理 +更改的人員。 + +**通用提醒** ：當安裝和測試上述內核時，請確保它是普通的（即：沒有補丁，也沒 +有使用附加模塊）。還要確保它是在一個正常的環境中構建和運行，並且在問題發生 +之前沒有被汙染（tainted）。 + +在編寫報告時，要涵蓋與問題相關的所有信息，如使用的內核和發行版。在碰見回歸時， +嘗試給出引入它的更改的提交ID，二分可以找到它。如果您同時面臨Linux內核的多個 +問題，請分別報告每個問題。 + +一旦報告發出，請回答任何出現的問題，並儘可能地提供幫助。這包括通過不時重新 +測試新版本並發送狀態更新來推動進展。 + + +如何向內核維護人員報告問題的逐步指南 +===================================== + +上面的簡明指南概述了如何向Linux內核開發人員報告問題。對於已經熟悉向自由和開 +源軟體（FLOSS）項目報告問題的人來說，這可能是他們所需要的全部內容。對於其他 +人，本部分更爲詳細，並一步一步地描述。爲了便於閱讀，它仍然儘量簡潔，並省略 +了許多細節；這些在逐步指南後的參考章節中進行了描述，該章節更詳細地解釋了每 +個步驟。 + +注意：本節涉及的方面比簡明指南多，順序也稍有不同。這符合你的利益，以確保您 +儘早意識到看起來像Linux內核毛病的問題可能實際上是由其他原因引起的。這些步驟 +可以確保你最終不會覺得在這一過程中投入的時間是浪費： + + * 您是否面臨硬體或軟體供應商提供的Linux內核的問題？那麼基本上您最好停止閱讀 + 本文檔，轉而向您的供應商報告問題，除非您願意自己安裝最新的Linux版本。尋找 + 和解決問題往往需要後者。 + + * 使用您喜愛的網絡搜尋引擎對現有報告進行粗略搜索；此外，請檢查 + `Linux內核郵件列表（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 的首頁 + `_ ，確保此特定版本線的最新版沒有「[EOL]」標記。 + + * 檢查 `Linux穩定版郵件列表 `_ 中的現有報告。 + + * 從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被汙染，並且仍然 + 存在問題，因爲問題可能已經在那裡被修復了。如果您第一次發現供應商內核的問題， + 請檢查已知最新版本的普通構建是否可以正常運行。 + + * 向Linux穩定版郵件列表發送一個簡短的問題報告(stable@vger.kernel.org)。大致 + 描述問題，並解釋如何復現。講清楚首個出現問題的版本和最後一個工作正常的版本。 + 然後等待進一步的指示。 + +下面的參考章節部分詳細解釋了這些步驟中的每一步。 + + +報告只發生在較舊內核版本線的問題 +---------------------------------- + +若您嘗試了上述的最新主線內核，但未能在那裡復現問題，那麼本小節適用於您；以下 +流程有助於使問題在仍然支持的穩定版或長期支持版本線，或者定期基於最新穩定版或 +長期支持內核的供應商內核中得到修復。如果是這種情況，請執行以下步驟： + + * 請做好準備，接下來的幾個步驟可能無法在舊版本中解決問題：修復可能太大或太 + 冒險，無法移植到那裡。 + + * 執行前節「報告穩定版和長期支持內核線的回歸」中的前三個步驟。 + + * 在Linux內核版本控制系統中搜索修復主線問題的更改，因爲它的提交消息可能會 + 告訴你修復是否已經計劃好了支持。如果你沒有找到，搜索適當的郵件列表，尋找 + 討論此類問題或同行評議可能修復的帖子；然後檢查討論是否認爲修復不適合支持。 + 如果支持根本不被考慮，加入最新的討論，詢問是否有可能。 + + * 前面的步驟之一應該會給出一個解決方案。如果仍未能成功，請向可能引起問題的 + 子系統的維護人員詢問建議；抄送特定子系統的郵件列表以及穩定版郵件列表 + +下面的參考章節部分詳細解釋了這些步驟中的每一步。 + + +參考章節：向內核維護者報告問題 +=============================== + +上面的詳細指南簡要地列出了所有主要步驟，這對大多數人來說應該足夠了。但有時， +即使是有經驗的用戶也可能想知道如何實際執行這些步驟之一。這就是本節的目的， +因爲它將提供關於上述每個步驟的更多細節。請將此作爲參考文檔：可以從頭到尾 +閱讀它。但它主要是爲了瀏覽和查找如何實際執行這些步驟的詳細信息。 + +在深入挖掘細節之前，我想先給你一些一般性建議： + + * Linux內核開發人員很清楚這個過程很複雜，比其他的FLOSS項目要求更多。我們很 + 希望讓它更簡單。但這需要在不同的地方以及一些基礎設施上付諸努力，這些基礎 + 設施需要持續的維護；尚未有人站出來做這些工作，所以目前情況就是這樣。 + + * 與某些供應商簽訂的保證或支持合同並不能使您有權要求上游Linux內核社區的開 + 發人員進行修復：這樣的合同完全在Linux內核、其開發社區和本文檔的範圍之外。 + 這就是爲什麼在這種情況下，你不能要求任何契約保證，即使開發人員處理的問 + 題對供應商有效。如果您想主張您的權利，使用供應商的支持渠道代替。當這樣做 + 的時候，你可能想提出你希望看到這個問題在上游Linux內核中修復；可以這是確 + 保最終修復將被納入所有Linux發行版的唯一方法來鼓勵他們。 + + * 如果您從未向FLOSS項目報告過任何問題，那麼您應該考慮閱讀 `如何有效地報告 + 缺陷 `_ ， `如何 + 以明智的方式提問 `_ ， + 和 `如何提出好問題 `_ 。 + +解決這些問題之後，可以在下面找到如何正確地向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 `_ 網站可能 +也是一個好主意，因爲這可能會提供有價值的見解或找到匹配的報告。如果您發現後者， +請記住：大多數子系統都希望在不同的位置報告，如下面「你需要將問題報告到何處」 +一節中所述。因此本應處理這個問題的開發人員甚至可能不知道bugzilla的工單。所以 +請檢查工單中的問題是否已經按照本文檔所述得到報告，如果沒有，請考慮這樣做。 + +高優先級的問題？ +----------------- + + *看看你正在處理的問題是否是回歸問題、安全問題或非常嚴重的問題：這些都是 + 需要在接下來的一些步驟中特別處理的「高優先級問題」。* + +Linus Torvalds和主要的Linux內核開發人員希望看到一些問題儘快得到解決，因此在 +報告過程中有一些「高優先級問題」的處理略有不同。有三種情況符合條件:回歸、安全 +問題和非常嚴重的問題。 + +如果在舊版本的Linux內核中工作的東西不能在新版本的Linux內核中工作，或者某種 +程度上在新版本的Linux內核中工作得更差，那麼你就需要處理「回歸」。因此，當一個 +在Linux 5.7中表現良好的WiFi驅動程序在5.8中表現不佳或根本不能工作時，這是一 +種回歸。如果應用程式在新的內核中出現不穩定的現象，這也是一種回歸，這可能是 +由於內核和用戶空間之間的接口（如procfs和sysfs）發生不兼容的更改造成的。顯著 +的性能降低或功耗增加也可以稱爲回歸。但是請記住:新內核需要使用與舊內核相似的 +配置來構建（參見下面如何實現這一點）。這是因爲內核開發人員在實現新特性時有 +時無法避免不兼容性；但是爲了避免回歸，這些特性必須在構建配置期間顯式地啓用。 + +什麼是安全問題留給您自己判斷。在繼續之前，請考慮閱讀 +「Documentation/translations/zh_TW/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_TW/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 ` 文件，讓我們假設您的筆記 +本電腦中的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 + 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） +。在以後通過郵件發送問題報告時，不要遺漏任何 +一個郵件列表!維護者都是大忙人，可能會把一些工作留給子系統特定列表上的其他開 +發者；而 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 (supporter:QUALCOMM ATHEROS ATH10K WIRELESS DRIVER) + Another S. Human (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 」 ，並抄送 +「ath10k@lists.infradead.org」和「linux-kernel@vger.kernel.org」。 + +注意：如果你用 git 克隆了 Linux 原始碼，你可能需要用--git 再次調用 +get_maintainer.pl。腳本會查看提交歷史，以找到最近哪些人參與了相關代碼的編寫， +因爲他們可能會提供幫助。但要小心使用這些結果，因爲它很容易讓你誤入歧途。 +例如，這種情況常常會發生在很少被修改的地方（比如老舊的或未維護的驅動程序）： +有時這樣的代碼會在樹級清理期間被根本不關心此驅動程序的開發者修改。 + + +搜索現有報告（第二部分） +-------------------------- + + *在缺陷追蹤器或問題相關郵件列表的存檔中徹底搜索可能與您的問題匹配的報告。 + 如果找到匹配的報告，請加入討論而不是發送新報告。* + +如前所述：報告一個別人已經提出的問題，對每個人來說都是浪費時間，尤其是作爲報告 +人的你。這就是爲什麼你應該再次搜索現有的報告。現在你已經知道問題需要報告到哪裡。 +如果是郵件列表，那麼一般在 `lore.kernel.org `_ 可以 +找到相應存檔。 + +但有些列表運行在其他地方。例如前面步驟中當例子的ath10k WiFi驅動程序就是這種 +情況。但是你通常可以在網上很容易地找到這些列表的檔案。例如搜索「archive +ath10k@lists.infradead.org」，將引導您到ath10k郵件列表的信息頁，該頁面頂部連結 +到其 `列表存檔 `_ 。遺憾的是， +這個列表和其他一些列表缺乏搜索其存檔的功能。在這種情況下可以使用常規的網際網路 +搜尋引擎，並添加類似「site:lists.infadead.org/pipermail/ath10k/」這 +樣的搜索條件，這會把結果限制在該連結中的檔案。 + +也請進一步搜索網絡、LKML和bugzilla.kernel.org網站。 + +有關如何搜索以及在找到匹配報告時如何操作的詳細信息，請參閱上面的「搜索現有報告 +（第一部分）」。 + +不要急著完成報告過程的這一步：花30到60分鐘甚至更多的時間可以爲你和其他人節省 / +減少相當多的時間和麻煩。 + + +安裝一個新的內核進行測試 +-------------------------- + + *除非您已經在運行最新的「主線」Linux內核，否則最好在報告流程前安裝它。在 + 某些情況下，使用最新的「穩定版」Linux進行測試和報告也是可以接受的替代方案； + 在合併窗口期間，這實際上可能是最好的方法，但在開發階段最好還是暫停幾天。 + 無論你選擇什麼版本，最好使用「普通」構建。忽略這些建議會大大增加您的報告 + 被拒絕或忽略的風險。* + +正如第一步的詳細解釋中所提到的：與大多數程式設計師一樣，與大多數程式設計師一樣，Linux +內核開發人員不喜歡花時間處理他們維護的原始碼中根本不會發生的問題的報告。這隻 +會浪費每個人的時間，尤其是你的時間。這就是爲什麼在報告問題之前，您必須先確認 +問題仍然存在於最新的上游代碼中，這符合每個人的利益。您可以忽略此建議，但如前 +所述：這樣做會極大地增加問題報告被拒絕或被忽略的風險。 + +內核「最新上游」的範圍通常指： + + * 安裝一個主線內核；最新的穩定版內核也可以是一個選擇，但大多數時候都最好避免。 + 長期支持內核（有時稱爲「LTS內核」）不適合此流程。下一小節將更詳細地解釋所有 + 這些。 + + * 下一小節描述獲取和安裝這樣一個內核的方法。它還指出了使用預編譯內核是可以的， + 但普通的內核更好，這意味著：它是直接使用從 `kernel.org `_ + 獲得的Linux原始碼構建並且沒有任何方式修改或增強。 + + +選擇適合測試的版本 +~~~~~~~~~~~~~~~~~~~~ + +前往 `kernel.org `_ 來決定使用哪個版本。忽略那個寫著 +「Latest release最新版本」的巨大黃色按鈕，往下看有一個表格。在表格的頂部，你會 +看到一行以「mainline」開頭的字樣，大多數情況下它會指向一個版本號類似「5.8-rc2」 +的預發布版本。如果是這樣的話，你將需要使用這個主線內核進行測試。不要讓「rc」 +嚇到你，這些「開發版內核」實際上非常可靠——而且你已經按照上面的指示做了備份， +不是嗎？ + +大概每九到十周，「mainline」可能會給你指出一個版本號類似「5.7」的正式版本。如果 +碰見這種情況，請考慮暫停報告過程，直到下一個版本的第一個預發布（5.8-rc1）出 +現在 `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 上的官方開發倉庫 +`_ +中獲取最新的 Linux 內核原始碼。這些很可能比最新的主線預發布版本更新一些。不 +用擔心：它們和正式的預發布版本一樣可靠，除非內核的開發周期目前正處於合併窗 +口中。不過即便如此，它們也是相當可靠的。 + +**常規方法** ：不熟悉 git 的人通常最好從 `kernel.org `_ +下載源碼的tar 存檔包。 + +如何實際構建一個內核並不在這裡描述，因爲許多網站已經解釋了必要的步驟。如果 +你是新手，可以考慮按照那些建議使用 ``make localmodconfig`` 來做，它將嘗試獲 +取你當前內核的配置，然後根據你的系統進行一些調整。這樣做並不能使編譯出來的 +內核更好，但可以更快地編譯。 + +注意：如果您正在處理來自內核的pannc、Oops、warning或BUG，請在配置內核時嘗試 +啓用 CONFIG_KALLSYMS 選項。此外，還可以啓用 CONFIG_DEBUG_KERNEL 和 +CONFIG_DEBUG_INFO；後者是相關選項，但只有啓用前者才能開啓。請注意， +CONFIG_DEBUG_INFO 會需要更多儲存空間來構建內核。但這是值得的，因爲這些選項將 +允許您稍後精確定位觸發問題的確切代碼行。下面的「解碼失敗信息」一節對此進行了更 +詳細的解釋。 + +但請記住：始終記錄遇到的問題，以防難以重現。發送未解碼的報告總比不報告要好。 + + +檢查「汙染」標誌 +---------------- + + *確保您剛剛安裝的內核在運行時不會「汙染」自己。* + +正如上面已經詳細介紹過的：當發生一些可能會導致一些看起來完全不相關的後續錯 +誤的事情時，內核會設置一個「汙染」標誌。這就是爲什麼你需要檢查你剛剛安裝的內 +核是否有設置此標誌。如果有的話，幾乎在任何情況下你都需要在報告問題之前先消 +除它。詳細的操作方法請看上面的章節。 + + +用新內核重現問題 +------------------ + + *在您剛剛安裝的內核中復現這個問題。如果它沒有出現，請查看下方只發生在 + 穩定版和長期支持內核的問題的說明。* + +檢查這個問題是否發生在你剛剛安裝的新 Linux 內核版本上。如果新內核已經修復了， +可以考慮使用此版本線，放棄報告問題。但是請記住，只要它沒有在 `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_TW/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 `_ 上創建的工單……）， + 並在你的報告中放上連結。理想情況下請使用允許這些文件保存很多年的地方，因 + 爲它們可能在很多年後對別人有用；例如 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`` `就是這樣一個工具，它是音頻/聲 + 音子系統開發者提供的 `_ 。 + +這些例子應該會給你一些知識點，讓你知道附上什麼數據可能是明智的，但你自己也 +要想一想，哪些數據對別人會有幫助。不要太擔心忘記一些東西，因爲開發人員會要 +求提供他們需要的額外細節。但從一開始就把所有重要的東西都提供出來，會增加別 +人仔細查看的機會。 + + +重要部分：報告的開頭 +~~~~~~~~~~~~~~~~~~~~~~ + +現在你已經準備好了報告的詳細部分，讓我們進入最重要的部分：開頭幾句。現在到 +報告的最前面，在你剛才寫的部分之前加上類似「The detailed description:」（詳細 +描述）這樣的內容，並在最前面插入兩個新行。現在寫一個正常長度的段落，大致概 +述這個問題。去掉所有枯燥的細節，把重點放在讀者需要知道的關鍵部分，以讓人了 +解這是怎麼回事；如果你認爲這個缺陷影響了很多用戶，就提一下這點來吸引大家關 +注。 + +做好這一點後，在頂部再插入兩行，寫一句話的摘要，快速解釋報告的內容。之後你 +要更加抽象，爲報告寫一個更短的主題/標題。 + +現在你已經寫好了這部分，請花點時間來優化它，因爲它是你的報告中最重要的部分： +很多人會先讀這部分，然後才會決定是否值得花時間閱讀其他部分。 + +現在就像 :ref:`MAINTAINERS ` 維護者文件告訴你的那樣發送或提交 +報告，除非它是前面概述的那些「高優先級問題」之一：在這種情況下，請先閱讀下一 +小節，然後再發送報告。 + +高優先級問題的特殊處理 +~~~~~~~~~~~~~~~~~~~~~~~~ + +高優先級問題的報告需要特殊處理。 + +**非常嚴重的缺陷** ：確保在主題或工單標題以及第一段中明顯標出 severeness +（非常嚴重的）。 + +**回歸** ：如果問題是一個回歸，請在郵件的主題或缺陷跟蹤器的標題中添加 +[REGRESSION]。如果您沒有進行二分，請至少註明您測試的最新主線版本（比如 5.7） +和出現問題的最新版本（比如 5.8）。如果您成功地進行了二分，請註明導致回歸 +的提交ID和主題。也請添加該變更的作者到你的報告中；如果您需要將您的缺陷提交 +到缺陷跟蹤器中，請將報告以私人郵件的形式轉發給他，並註明報告提交地點。 + +**安全問題** ：對於這種問題，你將必須評估：如果細節被公開披露，是否會對其他 +用戶產生短期風險。如果不會，只需按照所述繼續報告問題。如果有此風險，你需要 +稍微調整一下報告流程。 + + * 如果 MAINTAINERS 文件指示您通過郵件報告問題，請不要抄送任何公共郵件列表。 + + * 如果你應該在缺陷跟蹤器中提交問題，請確保將工單標記爲「私有」或「安全問題」。 + 如果缺陷跟蹤器沒有提供保持報告私密性的方法，那就別想了，把你的報告以私人 + 郵件的形式發送給維護者吧。 + +在這兩種情況下，都一定要將報告發到 MAINTAINERS 文件中「安全聯絡」部分列出的 +地址。理想的情況是在發送報告的時候直接抄送他們。如果您在缺陷跟蹤器中提交了 +報告，請將報告的文本轉發到這些地址；但請在報告的頂部加上注釋，表明您提交了 +報告，並附上工單連結。 + +更多信息請參見「Documentation/translations/zh_TW/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 `_ 在首頁上列出了兩個「穩定」版本， +你應該考慮切換到較新的版本，而忘掉較舊的版本：對它的支持可能很快就會結束。 +然後，它將被標記爲「生命周期結束」（EOL）。達到這個程度的版本線仍然會在 +`kernel.org `_ 首頁上被顯示一兩周，但不適合用於測試和 +報告。 + +搜索穩定版郵件列表 +~~~~~~~~~~~~~~~~~~~ + + *檢查Linux穩定版郵件列表中的現有報告。* + +也許你所面臨的問題已經被發現，並且已經或即將被修復。因此，請在 `Linux 穩定 +版郵件列表的檔案 `_ 中搜索類似問題的報告。 +如果你找到任何匹配的問題，可以考慮加入討論，除非修復工作已經完成並計劃很快 +得到應用。 + +用最新版本復現問題 +~~~~~~~~~~~~~~~~~~~ + + *從特定的版本線安裝最新版本作爲純淨內核。確保這個內核沒有被汙染，並且仍 + 然存在問題，因爲問題可能已經在那裡被修復了。* + +在投入更多時間到這個過程中之前，你要檢查這個問題是否在你關注的版本線的最新 +版本中已經得到了修復。這個內核需要是純淨的，在問題發生之前不應該被汙染，正 +如上面已經在測試主線的過程中詳細介紹過的一樣。 + +您是否是第一次注意到供應商內核的回歸？供應商的更改可能會發生變化。你需要重新 +檢查排除來這個問題。當您從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_TW/admin-guide/bug-bisect.rst」。 + + +「報告僅在舊內核版本線中發生的問題」的參考 +------------------------------------------ + +本節詳細介紹了如果無法用主線內核重現問題，但希望在舊版本線（又稱穩定版內核和 +長期支持內核）中修復問題時需要採取的步驟。 + +有些修復太複雜 +~~~~~~~~~~~~~~~ + + *請做好準備，接下來的幾個步驟可能無法在舊版本中解決問題：修復可能太大或 + 太冒險，無法移植到那裡。* + +即使是微小的、看似明顯的代碼變化，有時也會帶來新的、完全意想不到的問題。穩 +定版和長期支持內核的維護者非常清楚這一點，因此他們只對這些內核進行符合 +「Documentation/translations/zh_TW/process/stable-kernel-rules.rst」中所列出的 +規則的修改。 + +複雜或有風險的修改不符合條件，因此只能應用於主線。其他的修復很容易被回溯到 +最新的穩定版和長期支持內核，但是風險太大，無法集成到舊版內核中。所以要注意 +你所希望的修復可能是那些不會被回溯到你所關心的版本線的修復之一。在這種情況 +下，你將別無選擇，要麼忍受這個問題，要麼切換到一個較新的 Linux 版本，除非你 +想自己把修復補丁應用到你的內核中。 + +通用準備 +~~~~~~~~~~ + + *執行上面「報告僅在舊內核版本線中發生的問題」一節中的前三個步驟。* + +您需要執行本指南另一節中已經描述的幾個步驟。這些步驟將讓您： + + * 檢查內核開發人員是否仍然維護您關心的Linux內核版本行。 + + * 在Linux穩定郵件列表中搜索退出的報告。 + + * 檢查最新版本。 + + +檢查代碼歷史和搜索現有的討論 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + *在Linux內核版本控制系統中搜索修復主線問題的更改，因爲它的提交消息可能 + 會告訴你修復是否已經計劃好了支持。如果你沒有找到，搜索適當的郵件列表， + 尋找討論此類問題或同行評議可能修復的帖子；然後檢查討論是否認爲修復不適 + 合支持。如果支持根本不被考慮，加入最新的討論，詢問是否有可能。* + +在許多情況下，你所處理的問題會發生在主線上，但已在主線上得到了解決。修正它 +的提交也需要被回溯才能解決這個問題。這就是爲什麼你要搜索它或任何相關討論。 + + * 首先嘗試在存放 Linux 內核原始碼的 Git 倉庫中找到修復。你可以通過 + `kernel.org 上的網頁 + `_ + 或 `GitHub 上的鏡像 `_ 來實現；如果你 + 有一個本地克隆，你也可以在命令行用 ``git log --grep=`` 來搜索。 + + 如果你找到了修復，請查看提交消息的尾部是否包含了類似這樣的「穩定版標籤」： + + Cc: # 5.4+ + + 像上面這行，開發者標記了安全修復可以回傳到 5.4 及以後的版本。大多數情況 + 下，它會在兩周內被應用到那裡，但有時需要更長的時間。 + + * 如果提交沒有告訴你任何東西，或者你找不到修復，請再找找關於這個問題的討論。 + 用你最喜歡的搜尋引擎搜索網絡，以及 `Linux kernel developers mailing + list 內核開發者郵件列表 `_ 的檔案。也可以 + 閱讀上面的 `定位導致問題的內核區域` 一節，然後按照說明找到導致問題的子系 + 統：它的缺陷跟蹤器或郵件列表存檔中可能有你要找的答案。 + + * 如果你看到了一個計劃的修復，請按上所述在版本控制系統中搜索它，因爲提交可 + 能會告訴你是否可以進行回溯。 + + * 檢查討論中是否有任何跡象表明，該修復程序可能風險太大，無法回溯到你關心 + 的版本線。如果是這樣的話，你必須忍受這個問題，或者切換到應用了修復的內 + 核版本線。 + + * 如果修復的問題未包含穩定版標籤，並且沒有討論過回溯問題，請加入討論：如 + 果合適的話，請提及你所面對的問題的版本，以及你希望看到它被修復。 + + +請求建議 +~~~~~~~~~ + + *前面的步驟之一應該會給出一個解決方案。如果仍未能成功，請向可能引起問題 + 的子系統的維護人員詢問建議；抄送特定子系統的郵件列表以及穩定版郵件列表。* + +如果前面的三個步驟都沒有讓你更接近解決方案，那麼只剩下一個選擇：請求建議。 +在你發給可能是問題根源的子系統的維護者的郵件中這樣做；抄送子系統的郵件列表 +以及穩定版郵件列表（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_TW/admin-guide/security-bugs.rst b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst new file mode 100644 index 000000000..eed260ef0 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/security-bugs.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/security-bugs` + +:譯者: + + 吳想成 Wu XiangCheng + 胡皓文 Hu Haowen + +安全缺陷 +========= + +Linux內核開發人員非常重視安全性。因此我們想知道何時發現了安全漏洞，以便儘快 +修復和披露。請向Linux內核安全團隊報告安全漏洞。 + +聯絡 +----- + +可以通過電子郵件聯繫Linux內核安全團隊。這是一個安全人員 +的私有列表，他們將幫助驗證錯誤報告並開發和發布修復程序。如果您已經有了一個 +修復，請將其包含在您的報告中，這樣可以大大加快進程。安全團隊可能會從區域維護 +人員那裡獲得額外的幫助，以理解和修復安全漏洞。 + +與任何缺陷一樣，提供的信息越多，診斷和修復就越容易。如果您不清楚哪些信息有用， +請查看「Documentation/translations/zh_TW/admin-guide/reporting-issues.rst」中 +概述的步驟。任何利用漏洞的攻擊代碼都非常有用，未經報告者同意不會對外發布，除 +非已經公開。 + +請儘可能發送無附件的純文本電子郵件。如果所有的細節都藏在附件里，那麼就很難對 +一個複雜的問題進行上下文引用的討論。把它想像成一個 +:doc:`常規的補丁提交 <../process/submitting-patches>` （即使你還沒有補丁）： +描述問題和影響，列出復現步驟，然後給出一個建議的解決方案，所有這些都是純文本的。 + +披露和限制信息 +--------------- + +安全列表不是公開渠道。爲此，請參見下面的協作。 + +一旦開發出了健壯的補丁，發布過程就開始了。對公開的缺陷的修復會立即發布。 + +儘管我們傾向於在未公開缺陷的修復可用時即發布補丁，但應報告者或受影響方的請求， +這可能會被推遲到發布過程開始後的7日內，如果根據缺陷的嚴重性需要更多的時間， +則可額外延長到14天。推遲發布修復的唯一有效原因是爲了適應QA的邏輯和需要發布 +協調的大規模部署。 + +雖然可能與受信任的個人共享受限信息以開發修復，但未經報告者許可，此類信息不會 +與修復程序一起發布或發布在任何其他披露渠道上。這包括但不限於原始錯誤報告和 +後續討論（如有）、漏洞、CVE信息或報告者的身份。 + +換句話說，我們唯一感興趣的是修復缺陷。提交給安全列表的所有其他資料以及對報告 +的任何後續討論，即使在解除限制之後，也將永久保密。 + +協調 +------ + +對敏感缺陷（例如那些可能導致權限提升的缺陷）的修復可能需要與私有郵件列表 +進行協調，以便分發供應商做好準備，在公開披露 +上游補丁時發布一個已修復的內核。發行版將需要一些時間來測試建議的補丁，通常 +會要求至少幾天的限制，而供應商更新發布更傾向於周二至周四。若合適，安全團隊 +可以協助這種協調，或者報告者可以從一開始就包括linux發行版。在這種情況下，請 +記住在電子郵件主題行前面加上「[vs]」，如linux發行版wiki中所述： +。 + +CVE分配 +-------- + +安全團隊通常不分配CVE，我們也不需要它們來進行報告或修復，因爲這會使過程不必 +要的複雜化，並可能耽誤缺陷處理。如果報告者希望在公開披露之前分配一個CVE編號， +他們需要聯繫上述的私有linux-distros列表。當在提供補丁之前已有這樣的CVE編號時， +如報告者願意，最好在提交消息中提及它。 + +保密協議 +--------- + +Linux內核安全團隊不是一個正式的機構實體，因此無法簽訂任何保密協議。 + diff --git a/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst new file mode 100644 index 000000000..d7b3c4276 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/tainted-kernels.rst @@ -0,0 +1,161 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../admin-guide/tainted-kernels` + +:譯者: + + 吳想成 Wu XiangCheng + 胡皓文 Hu Haowen + +受汙染的內核 +------------- + +當發生一些在稍後調查問題時可能相關的事件時，內核會將自己標記爲「受汙染 +（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 `_ +網站下載此腳本並用 ``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_TW/admin-guide/unicode.rst b/Documentation/translations/zh_TW/admin-guide/unicode.rst new file mode 100644 index 000000000..720875be5 --- /dev/null +++ b/Documentation/translations/zh_TW/admin-guide/unicode.rst @@ -0,0 +1,174 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: Documentation/admin-guide/unicode.rst + +:譯者: + + 吳想成 Wu XiangCheng + 胡皓文 Hu Haowen + +Unicode（統一碼）支持 +====================== + + （英文版）上次更新：2005-01-17，版本號 1.4 + +此文檔由H. Peter Anvin 管理，是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 in standard Okrand Latin transliteration +U+F8E0 KLINGON LETTER QH + - Written 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 +和 Michael Everson 建立了一個虛構和人工字母的註冊表。 +徵募Unicode註冊表請訪問： + + https://www.evertype.com/standards/csur/ + +所使用的範圍位於最終用戶區域的低端，因此無法進行規範化分配，但建議希望對虛構 +字母進行編碼的人員使用這些代碼，以實現互操作性。對於克林貢語，CSUR採用了Linux +編碼。CSUR的人正在推動將Tengwar和Cirth添加到Unicode平面一；將克林貢添加到 +Unicode平面一被拒絕，因此上述編碼仍然是官方的。 + diff --git a/Documentation/translations/zh_TW/arm64/amu.rst b/Documentation/translations/zh_TW/arm64/amu.rst new file mode 100644 index 000000000..ffdc466e0 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/amu.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/amu.rst ` + +Translator: Bailu Lin + Hu Haowen + +================================== +AArch64 Linux 中擴展的活動監控單元 +================================== + +作者: Ionela Voinescu + +日期: 2019-09-10 + +本文檔簡要描述了 AArch64 Linux 支持的活動監控單元的規範。 + + +架構總述 +-------- + +活動監控是 ARMv8.4 CPU 架構引入的一個可選擴展特性。 + +活動監控單元(在每個 CPU 中實現)爲系統管理提供了性能計數器。既可以通 +過系統寄存器的方式訪問計數器，同時也支持外部內存映射的方式訪問計數器。 + +AMUv1 架構實現了一個由4個固定的64位事件計數器組成的計數器組。 + + - CPU 周期計數器：同 CPU 的頻率增長 + - 常量計數器：同固定的系統時鐘頻率增長 + - 淘汰指令計數器: 同每次架構指令執行增長 + - 內存停頓周期計數器：計算由在時鐘域內的最後一級緩存中未命中而引起 + 的指令調度停頓周期數 + +當處於 WFI 或者 WFE 狀態時，計數器不會增長。 + +AMU 架構提供了一個高達16位的事件計數器空間，未來新的 AMU 版本中可能 +用它來實現新增的事件計數器。 + +另外，AMUv1 實現了一個多達16個64位輔助事件計數器的計數器組。 + +冷復位時所有的計數器會清零。 + + +基本支持 +-------- + +內核可以安全地運行在支持 AMU 和不支持 AMU 的 CPU 組合中。 +因此，當配置 CONFIG_ARM64_AMU_EXTN 後我們無條件使能後續 +(secondary or hotplugged) CPU 檢測和使用這個特性。 + +當在 CPU 上檢測到該特性時，我們會標記爲特性可用但是不能保證計數器的功能， +僅表明有擴展屬性。 + +固件(代碼運行在高異常級別，例如 arm-tf )需支持以下功能： + + - 提供低異常級別(EL2 和 EL1)訪問 AMU 寄存器的能力。 + - 使能計數器。如果未使能，它的值應爲 0。 + - 在從電源關閉狀態啓動 CPU 前或後保存或者恢復計數器。 + +當使用使能了該特性的內核啓動但固件損壞時，訪問計數器寄存器可能會遭遇 +panic 或者死鎖。即使未發現這些症狀，計數器寄存器返回的數據結果並不一 +定能反映真實情況。通常，計數器會返回 0，表明他們未被使能。 + +如果固件沒有提供適當的支持最好關閉 CONFIG_ARM64_AMU_EXTN。 +值得注意的是，出於安全原因，不要繞過 AMUSERRENR_EL0 設置而捕獲從 +EL0(用戶空間) 訪問 EL1(內核空間)。 因此，固件應該確保訪問 AMU寄存器 +不會困在 EL2或EL3。 + +AMUv1 的固定計數器可以通過如下系統寄存器訪問： + + - SYS_AMEVCNTR0_CORE_EL0 + - SYS_AMEVCNTR0_CONST_EL0 + - SYS_AMEVCNTR0_INST_RET_EL0 + - SYS_AMEVCNTR0_MEM_STALL_EL0 + +特定輔助計數器可以通過 SYS_AMEVCNTR1_EL0(n) 訪問，其中n介於0到15。 + +詳細信息定義在目錄：arch/arm64/include/asm/sysreg.h。 + + +用戶空間訪問 +------------ + +由於以下原因，當前禁止從用戶空間訪問 AMU 的寄存器： + + - 安全因數：可能會暴露處於安全模式執行的代碼信息。 + - 意願：AMU 是用於系統管理的。 + +同樣，該功能對用戶空間不可見。 + + +虛擬化 +------ + +由於以下原因，當前禁止從 KVM 客戶端的用戶空間(EL0)和內核空間(EL1) +訪問 AMU 的寄存器： + + - 安全因數：可能會暴露給其他客戶端或主機端執行的代碼信息。 + +任何試圖訪問 AMU 寄存器的行爲都會觸發一個註冊在客戶端的未定義異常。 + diff --git a/Documentation/translations/zh_TW/arm64/booting.txt b/Documentation/translations/zh_TW/arm64/booting.txt new file mode 100644 index 000000000..b9439dd54 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/booting.txt @@ -0,0 +1,251 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/arm64/booting.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +M: Will Deacon +zh_CN: Fu Wei +zh_TW: Hu Haowen +C: 55f058e7574c3615dea4615573a19bdb258696c6 +--------------------------------------------------------------------- +Documentation/arm64/booting.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +英文版維護者： Will Deacon +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者： 胡皓文 Hu Haowen +本文翻譯提交時的 Git 檢出點爲： 55f058e7574c3615dea4615573a19bdb258696c6 + +以下爲正文 +--------------------------------------------------------------------- + 啓動 AArch64 Linux + ================== + +作者: Will Deacon +日期: 2012 年 09 月 07 日 + +本文檔基於 Russell King 的 ARM 啓動文檔，且適用於所有公開發布的 +AArch64 Linux 內核代碼。 + +AArch64 異常模型由多個異常級（EL0 - EL3）組成，對於 EL0 和 EL1 異常級 +有對應的安全和非安全模式。EL2 是系統管理級，且僅存在於非安全模式下。 +EL3 是最高特權級，且僅存在於安全模式下。 + +基於本文檔的目的，我們將簡單地使用『引導裝載程序』（『boot loader』） +這個術語來定義在將控制權交給 Linux 內核前 CPU 上執行的所有軟體。 +這可能包含安全監控和系統管理代碼，或者它可能只是一些用於準備最小啓動 +環境的指令。 + +基本上，引導裝載程序（至少）應實現以下操作： + +1、設置和初始化 RAM +2、設置設備樹數據 +3、解壓內核映像 +4、調用內核映像 + + +1、設置和初始化 RAM +----------------- + +必要性: 強制 + +引導裝載程序應該找到並初始化系統中所有內核用於保持系統變量數據的 RAM。 +這個操作的執行方式因設備而異。（它可能使用內部算法來自動定位和計算所有 +RAM，或可能使用對這個設備已知的 RAM 信息，還可能是引導裝載程序設計者 +想到的任何合適的方法。） + + +2、設置設備樹數據 +--------------- + +必要性: 強制 + +設備樹數據塊（dtb）必須 8 字節對齊，且大小不能超過 2MB。由於設備樹 +數據塊將在使能緩存的情況下以 2MB 粒度被映射，故其不能被置於必須以特定 +屬性映射的2M區域內。 + +註： v4.2 之前的版本同時要求設備樹數據塊被置於從內核映像以下 +text_offset 字節處算起第一個 512MB 內。 + +3、解壓內核映像 +------------- + +必要性: 可選 + +AArch64 內核當前沒有提供自解壓代碼，因此如果使用了壓縮內核映像文件 +（比如 Image.gz），則需要通過引導裝載程序（使用 gzip 等）來進行解壓。 +若引導裝載程序沒有實現這個功能，就要使用非壓縮內核映像文件。 + + +4、調用內核映像 +------------- + +必要性: 強制 + +已解壓的內核映像包含一個 64 字節的頭，內容如下： + + u32 code0; /* 可執行代碼 */ + u32 code1; /* 可執行代碼 */ + u64 text_offset; /* 映像裝載偏移，小端模式 */ + u64 image_size; /* 映像實際大小, 小端模式 */ + u64 flags; /* 內核旗標, 小端模式 * + u64 res2 = 0; /* 保留 */ + u64 res3 = 0; /* 保留 */ + u64 res4 = 0; /* 保留 */ + u32 magic = 0x644d5241; /* 魔數, 小端, "ARM\x64" */ + u32 res5; /* 保留 （用於 PE COFF 偏移） */ + + +映像頭注釋： + +- 自 v3.17 起，除非另有說明，所有域都是小端模式。 + +- code0/code1 負責跳轉到 stext. + +- 當通過 EFI 啓動時， 最初 code0/code1 被跳過。 + res5 是到 PE 文件頭的偏移，而 PE 文件頭含有 EFI 的啓動入口點 + （efi_stub_entry）。當 stub 代碼完成了它的使命，它會跳轉到 code0 + 繼續正常的啓動流程。 + +- v3.17 之前，未明確指定 text_offset 的字節序。此時，image_size 爲零， + 且 text_offset 依照內核字節序爲 0x80000。 + 當 image_size 非零，text_offset 爲小端模式且是有效值，應被引導加載 + 程序使用。當 image_size 爲零，text_offset 可假定爲 0x80000。 + +- flags 域 (v3.17 引入) 爲 64 位小端模式，其編碼如下： + 位 0: 內核字節序。 1 表示大端模式，0 表示小端模式。 + 位 1-2: 內核頁大小。 + 0 - 未指定。 + 1 - 4K + 2 - 16K + 3 - 64K + 位 3: 內核物理位置 + 0 - 2MB 對齊基址應儘量靠近內存起始處，因爲 + 其基址以下的內存無法通過線性映射訪問 + 1 - 2MB 對齊基址可以在物理內存的任意位置 + 位 4-63: 保留。 + +- 當 image_size 爲零時，引導裝載程序應試圖在內核映像末尾之後儘可能 + 多地保留空閒內存供內核直接使用。對內存空間的需求量因所選定的內核 + 特性而異, 並無實際限制。 + +內核映像必須被放置在任意一個可用系統內存 2MB 對齊基址的 text_offset +字節處，並從該處被調用。2MB 對齊基址和內核映像起始地址之間的區域對於 +內核來說沒有特殊意義，且可能被用於其他目的。 +從映像起始地址算起，最少必須準備 image_size 字節的空閒內存供內核使用。 +註： v4.6 之前的版本無法使用內核映像物理偏移以下的內存，所以當時建議 +將映像儘量放置在靠近系統內存起始的地方。 + +任何提供給內核的內存（甚至在映像起始地址之前），若未從內核中標記爲保留 +(如在設備樹（dtb）的 memreserve 區域），都將被認爲對內核是可用。 + +在跳轉入內核前，必須符合以下狀態： + +- 停止所有 DMA 設備，這樣內存數據就不會因爲虛假網絡包或磁碟數據而 + 被破壞。這可能可以節省你許多的調試時間。 + +- 主 CPU 通用寄存器設置 + x0 = 系統 RAM 中設備樹數據塊（dtb）的物理地址。 + x1 = 0 (保留，將來可能使用) + x2 = 0 (保留，將來可能使用) + x3 = 0 (保留，將來可能使用) + +- CPU 模式 + 所有形式的中斷必須在 PSTATE.DAIF 中被屏蔽（Debug、SError、IRQ + 和 FIQ）。 + CPU 必須處於 EL2（推薦，可訪問虛擬化擴展）或非安全 EL1 模式下。 + +- 高速緩存、MMU + MMU 必須關閉。 + 指令緩存開啓或關閉皆可。 + 已載入的內核映像的相應內存區必須被清理，以達到緩存一致性點（PoC）。 + 當存在系統緩存或其他使能緩存的一致性主控器時，通常需使用虛擬地址 + 維護其緩存，而非 set/way 操作。 + 遵從通過虛擬地址操作維護構架緩存的系統緩存必須被配置，並可以被使能。 + 而不通過虛擬地址操作維護構架緩存的系統緩存（不推薦），必須被配置且 + 禁用。 + + *譯者註：對於 PoC 以及緩存相關內容，請參考 ARMv8 構架參考手冊 + ARM DDI 0487A + +- 架構計時器 + CNTFRQ 必須設定爲計時器的頻率，且 CNTVOFF 必須設定爲對所有 CPU + 都一致的值。如果在 EL1 模式下進入內核，則 CNTHCTL_EL2 中的 + EL1PCTEN (bit 0) 必須置位。 + +- 一致性 + 通過內核啓動的所有 CPU 在內核入口地址上必須處於相同的一致性域中。 + 這可能要根據具體實現來定義初始化過程，以使能每個CPU上對維護操作的 + 接收。 + +- 系統寄存器 + 在進入內核映像的異常級中，所有構架中可寫的系統寄存器必須通過軟體 + 在一個更高的異常級別下初始化，以防止在 未知 狀態下運行。 + + 對於擁有 GICv3 中斷控制器並以 v3 模式運行的系統： + - 如果 EL3 存在： + ICC_SRE_EL3.Enable (位 3) 必須初始化爲 0b1。 + ICC_SRE_EL3.SRE (位 0) 必須初始化爲 0b1。 + - 若內核運行在 EL1： + ICC_SRE_EL2.Enable (位 3) 必須初始化爲 0b1。 + ICC_SRE_EL2.SRE (位 0) 必須初始化爲 0b1。 + - 設備樹（DT）或 ACPI 表必須描述一個 GICv3 中斷控制器。 + + 對於擁有 GICv3 中斷控制器並以兼容（v2）模式運行的系統： + - 如果 EL3 存在： + ICC_SRE_EL3.SRE (位 0) 必須初始化爲 0b0。 + - 若內核運行在 EL1： + ICC_SRE_EL2.SRE (位 0) 必須初始化爲 0b0。 + - 設備樹（DT）或 ACPI 表必須描述一個 GICv2 中斷控制器。 + +以上對於 CPU 模式、高速緩存、MMU、架構計時器、一致性、系統寄存器的 +必要條件描述適用於所有 CPU。所有 CPU 必須在同一異常級別跳入內核。 + +引導裝載程序必須在每個 CPU 處於以下狀態時跳入內核入口： + +- 主 CPU 必須直接跳入內核映像的第一條指令。通過此 CPU 傳遞的設備樹 + 數據塊必須在每個 CPU 節點中包含一個 『enable-method』 屬性，所 + 支持的 enable-method 請見下文。 + + 引導裝載程序必須生成這些設備樹屬性，並在跳入內核入口之前將其插入 + 數據塊。 + +- enable-method 爲 「spin-table」 的 CPU 必須在它們的 CPU + 節點中包含一個 『cpu-release-addr』 屬性。這個屬性標識了一個 + 64 位自然對齊且初始化爲零的內存位置。 + + 這些 CPU 必須在內存保留區（通過設備樹中的 /memreserve/ 域傳遞 + 給內核）中自旋於內核之外，輪詢它們的 cpu-release-addr 位置（必須 + 包含在保留區中）。可通過插入 wfe 指令來降低忙循環開銷，而主 CPU 將 + 發出 sev 指令。當對 cpu-release-addr 所指位置的讀取操作返回非零值 + 時，CPU 必須跳入此值所指向的地址。此值爲一個單獨的 64 位小端值， + 因此 CPU 須在跳轉前將所讀取的值轉換爲其本身的端模式。 + +- enable-method 爲 「psci」 的 CPU 保持在內核外（比如，在 + memory 節點中描述爲內核空間的內存區外，或在通過設備樹 /memreserve/ + 域中描述爲內核保留區的空間中）。內核將會發起在 ARM 文檔（編號 + ARM DEN 0022A：用於 ARM 上的電源狀態協調接口系統軟體）中描述的 + CPU_ON 調用來將 CPU 帶入內核。 + + *譯者注: ARM DEN 0022A 已更新到 ARM DEN 0022C。 + + 設備樹必須包含一個 『psci』 節點，請參考以下文檔： + Documentation/devicetree/bindings/arm/psci.yaml + + +- 輔助 CPU 通用寄存器設置 + x0 = 0 (保留，將來可能使用) + x1 = 0 (保留，將來可能使用) + x2 = 0 (保留，將來可能使用) + x3 = 0 (保留，將來可能使用) + diff --git a/Documentation/translations/zh_TW/arm64/elf_hwcaps.rst b/Documentation/translations/zh_TW/arm64/elf_hwcaps.rst new file mode 100644 index 000000000..3eb1c623c --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/elf_hwcaps.rst @@ -0,0 +1,244 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/elf_hwcaps.rst ` + +Translator: Bailu Lin + Hu Haowen + +================ +ARM64 ELF hwcaps +================ + +這篇文檔描述了 arm64 ELF hwcaps 的用法和語義。 + + +1. 簡介 +------- + +有些硬體或軟體功能僅在某些 CPU 實現上和/或在具體某個內核配置上可用，但 +對於處於 EL0 的用戶空間代碼沒有可用的架構發現機制。內核通過在輔助向量表 +公開一組稱爲 hwcaps 的標誌而把這些功能暴露給用戶空間。 + +用戶空間軟體可以通過獲取輔助向量的 AT_HWCAP 或 AT_HWCAP2 條目來測試功能， +並測試是否設置了相關標誌，例如:: + + bool floating_point_is_present(void) + { + unsigned long hwcaps = getauxval(AT_HWCAP); + if (hwcaps & HWCAP_FP) + return true; + + return false; + } + +如果軟體依賴於 hwcap 描述的功能，在嘗試使用該功能前則應檢查相關的 hwcap +標誌以驗證該功能是否存在。 + +不能通過其他方式探查這些功能。當一個功能不可用時，嘗試使用它可能導致不可 +預測的行爲，並且無法保證能確切的知道該功能不可用，例如 SIGILL。 + + +2. Hwcaps 的說明 +---------------- + +大多數 hwcaps 旨在說明通過架構 ID 寄存器(處於 EL0 的用戶空間代碼無法訪問) +描述的功能的存在。這些 hwcap 通過 ID 寄存器欄位定義，並且應根據 ARM 體系 +結構參考手冊（ARM ARM）中定義的欄位來解釋說明。 + +這些 hwcaps 以下面的形式描述:: + + idreg.field == val 表示有某個功能。 + +當 idreg.field 中有 val 時，hwcaps 表示 ARM ARM 定義的功能是有效的，但是 +並不是說要完全和 val 相等，也不是說 idreg.field 描述的其他功能就是缺失的。 + +其他 hwcaps 可能表明無法僅由 ID 寄存器描述的功能的存在。這些 hwcaps 可能 +沒有被 ID 寄存器描述，需要參考其他文檔。 + + +3. AT_HWCAP 中揭示的 hwcaps +--------------------------- + +HWCAP_FP + ID_AA64PFR0_EL1.FP == 0b0000 表示有此功能。 + +HWCAP_ASIMD + ID_AA64PFR0_EL1.AdvSIMD == 0b0000 表示有此功能。 + +HWCAP_EVTSTRM + 通用計時器頻率配置爲大約100KHz以生成事件。 + +HWCAP_AES + ID_AA64ISAR0_EL1.AES == 0b0001 表示有此功能。 + +HWCAP_PMULL + ID_AA64ISAR0_EL1.AES == 0b0010 表示有此功能。 + +HWCAP_SHA1 + ID_AA64ISAR0_EL1.SHA1 == 0b0001 表示有此功能。 + +HWCAP_SHA2 + ID_AA64ISAR0_EL1.SHA2 == 0b0001 表示有此功能。 + +HWCAP_CRC32 + ID_AA64ISAR0_EL1.CRC32 == 0b0001 表示有此功能。 + +HWCAP_ATOMICS + ID_AA64ISAR0_EL1.Atomic == 0b0010 表示有此功能。 + +HWCAP_FPHP + ID_AA64PFR0_EL1.FP == 0b0001 表示有此功能。 + +HWCAP_ASIMDHP + ID_AA64PFR0_EL1.AdvSIMD == 0b0001 表示有此功能。 + +HWCAP_CPUID + 根據 Documentation/arm64/cpu-feature-registers.rst 描述，EL0 可以訪問 + 某些 ID 寄存器。 + + 這些 ID 寄存器可能表示功能的可用性。 + +HWCAP_ASIMDRDM + ID_AA64ISAR0_EL1.RDM == 0b0001 表示有此功能。 + +HWCAP_JSCVT + ID_AA64ISAR1_EL1.JSCVT == 0b0001 表示有此功能。 + +HWCAP_FCMA + ID_AA64ISAR1_EL1.FCMA == 0b0001 表示有此功能。 + +HWCAP_LRCPC + ID_AA64ISAR1_EL1.LRCPC == 0b0001 表示有此功能。 + +HWCAP_DCPOP + ID_AA64ISAR1_EL1.DPB == 0b0001 表示有此功能。 + +HWCAP_SHA3 + ID_AA64ISAR0_EL1.SHA3 == 0b0001 表示有此功能。 + +HWCAP_SM3 + ID_AA64ISAR0_EL1.SM3 == 0b0001 表示有此功能。 + +HWCAP_SM4 + ID_AA64ISAR0_EL1.SM4 == 0b0001 表示有此功能。 + +HWCAP_ASIMDDP + ID_AA64ISAR0_EL1.DP == 0b0001 表示有此功能。 + +HWCAP_SHA512 + ID_AA64ISAR0_EL1.SHA2 == 0b0010 表示有此功能。 + +HWCAP_SVE + ID_AA64PFR0_EL1.SVE == 0b0001 表示有此功能。 + +HWCAP_ASIMDFHM + ID_AA64ISAR0_EL1.FHM == 0b0001 表示有此功能。 + +HWCAP_DIT + ID_AA64PFR0_EL1.DIT == 0b0001 表示有此功能。 + +HWCAP_USCAT + ID_AA64MMFR2_EL1.AT == 0b0001 表示有此功能。 + +HWCAP_ILRCPC + ID_AA64ISAR1_EL1.LRCPC == 0b0010 表示有此功能。 + +HWCAP_FLAGM + ID_AA64ISAR0_EL1.TS == 0b0001 表示有此功能。 + +HWCAP_SSBS + ID_AA64PFR1_EL1.SSBS == 0b0010 表示有此功能。 + +HWCAP_SB + ID_AA64ISAR1_EL1.SB == 0b0001 表示有此功能。 + +HWCAP_PACA + 如 Documentation/arm64/pointer-authentication.rst 所描述， + ID_AA64ISAR1_EL1.APA == 0b0001 或 ID_AA64ISAR1_EL1.API == 0b0001 + 表示有此功能。 + +HWCAP_PACG + 如 Documentation/arm64/pointer-authentication.rst 所描述， + ID_AA64ISAR1_EL1.GPA == 0b0001 或 ID_AA64ISAR1_EL1.GPI == 0b0001 + 表示有此功能。 + +HWCAP2_DCPODP + + ID_AA64ISAR1_EL1.DPB == 0b0010 表示有此功能。 + +HWCAP2_SVE2 + + ID_AA64ZFR0_EL1.SVEVer == 0b0001 表示有此功能。 + +HWCAP2_SVEAES + + ID_AA64ZFR0_EL1.AES == 0b0001 表示有此功能。 + +HWCAP2_SVEPMULL + + ID_AA64ZFR0_EL1.AES == 0b0010 表示有此功能。 + +HWCAP2_SVEBITPERM + + ID_AA64ZFR0_EL1.BitPerm == 0b0001 表示有此功能。 + +HWCAP2_SVESHA3 + + ID_AA64ZFR0_EL1.SHA3 == 0b0001 表示有此功能。 + +HWCAP2_SVESM4 + + ID_AA64ZFR0_EL1.SM4 == 0b0001 表示有此功能。 + +HWCAP2_FLAGM2 + + ID_AA64ISAR0_EL1.TS == 0b0010 表示有此功能。 + +HWCAP2_FRINT + + ID_AA64ISAR1_EL1.FRINTTS == 0b0001 表示有此功能。 + +HWCAP2_SVEI8MM + + ID_AA64ZFR0_EL1.I8MM == 0b0001 表示有此功能。 + +HWCAP2_SVEF32MM + + ID_AA64ZFR0_EL1.F32MM == 0b0001 表示有此功能。 + +HWCAP2_SVEF64MM + + ID_AA64ZFR0_EL1.F64MM == 0b0001 表示有此功能。 + +HWCAP2_SVEBF16 + + ID_AA64ZFR0_EL1.BF16 == 0b0001 表示有此功能。 + +HWCAP2_I8MM + + ID_AA64ISAR1_EL1.I8MM == 0b0001 表示有此功能。 + +HWCAP2_BF16 + + ID_AA64ISAR1_EL1.BF16 == 0b0001 表示有此功能。 + +HWCAP2_DGH + + ID_AA64ISAR1_EL1.DGH == 0b0001 表示有此功能。 + +HWCAP2_RNG + + ID_AA64ISAR0_EL1.RNDR == 0b0001 表示有此功能。 + +HWCAP2_BTI + + ID_AA64PFR0_EL1.BT == 0b0001 表示有此功能。 + + +4. 未使用的 AT_HWCAP 位 +----------------------- + +爲了與用戶空間交互，內核保證 AT_HWCAP 的第62、63位將始終返回0。 + diff --git a/Documentation/translations/zh_TW/arm64/hugetlbpage.rst b/Documentation/translations/zh_TW/arm64/hugetlbpage.rst new file mode 100644 index 000000000..846b500da --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/hugetlbpage.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/hugetlbpage.rst ` + +Translator: Bailu Lin + Hu Haowen + +===================== +ARM64中的 HugeTLBpage +===================== + +大頁依靠有效利用 TLBs 來提高地址翻譯的性能。這取決於以下 +兩點 - + + - 大頁的大小 + - TLBs 支持的條目大小 + +ARM64 接口支持2種大頁方式。 + +1) pud/pmd 級別的塊映射 +----------------------- + +這是常規大頁，他們的 pmd 或 pud 頁面表條目指向一個內存塊。 +不管 TLB 中支持的條目大小如何，塊映射可以減少翻譯大頁地址 +所需遍歷的頁表深度。 + +2) 使用連續位 +------------- + +架構中轉換頁表條目(D4.5.3, ARM DDI 0487C.a)中提供一個連續 +位告訴 MMU 這個條目是一個連續條目集的一員，它可以被緩存在單 +個 TLB 條目中。 + +在 Linux 中連續位用來增加 pmd 和 pte(最後一級)級別映射的大 +小。受支持的連續頁表條目數量因頁面大小和頁表級別而異。 + + +支持以下大頁尺寸配置 - + + ====== ======== ==== ======== === + - CONT PTE PMD CONT PMD PUD + ====== ======== ==== ======== === + 4K: 64K 2M 32M 1G + 16K: 2M 32M 1G + 64K: 2M 512M 16G + ====== ======== ==== ======== === + diff --git a/Documentation/translations/zh_TW/arm64/index.rst b/Documentation/translations/zh_TW/arm64/index.rst new file mode 100644 index 000000000..2322783f3 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/index.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/index.rst ` +:Translator: Bailu Lin + Hu Haowen + +.. _tw_arm64_index: + + +========== +ARM64 架構 +========== + +.. toctree:: + :maxdepth: 2 + + amu + hugetlbpage + perf + elf_hwcaps + diff --git a/Documentation/translations/zh_TW/arm64/legacy_instructions.txt b/Documentation/translations/zh_TW/arm64/legacy_instructions.txt new file mode 100644 index 000000000..6d4454f77 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/legacy_instructions.txt @@ -0,0 +1,77 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/arm64/legacy_instructions.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Punit Agrawal + Suzuki K. Poulose +Chinese maintainer: Fu Wei +Traditional Chinese maintainer: Hu Haowen +--------------------------------------------------------------------- +Documentation/arm64/legacy_instructions.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +本文翻譯提交時的 Git 檢出點爲： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6 + +英文版維護者： Punit Agrawal + Suzuki K. Poulose +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者：胡皓文 Hu Haowen + +以下爲正文 +--------------------------------------------------------------------- +Linux 內核在 arm64 上的移植提供了一個基礎框架，以支持構架中正在被淘汰或已廢棄指令的模擬執行。 +這個基礎框架的代碼使用未定義指令鉤子（hooks）來支持模擬。如果指令存在，它也允許在硬體中啓用該指令。 + +模擬模式可通過寫 sysctl 節點（/proc/sys/abi）來控制。 +不同的執行方式及 sysctl 節點的相應值，解釋如下： + +* Undef（未定義） + 值： 0 + 產生未定義指令終止異常。它是那些構架中已廢棄的指令，如 SWP，的默認處理方式。 + +* Emulate（模擬） + 值： 1 + 使用軟體模擬方式。爲解決軟體遷移問題，這種模擬指令模式的使用是被跟蹤的，並會發出速率限制警告。 + 它是那些構架中正在被淘汰的指令，如 CP15 barriers（隔離指令），的默認處理方式。 + +* Hardware Execution（硬體執行） + 值： 2 + 雖然標記爲正在被淘汰，但一些實現可能提供硬體執行這些指令的使能/禁用操作。 + 使用硬體執行一般會有更好的性能，但將無法收集運行時對正被淘汰指令的使用統計數據。 + +默認執行模式依賴於指令在構架中狀態。正在被淘汰的指令應該以模擬（Emulate）作爲默認模式， +而已廢棄的指令必須默認使用未定義（Undef）模式 + +注意：指令模擬可能無法應對所有情況。更多詳情請參考單獨的指令注釋。 + +受支持的遺留指令 +------------- +* SWP{B} +節點: /proc/sys/abi/swp +狀態: 已廢棄 +默認執行方式: Undef (0) + +* CP15 Barriers +節點: /proc/sys/abi/cp15_barrier +狀態: 正被淘汰，不推薦使用 +默認執行方式: Emulate (1) + +* SETEND +節點: /proc/sys/abi/setend +狀態: 正被淘汰，不推薦使用 +默認執行方式: Emulate (1)* +註：爲了使能這個特性，系統中的所有 CPU 必須在 EL0 支持混合字節序。 +如果一個新的 CPU （不支持混合字節序） 在使能這個特性後被熱插入系統， +在應用中可能會出現不可預期的結果。 + diff --git a/Documentation/translations/zh_TW/arm64/memory.txt b/Documentation/translations/zh_TW/arm64/memory.txt new file mode 100644 index 000000000..99c2b78b5 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/memory.txt @@ -0,0 +1,119 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/arm64/memory.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Catalin Marinas +Chinese maintainer: Fu Wei +Traditional Chinese maintainer: Hu Haowen +--------------------------------------------------------------------- +Documentation/arm64/memory.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +本文翻譯提交時的 Git 檢出點爲： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6 + +英文版維護者： Catalin Marinas +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者： 胡皓文 Hu Haowen + +以下爲正文 +--------------------------------------------------------------------- + Linux 在 AArch64 中的內存布局 + =========================== + +作者: Catalin Marinas + +本文檔描述 AArch64 Linux 內核所使用的虛擬內存布局。此構架可以實現 +頁大小爲 4KB 的 4 級轉換表和頁大小爲 64KB 的 3 級轉換表。 + +AArch64 Linux 使用 3 級或 4 級轉換表，其頁大小配置爲 4KB，對於用戶和內核 +分別都有 39-bit (512GB) 或 48-bit (256TB) 的虛擬地址空間。 +對於頁大小爲 64KB的配置，僅使用 2 級轉換表，有 42-bit (4TB) 的虛擬地址空間，但內存布局相同。 + +用戶地址空間的 63:48 位爲 0，而內核地址空間的相應位爲 1。TTBRx 的 +選擇由虛擬地址的 63 位給出。swapper_pg_dir 僅包含內核（全局）映射， +而用戶 pgd 僅包含用戶（非全局）映射。swapper_pg_dir 地址被寫入 +TTBR1 中，且從不寫入 TTBR0。 + + +AArch64 Linux 在頁大小爲 4KB，並使用 3 級轉換表時的內存布局： + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 0000007fffffffff 512GB 用戶空間 +ffffff8000000000 ffffffffffffffff 512GB 內核空間 + + +AArch64 Linux 在頁大小爲 4KB，並使用 4 級轉換表時的內存布局： + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 0000ffffffffffff 256TB 用戶空間 +ffff000000000000 ffffffffffffffff 256TB 內核空間 + + +AArch64 Linux 在頁大小爲 64KB，並使用 2 級轉換表時的內存布局： + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 000003ffffffffff 4TB 用戶空間 +fffffc0000000000 ffffffffffffffff 4TB 內核空間 + + +AArch64 Linux 在頁大小爲 64KB，並使用 3 級轉換表時的內存布局： + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000000000000000 0000ffffffffffff 256TB 用戶空間 +ffff000000000000 ffffffffffffffff 256TB 內核空間 + + +更詳細的內核虛擬內存布局，請參閱內核啓動信息。 + + +4KB 頁大小的轉換表查找： + ++--------+--------+--------+--------+--------+--------+--------+--------+ +|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| ++--------+--------+--------+--------+--------+--------+--------+--------+ + | | | | | | + | | | | | v + | | | | | [11:0] 頁內偏移 + | | | | +-> [20:12] L3 索引 + | | | +-----------> [29:21] L2 索引 + | | +---------------------> [38:30] L1 索引 + | +-------------------------------> [47:39] L0 索引 + +-------------------------------------------------> [63] TTBR0/1 + + +64KB 頁大小的轉換表查找： + ++--------+--------+--------+--------+--------+--------+--------+--------+ +|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| ++--------+--------+--------+--------+--------+--------+--------+--------+ + | | | | | + | | | | v + | | | | [15:0] 頁內偏移 + | | | +----------> [28:16] L3 索引 + | | +--------------------------> [41:29] L2 索引 + | +-------------------------------> [47:42] L1 索引 + +-------------------------------------------------> [63] TTBR0/1 + + +當使用 KVM 時, 管理程序（hypervisor）在 EL2 中通過相對內核虛擬地址的 +一個固定偏移來映射內核頁（內核虛擬地址的高 24 位設爲零）: + +起始地址 結束地址 大小 用途 +----------------------------------------------------------------------- +0000004000000000 0000007fffffffff 256GB 在 HYP 中映射的內核對象 + diff --git a/Documentation/translations/zh_TW/arm64/perf.rst b/Documentation/translations/zh_TW/arm64/perf.rst new file mode 100644 index 000000000..f1ffd55df --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/perf.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :ref:`Documentation/arm64/perf.rst ` + +Translator: Bailu Lin + Hu Haowen + +============= +Perf 事件屬性 +============= + +:作者: Andrew Murray +:日期: 2019-03-06 + +exclude_user +------------ + +該屬性排除用戶空間。 + +用戶空間始終運行在 EL0，因此該屬性將排除 EL0。 + + +exclude_kernel +-------------- + +該屬性排除內核空間。 + +打開 VHE 時內核運行在 EL2，不打開 VHE 時內核運行在 EL1。客戶機 +內核總是運行在 EL1。 + +對於宿主機，該屬性排除 EL1 和 VHE 上的 EL2。 + +對於客戶機，該屬性排除 EL1。請注意客戶機從來不會運行在 EL2。 + + +exclude_hv +---------- + +該屬性排除虛擬機監控器。 + +對於 VHE 宿主機該屬性將被忽略，此時我們認爲宿主機內核是虛擬機監 +控器。 + +對於 non-VHE 宿主機該屬性將排除 EL2，因爲虛擬機監控器運行在 EL2 +的任何代碼主要用於客戶機和宿主機的切換。 + +對於客戶機該屬性無效。請注意客戶機從來不會運行在 EL2。 + + +exclude_host / exclude_guest +---------------------------- + +這些屬性分別排除了 KVM 宿主機和客戶機。 + +KVM 宿主機可能運行在 EL0（用戶空間），EL1（non-VHE 內核）和 +EL2（VHE 內核 或 non-VHE 虛擬機監控器）。 + +KVM 客戶機可能運行在 EL0（用戶空間）和 EL1（內核）。 + +由於宿主機和客戶機之間重疊的異常級別，我們不能僅僅依靠 PMU 的硬體異 +常過濾機制-因此我們必須啓用/禁用對於客戶機進入和退出的計數。而這在 +VHE 和 non-VHE 系統上表現不同。 + +對於 non-VHE 系統的 exclude_host 屬性排除 EL2 - 在進入和退出客戶 +機時，我們會根據 exclude_host 和 exclude_guest 屬性在適當的情況下 +禁用/啓用該事件。 + +對於 VHE 系統的 exclude_guest 屬性排除 EL1，而對其中的 exclude_host +屬性同時排除 EL0，EL2。在進入和退出客戶機時，我們會適當地根據 +exclude_host 和 exclude_guest 屬性包括/排除 EL0。 + +以上聲明也適用於在 not-VHE 客戶機使用這些屬性時，但是請注意客戶機從 +來不會運行在 EL2。 + + +準確性 +------ + +在 non-VHE 宿主機上，我們在 EL2 進入/退出宿主機/客戶機的切換時啓用/ +關閉計數器 -但是在啓用/禁用計數器和進入/退出客戶機之間存在一段延時。 +對於 exclude_host， 我們可以通過過濾 EL2 消除在客戶機進入/退出邊界 +上用於計數客戶機事件的宿主機事件計數器。但是當使用 !exclude_hv 時， +在客戶機進入/退出有一個小的停電窗口無法捕獲到宿主機的事件。 + +在 VHE 系統沒有停電窗口。 + diff --git a/Documentation/translations/zh_TW/arm64/silicon-errata.txt b/Documentation/translations/zh_TW/arm64/silicon-errata.txt new file mode 100644 index 000000000..bf2077197 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/silicon-errata.txt @@ -0,0 +1,79 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/arm64/silicon-errata.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +M: Will Deacon +zh_CN: Fu Wei +zh_TW: Hu Haowen +C: 1926e54f115725a9248d0c4c65c22acaf94de4c4 +--------------------------------------------------------------------- +Documentation/arm64/silicon-errata.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +英文版維護者： Will Deacon +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者： 胡皓文 Hu Haowen +本文翻譯提交時的 Git 檢出點爲： 1926e54f115725a9248d0c4c65c22acaf94de4c4 + +以下爲正文 +--------------------------------------------------------------------- + 晶片勘誤和軟體補救措施 + ================== + +作者: Will Deacon +日期: 2015年11月27日 + +一個不幸的現實：硬體經常帶有一些所謂的「瑕疵（errata）」，導致其在 +某些特定情況下會違背構架定義的行爲。就基於 ARM 的硬體而言，這些瑕疵 +大體可分爲以下幾類： + + A 類：無可行補救措施的嚴重缺陷。 + B 類：有可接受的補救措施的重大或嚴重缺陷。 + C 類：在正常操作中不會顯現的小瑕疵。 + +更多資訊，請在 infocenter.arm.com （需註冊）中查閱「軟體開發者勘誤 +筆記」（「Software Developers Errata Notice」）文檔。 + +對於 Linux 而言，B 類缺陷可能需要作業系統的某些特別處理。例如，避免 +一個特殊的代碼序列，或是以一種特定的方式配置處理器。在某種不太常見的 +情況下，爲將 A 類缺陷當作 C 類處理，可能需要用類似的手段。這些手段被 +統稱爲「軟體補救措施」，且僅在少數情況需要（例如，那些需要一個運行在 +非安全異常級的補救措施 *並且* 能被 Linux 觸發的情況）。 + +對於尚在討論中的可能對未受瑕疵影響的系統產生干擾的軟體補救措施，有一個 +相應的內核配置（Kconfig）選項被加在 「內核特性（Kernel Features）」-> +「基於可選方法框架的 ARM 瑕疵補救措施（ARM errata workarounds via +the alternatives framework）"。這些選項被默認開啓，若探測到受影響的CPU， +補丁將在運行時被使用。至於對系統運行影響較小的補救措施，內核配置選項 +並不存在，且代碼以某種規避瑕疵的方式被構造（帶注釋爲宜）。 + +這種做法對於在任意內核原始碼樹中準確地判斷出哪個瑕疵已被軟體方法所補救 +稍微有點麻煩，所以在 Linux 內核中此文件作爲軟體補救措施的註冊表， +並將在新的軟體補救措施被提交和向後移植（backported）到穩定內核時被更新。 + +| 實現者 | 受影響的組件 | 勘誤編號 | 內核配置 | ++----------------+-----------------+-----------------+-------------------------+ +| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | +| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | +| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 | +| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 | +| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 | +| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 | +| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 | +| ARM | Cortex-A57 | #852523 | N/A | +| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 | +| | | | | +| Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | +| Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 | + diff --git a/Documentation/translations/zh_TW/arm64/tagged-pointers.txt b/Documentation/translations/zh_TW/arm64/tagged-pointers.txt new file mode 100644 index 000000000..87f886284 --- /dev/null +++ b/Documentation/translations/zh_TW/arm64/tagged-pointers.txt @@ -0,0 +1,57 @@ +SPDX-License-Identifier: GPL-2.0 + +Chinese translated version of Documentation/arm64/tagged-pointers.rst + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Will Deacon +Chinese maintainer: Fu Wei +Traditional Chinese maintainer: Hu Haowen +--------------------------------------------------------------------- +Documentation/arm64/tagged-pointers.rst 的中文翻譯 + +如果想評論或更新本文的內容，請直接聯繫原文檔的維護者。如果你使用英文 +交流有困難的話，也可以向中文版維護者求助。如果本翻譯更新不及時或者翻 +譯存在問題，請聯繫中文版維護者。 + +英文版維護者： Will Deacon +中文版維護者： 傅煒 Fu Wei +中文版翻譯者： 傅煒 Fu Wei +中文版校譯者： 傅煒 Fu Wei +繁體中文版校譯者： 胡皓文 Hu Haowen + +以下爲正文 +--------------------------------------------------------------------- + Linux 在 AArch64 中帶標記的虛擬地址 + ================================= + +作者: Will Deacon +日期: 2013 年 06 月 12 日 + +本文檔簡述了在 AArch64 地址轉換系統中提供的帶標記的虛擬地址及其在 +AArch64 Linux 中的潛在用途。 + +內核提供的地址轉換表配置使通過 TTBR0 完成的虛擬地址轉換（即用戶空間 +映射），其虛擬地址的最高 8 位（63:56）會被轉換硬體所忽略。這種機制 +讓這些位可供應用程式自由使用，其注意事項如下： + + (1) 內核要求所有傳遞到 EL1 的用戶空間地址帶有 0x00 標記。 + 這意味著任何攜帶用戶空間虛擬地址的系統調用（syscall） + 參數 *必須* 在陷入內核前使它們的最高字節被清零。 + + (2) 非零標記在傳遞信號時不被保存。這意味著在應用程式中利用了 + 標記的信號處理函數無法依賴 siginfo_t 的用戶空間虛擬 + 地址所攜帶的包含其內部域信息的標記。此規則的一個例外是 + 當信號是在調試觀察點的異常處理程序中產生的，此時標記的 + 信息將被保存。 + + (3) 當使用帶標記的指針時需特別留心，因爲僅對兩個虛擬地址 + 的高字節，C 編譯器很可能無法判斷它們是不同的。 + +此構架會阻止對帶標記的 PC 指針的利用，因此在異常返回時，其高字節 +將被設置成一個爲 「55」 的擴展符。 + diff --git a/Documentation/translations/zh_TW/cpu-freq/core.rst b/Documentation/translations/zh_TW/cpu-freq/core.rst new file mode 100644 index 000000000..3d890c2f2 --- /dev/null +++ b/Documentation/translations/zh_TW/cpu-freq/core.rst @@ -0,0 +1,108 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../cpu-freq/core` +:Translator: Yanteng Si + Hu Haowen + +.. _tw_core.rst: + + +==================================== +CPUFreq核心和CPUFreq通知器的通用說明 +==================================== + +作者: + - Dominik Brodowski + - David Kimdon + - Rafael J. Wysocki + - Viresh Kumar + +.. 目錄: + + 1. CPUFreq核心和接口 + 2. CPUFreq通知器 + 3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 + +1. CPUFreq核心和接口 +====================== + +cpufreq核心代碼位於drivers/cpufreq/cpufreq.c中。這些cpufreq代碼爲CPUFreq架構的驅 +動程序（那些操作硬體切換頻率的代碼）以及 "通知器 "提供了一個標準化的接口。 +這些是設備驅動程序或需要了解策略變化的其它內核部分（如 ACPI 熱量管理）或所有頻率更改（除 +計時代碼外），甚至需要強制確定速度限制的通知器（如 ARM 架構上的 LCD 驅動程序）。 +此外， 內核 "常數" loops_per_jiffy會根據頻率變化而更新。 + +cpufreq策略的引用計數由 cpufreq_cpu_get 和 cpufreq_cpu_put 來完成，以確保 cpufreq 驅 +動程序被正確地註冊到核心中，並且驅動程序在 cpufreq_put_cpu 被調用之前不會被卸載。這也保證 +了每個CPU核的cpufreq 策略在使用期間不會被釋放。 + +2. CPUFreq 通知器 +==================== + +CPUFreq通知器符合標準的內核通知器接口。 +關於通知器的細節請參閱 linux/include/linux/notifier.h。 + +這裡有兩個不同的CPUfreq通知器 - 策略通知器和轉換通知器。 + + +2.1 CPUFreq策略通知器 +---------------------------- + +當創建或移除策略時，這些都會被通知。 + +階段是在通知器的第二個參數中指定的。當第一次創建策略時，階段是CPUFREQ_CREATE_POLICY，當 +策略被移除時，階段是CPUFREQ_REMOVE_POLICY。 + +第三個參數 ``void *pointer`` 指向一個結構體cpufreq_policy，其包括min，max(新策略的下限和 +上限（單位爲kHz）)這幾個值。 + + +2.2 CPUFreq轉換通知器 +-------------------------------- + +當CPUfreq驅動切換CPU核心頻率時，策略中的每個在線CPU都會收到兩次通知，這些變化沒有任何外部干 +預。 + +第二個參數指定階段 - CPUFREQ_PRECHANGE or CPUFREQ_POSTCHANGE. + +第三個參數是一個包含如下值的結構體cpufreq_freqs： + +===== ==================== +cpu 受影響cpu的編號 +old 舊頻率 +new 新頻率 +flags cpufreq驅動的標誌 +===== ==================== + +3. 含有Operating Performance Point (OPP)的CPUFreq表的生成 +================================================================== +關於OPP的細節請參閱 Documentation/power/opp.rst + +dev_pm_opp_init_cpufreq_table - + 這個功能提供了一個隨時可用的轉換程序，用來將OPP層關於可用頻率的內部信息翻譯成一種容易提供給 + cpufreq的格式。 + + .. Warning:: + + 不要在中斷上下文中使用此函數。 + + 例如:: + + soc_pm_init() + { + /* Do things */ + r = dev_pm_opp_init_cpufreq_table(dev, &freq_table); + if (!r) + policy->freq_table = freq_table; + /* Do other things */ + } + + .. note:: + + 該函數只有在CONFIG_PM_OPP之外還啓用了CONFIG_CPU_FREQ時才可用。 + +dev_pm_opp_free_cpufreq_table + 釋放dev_pm_opp_init_cpufreq_table分配的表。 + diff --git a/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst b/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst new file mode 100644 index 000000000..2bb8197cd --- /dev/null +++ b/Documentation/translations/zh_TW/cpu-freq/cpu-drivers.rst @@ -0,0 +1,256 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../cpu-freq/cpu-drivers` +:Translator: Yanteng Si + Hu Haowen + +.. _tw_cpu-drivers.rst: + + +======================================= +如何實現一個新的CPUFreq處理器驅動程序？ +======================================= + +作者: + + + - Dominik Brodowski + - Rafael J. Wysocki + - Viresh Kumar + +.. Contents + + 1. 怎麼做？ + 1.1 初始化 + 1.2 Per-CPU 初始化 + 1.3 驗證 + 1.4 target/target_index 或 setpolicy? + 1.5 target/target_index + 1.6 setpolicy + 1.7 get_intermediate 與 target_intermediate + 2. 頻率表助手 + + + +1. 怎麼做？ +=========== + +如此，你剛剛得到了一個全新的CPU/晶片組及其數據手冊，並希望爲這個CPU/晶片組添加cpufreq +支持？很好，這裡有一些至關重要的提示： + + +1.1 初始化 +---------- + +首先，在__initcall_level_7 (module_init())或更靠後的函數中檢查這個內核是否 +運行在正確的CPU和正確的晶片組上。如果是，則使用cpufreq_register_driver()向 +CPUfreq核心層註冊一個cpufreq_driver結構體。 + +結構體cpufreq_driver應該包含什麼成員? + + .name - 驅動的名字。 + + .init - 一個指向per-policy初始化函數的指針。 + + .verify - 一個指向"verification"函數的指針。 + + .setpolicy 或 .fast_switch 或 .target 或 .target_index - 差異見 + 下文。 + +並且可選擇 + + .flags - cpufreq核的提示。 + + .driver_data - cpufreq驅動程序的特定數據。 + + .get_intermediate 和 target_intermediate - 用於在改變CPU頻率時切換到穩定 + 的頻率。 + + .get - 返回CPU的當前頻率。 + + .bios_limit - 返回HW/BIOS對CPU的最大頻率限制值。 + + .exit - 一個指向per-policy清理函數的指針，該函數在cpu熱插拔過程的CPU_POST_DEAD + 階段被調用。 + + .suspend - 一個指向per-policy暫停函數的指針，該函數在關中斷且在該策略的調節器停止 + 後被調用。 + + .resume - 一個指向per-policy恢復函數的指針，該函數在關中斷且在調節器再一次開始前被 + 調用。 + + .ready - 一個指向per-policy準備函數的指針，該函數在策略完全初始化之後被調用。 + + .attr - 一個指向NULL結尾的"struct freq_attr"列表的指針，該函數允許導出值到 + sysfs。 + + .boost_enabled - 如果設置，則啓用提升(boost)頻率。 + + .set_boost - 一個指向per-policy函數的指針，該函數用來開啓/關閉提升(boost)頻率功能。 + + +1.2 Per-CPU 初始化 +------------------ + +每當一個新的CPU被註冊到設備模型中，或者在cpufreq驅動註冊自己之後，如果此CPU的cpufreq策 +略不存在，則會調用per-policy的初始化函數cpufreq_driver.init。請注意，.init()和.exit()程序 +只對策略調用一次，而不是對策略管理的每個CPU調用一次。它需要一個 ``struct cpufreq_policy +*policy`` 作爲參數。現在該怎麼做呢？ + +如果有必要，請在你的CPU上激活CPUfreq功能支持。 + +然後，驅動程序必須填寫以下數值: + ++-----------------------------------+--------------------------------------+ +|policy->cpuinfo.min_freq 和 | | +|policy->cpuinfo.max_freq | 該CPU支持的最低和最高頻率（kHz） | +| | | +| | | ++-----------------------------------+--------------------------------------+ +|policy->cpuinfo.transition_latency | | +| | CPU在兩個頻率之間切換所需的時間，以 | +| | 納秒爲單位（如適用，否則指定 | +| | CPUFREQ_ETERNAL） | ++-----------------------------------+--------------------------------------+ +|policy->cur | 該CPU當前的工作頻率(如適用) | +| | | ++-----------------------------------+--------------------------------------+ +|policy->min, | | +|policy->max, | | +|policy->policy and, if necessary, | | +|policy->governor | 必須包含該cpu的 「默認策略」。稍後 | +| | 會用這些值調用 | +| | cpufreq_driver.verify and either | +| | cpufreq_driver.setpolicy or | +| | cpufreq_driver.target/target_index | +| | | ++-----------------------------------+--------------------------------------+ +|policy->cpus | 用與這個CPU一起做DVFS的(在線+離線) | +| | CPU(即與它共享時鐘/電壓軌)的掩碼更新 | +| | 這個 | +| | | ++-----------------------------------+--------------------------------------+ + +對於設置其中的一些值(cpuinfo.min[max]_freq, policy->min[max])，頻率表助手可能會有幫 +助。關於它們的更多信息，請參見第2節。 + + +1.3 驗證 +-------- + +當用戶決定設置一個新的策略(由 「policy,governor,min,max組成」)時，必須對這個策略進行驗證， +以便糾正不兼容的值。爲了驗證這些值，cpufreq_verify_within_limits(``struct cpufreq_policy +*policy``, ``unsigned int min_freq``, ``unsigned int max_freq``)函數可能會有幫助。 +關於頻率表助手的詳細內容請參見第2節。 + +您需要確保至少有一個有效頻率（或工作範圍）在 policy->min 和 policy->max 範圍內。如果有必 +要，先增加policy->max，只有在沒有辦法的情況下，才減少policy->min。 + + +1.4 target 或 target_index 或 setpolicy 或 fast_switch? +------------------------------------------------------- + +大多數cpufreq驅動甚至大多數cpu頻率升降算法只允許將CPU頻率設置爲預定義的固定值。對於這些，你 +可以使用->target()，->target_index()或->fast_switch()回調。 + +有些cpufreq功能的處理器可以自己在某些限制之間切換頻率。這些應使用->setpolicy()回調。 + + +1.5. target/target_index +------------------------ + +target_index調用有兩個參數：``struct cpufreq_policy * policy``和``unsigned int`` +索引(於列出的頻率表)。 + +當調用這裡時，CPUfreq驅動必須設置新的頻率。實際頻率必須由freq_table[index].frequency決定。 + +它應該總是在錯誤的情況下恢復到之前的頻率(即policy->restore_freq)，即使我們之前切換到中間頻率。 + +已棄用 +---------- +目標調用有三個參數。``struct cpufreq_policy * policy``, unsigned int target_frequency, +unsigned int relation. + +CPUfreq驅動在調用這裡時必須設置新的頻率。實際的頻率必須使用以下規則來確定。 + +- 緊跟 "目標頻率"。 +- policy->min <= new_freq <= policy->max (這必須是有效的!!!) +- 如果 relation==CPUFREQ_REL_L，嘗試選擇一個高於或等於 target_freq 的 new_freq。("L代表 + 最低，但不能低於") +- 如果 relation==CPUFREQ_REL_H，嘗試選擇一個低於或等於 target_freq 的 new_freq。("H代表 + 最高，但不能高於") + +這裡，頻率表助手可能會幫助你--詳見第2節。 + +1.6. fast_switch +---------------- + +這個函數用於從調度器的上下文進行頻率切換。並非所有的驅動都要實現它，因爲不允許在這個回調中睡眠。這 +個回調必須經過高度優化，以儘可能快地進行切換。 + +這個函數有兩個參數： ``struct cpufreq_policy *policy`` 和 ``unsigned int target_frequency``。 + + +1.7 setpolicy +------------- + +setpolicy調用只需要一個``struct cpufreq_policy * policy``作爲參數。需要將處理器內或晶片組內動態頻 +率切換的下限設置爲policy->min，上限設置爲policy->max，如果支持的話，當policy->policy爲 +CPUFREQ_POLICY_PERFORMANCE時選擇面向性能的設置，當CPUFREQ_POLICY_POWERSAVE時選擇面向省電的設置。 +也可以查看drivers/cpufreq/longrun.c中的參考實現。 + +1.8 get_intermediate 和 target_intermediate +-------------------------------------------- + +僅適用於 target_index() 和 CPUFREQ_ASYNC_NOTIFICATION 未設置的驅動。 + +get_intermediate應該返回一個平台想要切換到的穩定的中間頻率，target_intermediate()應該將CPU設置爲 +該頻率，然後再跳轉到'index'對應的頻率。核心會負責發送通知，驅動不必在target_intermediate()或 +target_index()中處理。 + +在驅動程序不想因爲某個目標頻率切換到中間頻率的情況下，它們可以從get_intermediate()中返回'0'。在這種情況 +下，核心將直接調用->target_index()。 + +注意：->target_index()應該在失敗的情況下恢復到policy->restore_freq，因爲core會爲此發送通知。 + + +2. 頻率表助手 +============= + +由於大多數cpufreq處理器只允許被設置爲幾個特定的頻率，因此，一個帶有一些函數的 「頻率表」可能會輔助處理器驅動 +程序的一些工作。這樣的 "頻率表" 由一個cpufreq_frequency_table條目構成的數組組成，"driver_data" 中包 +含了驅動程序的具體數值，"frequency" 中包含了相應的頻率，並設置了標誌。在表的最後，需要添加一個 +cpufreq_frequency_table條目，頻率設置爲CPUFREQ_TABLE_END。而如果想跳過表中的一個條目，則將頻率設置爲 +CPUFREQ_ENTRY_INVALID。這些條目不需要按照任何特定的順序排序，但如果它們是cpufreq 核心會對它們進行快速的DVFS， +因爲搜索最佳匹配會更快。 + +如果策略在其policy->freq_table欄位中包含一個有效的指針，cpufreq表就會被核心自動驗證。 + +cpufreq_frequency_table_verify()保證至少有一個有效的頻率在policy->min和policy->max範圍內，並且所有其他 +標準都被滿足。這對->verify調用很有幫助。 + +cpufreq_frequency_table_target()是對應於->target階段的頻率表助手。只要把數值傳遞給這個函數，這個函數就會返 +回包含CPU要設置的頻率的頻率表條目。 + +以下宏可以作爲cpufreq_frequency_table的疊代器。 + +cpufreq_for_each_entry(pos, table) - 遍歷頻率表的所有條目。 + +cpufreq_for_each_valid_entry(pos, table) - 該函數遍歷所有條目，不包括CPUFREQ_ENTRY_INVALID頻率。 +使用參數 "pos"-一個``cpufreq_frequency_table * `` 作爲循環變量，使用參數 "table"-作爲你想疊代 +的``cpufreq_frequency_table * `` 。 + +例如:: + + struct cpufreq_frequency_table *pos, *driver_freq_table; + + cpufreq_for_each_entry(pos, driver_freq_table) { + /* Do something with pos */ + pos->frequency = ... + } + +如果你需要在driver_freq_table中處理pos的位置，不要減去指針，因爲它的代價相當高。相反，使用宏 +cpufreq_for_each_entry_idx() 和 cpufreq_for_each_valid_entry_idx() 。 + diff --git a/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst b/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst new file mode 100644 index 000000000..d80bfed50 --- /dev/null +++ b/Documentation/translations/zh_TW/cpu-freq/cpufreq-stats.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-zh_TW.rst + +:Original: :doc:`../../../cpu-freq/cpufreq-stats` +:Translator: Yanteng Si + Hu Haowen + +.. _tw_cpufreq-stats.rst: + + +========================================== +sysfs CPUFreq Stats的一般說明 +========================================== + +用戶信息 + + +作者: Venkatesh Pallipadi + +.. Contents + + 1. 簡介 + 2. 提供的統計數據(舉例說明) + 3. 配置cpufreq-stats + + +1. 簡介 +=============== + +cpufreq-stats是一個爲每個CPU提供CPU頻率統計的驅動。 +這些統計數據在/sysfs中以一堆只讀接口的形式提供。這個接口（在配置好後）將出現在 +/sysfs（/devices/system/cpu/cpuX/cpufreq/stats/）中cpufreq下的一個單 +獨的目錄中，提供給每個CPU。 +各種統計數據將在此目錄下形成只讀文件。 + +此驅動是獨立於任何可能運行在你所用CPU上的特定cpufreq_driver而設計的。因此，它將與所有 +cpufreq_driver一起工作。 + + +2. 提供的統計數據(舉例說明) +===================================== + +cpufreq stats提供了以下統計數據（在下面詳細解釋）。 + +- time_in_state +- total_trans +- trans_table + +所有的統計數據將從統計驅動被載入的時間（或統計被重置的時間）開始，到某一統計數據被讀取的時間爲止。 +顯然，統計驅動不會有任何關於統計驅動載入之前的頻率轉換信息。 + +:: + + :/sys/devices/system/cpu/cpu0/cpufreq/stats # ls -l + total 0 + drwxr-xr-x 2 root root 0 May 14 16:06 . + drwxr-xr-x 3 root root 0 May 14 15:58 .. + --w------- 1 root root 4096 May 14 16:06 reset + -r--r--r-- 1 root root 4096 May 14 16:06 time_in_state + -r--r--r-- 1 root root 4096 May 14 16:06 total_trans + -r--r--r-- 1 root root 4096 May 14 16:06 trans_table + +- **reset** + +只寫屬性，可用於重置統計計數器。這對於評估不同調節器下的系統行爲非常有用，且無需重啓。 + + +- **time_in_state** + +此項給出了這個CPU所支持的每個頻率所花費的時間。cat輸出的每一行都會有" +