aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLinus Torvalds2022-08-02 19:24:24 -0700
committerLinus Torvalds2022-08-02 19:24:24 -0700
commitaad26f55f47a33d6de3df65f0b18e2886059ed6d (patch)
treeb514fc4c702105ceaa37f423a39f4b0688cd63f7
parentb069122256e45216b5c49d9441f9713991a4c645 (diff)
parent339170d8d3da5685762619080263abb78700ab4c (diff)
Merge tag 'docs-6.0' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "This was a moderately busy cycle for documentation, but nothing all that earth-shaking: - More Chinese translations, and an update to the Italian translations. The Japanese, Korean, and traditional Chinese translations are more-or-less unmaintained at this point, instead. - Some build-system performance improvements. - The removal of the archaic submitting-drivers.rst document, with the movement of what useful material that remained into other docs. - Improvements to sphinx-pre-install to, hopefully, give more useful suggestions. - A number of build-warning fixes Plus the usual collection of typo fixes, updates, and more" * tag 'docs-6.0' of git://git.lwn.net/linux: (92 commits) docs: efi-stub: Fix paths for x86 / arm stubs Docs/zh_CN: Update the translation of sched-stats to 5.19-rc8 Docs/zh_CN: Update the translation of pci to 5.19-rc8 Docs/zh_CN: Update the translation of pci-iov-howto to 5.19-rc8 Docs/zh_CN: Update the translation of usage to 5.19-rc8 Docs/zh_CN: Update the translation of testing-overview to 5.19-rc8 Docs/zh_CN: Update the translation of sparse to 5.19-rc8 Docs/zh_CN: Update the translation of kasan to 5.19-rc8 Docs/zh_CN: Update the translation of iio_configfs to 5.19-rc8 doc:it_IT: align Italian documentation docs: Remove spurious tag from admin-guide/mm/overcommit-accounting.rst Documentation: process: Update email client instructions for Thunderbird docs: ABI: correct QEMU fw_cfg spec path doc/zh_CN: remove submitting-driver reference from docs docs: zh_TW: align to submitting-drivers removal docs: zh_CN: align to submitting-drivers removal docs: ko_KR: howto: remove reference to removed submitting-drivers docs: ja_JP: howto: remove reference to removed submitting-drivers docs: it_IT: align to submitting-drivers removal docs: process: remove outdated submitting-drivers.rst ...
-rw-r--r--Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg5
-rw-r--r--Documentation/Kconfig23
-rw-r--r--Documentation/admin-guide/devices.rst7
-rw-r--r--Documentation/admin-guide/efi-stub.rst4
-rw-r--r--Documentation/admin-guide/kernel-parameters.txt2
-rw-r--r--Documentation/admin-guide/sysctl/kernel.rst4
-rw-r--r--Documentation/arm64/elf_hwcaps.rst23
-rw-r--r--Documentation/dev-tools/coccinelle.rst2
-rw-r--r--Documentation/dev-tools/kselftest.rst27
-rw-r--r--Documentation/devicetree/bindings/input/da9062-onkey.txt2
-rw-r--r--Documentation/doc-guide/kernel-doc.rst2
-rw-r--r--Documentation/doc-guide/sphinx.rst14
-rw-r--r--Documentation/driver-api/gpio/consumer.rst2
-rw-r--r--Documentation/driver-api/gpio/driver.rst6
-rw-r--r--Documentation/driver-api/gpio/using-gpio.rst2
-rw-r--r--Documentation/driver-api/hte/tegra194-hte.rst5
-rw-r--r--Documentation/filesystems/f2fs.rst13
-rw-r--r--Documentation/filesystems/overlayfs.rst2
-rw-r--r--Documentation/hwmon/submitting-patches.rst1
-rw-r--r--Documentation/kernel-hacking/hacking.rst3
-rw-r--r--Documentation/process/5.Posting.rst3
-rw-r--r--Documentation/process/8.Conclusion.rst16
-rw-r--r--Documentation/process/email-clients.rst69
-rw-r--r--Documentation/process/howto.rst4
-rw-r--r--Documentation/process/index.rst1
-rw-r--r--Documentation/process/kernel-docs.rst62
-rw-r--r--Documentation/process/submitting-drivers.rst194
-rw-r--r--Documentation/process/submitting-patches.rst5
-rw-r--r--Documentation/security/keys/core.rst2
-rw-r--r--Documentation/security/secrets/coco.rst2
-rw-r--r--Documentation/security/siphash.rst2
-rw-r--r--Documentation/sphinx/automarkup.py56
-rw-r--r--Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst11
-rw-r--r--Documentation/translations/it_IT/doc-guide/kernel-doc.rst2
-rw-r--r--Documentation/translations/it_IT/doc-guide/sphinx.rst18
-rw-r--r--Documentation/translations/it_IT/kernel-hacking/hacking.rst27
-rw-r--r--Documentation/translations/it_IT/kernel-hacking/locking.rst14
-rw-r--r--Documentation/translations/it_IT/maintainer/configure-git.rst10
-rw-r--r--Documentation/translations/it_IT/networking/netdev-FAQ.rst2
-rw-r--r--Documentation/translations/it_IT/process/3.Early-stage.rst17
-rw-r--r--Documentation/translations/it_IT/process/5.Posting.rst32
-rw-r--r--Documentation/translations/it_IT/process/8.Conclusion.rst5
-rw-r--r--Documentation/translations/it_IT/process/changes.rst25
-rw-r--r--Documentation/translations/it_IT/process/coding-style.rst42
-rw-r--r--Documentation/translations/it_IT/process/deprecated.rst24
-rw-r--r--Documentation/translations/it_IT/process/howto.rst3
-rw-r--r--Documentation/translations/it_IT/process/index.rst2
-rw-r--r--Documentation/translations/it_IT/process/maintainer-handbooks.rst24
-rw-r--r--Documentation/translations/it_IT/process/maintainer-pgp-guide.rst14
-rw-r--r--Documentation/translations/it_IT/process/maintainer-tip.rst10
-rw-r--r--Documentation/translations/it_IT/process/maintainers.rst13
-rw-r--r--Documentation/translations/it_IT/process/stable-kernel-rules.rst42
-rw-r--r--Documentation/translations/it_IT/process/submitting-drivers.rst16
-rw-r--r--Documentation/translations/it_IT/process/submitting-patches.rst72
-rw-r--r--Documentation/translations/ja_JP/howto.rst4
-rw-r--r--Documentation/translations/ko_KR/howto.rst2
-rw-r--r--Documentation/translations/zh_CN/PCI/pci-iov-howto.rst7
-rw-r--r--Documentation/translations/zh_CN/PCI/pci.rst6
-rw-r--r--Documentation/translations/zh_CN/admin-guide/index.rst2
-rw-r--r--Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst2
-rw-r--r--Documentation/translations/zh_CN/admin-guide/reporting-issues.rst125
-rw-r--r--Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst370
-rw-r--r--Documentation/translations/zh_CN/core-api/cachetlb.rst6
-rw-r--r--Documentation/translations/zh_CN/core-api/cpu_hotplug.rst435
-rw-r--r--Documentation/translations/zh_CN/core-api/index.rst1
-rw-r--r--Documentation/translations/zh_CN/core-api/irq/irq-domain.rst22
-rw-r--r--Documentation/translations/zh_CN/core-api/kernel-api.rst3
-rw-r--r--Documentation/translations/zh_CN/core-api/mm-api.rst23
-rw-r--r--Documentation/translations/zh_CN/core-api/printk-basics.rst3
-rw-r--r--Documentation/translations/zh_CN/core-api/printk-formats.rst3
-rw-r--r--Documentation/translations/zh_CN/core-api/watch_queue.rst313
-rw-r--r--Documentation/translations/zh_CN/core-api/workqueue.rst21
-rw-r--r--Documentation/translations/zh_CN/core-api/xarray.rst4
-rw-r--r--Documentation/translations/zh_CN/dev-tools/kasan.rst117
-rw-r--r--Documentation/translations/zh_CN/dev-tools/sparse.rst2
-rw-r--r--Documentation/translations/zh_CN/dev-tools/testing-overview.rst25
-rw-r--r--Documentation/translations/zh_CN/devicetree/index.rst2
-rw-r--r--Documentation/translations/zh_CN/devicetree/of_unittest.rst2
-rw-r--r--Documentation/translations/zh_CN/devicetree/usage-model.rst2
-rw-r--r--Documentation/translations/zh_CN/doc-guide/kernel-doc.rst2
-rw-r--r--Documentation/translations/zh_CN/iio/iio_configfs.rst12
-rw-r--r--Documentation/translations/zh_CN/kernel-hacking/hacking.rst25
-rw-r--r--Documentation/translations/zh_CN/locking/index.rst5
-rw-r--r--Documentation/translations/zh_CN/locking/mutex-design.rst145
-rw-r--r--Documentation/translations/zh_CN/process/5.Posting.rst3
-rw-r--r--Documentation/translations/zh_CN/process/8.Conclusion.rst1
-rw-r--r--Documentation/translations/zh_CN/process/howto.rst1
-rw-r--r--Documentation/translations/zh_CN/process/index.rst1
-rw-r--r--Documentation/translations/zh_CN/process/submitting-drivers.rst160
-rw-r--r--Documentation/translations/zh_CN/process/submitting-patches.rst4
-rw-r--r--Documentation/translations/zh_CN/riscv/index.rst1
-rw-r--r--Documentation/translations/zh_CN/riscv/pmu.rst235
-rw-r--r--Documentation/translations/zh_CN/riscv/vm-layout.rst37
-rw-r--r--Documentation/translations/zh_CN/scheduler/sched-stats.rst8
-rw-r--r--Documentation/translations/zh_CN/vm/free_page_reporting.rst2
-rw-r--r--Documentation/translations/zh_CN/vm/frontswap.rst2
-rw-r--r--Documentation/translations/zh_CN/vm/highmem.rst77
-rw-r--r--Documentation/translations/zh_CN/vm/index.rst31
-rw-r--r--Documentation/translations/zh_CN/vm/page_frags.rst2
-rw-r--r--Documentation/translations/zh_CN/vm/page_migration.rst228
-rw-r--r--Documentation/translations/zh_CN/vm/page_owner.rst79
-rw-r--r--Documentation/translations/zh_CN/vm/vmalloced-kernel-stacks.rst133
-rw-r--r--Documentation/translations/zh_CN/vm/zsmalloc.rst2
-rw-r--r--Documentation/translations/zh_TW/process/5.Posting.rst3
-rw-r--r--Documentation/translations/zh_TW/process/8.Conclusion.rst1
-rw-r--r--Documentation/translations/zh_TW/process/howto.rst1
-rw-r--r--Documentation/translations/zh_TW/process/index.rst1
-rw-r--r--Documentation/translations/zh_TW/process/submitting-drivers.rst164
-rw-r--r--Documentation/translations/zh_TW/process/submitting-patches.rst4
-rw-r--r--Documentation/virt/hyperv/clocks.rst73
-rw-r--r--Documentation/virt/hyperv/index.rst12
-rw-r--r--Documentation/virt/hyperv/overview.rst207
-rw-r--r--Documentation/virt/hyperv/vmbus.rst303
-rw-r--r--Documentation/virt/index.rst1
-rw-r--r--Documentation/virt/kvm/api.rst4
-rw-r--r--Documentation/virt/kvm/s390/s390-pv-boot.rst2
-rw-r--r--Documentation/virt/kvm/x86/hypercalls.rst2
-rw-r--r--Documentation/virt/uml/user_mode_linux_howto_v2.rst2
-rw-r--r--Documentation/vm/overcommit-accounting.rst2
-rw-r--r--Documentation/x86/orc-unwinder.rst2
-rw-r--r--MAINTAINERS7
-rw-r--r--arch/m68k/q40/README5
-rw-r--r--include/linux/fscache.h2
-rw-r--r--include/linux/objtool.h2
-rw-r--r--include/linux/watch_queue.h2
-rw-r--r--init/Kconfig2
-rw-r--r--kernel/watch_queue.c2
-rw-r--r--lib/Kconfig.debug2
-rwxr-xr-xscripts/get_feat.pl2
-rwxr-xr-xscripts/kernel-doc82
-rwxr-xr-xscripts/sphinx-pre-install90
-rw-r--r--tools/include/linux/objtool.h2
-rw-r--r--tools/objtool/check.c2
133 files changed, 3274 insertions, 1400 deletions
diff --git a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
index ee0d6dbc810e..54d1bfd0db12 100644
--- a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
+++ b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
@@ -12,8 +12,9 @@ Description:
configuration data to the guest userspace.
The authoritative guest-side hardware interface documentation
- to the fw_cfg device can be found in "docs/specs/fw_cfg.txt"
- in the QEMU source tree.
+ to the fw_cfg device can be found in "docs/specs/fw_cfg.rst"
+ in the QEMU source tree, or online at:
+ https://qemu-project.gitlab.io/qemu/specs/fw_cfg.html
**SysFS fw_cfg Interface**
diff --git a/Documentation/Kconfig b/Documentation/Kconfig
index e549a61f4d96..252bfc164dbd 100644
--- a/Documentation/Kconfig
+++ b/Documentation/Kconfig
@@ -1,23 +1,22 @@
config WARN_MISSING_DOCUMENTS
-
bool "Warn if there's a missing documentation file"
depends on COMPILE_TEST
help
- It is not uncommon that a document gets renamed.
- This option makes the Kernel to check for missing dependencies,
- warning when something is missing. Works only if the Kernel
- is built from a git tree.
+ It is not uncommon that a document gets renamed.
+ This option makes the Kernel to check for missing dependencies,
+ warning when something is missing. Works only if the Kernel
+ is built from a git tree.
- If unsure, select 'N'.
+ If unsure, select 'N'.
config WARN_ABI_ERRORS
bool "Warn if there are errors at ABI files"
depends on COMPILE_TEST
help
- The files under Documentation/ABI should follow what's
- described at Documentation/ABI/README. Yet, as they're manually
- written, it would be possible that some of those files would
- have errors that would break them for being parsed by
- scripts/get_abi.pl. Add a check to verify them.
+ The files under Documentation/ABI should follow what's
+ described at Documentation/ABI/README. Yet, as they're manually
+ written, it would be possible that some of those files would
+ have errors that would break them for being parsed by
+ scripts/get_abi.pl. Add a check to verify them.
- If unsure, select 'N'.
+ If unsure, select 'N'.
diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst
index 035275fedbdd..e3776d77374b 100644
--- a/Documentation/admin-guide/devices.rst
+++ b/Documentation/admin-guide/devices.rst
@@ -7,10 +7,9 @@ This list is the Linux Device List, the official registry of allocated
device numbers and ``/dev`` directory nodes for the Linux operating
system.
-The LaTeX version of this document is no longer maintained, nor is
-the document that used to reside at lanana.org. This version in the
-mainline Linux kernel is the master document. Updates shall be sent
-as patches to the kernel maintainers (see the
+The version of this document at lanana.org is no longer maintained. This
+version in the mainline Linux kernel is the master document. Updates
+shall be sent as patches to the kernel maintainers (see the
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` document).
Specifically explore the sections titled "CHAR and MISC DRIVERS", and
"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers
diff --git a/Documentation/admin-guide/efi-stub.rst b/Documentation/admin-guide/efi-stub.rst
index 833edb0d0bc4..b24e7c40d832 100644
--- a/Documentation/admin-guide/efi-stub.rst
+++ b/Documentation/admin-guide/efi-stub.rst
@@ -7,10 +7,10 @@ as a PE/COFF image, thereby convincing EFI firmware loaders to load
it as an EFI executable. The code that modifies the bzImage header,
along with the EFI-specific entry point that the firmware loader
jumps to are collectively known as the "EFI boot stub", and live in
-arch/x86/boot/header.S and arch/x86/boot/compressed/eboot.c,
+arch/x86/boot/header.S and drivers/firmware/efi/libstub/x86-stub.c,
respectively. For ARM the EFI stub is implemented in
arch/arm/boot/compressed/efi-header.S and
-arch/arm/boot/compressed/efi-stub.c. EFI stub code that is shared
+drivers/firmware/efi/libstub/arm32-stub.c. EFI stub code that is shared
between architectures is in drivers/firmware/efi/libstub.
For arm64, there is no compressed kernel support, so the Image itself
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index df9a5b60ee46..0e990f7c2aa3 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -3109,7 +3109,7 @@
mem_encrypt=on: Activate SME
mem_encrypt=off: Do not activate SME
- Refer to Documentation/virt/kvm/amd-memory-encryption.rst
+ Refer to Documentation/virt/kvm/x86/amd-memory-encryption.rst
for details on when memory encryption can be activated.
mem_sleep_default= [SUSPEND] Default system suspend mode:
diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst
index ddccd1077462..8ab042beeb76 100644
--- a/Documentation/admin-guide/sysctl/kernel.rst
+++ b/Documentation/admin-guide/sysctl/kernel.rst
@@ -38,8 +38,8 @@ acct
If BSD-style process accounting is enabled these values control
its behaviour. If free space on filesystem where the log lives
-goes below ``lowwater``% accounting suspends. If free space gets
-above ``highwater``% accounting resumes. ``frequency`` determines
+goes below ``lowwater``\ % accounting suspends. If free space gets
+above ``highwater``\ % accounting resumes. ``frequency`` determines
how often do we check the amount of free space (value is in
seconds). Default:
diff --git a/Documentation/arm64/elf_hwcaps.rst b/Documentation/arm64/elf_hwcaps.rst
index 31fc10b833dd..52b75a25c205 100644
--- a/Documentation/arm64/elf_hwcaps.rst
+++ b/Documentation/arm64/elf_hwcaps.rst
@@ -171,96 +171,73 @@ HWCAP_PACG
Documentation/arm64/pointer-authentication.rst.
HWCAP2_DCPODP
-
Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0010.
HWCAP2_SVE2
-
Functionality implied by ID_AA64ZFR0_EL1.SVEVer == 0b0001.
HWCAP2_SVEAES
-
Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0001.
HWCAP2_SVEPMULL
-
Functionality implied by ID_AA64ZFR0_EL1.AES == 0b0010.
HWCAP2_SVEBITPERM
-
Functionality implied by ID_AA64ZFR0_EL1.BitPerm == 0b0001.
HWCAP2_SVESHA3
-
Functionality implied by ID_AA64ZFR0_EL1.SHA3 == 0b0001.
HWCAP2_SVESM4
-
Functionality implied by ID_AA64ZFR0_EL1.SM4 == 0b0001.
HWCAP2_FLAGM2
-
Functionality implied by ID_AA64ISAR0_EL1.TS == 0b0010.
HWCAP2_FRINT
-
Functionality implied by ID_AA64ISAR1_EL1.FRINTTS == 0b0001.
HWCAP2_SVEI8MM
-
Functionality implied by ID_AA64ZFR0_EL1.I8MM == 0b0001.
HWCAP2_SVEF32MM
-
Functionality implied by ID_AA64ZFR0_EL1.F32MM == 0b0001.
HWCAP2_SVEF64MM
-
Functionality implied by ID_AA64ZFR0_EL1.F64MM == 0b0001.
HWCAP2_SVEBF16
-
Functionality implied by ID_AA64ZFR0_EL1.BF16 == 0b0001.
HWCAP2_I8MM
-
Functionality implied by ID_AA64ISAR1_EL1.I8MM == 0b0001.
HWCAP2_BF16
-
Functionality implied by ID_AA64ISAR1_EL1.BF16 == 0b0001.
HWCAP2_DGH
-
Functionality implied by ID_AA64ISAR1_EL1.DGH == 0b0001.
HWCAP2_RNG
-
Functionality implied by ID_AA64ISAR0_EL1.RNDR == 0b0001.
HWCAP2_BTI
-
Functionality implied by ID_AA64PFR0_EL1.BT == 0b0001.
HWCAP2_MTE
-
Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0010, as described
by Documentation/arm64/memory-tagging-extension.rst.
HWCAP2_ECV
-
Functionality implied by ID_AA64MMFR0_EL1.ECV == 0b0001.
HWCAP2_AFP
-
Functionality implied by ID_AA64MFR1_EL1.AFP == 0b0001.
HWCAP2_RPRES
-
Functionality implied by ID_AA64ISAR2_EL1.RPRES == 0b0001.
HWCAP2_MTE3
-
Functionality implied by ID_AA64PFR1_EL1.MTE == 0b0011, as described
by Documentation/arm64/memory-tagging-extension.rst.
diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst
index 9c454de5a7f7..d9976069ed12 100644
--- a/Documentation/dev-tools/coccinelle.rst
+++ b/Documentation/dev-tools/coccinelle.rst
@@ -66,7 +66,7 @@ The wiki documentation always refers to the linux-next version of the script.
For Semantic Patch Language(SmPL) grammar documentation refer to:
-http://coccinelle.lip6.fr/documentation.php
+https://coccinelle.gitlabpages.inria.fr/website/docs/main_grammar.html
Using Coccinelle on the Linux kernel
------------------------------------
diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst
index a833ecf12fbc..ee6467ca8293 100644
--- a/Documentation/dev-tools/kselftest.rst
+++ b/Documentation/dev-tools/kselftest.rst
@@ -208,6 +208,14 @@ In general, the rules for selftests are
Contributing new tests (details)
================================
+ * In your Makefile, use facilities from lib.mk by including it instead of
+ reinventing the wheel. Specify flags and binaries generation flags on
+ need basis before including lib.mk. ::
+
+ CFLAGS = $(KHDR_INCLUDES)
+ TEST_GEN_PROGS := close_range_test
+ include ../lib.mk
+
* Use TEST_GEN_XXX if such binaries or files are generated during
compiling.
@@ -230,13 +238,30 @@ Contributing new tests (details)
* First use the headers inside the kernel source and/or git repo, and then the
system headers. Headers for the kernel release as opposed to headers
installed by the distro on the system should be the primary focus to be able
- to find regressions.
+ to find regressions. Use KHDR_INCLUDES in Makefile to include headers from
+ the kernel source.
* If a test needs specific kernel config options enabled, add a config file in
the test directory to enable them.
e.g: tools/testing/selftests/android/config
+ * Create a .gitignore file inside test directory and add all generated objects
+ in it.
+
+ * Add new test name in TARGETS in selftests/Makefile::
+
+ TARGETS += android
+
+ * All changes should pass::
+
+ kselftest-{all,install,clean,gen_tar}
+ kselftest-{all,install,clean,gen_tar} O=abo_path
+ kselftest-{all,install,clean,gen_tar} O=rel_path
+ make -C tools/testing/selftests {all,install,clean,gen_tar}
+ make -C tools/testing/selftests {all,install,clean,gen_tar} O=abs_path
+ make -C tools/testing/selftests {all,install,clean,gen_tar} O=rel_path
+
Test Module
===========
diff --git a/Documentation/devicetree/bindings/input/da9062-onkey.txt b/Documentation/devicetree/bindings/input/da9062-onkey.txt
index 5f9fbc68e58a..e5eef59a93dc 100644
--- a/Documentation/devicetree/bindings/input/da9062-onkey.txt
+++ b/Documentation/devicetree/bindings/input/da9062-onkey.txt
@@ -2,7 +2,7 @@
This module is part of the DA9061/DA9062/DA9063. For more details about entire
DA9062 and DA9061 chips see Documentation/devicetree/bindings/mfd/da9062.txt
-For DA9063 see Documentation/devicetree/bindings/mfd/da9063.txt
+For DA9063 see Documentation/devicetree/bindings/mfd/dlg,da9063.yaml
This module provides the KEY_POWER event.
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index a7cb2afd7990..9c779bd7a751 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -1,3 +1,5 @@
+.. title:: Kernel-doc comments
+
===========================
Writing kernel-doc comments
===========================
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 2ff1ab4158d4..1228b85f6f77 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -132,7 +132,8 @@ format-specific subdirectories under ``Documentation/output``.
To generate documentation, Sphinx (``sphinx-build``) must obviously be
installed. For prettier HTML output, the Read the Docs Sphinx theme
(``sphinx_rtd_theme``) is used if available. For PDF output you'll also need
-``XeLaTeX`` and ``convert(1)`` from ImageMagick (https://www.imagemagick.org).
+``XeLaTeX`` and ``convert(1)`` from ImageMagick
+(https://www.imagemagick.org).\ [#ink]_
All of these are widely available and packaged in distributions.
To pass extra options to Sphinx, you can use the ``SPHINXOPTS`` make
@@ -150,8 +151,19 @@ If the theme is not available, it will fall-back to the classic one.
The Sphinx theme can be overridden by using the ``DOCS_THEME`` make variable.
+There is another make variable ``SPHINXDIRS``, which is useful when test
+building a subset of documentation. For example, you can build documents
+under ``Documentation/doc-guide`` by running
+``make SPHINXDIRS=doc-guide htmldocs``.
+The documentation section of ``make help`` will show you the list of
+subdirectories you can specify.
+
To remove the generated documentation, run ``make cleandocs``.
+.. [#ink] Having ``inkscape(1)`` from Inkscape (https://inkscape.org)
+ as well would improve the quality of images embedded in PDF
+ documents, especially for kernel releases 5.18 and later.
+
Writing Documentation
=====================
diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst
index 72bcf5f5e3a2..de6fc79ad6f0 100644
--- a/Documentation/driver-api/gpio/consumer.rst
+++ b/Documentation/driver-api/gpio/consumer.rst
@@ -114,7 +114,7 @@ For a function using multiple GPIOs all of those can be obtained with one call::
This function returns a struct gpio_descs which contains an array of
descriptors. It also contains a pointer to a gpiolib private structure which,
-if passed back to get/set array functions, may speed up I/O proocessing::
+if passed back to get/set array functions, may speed up I/O processing::
struct gpio_descs {
struct gpio_array *info;
diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 70ff43ac4fcc..6baaeab79534 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -119,7 +119,7 @@ GPIO lines with debounce support
Debouncing is a configuration set to a pin indicating that it is connected to
a mechanical switch or button, or similar that may bounce. Bouncing means the
line is pulled high/low quickly at very short intervals for mechanical
-reasons. This can result in the value being unstable or irqs fireing repeatedly
+reasons. This can result in the value being unstable or irqs firing repeatedly
unless the line is debounced.
Debouncing in practice involves setting up a timer when something happens on
@@ -219,7 +219,7 @@ use a trick: when a line is set as output, if the line is flagged as open
drain, and the IN output value is low, it will be driven low as usual. But
if the IN output value is set to high, it will instead *NOT* be driven high,
instead it will be switched to input, as input mode is high impedance, thus
-achieveing an "open drain emulation" of sorts: electrically the behaviour will
+achieving an "open drain emulation" of sorts: electrically the behaviour will
be identical, with the exception of possible hardware glitches when switching
the mode of the line.
@@ -642,7 +642,7 @@ In this case the typical set-up will look like this:
As you can see pretty similar, but you do not supply a parent handler for
the IRQ, instead a parent irqdomain, an fwnode for the hardware and
-a funcion .child_to_parent_hwirq() that has the purpose of looking up
+a function .child_to_parent_hwirq() that has the purpose of looking up
the parent hardware irq from a child (i.e. this gpio chip) hardware irq.
As always it is good to look at examples in the kernel tree for advice
on how to find the required pieces.
diff --git a/Documentation/driver-api/gpio/using-gpio.rst b/Documentation/driver-api/gpio/using-gpio.rst
index 64c8d3f76c3a..894d88855d73 100644
--- a/Documentation/driver-api/gpio/using-gpio.rst
+++ b/Documentation/driver-api/gpio/using-gpio.rst
@@ -44,7 +44,7 @@ These devices will appear on the system as ``/dev/gpiochip0`` thru
found in the kernel tree ``tools/gpio`` subdirectory.
For structured and managed applications, we recommend that you make use of the
-libgpiod_ library. This provides helper abstractions, command line utlities
+libgpiod_ library. This provides helper abstractions, command line utilities
and arbitration for multiple simultaneous consumers on the same GPIO chip.
.. _libgpiod: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/
diff --git a/Documentation/driver-api/hte/tegra194-hte.rst b/Documentation/driver-api/hte/tegra194-hte.rst
index 41983e04d2a0..f2d617265546 100644
--- a/Documentation/driver-api/hte/tegra194-hte.rst
+++ b/Documentation/driver-api/hte/tegra194-hte.rst
@@ -25,8 +25,7 @@ and userspace consumers. The kernel space consumers can directly talk to HTE
subsystem while userspace consumers timestamp requests go through GPIOLIB CDEV
framework to HTE subsystem.
-.. kernel-doc:: drivers/gpio/gpiolib.c
- :functions: gpiod_enable_hw_timestamp_ns gpiod_disable_hw_timestamp_ns
+See gpiod_enable_hw_timestamp_ns() and gpiod_disable_hw_timestamp_ns().
For userspace consumers, GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE flag must be
specified during IOCTL calls. Refer to ``tools/gpio/gpio-event-mon.c``, which
@@ -37,7 +36,7 @@ LIC (Legacy Interrupt Controller) IRQ GTE
This GTE instance timestamps LIC IRQ lines in real time. There are 352 IRQ
lines which this instance can add timestamps to in real time. The hte
-devicetree binding described at ``Documentation/devicetree/bindings/hte/``
+devicetree binding described at ``Documentation/devicetree/bindings/timestamp``
provides an example of how a consumer can request an IRQ line. Since it is a
one-to-one mapping with IRQ GTE provider, consumers can simply specify the IRQ
number that they are interested in. There is no userspace consumer support for
diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst
index ad8dc8c040a2..98dc24f5c6f0 100644
--- a/Documentation/filesystems/f2fs.rst
+++ b/Documentation/filesystems/f2fs.rst
@@ -818,10 +818,11 @@ Compression implementation
Instead, the main goal is to reduce data writes to flash disk as much as
possible, resulting in extending disk life time as well as relaxing IO
congestion. Alternatively, we've added ioctl(F2FS_IOC_RELEASE_COMPRESS_BLOCKS)
- interface to reclaim compressed space and show it to user after putting the
- immutable bit. Immutable bit, after release, it doesn't allow writing/mmaping
- on the file, until reserving compressed space via
- ioctl(F2FS_IOC_RESERVE_COMPRESS_BLOCKS) or truncating filesize to zero.
+ interface to reclaim compressed space and show it to user after setting a
+ special flag to the inode. Once the compressed space is released, the flag
+ will block writing data to the file until either the compressed space is
+ reserved via ioctl(F2FS_IOC_RESERVE_COMPRESS_BLOCKS) or the file size is
+ truncated to zero.
Compress metadata layout::
@@ -830,12 +831,12 @@ Compress metadata layout::
| cluster 1 | cluster 2 | ......... | cluster N |
+-----------------------------------------------+
. . . .
- . . . .
+ . . . .
. Compressed Cluster . . Normal Cluster .
+----------+---------+---------+---------+ +---------+---------+---------+---------+
|compr flag| block 1 | block 2 | block 3 | | block 1 | block 2 | block 3 | block 4 |
+----------+---------+---------+---------+ +---------+---------+---------+---------+
- . .
+ . .
. .
. .
+-------------+-------------+----------+----------------------------+
diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst
index 7da6c30ed596..4c76fda07645 100644
--- a/Documentation/filesystems/overlayfs.rst
+++ b/Documentation/filesystems/overlayfs.rst
@@ -607,7 +607,7 @@ can be removed.
User xattr
----------
-The the "-o userxattr" mount option forces overlayfs to use the
+The "-o userxattr" mount option forces overlayfs to use the
"user.overlay." xattr namespace instead of "trusted.overlay.". This is
useful for unprivileged mounting of overlayfs.
diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst
index 9a218ea996d8..d953ee763c96 100644
--- a/Documentation/hwmon/submitting-patches.rst
+++ b/Documentation/hwmon/submitting-patches.rst
@@ -12,7 +12,6 @@ increase the chances of your change being accepted.
* It should be unnecessary to mention, but please read and follow:
- Documentation/process/submit-checklist.rst
- - Documentation/process/submitting-drivers.rst
- Documentation/process/submitting-patches.rst
- Documentation/process/coding-style.rst
diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
index ebd9d90882ea..9a1f020c8449 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -755,8 +755,7 @@ make a neat patch, there's administrative work to be done:
it implies a more-than-passing commitment to some part of the code.
- Finally, don't forget to read
- ``Documentation/process/submitting-patches.rst`` and possibly
- ``Documentation/process/submitting-drivers.rst``.
+ ``Documentation/process/submitting-patches.rst``
Kernel Cantrips
===============
diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
index bd36ecb29409..906235c11c24 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -10,8 +10,7 @@ of conventions and procedures which are used in the posting of patches;
following them will make life much easier for everybody involved. This
document will attempt to cover these expectations in reasonable detail;
more information can also be found in the files
-:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`,
-:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
+:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst
index b32a40215858..8c847dffe76b 100644
--- a/Documentation/process/8.Conclusion.rst
+++ b/Documentation/process/8.Conclusion.rst
@@ -5,15 +5,13 @@ For more information
There are numerous sources of information on Linux kernel development and
related topics. First among those will always be the Documentation
-directory found in the kernel source distribution. The top-level :ref:`process/howto.rst <process_howto>`
-file is an important starting point; :ref:`process/submitting-patches.rst <submittingpatches>`
-and :ref:`process/submitting-drivers.rst <submittingdrivers>`
-are also something which all kernel developers should
-read. Many internal kernel APIs are documented using the kerneldoc
-mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those
-documents in HTML or PDF format (though the version of TeX shipped by some
-distributions runs into internal limits and fails to process the documents
-properly).
+directory found in the kernel source distribution. Start with the
+top-level :ref:`process/howto.rst <process_howto>`; also read
+:ref:`process/submitting-patches.rst <submittingpatches>`. Many internal
+kernel APIs are documented using the kerneldoc mechanism; "make htmldocs"
+or "make pdfdocs" can be used to generate those documents in HTML or PDF
+format (though the version of TeX shipped by some distributions runs into
+internal limits and fails to process the documents properly).
Various web sites discuss kernel development at all levels of detail. Your
author would like to humbly suggest https://lwn.net/ as a source;
diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst
index 16586f6cc888..fc2c46f3f82d 100644
--- a/Documentation/process/email-clients.rst
+++ b/Documentation/process/email-clients.rst
@@ -277,36 +277,61 @@ Thunderbird (GUI)
Thunderbird is an Outlook clone that likes to mangle text, but there are ways
to coerce it into behaving.
+After doing the modifications, this includes installing the extensions,
+you need to restart Thunderbird.
+
- Allow use of an external editor:
- The easiest thing to do with Thunderbird and patches is to use an
- "external editor" extension and then just use your favorite ``$EDITOR``
- for reading/merging patches into the body text. To do this, download
- and install the extension, then add a button for it using
- :menuselection:`View-->Toolbars-->Customize...` and finally just click on it
- when in the :menuselection:`Compose` dialog.
-
- Please note that "external editor" requires that your editor must not
- fork, or in other words, the editor must not return before closing.
- You may have to pass additional flags or change the settings of your
- editor. Most notably if you are using gvim then you must pass the -f
- option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in
- ``/usr/bin``) to the text editor field in :menuselection:`external editor`
- settings. If you are using some other editor then please read its manual
- to find out how to do this.
+
+ The easiest thing to do with Thunderbird and patches is to use extensions
+ which open your favorite external editor.
+
+ Here are some example extensions which are capable of doing this.
+
+ - "External Editor Revived"
+
+ https://github.com/Frederick888/external-editor-revived
+
+ https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/
+
+ It requires installing a "native messaging host".
+ Please read the wiki which can be found here:
+ https://github.com/Frederick888/external-editor-revived/wiki
+
+ - "External Editor"
+
+ https://github.com/exteditor/exteditor
+
+ To do this, download and install the extension, then open the
+ :menuselection:`compose` window, add a button for it using
+ :menuselection:`View-->Toolbars-->Customize...`
+ then just click on the new button when you wish to use the external editor.
+
+ Please note that "External Editor" requires that your editor must not
+ fork, or in other words, the editor must not return before closing.
+ You may have to pass additional flags or change the settings of your
+ editor. Most notably if you are using gvim then you must pass the -f
+ option to gvim by putting ``/usr/bin/gvim --nofork"`` (if the binary is in
+ ``/usr/bin``) to the text editor field in :menuselection:`external editor`
+ settings. If you are using some other editor then please read its manual
+ to find out how to do this.
To beat some sense out of the internal editor, do this:
-- Edit your Thunderbird config settings so that it won't use ``format=flowed``.
- Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up
- the thunderbird's registry editor.
+- Edit your Thunderbird config settings so that it won't use ``format=flowed``!
+ Go to your main window and find the button for your main dropdown menu.
+ :menuselection:`Main Menu-->Preferences-->General-->Config Editor...`
+ to bring up the thunderbird's registry editor.
-- Set ``mailnews.send_plaintext_flowed`` to ``false``
+ - Set ``mailnews.send_plaintext_flowed`` to ``false``
-- Set ``mailnews.wraplength`` from ``72`` to ``0``
+ - Set ``mailnews.wraplength`` from ``72`` to ``0``
-- :menuselection:`View-->Message Body As-->Plain Text`
+- Don't write HTML messages! Go to the main window
+ :menuselection:`Main Menu-->Account Settings-->youracc@server.something-->Composition & Addressing`!
+ There you can disable the option "Compose messages in HTML format".
-- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)`
+- Open messages only as plain text! Go to the main window
+ :menuselection:`Main Menu-->View-->Message Body As-->Plain Text`!
TkRat (GUI)
***********
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index e4beeca57e5f..cd6997a9d203 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -105,8 +105,8 @@ required reading:
patches if these rules are followed, and many people will only
review code if it is in the proper style.
- :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
- These files describe in explicit detail how to successfully create
+ :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
+ This file describes in explicit detail how to successfully create
and send a patch, including (but not limited to):
- Email contents
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 3587dae4d0ef..2ba2a1582bbe 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -40,7 +40,6 @@ Other guides to the community that are of interest to most developers are:
:maxdepth: 1
changes
- submitting-drivers
stable-api-nonsense
management-style
stable-kernel-rules
diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
index da9527502ef0..502289d63385 100644
--- a/Documentation/process/kernel-docs.rst
+++ b/Documentation/process/kernel-docs.rst
@@ -1,9 +1,10 @@
.. _kernel_docs:
-Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel
-=============================================================================================
+Index of Further Kernel Documentation
+=====================================
- Juan-Mariano de Goyeneche <jmseyas@dit.upm.es>
+Initial Author: Juan-Mariano de Goyeneche (<jmseyas@dit.upm.es>;
+email address is defunct now.)
The need for a document like this one became apparent in the
linux-kernel mailing list as the same questions, asking for pointers
@@ -16,21 +17,16 @@ philosophy and design decisions behind this code.
Unfortunately, not many documents are available for beginners to
start. And, even if they exist, there was no "well-known" place which
-kept track of them. These lines try to cover this lack. All documents
-available on line known by the author are listed, while some reference
-books are also mentioned.
+kept track of them. These lines try to cover this lack.
PLEASE, if you know any paper not listed here or write a new document,
-send me an e-mail, and I'll include a reference to it here. Any
-corrections, ideas or comments are also welcomed.
+include a reference to it here, following the kernel's patch submission
+process. Any corrections, ideas or comments are also welcome.
-The papers that follow are listed in no particular order. All are
-cataloged with the following fields: the document's "Title", the
-"Author"/s, the "URL" where they can be found, some "Keywords" helpful
-when searching for specific topics, and a brief "Description" of the
-Document.
-
-Enjoy!
+All documents are cataloged with the following fields: the document's
+"Title", the "Author"/s, the "URL" where they can be found, some
+"Keywords" helpful when searching for specific topics, and a brief
+"Description" of the Document.
.. note::
@@ -83,6 +79,18 @@ On-line docs
Finally this trace-log is used as base for more a exact conceptual
exploration and description of the Linux TCP/IP implementation.*
+ * Title: **The Linux Kernel Module Programming Guide**
+
+ :Author: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram,
+ Jim Huang.
+ :URL: https://sysprog21.github.io/lkmpg/
+ :Date: 2021
+ :Keywords: modules, GPL book, /proc, ioctls, system calls,
+ interrupt handlers .
+ :Description: A very nice GPL book on the topic of modules
+ programming. Lots of examples. Currently the new version is being
+ actively maintained at https://github.com/sysprog21/lkmpg.
+
* Title: **On submitting kernel Patches**
:Author: Andi Kleen
@@ -126,17 +134,19 @@ On-line docs
describes how to write user-mode utilities for communicating with
Card Services.
- * Title: **The Linux Kernel Module Programming Guide**
-
- :Author: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram,
- Jim Huang.
- :URL: https://sysprog21.github.io/lkmpg/
- :Date: 2021
- :Keywords: modules, GPL book, /proc, ioctls, system calls,
- interrupt handlers .
- :Description: A very nice GPL book on the topic of modules
- programming. Lots of examples. Currently the new version is being
- actively maintained at https://github.com/sysprog21/lkmpg.
+ * Title: **How NOT to write kernel drivers**
+
+ :Author: Arjan van de Ven.
+ :URL: https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf
+ :Date: 2002
+ :Keywords: driver.
+ :Description: Programming bugs and Do-nots in kernel driver development
+ :Abstract: *Quit a few tutorials, articles and books give an introduction
+ on how to write Linux kernel drivers. Unfortunately the things one
+ should NOT do in Linux kernel code is either only a minor appendix
+ or, more commonly, completely absent. This paper tries to briefly touch
+ the areas in which the most common and serious bugs and do-nots are
+ encountered.*
* Title: **Global spinlock list and usage**
diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
deleted file mode 100644
index 8413b693d10d..000000000000
--- a/Documentation/process/submitting-drivers.rst
+++ /dev/null
@@ -1,194 +0,0 @@
-.. _submittingdrivers:
-
-Submitting Drivers For The Linux Kernel
-=======================================
-
-This document is intended to explain how to submit device drivers to the
-various kernel trees. Note that if you are interested in video card drivers
-you should probably talk to XFree86 (https://www.xfree86.org/) and/or X.Org
-(https://x.org/) instead.
-
-.. note::
-
- This document is old and has seen little maintenance in recent years; it
- should probably be updated or, perhaps better, just deleted. Most of
- what is here can be found in the other development documents anyway.
-
- Oh, and we don't really recommend submitting changes to XFree86 :)
-
-Also read the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
-document.
-
-
-Allocating Device Numbers
--------------------------
-
-Major and minor numbers for block and character devices are allocated
-by the Linux assigned name and number authority (currently this is
-Torben Mathiasen). The site is https://www.lanana.org/. This
-also deals with allocating numbers for devices that are not going to
-be submitted to the mainstream kernel.
-See :ref:`Documentation/admin-guide/devices.rst <admin_devices>`
-for more information on this.
-
-If you don't use assigned numbers then when your device is submitted it will
-be given an assigned number even if that is different from values you may
-have shipped to customers before.
-
-Who To Submit Drivers To
-------------------------
-
-Linux 2.0:
- No new drivers are accepted for this kernel tree.
-
-Linux 2.2:
- No new drivers are accepted for this kernel tree.
-
-Linux 2.4:
- If the code area has a general maintainer then please submit it to
- the maintainer listed in MAINTAINERS in the kernel file. If the
- maintainer does not respond or you cannot find the appropriate
- maintainer then please contact Willy Tarreau <w@1wt.eu>.
-
-Linux 2.6 and upper:
- The same rules apply as 2.4 except that you should follow linux-kernel
- to track changes in API's. The final contact point for Linux 2.6+
- submissions is Andrew Morton.
-
-What Criteria Determine Acceptance
-----------------------------------
-
-Licensing:
- The code must be released to us under the
- GNU General Public License. If you wish the driver to be
- useful to other communities such as BSD you may release
- under multiple licenses. If you choose to release under
- licenses other than the GPL, you should include your
- rationale for your license choices in your cover letter.
- See accepted licenses at include/linux/module.h
-
-Copyright:
- The copyright owner must agree to use of GPL.
- It's best if the submitter and copyright owner
- are the same person/entity. If not, the name of
- the person/entity authorizing use of GPL should be
- listed in case it's necessary to verify the will of
- the copyright owner.
-
-Interfaces:
- If your driver uses existing interfaces and behaves like
- other drivers in the same class it will be much more likely
- to be accepted than if it invents gratuitous new ones.
- If you need to implement a common API over Linux and NT
- drivers do it in userspace.
-
-Code:
- Please use the Linux style of code formatting as documented
- in :ref:`Documentation/process/coding-style.rst <codingStyle>`.
- If you have sections of code
- that need to be in other formats, for example because they
- are shared with a windows driver kit and you want to
- maintain them just once separate them out nicely and note
- this fact.
-
-Portability:
- Pointers are not always 32bits, not all computers are little
- endian, people do not all have floating point and you
- shouldn't use inline x86 assembler in your driver without
- careful thought. Pure x86 drivers generally are not popular.
- If you only have x86 hardware it is hard to test portability
- but it is easy to make sure the code can easily be made
- portable.
-
-Clarity:
- It helps if anyone can see how to fix the driver. It helps
- you because you get patches not bug reports. If you submit a
- driver that intentionally obfuscates how the hardware works
- it will go in the bitbucket.
-
-PM support:
- Since Linux is used on many portable and desktop systems, your
- driver is likely to be used on such a system and therefore it
- should support basic power management by implementing, if
- necessary, the .suspend and .resume methods used during the
- system-wide suspend and resume transitions. You should verify
- that your driver correctly handles the suspend and resume, but
- if you are unable to ensure that, please at least define the
- .suspend method returning the -ENOSYS ("Function not
- implemented") error. You should also try to make sure that your
- driver uses as little power as possible when it's not doing
- anything. For the driver testing instructions see
- Documentation/power/drivers-testing.rst and for a relatively
- complete overview of the power management issues related to
- drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`.
-
-Control:
- In general if there is active maintenance of a driver by
- the author then patches will be redirected to them unless
- they are totally obvious and without need of checking.
- If you want to be the contact and update point for the
- driver it is a good idea to state this in the comments,
- and include an entry in MAINTAINERS for your driver.
-
-What Criteria Do Not Determine Acceptance
------------------------------------------
-
-Vendor:
- Being the hardware vendor and maintaining the driver is
- often a good thing. If there is a stable working driver from
- other people already in the tree don't expect 'we are the
- vendor' to get your driver chosen. Ideally work with the
- existing driver author to build a single perfect driver.
-
-Author:
- It doesn't matter if a large Linux company wrote the driver,
- or you did. Nobody has any special access to the kernel
- tree. Anyone who tells you otherwise isn't telling the
- whole story.
-
-
-Resources
----------
-
-Linux kernel master tree:
- ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/...
-
- where *country_code* == your country code, such as
- **us**, **uk**, **fr**, etc.
-
- https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git
-
-Linux kernel mailing list:
- linux-kernel@vger.kernel.org
- [mail majordomo@vger.kernel.org to subscribe]
-
-Linux Device Drivers, Third Edition (covers 2.6.10):
- https://lwn.net/Kernel/LDD3/ (free version)
-
-LWN.net:
- Weekly summary of kernel development activity - https://lwn.net/
-
- 2.6 API changes:
-
- https://lwn.net/Articles/2.6-kernel-api/
-
- Porting drivers from prior kernels to 2.6:
-
- https://lwn.net/Articles/driver-porting/
-
-KernelNewbies:
- Documentation and assistance for new kernel programmers
-
- https://kernelnewbies.org/
-
-Linux USB project:
- http://www.linux-usb.org/
-
-How to NOT write kernel driver by Arjan van de Ven:
- https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf
-
-Kernel Janitor:
- https://kernelnewbies.org/KernelJanitors
-
-GIT, Fast Version Control System:
- https://git-scm.com/
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index a1cb6280fbcf..be49d8f2601b 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -12,9 +12,8 @@ This document contains a large number of suggestions in a relatively terse
format. For detailed information on how the kernel development process
works, see Documentation/process/development-process.rst. Also, read
Documentation/process/submit-checklist.rst
-for a list of items to check before submitting code. If you are submitting
-a driver, also read Documentation/process/submitting-drivers.rst; for device
-tree binding patches, read
+for a list of items to check before submitting code.
+For device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.rst.
This documentation assumes that you're using ``git`` to prepare your patches.
diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
index b3ed5c581034..811b905b56bf 100644
--- a/Documentation/security/keys/core.rst
+++ b/Documentation/security/keys/core.rst
@@ -1046,7 +1046,7 @@ The keyctl syscall functions are:
"filter" is either NULL to remove a watch or a filter specification to
indicate what events are required from the key.
- See Documentation/watch_queue.rst for more information.
+ See Documentation/core-api/watch_queue.rst for more information.
Note that only one watch may be emplaced for any particular { key,
queue_fd } combination.
diff --git a/Documentation/security/secrets/coco.rst b/Documentation/security/secrets/coco.rst
index 262e7abb1b24..087e2d1ae38b 100644
--- a/Documentation/security/secrets/coco.rst
+++ b/Documentation/security/secrets/coco.rst
@@ -98,6 +98,6 @@ References
See [sev-api-spec]_ for more info regarding SEV ``LAUNCH_SECRET`` operation.
-.. [sev] Documentation/virt/kvm/amd-memory-encryption.rst
+.. [sev] Documentation/virt/kvm/x86/amd-memory-encryption.rst
.. [secrets-coco-abi] Documentation/ABI/testing/securityfs-secrets-coco
.. [sev-api-spec] https://www.amd.com/system/files/TechDocs/55766_SEV-KM_API_Specification.pdf
diff --git a/Documentation/security/siphash.rst b/Documentation/security/siphash.rst
index a10380cb78e5..023bd95c74a5 100644
--- a/Documentation/security/siphash.rst
+++ b/Documentation/security/siphash.rst
@@ -85,7 +85,7 @@ Often times the XuY functions will not be large enough, and instead you'll
want to pass a pre-filled struct to siphash. When doing this, it's important
to always ensure the struct has no padding holes. The easiest way to do this
is to simply arrange the members of the struct in descending order of size,
-and to use offsetendof() instead of sizeof() for getting the size. For
+and to use offsetofend() instead of sizeof() for getting the size. For
performance reasons, if possible, it's probably a good thing to align the
struct to the right boundary. Here's an example::
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index cc348b219fca..06b34740bf90 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -121,13 +121,20 @@ def markup_refs(docname, app, node):
return repl
#
+# Keep track of cross-reference lookups that failed so we don't have to
+# do them again.
+#
+failed_lookups = { }
+def failure_seen(target):
+ return (target) in failed_lookups
+def note_failure(target):
+ failed_lookups[target] = True
+
+#
# In sphinx3 we can cross-reference to C macro and function, each one with its
# own C role, but both match the same regex, so we try both.
#
def markup_func_ref_sphinx3(docname, app, match):
- class_str = ['c-func', 'c-macro']
- reftype_str = ['function', 'macro']
-
cdom = app.env.domains['c']
#
# Go through the dance of getting an xref out of the C domain
@@ -143,27 +150,28 @@ def markup_func_ref_sphinx3(docname, app, match):
if base_target not in Skipnames:
for target in possible_targets:
- if target not in Skipfuncs:
- for class_s, reftype_s in zip(class_str, reftype_str):
- lit_text = nodes.literal(classes=['xref', 'c', class_s])
- lit_text += target_text
- pxref = addnodes.pending_xref('', refdomain = 'c',
- reftype = reftype_s,
- reftarget = target, modname = None,
- classname = None)
- #
- # XXX The Latex builder will throw NoUri exceptions here,
- # work around that by ignoring them.
- #
- try:
- xref = cdom.resolve_xref(app.env, docname, app.builder,
- reftype_s, target, pxref,
- lit_text)
- except NoUri:
- xref = None
-
- if xref:
- return xref
+ if (target not in Skipfuncs) and not failure_seen(target):
+ lit_text = nodes.literal(classes=['xref', 'c', 'c-func'])
+ lit_text += target_text
+ pxref = addnodes.pending_xref('', refdomain = 'c',
+ reftype = 'function',
+ reftarget = target,
+ modname = None,
+ classname = None)
+ #
+ # XXX The Latex builder will throw NoUri exceptions here,
+ # work around that by ignoring them.
+ #
+ try:
+ xref = cdom.resolve_xref(app.env, docname, app.builder,
+ 'function', target, pxref,
+ lit_text)
+ except NoUri:
+ xref = None
+
+ if xref:
+ return xref
+ note_failure(target)
return target_text
diff --git a/Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst b/Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst
new file mode 100644
index 000000000000..b473cd2190be
--- /dev/null
+++ b/Documentation/translations/it_IT/devicetree/bindings/submitting-patches.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../../disclaimer-ita.rst
+
+:Original: Documentation/devicetree/bindings/submitting-patches.rst
+
+================================================
+Sottomettere patch per devicetree (DT) *binding*
+================================================
+
+.. note:: to be translated
diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
index 009cdac014b6..78082281acf9 100644
--- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst
@@ -5,6 +5,7 @@
.. _it_kernel_doc:
+=================================
Scrivere i commenti in kernel-doc
=================================
@@ -469,6 +470,7 @@ Il titolo che segue ``DOC:`` funziona da intestazione all'interno del file
sorgente, ma anche come identificatore per l'estrazione di questi commenti di
documentazione. Quindi, il titolo dev'essere unico all'interno del file.
+=======================================
Includere i commenti di tipo kernel-doc
=======================================
diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst
index 9762452c584c..64528790dc34 100644
--- a/Documentation/translations/it_IT/doc-guide/sphinx.rst
+++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst
@@ -5,8 +5,9 @@
.. _it_sphinxdoc:
-Introduzione
-============
+=============================================
+Usare Sphinx per la documentazione del kernel
+=============================================
Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire
dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``.
@@ -158,6 +159,9 @@ Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.
+Potete anche personalizzare l'ouptut html passando un livello aggiuntivo
+DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.
+
Potete eliminare la documentazione generata tramite il comando
``make cleandocs``.
@@ -276,11 +280,11 @@ incrociato quando questa ha una voce nell'indice. Se trovate degli usi di
Tabelle a liste
---------------
-Raccomandiamo l'uso delle tabelle in formato lista (*list table*). Le tabelle
-in formato lista sono liste di liste. In confronto all'ASCII-art potrebbero
-non apparire di facile lettura nei file in formato testo. Il loro vantaggio è
-che sono facili da creare o modificare e che la differenza di una modifica è
-molto più significativa perché limitata alle modifiche del contenuto.
+Il formato ``list-table`` può essere utile per tutte quelle tabelle che non
+possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però,
+questo genere di tabelle sono illeggibili per chi legge direttamente i file di
+testo. Dunque, questo formato dovrebbe essere evitato senza forti argomenti che
+ne giustifichino l'uso.
La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table``
ma con delle funzionalità aggiuntive:
diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
index d5c521327f6a..560f1d0482d2 100644
--- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
@@ -129,8 +129,7 @@ eseguiti simultaneamente.
.. warning::
Il nome 'tasklet' è ingannevole: non hanno niente a che fare
- con i 'processi' ('tasks'), e probabilmente hanno più a che vedere
- con qualche pessima vodka che Alexey Kuznetsov si fece a quel tempo.
+ con i 'processi' ('tasks').
Potete determinate se siete in un softirq (o tasklet) utilizzando la
macro :c:func:`in_softirq()` (``include/linux/preempt.h``).
@@ -308,7 +307,7 @@ esse copiano una quantità arbitraria di dati da e verso lo spazio utente.
Al contrario di:c:func:`put_user()` e :c:func:`get_user()`, queste
funzioni ritornano la quantità di dati copiati (0 è comunque un successo).
-[Sì, questa stupida interfaccia mi imbarazza. La battaglia torna in auge anno
+[Sì, questa interfaccia mi imbarazza. La battaglia torna in auge anno
dopo anno. --RR]
Le funzioni potrebbero dormire implicitamente. Queste non dovrebbero mai essere
@@ -679,9 +678,8 @@ tutti sulle spine: questo riflette cambiamenti fondamentati (eg. la funzione
non può più essere chiamata con le funzioni attive, o fa controlli aggiuntivi,
o non fa più controlli che venivano fatti in precedenza). Solitamente a questo
s'accompagna un'adeguata e completa nota sulla lista di discussone
-linux-kernel; cercate negli archivi.
-Solitamente eseguire una semplice sostituzione su tutto un file rendere
-le cose **peggiori**.
+più adatta; cercate negli archivi. Solitamente eseguire una semplice
+sostituzione su tutto un file rendere le cose **peggiori**.
Inizializzazione dei campi d'una struttura
------------------------------------------
@@ -759,14 +757,14 @@ Mettere le vostre cose nel kernel
Al fine d'avere le vostre cose in ordine per l'inclusione ufficiale, o
anche per avere patch pulite, c'è del lavoro amministrativo da fare:
-- Trovare di chi è lo stagno in cui state pisciando. Guardare in cima
+- Trovare chi è responsabile del codice che state modificando. Guardare in cima
ai file sorgenti, all'interno del file ``MAINTAINERS``, ed alla fine
di tutti nel file ``CREDITS``. Dovreste coordinarvi con queste persone
per evitare di duplicare gli sforzi, o provare qualcosa che è già stato
rigettato.
Assicuratevi di mettere il vostro nome ed indirizzo email in cima a
- tutti i file che create o che mangeggiate significativamente. Questo è
+ tutti i file che create o che maneggiate significativamente. Questo è
il primo posto dove le persone guarderanno quando troveranno un baco,
o quando **loro** vorranno fare una modifica.
@@ -787,16 +785,15 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare:
"obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file
``Documentation/kbuild/makefiles.rst``.
-- Aggiungete voi stessi in ``CREDITS`` se avete fatto qualcosa di notevole,
- solitamente qualcosa che supera il singolo file (comunque il vostro nome
- dovrebbe essere all'inizio dei file sorgenti). ``MAINTAINERS`` significa
+- Aggiungete voi stessi in ``CREDITS`` se credete di aver fatto qualcosa di
+ notevole, solitamente qualcosa che supera il singolo file (comunque il vostro
+ nome dovrebbe essere all'inizio dei file sorgenti). ``MAINTAINERS`` significa
che volete essere consultati quando vengono fatte delle modifiche ad un
- sottosistema, e quando ci sono dei bachi; questo implica molto di più
- di un semplice impegno su una parte del codice.
+ sottosistema, e quando ci sono dei bachi; questo implica molto di più di un
+ semplice impegno su una parte del codice.
- Infine, non dimenticatevi di leggere
- ``Documentation/process/submitting-patches.rst`` e possibilmente anche
- ``Documentation/process/submitting-drivers.rst``.
+ ``Documentation/process/submitting-patches.rst``.
Trucchetti del kernel
=====================
diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 163f1bd4e857..51af37f2d621 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -102,16 +102,11 @@ che non esistano.
Sincronizzazione nel kernel Linux
=================================
-Se posso darvi un suggerimento: non dormite mai con qualcuno più pazzo di
-voi. Ma se dovessi darvi un suggerimento sulla sincronizzazione:
-**mantenetela semplice**.
+Se dovessi darvi un suggerimento sulla sincronizzazione: **mantenetela
+semplice**.
Siate riluttanti nell'introduzione di nuovi *lock*.
-Abbastanza strano, quest'ultimo è l'esatto opposto del mio suggerimento
-su quando **avete** dormito con qualcuno più pazzo di voi. E dovreste
-pensare a prendervi un cane bello grande.
-
I due principali tipi di *lock* nel kernel: spinlock e mutex
------------------------------------------------------------
@@ -316,7 +311,7 @@ Pete Zaitcev ci offre il seguente riassunto:
- Se siete in un contesto utente (una qualsiasi chiamata di sistema)
e volete sincronizzarvi con altri processi, usate i mutex. Potete trattenere
- il mutex e dormire (``copy_from_user*(`` o ``kmalloc(x,GFP_KERNEL)``).
+ il mutex e dormire (``copy_from_user(`` o ``kmalloc(x,GFP_KERNEL)``).
- Altrimenti (== i dati possono essere manipolati da un'interruzione) usate
spin_lock_irqsave() e spin_unlock_irqrestore().
@@ -979,9 +974,6 @@ fallisce nel trovare quello che vuole, quindi rilascia il *lock* di lettura,
trattiene un *lock* di scrittura ed inserisce un oggetto; questo genere di
codice presenta una corsa critica.
-Se non riuscite a capire il perché, per favore state alla larga dal mio
-codice.
-
corsa fra temporizzatori: un passatempo del kernel
--------------------------------------------------
diff --git a/Documentation/translations/it_IT/maintainer/configure-git.rst b/Documentation/translations/it_IT/maintainer/configure-git.rst
new file mode 100644
index 000000000000..8316fa53946f
--- /dev/null
+++ b/Documentation/translations/it_IT/maintainer/configure-git.rst
@@ -0,0 +1,10 @@
+.. include:: ../disclaimer-ita.rst
+
+:Original: Documentation/process/botching-up-ioctls.rst
+
+.. _it_configuregit:
+
+Configurare Git
+===============
+
+.. note:: To be translated
diff --git a/Documentation/translations/it_IT/networking/netdev-FAQ.rst b/Documentation/translations/it_IT/networking/netdev-FAQ.rst
index 7e2456bb7d92..8a1e049585c0 100644
--- a/Documentation/translations/it_IT/networking/netdev-FAQ.rst
+++ b/Documentation/translations/it_IT/networking/netdev-FAQ.rst
@@ -1,6 +1,6 @@
.. include:: ../disclaimer-ita.rst
-:Original: :ref:`Documentation/networking/netdev-FAQ.rst <netdev-FAQ>`
+:Original: :ref:`Documentation/process/maintainer-netdev.rst <netdev-FAQ>`
.. _it_netdev-FAQ:
diff --git a/Documentation/translations/it_IT/process/3.Early-stage.rst b/Documentation/translations/it_IT/process/3.Early-stage.rst
index 443ac1e5558f..0809de39108a 100644
--- a/Documentation/translations/it_IT/process/3.Early-stage.rst
+++ b/Documentation/translations/it_IT/process/3.Early-stage.rst
@@ -168,14 +168,15 @@ in questa ricerca:
.../scripts/get_maintainer.pl
-Se questo script viene eseguito con l'opzione "-f" ritornerà il
-manutentore(i) attuale per un dato file o cartella. Se viene passata una
-patch sulla linea di comando, lo script elencherà i manutentori che
-dovrebbero riceverne una copia. Ci sono svariate opzioni che regolano
-quanto a fondo get_maintainer.pl debba cercare i manutentori;
-siate quindi prudenti nell'utilizzare le opzioni più aggressive poiché
-potreste finire per includere sviluppatori che non hanno un vero interesse
-per il codice che state modificando.
+Se questo script viene eseguito con l'opzione "-f" ritornerà il manutentore(i)
+attuale per un dato file o cartella. Se viene passata una patch sulla linea di
+comando, lo script elencherà i manutentori che dovrebbero riceverne una copia.
+Questo è la maniera raccomandata (non quella con "-f") per ottenere la lista di
+persone da aggiungere a Cc per le vostre patch. Ci sono svariate opzioni che
+regolano quanto a fondo get_maintainer.pl debba cercare i manutentori; siate
+quindi prudenti nell'utilizzare le opzioni più aggressive poiché potreste finire
+per includere sviluppatori che non hanno un vero interesse per il codice che
+state modificando.
Se tutto ciò dovesse fallire, parlare con Andrew Morton potrebbe essere
un modo efficace per capire chi è il manutentore di un dato pezzo di codice.
diff --git a/Documentation/translations/it_IT/process/5.Posting.rst b/Documentation/translations/it_IT/process/5.Posting.rst
index 1476d51eb5e5..cf92a16ed7e5 100644
--- a/Documentation/translations/it_IT/process/5.Posting.rst
+++ b/Documentation/translations/it_IT/process/5.Posting.rst
@@ -16,9 +16,8 @@ e di procedure per la pubblicazione delle patch; seguirle renderà la vita
più facile a tutti quanti. Questo documento cercherà di coprire questi
argomenti con un ragionevole livello di dettaglio; più informazioni possono
essere trovare nella cartella 'Documentation', nei file
-:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`,
-:ref:`translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`, e
-:ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.
+:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
+e :ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`.
Quando pubblicarle
@@ -214,13 +213,28 @@ irrilevanti (quelli generati dal processo di generazione, per esempio, o i file
di backup del vostro editor). Il file "dontdiff" nella cartella Documentation
potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X".
-Le etichette sopra menzionante sono usate per descrivere come i vari
-sviluppatori sono stati associati allo sviluppo di una patch. Sono descritte
-in dettaglio nel documento :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`;
-quello che segue è un breve riassunto. Ognuna di queste righe ha il seguente
-formato:
+Le etichette sopracitate danno un'idea di come una patch prende vita e sono
+descritte nel dettaglio nel documento
+:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`.
+Qui di seguito un breve riassunto.
-::
+Un'etichetta ci può dire quale commit ha introdotto il problema che viene corretto nella patch::
+
+ Fixes: 1f2e3d4c5b6a ("The first line of the commit specified by the first 12 characters of its SHA-1 ID")
+
+Un'altra etichetta viene usata per fornire collegamenti a pagine web contenenti
+maggiori informazioni, per esempio un rapporto circa il baco risolto dalla
+patch, oppure un documento con le specifiche implementate dalla patch::
+
+ Link: https://example.com/somewhere.html optional-other-stuff
+
+Alcuni manutentori aggiungono quest'etichetta alla patch per fare riferimento
+alla più recente discussione pubblica. A volte questo è fatto automaticamente da
+alcuni strumenti come b4 or un *hook* git come quello descritto qui
+'Documentation/translations/it_IT/maintainer/configure-git.rst'
+
+Un terzo tipo di etichetta viene usato per indicare chi ha contribuito allo
+sviluppo della patch. Tutte queste etichette seguono il formato::
tag: Full Name <email address> optional-other-stuff
diff --git a/Documentation/translations/it_IT/process/8.Conclusion.rst b/Documentation/translations/it_IT/process/8.Conclusion.rst
index 039bfc5a4108..32659ff467c0 100644
--- a/Documentation/translations/it_IT/process/8.Conclusion.rst
+++ b/Documentation/translations/it_IT/process/8.Conclusion.rst
@@ -13,9 +13,8 @@ e argomenti correlati. Primo tra questi sarà sempre la cartella Documentation
che si trova nei sorgenti kernel.
Il file :ref:`process/howto.rst <it_process_howto>` è un punto di partenza
-importante; :ref:`process/submitting-patches.rst <it_submittingpatches>` e
-:ref:`process/submitting-drivers.rst <it_submittingdrivers>` sono
-anch'essi qualcosa che tutti gli sviluppatori del kernel dovrebbero leggere.
+importante; :ref:`process/submitting-patches.rst <it_submittingpatches>` è
+anch'esso qualcosa che tutti gli sviluppatori del kernel dovrebbero leggere.
Molte API interne al kernel sono documentate utilizzando il meccanismo
kerneldoc; "make htmldocs" o "make pdfdocs" possono essere usati per generare
quei documenti in HTML o PDF (sebbene le versioni di TeX di alcune
diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst
index dc7193377b7f..10e0ef9c34b7 100644
--- a/Documentation/translations/it_IT/process/changes.rst
+++ b/Documentation/translations/it_IT/process/changes.rst
@@ -11,8 +11,8 @@ Requisiti minimi per compilare il kernel
Introduzione
============
-Questo documento fornisce una lista dei software necessari per eseguire i
-kernel 4.x.
+Questo documento fornisce una lista dei software necessari per eseguire questa
+versione del kernel.
Questo documento è basato sul file "Changes" del kernel 2.0.x e quindi le
persone che lo scrissero meritano credito (Jared Mauch, Axel Boldt,
@@ -32,12 +32,13 @@ PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils.
====================== ================= ========================================
Programma Versione minima Comando per verificare la versione
====================== ================= ========================================
-GNU C 4.9 gcc --version
-Clang/LLVM (optional) 10.0.1 clang --version
+GNU C 5.1 gcc --version
+Clang/LLVM (optional) 11.0.0 clang --version
GNU make 3.81 make --version
binutils 2.23 ld -v
flex 2.5.35 flex --version
bison 2.0 bison --version
+pahole 1.16 pahole --version
util-linux 2.10o fdformat --version
kmod 13 depmod -V
e2fsprogs 1.41.4 e2fsck -V
@@ -58,6 +59,7 @@ iptables 1.4.2 iptables -V
openssl & libcrypto 1.0.0 openssl version
bc 1.06.95 bc --version
Sphinx\ [#f1]_ 1.7 sphinx-build --version
+cpio any cpio --version
====================== ================= ========================================
.. [#f1] Sphinx è necessario solo per produrre la documentazione del Kernel
@@ -111,6 +113,16 @@ Bison
Dalla versione 4.16, il sistema di compilazione, durante l'esecuzione, genera
un parsificatore. Questo richiede bison 2.0 o successivo.
+pahole
+------
+
+Dalla versione 5.2, quando viene impostato CONFIG_DEBUG_INFO_BTF, il sistema di
+compilazione genera BTF (BPF Type Format) a partire da DWARF per vmlinux. Più
+tardi anche per i moduli. Questo richiede pahole v1.16 o successivo.
+
+A seconda della distribuzione, lo si può trovare nei pacchetti 'dwarves' o
+'pahole'. Oppure lo si può trovare qui: https://fedorapeople.org/~acme/dwarves/.
+
Perl
----
@@ -455,6 +467,11 @@ mcelog
- <http://www.mcelog.org/>
+cpio
+----
+
+- <https://www.gnu.org/software/cpio/>
+
Rete
****
diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index ecc74ba50d3e..a393ee4182af 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -466,14 +466,52 @@ la riga della parentesi graffa di chiusura. Ad esempio:
}
EXPORT_SYMBOL(system_is_up);
+6.1) Prototipi di funzione
+**************************
+
Nei prototipi di funzione, includete i nomi dei parametri e i loro tipi.
Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito
perché è un modo semplice per aggiungere informazioni importanti per il
lettore.
-Non usate la parola chiave ``extern`` coi prototipi di funzione perché
+Non usate la parola chiave ``extern`` con le dichiarazioni di funzione perché
rende le righe più lunghe e non è strettamente necessario.
+Quando scrivete i prototipi di funzione mantenete `l'ordine degli elementi <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/>`_.
+
+Prendiamo questa dichiarazione di funzione come esempio::
+
+ __init void * __must_check action(enum magic value, size_t size, u8 count,
+ char *fmt, ...) __printf(4, 5) __malloc;
+
+L'ordine suggerito per gli elementi di un prototipo di funzione è il seguente:
+
+- classe d'archiviazione (in questo caso ``static __always_inline``. Da notare
+ che ``__always_inline`` è tecnicamente un attributo ma che viene trattato come
+ ``inline``)
+- attributi della classe di archiviazione (in questo caso ``__init``, in altre
+ parole la sezione, ma anche cose tipo ``__cold``)
+- il tipo di ritorno (in questo caso, ``void *``)
+- attributi per il valore di ritorno (in questo caso, ``__must_check``)
+- il nome della funzione (in questo caso, ``action``)
+- i parametri della funzione(in questo caso,
+ ``(enum magic value, size_t size, u8 count, char *fmt, ...)``,
+ da notare che va messo anche il nome del parametro)
+- attributi dei parametri (in questo caso, ``__printf(4, 5)``)
+- attributi per il comportamento della funzione (in questo caso, ``__malloc_``)
+
+Notate che per la **definizione** di una funzione (il altre parole il corpo
+della funzione), il compilatore non permette di usare gli attributi per i
+parametri dopo i parametri. In questi casi, devono essere messi dopo gli
+attributi della classe d'archiviazione (notate che la posizione di
+``__printf(4,5)`` cambia rispetto alla **dichiarazione**)::
+
+ static __always_inline __init __printf(4, 5) void * __must_check action(enum magic value,
+ size_t size, u8 count, char *fmt, ...) __malloc
+ {
+ ...
+ }*)**``)**``)``)``*)``)``)``)``*``)``)``)*)
+
7) Centralizzare il ritorno delle funzioni
------------------------------------------
@@ -855,7 +893,7 @@ I messaggi del kernel non devono terminare con un punto fermo.
Scrivere i numeri fra parentesi (%d) non migliora alcunché e per questo
dovrebbero essere evitati.
-Ci sono alcune macro per la diagnostica in <linux/device.h> che dovreste
+Ci sono alcune macro per la diagnostica in <linux/dev_printk.h> che dovreste
usare per assicurarvi che i messaggi vengano associati correttamente ai
dispositivi e ai driver, e che siano etichettati correttamente: dev_err(),
dev_warn(), dev_info(), e così via. Per messaggi che non sono associati ad
diff --git a/Documentation/translations/it_IT/process/deprecated.rst b/Documentation/translations/it_IT/process/deprecated.rst
index 987f45ee1804..febf83897783 100644
--- a/Documentation/translations/it_IT/process/deprecated.rst
+++ b/Documentation/translations/it_IT/process/deprecated.rst
@@ -69,8 +69,8 @@ dovrebbero essere fatto negli argomenti di funzioni di allocazione di memoria
piccoli di quelli che il chiamante si aspettava. L'uso di questo modo di
allocare può portare ad un overflow della memoria di heap e altri
malfunzionamenti. (Si fa eccezione per valori numerici per i quali il
-compilatore può generare avvisi circa un potenziale overflow. Tuttavia usare
-i valori numerici come suggerito di seguito è innocuo).
+compilatore può generare avvisi circa un potenziale overflow. Tuttavia, anche in
+questi casi è preferibile riscrivere il codice come suggerito di seguito).
Per esempio, non usate ``count * size`` come argomento::
@@ -80,6 +80,9 @@ Al suo posto, si dovrebbe usare l'allocatore a due argomenti::
foo = kmalloc_array(count, size, GFP_KERNEL);
+Nello specifico, kmalloc() può essere sostituta da kmalloc_array(), e kzalloc()
+da kcalloc().
+
Se questo tipo di allocatore non è disponibile, allora dovrebbero essere usate
le funzioni del tipo *saturate-on-overflow*::
@@ -100,9 +103,20 @@ Invece, usate la seguente funzione::
invitati a riorganizzare il vostro codice usando il
`flexible array member <#zero-length-and-one-element-arrays>`_.
-Per maggiori dettagli fate riferimento a array_size(),
-array3_size(), e struct_size(), così come la famiglia di
-funzioni check_add_overflow() e check_mul_overflow().
+Per altri calcoli, usate le funzioni size_mul(), size_add(), e size_sub(). Per
+esempio, al posto di::
+
+ foo = krealloc(current_size + chunk_size * (count - 3), GFP_KERNEL);
+
+dovreste scrivere:
+
+ foo = krealloc(size_add(current_size,
+ size_mul(chunk_size,
+ size_sub(count, 3))), GFP_KERNEL);
+
+Per maggiori dettagli fate riferimento a array3_size() e flex_array_size(), ma
+anche le funzioni della famiglia check_mul_overflow(), check_add_overflow(),
+check_sub_overflow(), e check_shl_overflow().
simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
----------------------------------------------------------------------
diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst
index 9554368a2ae2..16ad5622d549 100644
--- a/Documentation/translations/it_IT/process/howto.rst
+++ b/Documentation/translations/it_IT/process/howto.rst
@@ -109,8 +109,7 @@ Di seguito una lista di file che sono presenti nei sorgente del kernel e che
accetteranno patch solo se queste osserveranno tali regole, e molte
persone revisioneranno il codice solo se scritto nello stile appropriato.
- :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` e
- :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`
+ :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`
Questo file descrive dettagliatamente come creare ed inviare una patch
con successo, includendo (ma non solo questo):
diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst
index c4c867132c88..8d4e36a07ff4 100644
--- a/Documentation/translations/it_IT/process/index.rst
+++ b/Documentation/translations/it_IT/process/index.rst
@@ -41,12 +41,12 @@ degli sviluppatori:
:maxdepth: 1
changes
- submitting-drivers
stable-api-nonsense
management-style
stable-kernel-rules
submit-checklist
kernel-docs
+ maintainers
Ed infine, qui ci sono alcune guide più tecniche che son state messe qua solo
perché non si è trovato un posto migliore.
diff --git a/Documentation/translations/it_IT/process/maintainer-handbooks.rst b/Documentation/translations/it_IT/process/maintainer-handbooks.rst
new file mode 100644
index 000000000000..d840145bcceb
--- /dev/null
+++ b/Documentation/translations/it_IT/process/maintainer-handbooks.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-ita.rst
+
+:Original: Documentation/process/maintainer-handbooks.rst
+:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
+
+.. _it_maintainer_handbooks_main:
+
+Note sul processo di sviluppo dei sottosistemi e dei sorgenti dei manutentori
+=============================================================================
+
+Lo scopo di questo documento è quello di fornire informazioni sul processo di
+sviluppo dedicate ai sottosistemi che vanno ad integrare quelle più generali
+descritte in :ref:`Documentation/translations/it_IT/process
+<it_development_process_main>`.
+
+Indice:
+
+.. toctree::
+ :numbered:
+ :maxdepth: 2
+
+ maintainer-tip
diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst
index f3c8e8d377ee..a1e98ec9532e 100644
--- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst
+++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst
@@ -931,12 +931,11 @@ che avete nel vostro portachiavi::
uid [ unknown] Linus Torvalds <torvalds@kernel.org>
sub rsa2048 2011-09-20 [E]
-Poi, aprite il `PGP pathfinder`_. Nel campo "From", incollate l'impronta
-digitale della chiave di Linus Torvalds che si vede nell'output qui sopra.
-Nel campo "to", incollate il key-id della chiave sconosciuta che avete
-trovato con ``gpg --search``, e poi verificare il risultato:
-
-- `Finding paths to Linus`_
+Poi, cercate un percorso affidabile da Linux Torvalds alla chiave che avete
+trovato con ``gpg --search`` usando la chiave sconosciuta.Per farlo potete usare
+diversi strumenti come https://github.com/mricon/wotmate,
+https://git.kernel.org/pub/scm/docs/kernel/pgpkeys.git/tree/graphs, e
+https://the.earth.li/~noodles/pathfind.html.
Se trovate un paio di percorsi affidabili è un buon segno circa la validità
della chiave. Ora, potete aggiungerla al vostro portachiavi dal keyserver::
@@ -948,6 +947,3 @@ fiducia nell'amministratore del servizio *PGP Pathfinder* sperando che non
sia malintenzionato (infatti, questo va contro :ref:`it_devs_not_infra`).
Tuttavia, se mantenete con cura la vostra rete di fiducia sarà un deciso
miglioramento rispetto alla cieca fiducia nei keyserver.
-
-.. _`PGP pathfinder`: https://pgp.cs.uu.nl/
-.. _`Finding paths to Linus`: https://pgp.cs.uu.nl/paths/79BE3E4300411886/to/C94035C21B4F2AEB.html
diff --git a/Documentation/translations/it_IT/process/maintainer-tip.rst b/Documentation/translations/it_IT/process/maintainer-tip.rst
new file mode 100644
index 000000000000..126f17ee541e
--- /dev/null
+++ b/Documentation/translations/it_IT/process/maintainer-tip.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-ita.rst
+
+:Original: Documentation/process/maintainer-tip.rst
+
+Il tascabile dei sorgenti tip
+=============================
+
+.. note:: To be translated
diff --git a/Documentation/translations/it_IT/process/maintainers.rst b/Documentation/translations/it_IT/process/maintainers.rst
new file mode 100644
index 000000000000..3225f7c89fda
--- /dev/null
+++ b/Documentation/translations/it_IT/process/maintainers.rst
@@ -0,0 +1,13 @@
+:Original: Documentation/process/maintainers.rst
+
+Lista dei manutentori e come inviare modifiche al kernel
+========================================================
+
+Questa pagina non verrà tradotta. Fate riferimento alla versione originale in
+inglese.
+
+.. note:: La pagina originale usa una direttiva speciale per integrare il file
+ `MAINTAINERS` in sphinx. La parte di quel documento che si potrebbe
+ tradurre contiene comunque informazioni già presenti in
+ :ref:`Documentation/translations/it_IT/process/submitting-patches.rst
+ <it_submittingpatches>`.
diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst
index 83f48afe48b9..0be675b03199 100644
--- a/Documentation/translations/it_IT/process/stable-kernel-rules.rst
+++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst
@@ -41,10 +41,10 @@ Regole sul tipo di patch che vengono o non vengono accettate nei sorgenti
Procedura per sottomettere patch per i sorgenti -stable
-------------------------------------------------------
- - Una patch di sicurezza non dovrebbero essere gestite (solamente) dal processo
- di revisione -stable, ma dovrebbe seguire le procedure descritte in
- :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`.
-
+.. note::
+ Una patch di sicurezza non dovrebbe essere gestita (solamente) dal processo
+ di revisione -stable, ma dovrebbe seguire le procedure descritte in
+ :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>`.
Per tutte le altre sottomissioni, scegliere una delle seguenti procedure
------------------------------------------------------------------------
@@ -90,9 +90,9 @@ L':ref:`it_option_2` e l':ref:`it_option_3` sono più utili quando, al momento
dell'inclusione dei sorgenti principali, si ritiene che non debbano essere
incluse anche in quelli stabili (per esempio, perché si crede che si dovrebbero
fare più verifiche per eventuali regressioni). L':ref:`it_option_3` è
-particolarmente utile se la patch ha bisogno di qualche modifica per essere
-applicata ad un kernel più vecchio (per esempio, perché nel frattempo l'API è
-cambiata).
+particolarmente utile se una patch dev'essere riportata su una versione
+precedente (per esempio la patch richiede modifiche a causa di cambiamenti di
+API).
Notate che per l':ref:`it_option_3`, se la patch è diversa da quella nei
sorgenti principali (per esempio perché è stato necessario un lavoro di
@@ -167,9 +167,18 @@ Ciclo di una revisione
della lista linux-kernel obietta la bontà della patch, sollevando problemi
che i manutentori ed i membri non avevano compreso, allora la patch verrà
rimossa dalla coda.
- - Alla fine del ciclo di revisione tutte le patch che hanno ricevuto l'ACK
- verranno aggiunte per il prossimo rilascio -stable, e successivamente
- questo nuovo rilascio verrà fatto.
+ - Le patch che hanno ricevuto un ACK verranno inviate nuovamente come parte di
+ un rilascio candidato (-rc) al fine di essere verificate dagli sviluppatori e
+ dai testatori.
+ - Solitamente si pubblica solo una -rc, tuttavia se si riscontrano problemi
+ importanti, alcune patch potrebbero essere modificate o essere scartate,
+ oppure nuove patch potrebbero essere messe in coda. Dunque, verranno pubblicate
+ nuove -rc e così via finché non si ritiene che non vi siano più problemi.
+ - Si può rispondere ad una -rc scrivendo sulla lista di discussione un'email
+ con l'etichetta "Tested-by:". Questa etichetta verrà raccolta ed aggiunta al
+ commit rilascio.
+ - Alla fine del ciclo di revisione il nuovo rilascio -stable conterrà tutte le
+ patch che erano in coda e sono state verificate.
- Le patch di sicurezza verranno accettate nei sorgenti -stable direttamente
dalla squadra per la sicurezza del kernel, e non passerà per il normale
ciclo di revisione. Contattate la suddetta squadra per maggiori dettagli
@@ -186,8 +195,19 @@ Sorgenti
- Il rilascio definitivo, e marchiato, di tutti i kernel stabili può essere
trovato in rami distinti per versione al seguente indirizzo:
- https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
+ https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
+
+ - I rilasci candidati di tutti i kernel stabili possono essere trovati al
+ seguente indirizzo:
+
+ https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/
+
+ .. warning::
+ I sorgenti -stable-rc sono un'istantanea dei sorgenti stable-queue e
+ subirà frequenti modifiche, dunque verrà anche trapiantato spesso.
+ Dovrebbe essere usato solo allo scopo di verifica (per esempio in un
+ sistema di CI)
Comitato per la revisione
-------------------------
diff --git a/Documentation/translations/it_IT/process/submitting-drivers.rst b/Documentation/translations/it_IT/process/submitting-drivers.rst
deleted file mode 100644
index dadd77e47613..000000000000
--- a/Documentation/translations/it_IT/process/submitting-drivers.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-.. include:: ../disclaimer-ita.rst
-
-:Original: :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
-:Translator: Federico Vaga <federico.vaga@vaga.pv.it>
-
-.. _it_submittingdrivers:
-
-Sottomettere driver per il kernel Linux
-=======================================
-
-.. note::
-
- Questo documento è vecchio e negli ultimi anni non è stato più aggiornato;
- dovrebbe essere aggiornato, o forse meglio, rimosso. La maggior parte di
- quello che viene detto qui può essere trovato anche negli altri documenti
- dedicati allo sviluppo. Per questo motivo il documento non verrà tradotto.
diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst
index 4fb5b3aa306d..a3bb0008837a 100644
--- a/Documentation/translations/it_IT/process/submitting-patches.rst
+++ b/Documentation/translations/it_IT/process/submitting-patches.rst
@@ -18,16 +18,18 @@ Questo documento contiene un vasto numero di suggerimenti concisi. Per maggiori
dettagli su come funziona il processo di sviluppo del kernel leggete
Documentation/translations/it_IT/process/development-process.rst. Leggete anche
Documentation/translations/it_IT/process/submit-checklist.rst per una lista di
-punti da verificare prima di inviare del codice. Se state inviando un driver,
-allora leggete anche
-Documentation/translations/it_IT/process/submitting-drivers.rst; per delle patch
-relative alle associazioni per Device Tree leggete
+punti da verificare prima di inviare del codice.
+Per delle patch relative alle associazioni per Device Tree leggete
Documentation/translations/it_IT/process/submitting-patches.rst.
Questa documentazione assume che sappiate usare ``git`` per preparare le patch.
Se non siete pratici di ``git``, allora è bene che lo impariate;
renderà la vostra vita di sviluppatore del kernel molto più semplice.
+I sorgenti di alcuni sottosistemi e manutentori contengono più informazioni
+riguardo al loro modo di lavorare ed aspettative. Consultate
+:ref:`Documentation/translations/it_IT/process/maintainer-handbooks.rst <it_maintainer_handbooks_main>`
+
Ottenere i sorgenti attuali
---------------------------
@@ -84,11 +86,11 @@ comporti come descritto.
I manutentori vi saranno grati se scrivete la descrizione della patch in un
formato che sia compatibile con il gestore dei sorgenti usato dal kernel,
-``git``, come un "commit log". Leggete :ref:`it_explicit_in_reply_to`.
+``git``, come un "commit log". Leggete :ref:`it_the_canonical_patch_format`.
Risolvete solo un problema per patch. Se la vostra descrizione inizia ad
essere lunga, potrebbe essere un segno che la vostra patch necessita d'essere
-divisa. Leggete :ref:`split_changes`.
+divisa. Leggete :ref:`it_split_changes`.
Quando inviate o rinviate una patch o una serie, includete la descrizione
completa delle modifiche e la loro giustificazione. Non limitatevi a dire che
@@ -104,17 +106,28 @@ do frotz" piuttosto che "[This patch] makes xyzzy do frotz" or "[I] changed
xyzzy to do frotz", come se steste dando ordini al codice di cambiare il suo
comportamento.
-Se la patch corregge un baco conosciuto, fare riferimento a quel baco inserendo
-il suo numero o il suo URL. Se la patch è la conseguenza di una discussione
-su una lista di discussione, allora fornite l'URL all'archivio di quella
-discussione; usate i collegamenti a https://lore.kernel.org/ con il
-``Message-Id``, in questo modo vi assicurerete che il collegamento non diventi
-invalido nel tempo.
+Se ci sono delle discussioni, o altre informazioni d'interesse, che fanno
+riferimento alla patch, allora aggiungete l'etichetta 'Link:' per farvi
+riferimento. Per esempio, se la vostra patch corregge un baco potete aggiungere
+quest'etichetta per fare riferimento ad un rapporto su una lista di discussione
+o un *bug tracker*. Un altro esempio; potete usare quest'etichetta per far
+riferimento ad una discussione precedentemente avvenuta su una lista di
+discussione, o qualcosa di documentato sul web, da cui poi è nata la patch in
+questione.
+
+Quando volete fare riferimento ad una lista di discussione, preferite il
+servizio d'archiviazione lore.kernel.org. Per create un collegamento URL è
+sufficiente usare il campo ``Message-Id``, presente nell'intestazione del
+messaggio, senza parentesi angolari. Per esempio::
+
+ Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
+
+Prima d'inviare il messaggio ricordatevi di verificare che il collegamento così
+creato funzioni e che indirizzi verso il messaggio desiderato.
-Tuttavia, cercate di rendere la vostra spiegazione comprensibile anche senza
-far riferimento a fonti esterne. In aggiunta ai collegamenti a bachi e liste
-di discussione, riassumente i punti più importanti della discussione che hanno
-portato alla creazione della patch.
+Tuttavia, provate comunque a dare una spiegazione comprensibile anche senza
+accedere alle fonti esterne. Inoltre, riassumente i punti più salienti che hanno
+condotto all'invio della patch.
Se volete far riferimento a uno specifico commit, non usate solo
l'identificativo SHA-1. Per cortesia, aggiungete anche la breve riga
@@ -226,10 +239,11 @@ nella vostra patch.
Dovreste sempre inviare una copia della patch ai manutentori dei sottosistemi
interessati dalle modifiche; date un'occhiata al file MAINTAINERS e alla storia
-delle revisioni per scoprire chi si occupa del codice. Lo script
-scripts/get_maintainer.pl può esservi d'aiuto. Se non riuscite a trovare un
-manutentore per il sottosistema su cui state lavorando, allora Andrew Morton
-(akpm@linux-foundation.org) sarà la vostra ultima possibilità.
+delle revisioni per scoprire chi si occupa del codice. Lo script
+scripts/get_maintainer.pl può esservi d'aiuto (passategli il percorso alle
+vostre patch). Se non riuscite a trovare un manutentore per il sottosistema su
+cui state lavorando, allora Andrew Morton (akpm@linux-foundation.org) sarà la
+vostra ultima possibilità.
Normalmente, dovreste anche scegliere una lista di discussione a cui inviare la
vostra serie di patch. La lista di discussione linux-kernel@vger.kernel.org
@@ -324,14 +338,19 @@ cosa stia accadendo.
Assicuratevi di dire ai revisori quali cambiamenti state facendo e di
ringraziarli per il loro tempo. Revisionare codice è un lavoro faticoso e che
-richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche
-in questo caso, rispondete con educazione e concentratevi sul problema che
-hanno evidenziato.
+richiede molto tempo, e a volte i revisori diventano burberi. Tuttavia, anche in
+questo caso, rispondete con educazione e concentratevi sul problema che hanno
+evidenziato. Quando inviate una version successiva ricordatevi di aggiungere un
+``patch changelog`` alla email di intestazione o ad ogni singola patch spiegando
+le differenze rispetto a sottomissioni precedenti (vedere
+:ref:`it_the_canonical_patch_format`).
Leggete Documentation/translations/it_IT/process/email-clients.rst per
le raccomandazioni sui programmi di posta elettronica e l'etichetta da usare
sulle liste di discussione.
+.. _it_resend_reminders:
+
Non scoraggiatevi - o impazientitevi
------------------------------------
@@ -504,7 +523,8 @@ Utilizzare Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: e Fixes:
L'etichetta Reported-by da credito alle persone che trovano e riportano i bachi
e si spera che questo possa ispirarli ad aiutarci nuovamente in futuro.
Rammentate che se il baco è stato riportato in privato, dovrete chiedere il
-permesso prima di poter utilizzare l'etichetta Reported-by.
+permesso prima di poter utilizzare l'etichetta Reported-by. Questa etichetta va
+usata per i bachi, dunque non usatela per richieste di nuove funzionalità.
L'etichetta Tested-by: indica che la patch è stata verificata con successo
(su un qualche sistema) dalla persona citata. Questa etichetta informa i
@@ -574,6 +594,8 @@ previste per i kernel stabili, e nemmeno dalla necessità di aggiungere
in copia conoscenza stable@vger.kernel.org su tutte le patch per
suddetti kernel.
+.. _it_the_canonical_patch_format:
+
Il formato canonico delle patch
-------------------------------
@@ -719,6 +741,8 @@ messe correttamente oltre la riga.::
Maggiori dettagli sul formato delle patch nei riferimenti qui di seguito.
+.. _it_backtraces:
+
Aggiungere i *backtrace* nei messaggi di commit
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst
index 38fed6fe62fe..649e2ff2a407 100644
--- a/Documentation/translations/ja_JP/howto.rst
+++ b/Documentation/translations/ja_JP/howto.rst
@@ -129,8 +129,8 @@ linux-api@vger.kernel.org ã«é€ã‚‹ã“ã¨ã‚’勧ã‚ã¾ã™ã€‚
ルã«å¾“ã£ã¦ã„ã‚‹ã‚‚ã®ã ã‘ã‚’å—ã‘付ã‘ã€å¤šãã®äººã¯æ­£ã—ã„スタイルã®ã‚³ãƒ¼ãƒ‰
ã ã‘をレビューã—ã¾ã™ã€‚
- :ref:`Documentation/process/submitting-patches.rst <codingstyle>` 㨠:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
- ã“れらã®ãƒ•ã‚¡ã‚¤ãƒ«ã«ã¯ã€ã©ã†ã‚„ã£ã¦ã†ã¾ãパッãƒã‚’作ã£ã¦æŠ•ç¨¿ã™ã‚‹ã‹ã«ã¤
+ :ref:`Documentation/process/submitting-patches.rst <codingstyle>`
+ ã“ã®ãƒ•ã‚¡ã‚¤ãƒ«ã«ã¯ã€ã©ã†ã‚„ã£ã¦ã†ã¾ãパッãƒã‚’作ã£ã¦æŠ•ç¨¿ã™ã‚‹ã‹ã«ã¤
ã„ã¦éžå¸¸ã«è©³ã—ã書ã‹ã‚Œã¦ãŠã‚Šã€ä»¥ä¸‹ã‚’å«ã¿ã¾ã™ (ã“ã‚Œã ã‘ã«é™ã‚‰ãªã„
ã‘ã‚Œã©ã‚‚)
diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst
index e3cdf0c84892..e43970584ca4 100644
--- a/Documentation/translations/ko_KR/howto.rst
+++ b/Documentation/translations/ko_KR/howto.rst
@@ -124,7 +124,7 @@ mtk.manpages@gmail.comì˜ ë©”ì¸í…Œì´ë„ˆì—게 보낼 ê²ƒì„ ê¶Œìž¥í•œë‹¤.
ë©”ì¸í…Œì´ë„ˆë“¤ì€ ì´ ê·œì¹™ì„ ë”°ë¥´ëŠ” íŒ¨ì¹˜ë“¤ë§Œì„ ë°›ì•„ë“¤ì¼ ê²ƒì´ê³  ë§Žì€ ì‚¬ëžŒë“¤ì´
ê·¸ 패치가 올바른 스타ì¼ì¼ 경우만 코드를 검토할 것ì´ë‹¤.
- :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` 와 :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
+ :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
ì´ íŒŒì¼ë“¤ì€ 성공ì ìœ¼ë¡œ 패치를 만들고 보내는 ë²•ì„ ë‹¤ìŒì˜ 내용들로
굉장히 ìƒì„¸ížˆ 설명하고 있다(그러나 다ìŒìœ¼ë¡œ 한정ë˜ì§„ 않는다).
diff --git a/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst
index fbc83dfdcead..fb023ea1374d 100644
--- a/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst
+++ b/Documentation/translations/zh_CN/PCI/pci-iov-howto.rst
@@ -123,14 +123,14 @@ nr_virtfn'是è¦å¯ç”¨çš„VFçš„ç¼–å·ã€‚
...
}
- static int dev_suspend(struct pci_dev *dev, pm_message_t state)
+ static int dev_suspend(struct device *dev)
{
...
return 0;
}
- static int dev_resume(struct pci_dev *dev)
+ static int dev_resume(struct device *dev)
{
...
@@ -163,8 +163,7 @@ nr_virtfn'是è¦å¯ç”¨çš„VFçš„ç¼–å·ã€‚
.id_table = dev_id_table,
.probe = dev_probe,
.remove = dev_remove,
- .suspend = dev_suspend,
- .resume = dev_resume,
+ .driver.pm = &dev_pm_ops
.shutdown = dev_shutdown,
.sriov_configure = dev_sriov_configure,
};
diff --git a/Documentation/translations/zh_CN/PCI/pci.rst b/Documentation/translations/zh_CN/PCI/pci.rst
index 520707787256..83c2a41d38d3 100644
--- a/Documentation/translations/zh_CN/PCI/pci.rst
+++ b/Documentation/translations/zh_CN/PCI/pci.rst
@@ -255,13 +255,13 @@ pci_set_master()将通过设置PCI_COMMAND寄存器中的总线主控ä½æ¥å¯ç”
虽然所有的驱动程åºéƒ½åº”该明确指出PCI总线主控的DMA功能(如32ä½æˆ–64ä½ï¼‰ï¼Œä½†å¯¹äºŽæµå¼
æ•°æ®æ¥è¯´ï¼Œå…·æœ‰è¶…过32ä½æ€»çº¿ä¸»ç«™åŠŸèƒ½çš„设备需è¦é©±åŠ¨ç¨‹åºé€šè¿‡è°ƒç”¨å¸¦æœ‰é€‚当å‚æ•°çš„
-``pci_set_dma_mask()`` æ¥â€œæ³¨å†Œâ€è¿™ç§åŠŸèƒ½ã€‚一般æ¥è¯´ï¼Œåœ¨ç³»ç»ŸRAM高于4G物ç†åœ°å€çš„情
+``dma_set_mask()`` æ¥â€œæ³¨å†Œâ€è¿™ç§åŠŸèƒ½ã€‚一般æ¥è¯´ï¼Œåœ¨ç³»ç»ŸRAM高于4G物ç†åœ°å€çš„情
况下,这å…许更有效的DMA。
-所有PCI-Xå’ŒPCIe兼容设备的驱动程åºå¿…须调用 ``pci_set_dma_mask()`` ,因为它们
+所有PCI-Xå’ŒPCIe兼容设备的驱动程åºå¿…须调用 ``dma_set_mask()`` ,因为它们
是64ä½DMA设备。
-åŒæ ·ï¼Œå¦‚果设备å¯ä»¥é€šè¿‡è°ƒç”¨ ``pci_set_consistent_dma_mask()`` 直接寻å€åˆ°
+åŒæ ·ï¼Œå¦‚果设备å¯ä»¥é€šè¿‡è°ƒç”¨ ``dma_set_coherent_mask()`` 直接寻å€åˆ°
4G物ç†åœ°å€ä»¥ä¸Šçš„系统RAM中的“一致性内存â€ï¼Œé‚£ä¹ˆé©±åŠ¨ç¨‹åºä¹Ÿå¿…须“注册â€è¿™ç§åŠŸèƒ½ã€‚åŒ
样,这包括所有PCI-Xå’ŒPCIe兼容设备的驱动程åºã€‚许多64ä½â€œPCIâ€è®¾å¤‡ï¼ˆåœ¨PCI-X之å‰ï¼‰
和一些PCI-X设备对有效载è·ï¼ˆâ€œæµå¼â€ï¼‰æ•°æ®å…·æœ‰64ä½DMA功能,但对控制(“一致性â€ï¼‰æ•°
diff --git a/Documentation/translations/zh_CN/admin-guide/index.rst b/Documentation/translations/zh_CN/admin-guide/index.rst
index be535ffaf4b0..2f6970d0a032 100644
--- a/Documentation/translations/zh_CN/admin-guide/index.rst
+++ b/Documentation/translations/zh_CN/admin-guide/index.rst
@@ -36,6 +36,7 @@ Todolist:
:maxdepth: 1
reporting-issues
+ reporting-regressions
security-bugs
bug-hunting
bug-bisect
@@ -44,7 +45,6 @@ Todolist:
Todolist:
-* reporting-bugs
* ramoops
* dynamic-debug-howto
* kdump/index
diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst
index eee0e8c5c368..2c7d9106e399 100644
--- a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst
+++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst
@@ -210,6 +210,8 @@ schemes/<N>/
- ``pageout``: 为具有 ``MADV_PAGEOUT`` 的区域调用 ``madvise()`` 。
- ``hugepage``: 为带有 ``MADV_HUGEPAGE`` 的区域调用 ``madvise()`` 。
- ``nohugepage``: 为带有 ``MADV_NOHUGEPAGE`` 的区域调用 ``madvise()``。
+ - ``lru_prio``: 在其LRU列表上对区域进行优先排åºã€‚
+ - ``lru_deprio``: 对区域的LRU列表进行é™ä½Žä¼˜å…ˆå¤„ç†ã€‚
- ``stat``: 什么都ä¸åšï¼Œåªè®¡ç®—统计数æ®
schemes/<N>/access_pattern/
diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst
index 6b4988da2c5a..59e51e3539b4 100644
--- a/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst
+++ b/Documentation/translations/zh_CN/admin-guide/reporting-issues.rst
@@ -1,13 +1,6 @@
.. 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.
+.. See the bottom of this file for additional redistribution information.
+
.. include:: ../disclaimer-zh_CN.rst
@@ -29,7 +22,9 @@
请æœç´¢ `LKML内核邮件列表 <https://lore.kernel.org/lkml/>`_ å’Œ
`Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ 存档中匹é…的报告并
加入讨论。如果找ä¸åˆ°åŒ¹é…的报告,请安装该系列的最新版本。如果它ä»ç„¶å‡ºçŽ°é—®é¢˜ï¼Œ
-报告给稳定版邮件列表(stable@vger.kernel.org)。
+请报告给稳定版邮件列表(stable@vger.kernel.org)并抄é€å›žå½’邮件列表
+(regressions@lists.linux.dev);ç†æƒ³æƒ…况下,还å¯ä»¥æŠ„é€ç»´æŠ¤è€…和相关å­ç³»ç»Ÿçš„
+邮件列表。
在所有其他情况下,请尽å¯èƒ½çŒœæµ‹æ˜¯å“ªä¸ªå†…核部分导致了问题。查看MAINTAINERS文件,
了解开å‘人员希望如何得知问题,大多数情况下,报告问题都是通过电å­é‚®ä»¶å’ŒæŠ„é€
@@ -46,9 +41,10 @@
有使用附加模å—)。还è¦ç¡®ä¿å®ƒæ˜¯åœ¨ä¸€ä¸ªæ­£å¸¸çš„环境中构建和è¿è¡Œï¼Œå¹¶ä¸”在问题å‘生
之å‰æ²¡æœ‰è¢«æ±¡æŸ“(tainted)。
-在编写报告时,è¦æ¶µç›–与问题相关的所有信æ¯ï¼Œå¦‚使用的内核和å‘行版。在碰è§å›žå½’时,
-å°è¯•ç»™å‡ºå¼•å…¥å®ƒçš„更改的æ交ID,二分å¯ä»¥æ‰¾åˆ°å®ƒã€‚如果您åŒæ—¶é¢ä¸´Linux内核的多个
-问题,请分别报告æ¯ä¸ªé—®é¢˜ã€‚
+当你åŒæ—¶é¢ä¸´Linux内核的多个问题时,请分别报告。在编写报告时,è¦æ¶µç›–与问题
+相关的所有信æ¯ï¼Œå¦‚使用的内核和å‘行版。如果碰è§å›žå½’,请把报告抄é€å›žå½’邮件列表
+(regressions@lists.linux.dev)。也请试试用二分法找出æºå¤´ï¼›å¦‚æžœæˆåŠŸæ‰¾åˆ°ï¼Œè¯·
+在报告中写上它的æ交ID并抄é€sign-off-by链中的所有人。
一旦报告å‘出,请回答任何出现的问题,并尽å¯èƒ½åœ°æ供帮助。这包括通过ä¸æ—¶é‡æ–°
测试新版本并å‘é€çŠ¶æ€æ›´æ–°æ¥æŽ¨åŠ¨è¿›å±•ã€‚
@@ -156,9 +152,10 @@
存在问题,因为问题å¯èƒ½å·²ç»åœ¨é‚£é‡Œè¢«ä¿®å¤äº†ã€‚如果您第一次å‘现供应商内核的问题,
请检查已知最新版本的普通构建是å¦å¯ä»¥æ­£å¸¸è¿è¡Œã€‚
- * å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸ­çš„问题报告(stable@vger.kernel.org)。大致
- æ述问题,并解释如何å¤çŽ°ã€‚讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ­£å¸¸çš„版本。
- 然åŽç­‰å¾…进一步的指示。
+ * å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸ­çš„问题报告(stable@vger.kernel.org)并抄é€
+ Linux回归邮件列表(regressions@lists.linux.dev);如果你怀疑是由æŸå­ç³»ç»Ÿ
+ 引起的,请抄é€å…¶ç»´æŠ¤äººå‘˜å’Œå­ç³»ç»Ÿé‚®ä»¶åˆ—表。大致æ述问题,并解释如何å¤çŽ°ã€‚
+ 讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ­£å¸¸çš„版本。然åŽç­‰å¾…进一步的指示。
下é¢çš„å‚考章节部分详细解释了这些步骤中的æ¯ä¸€æ­¥ã€‚
@@ -296,17 +293,14 @@ Linus Torvalds和主è¦çš„Linux内核开å‘人员希望看到一些问题尽快å
报告过程中有一些“高优先级问题â€çš„处ç†ç•¥æœ‰ä¸åŒã€‚有三ç§æƒ…况符åˆæ¡ä»¶:回归ã€å®‰å…¨
问题和éžå¸¸ä¸¥é‡çš„问题。
-如果在旧版本的Linux内核中工作的东西ä¸èƒ½åœ¨æ–°ç‰ˆæœ¬çš„Linux内核中工作,或者æŸç§
-程度上在新版本的Linux内核中工作得更差,那么你就需è¦å¤„ç†â€œå›žå½’â€ã€‚因此,当一个
-在Linux 5.7中表现良好的WiFi驱动程åºåœ¨5.8中表现ä¸ä½³æˆ–根本ä¸èƒ½å·¥ä½œæ—¶ï¼Œè¿™æ˜¯ä¸€
-ç§å›žå½’。如果应用程åºåœ¨æ–°çš„内核中出现ä¸ç¨³å®šçš„现象,这也是一ç§å›žå½’,这å¯èƒ½æ˜¯
-由于内核和用户空间之间的接å£ï¼ˆå¦‚procfså’Œsysfs)å‘生ä¸å…¼å®¹çš„更改造æˆçš„。显著
-的性能é™ä½Žæˆ–功耗增加也å¯ä»¥ç§°ä¸ºå›žå½’。但是请记ä½:新内核需è¦ä½¿ç”¨ä¸Žæ—§å†…核相似的
-é…ç½®æ¥æž„建(å‚è§ä¸‹é¢å¦‚何实现这一点)。这是因为内核开å‘人员在实现新特性时有
-时无法é¿å…ä¸å…¼å®¹æ€§ï¼›ä½†æ˜¯ä¸ºäº†é¿å…回归,这些特性必须在构建é…置期间显å¼åœ°å¯ç”¨ã€‚
+如果æŸä¸ªåº”用程åºæˆ–实际用例在原先的Linux内核上è¿è¡Œè‰¯å¥½ï¼Œä½†åœ¨ä½¿ç”¨ç±»ä¼¼é…置编译的
+较新版本上效果更差ã€æˆ–者根本ä¸èƒ½ç”¨ï¼Œé‚£ä¹ˆä½ å°±éœ€è¦å¤„ç†å›žå½’问题。
+Documentation/admin-guide/reporting-regressions.rst 对此进行了更详细的解释。
+它还æ供了很多你å¯èƒ½æƒ³çŸ¥é“的关于回归的其他信æ¯ï¼›ä¾‹å¦‚,它解释了如何将您的问题
+添加到回归跟踪列表中,以确ä¿å®ƒä¸ä¼šè¢«å¿½ç•¥ã€‚
什么是安全问题留给您自己判断。在继续之å‰ï¼Œè¯·è€ƒè™‘阅读
-“Documentation/translations/zh_CN/admin-guide/security-bugs.rstâ€ï¼Œ
+Documentation/translations/zh_CN/admin-guide/security-bugs.rst ,
因为它æ供了如何最æ°å½“地处ç†å®‰å…¨é—®é¢˜çš„é¢å¤–细节。
当å‘生了完全无法接å—的糟糕事情时,此问题就是一个“éžå¸¸ä¸¥é‡çš„问题â€ã€‚例如,
@@ -390,7 +384,7 @@ Linux内核破å了它处ç†çš„æ•°æ®æˆ–æŸå了它è¿è¡Œçš„硬件。当内核
核未被污染,那么它应该以“Not infectedâ€ç»“æŸï¼›å¦‚果你看到“Tainted:â€ä¸”åŽè·Ÿä¸€äº›
空格和字æ¯ï¼Œé‚£å°±è¢«æ±¡æŸ“了。
-如果你的内核被污染了,请阅读“Documentation/translations/zh_CN/admin-guide/tainted-kernels.rstâ€
+如果你的内核被污染了,请阅读 Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst
以找出原因。设法消除污染因素。通常是由以下三ç§å› ç´ ä¹‹ä¸€å¼•èµ·çš„:
1. å‘生了一个å¯æ¢å¤çš„错误(“kernel Oopsâ€ï¼‰ï¼Œå†…核污染了自己,因为内核知é“在
@@ -591,7 +585,8 @@ ath10k@lists.infradead.orgâ€ï¼Œå°†å¼•å¯¼æ‚¨åˆ°ath10k邮件列表的信æ¯é¡µï¼Œ
æœç´¢å¼•æ“Žï¼Œå¹¶æ·»åŠ ç±»ä¼¼â€œsite:lists.infadead.org/pipermail/ath10k/â€è¿™
æ ·çš„æœç´¢æ¡ä»¶ï¼Œè¿™ä¼šæŠŠç»“æžœé™åˆ¶åœ¨è¯¥é“¾æŽ¥ä¸­çš„档案。
-也请进一步æœç´¢ç½‘络ã€LKMLå’Œbugzilla.kernel.org网站。
+也请进一步æœç´¢ç½‘络ã€LKMLå’Œbugzilla.kernel.org网站。如果你的报告需è¦å‘é€åˆ°ç¼ºé™·
+跟踪器中,那么您å¯èƒ½è¿˜éœ€è¦æ£€æŸ¥å­ç³»ç»Ÿçš„邮件列表存档,因为å¯èƒ½æœ‰äººåªåœ¨é‚£é‡ŒæŠ¥å‘Šäº†å®ƒã€‚
有关如何æœç´¢ä»¥åŠåœ¨æ‰¾åˆ°åŒ¹é…报告时如何æ“作的详细信æ¯ï¼Œè¯·å‚阅上é¢çš„“æœç´¢çŽ°æœ‰æŠ¥å‘Š
(第一部分)â€ã€‚
@@ -802,10 +797,10 @@ Linux 首席开å‘者 Linus Torvalds 认为 Linux 内核永远ä¸åº”æ¶åŒ–,这
é‡çŽ°å®ƒã€‚
有一个å«åšâ€œäºŒåˆ†â€çš„过程å¯ä»¥æ¥å¯»æ‰¾å˜åŒ–,这在
-“Documentation/translations/zh_CN/admin-guide/bug-bisect.rstâ€æ–‡æ¡£ä¸­è¿›è¡Œäº†è¯¦ç»†
+Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 文档中进行了详细
çš„æ述,这个过程通常需è¦ä½ æž„建å到二å个内核镜åƒï¼Œæ¯æ¬¡éƒ½å°è¯•åœ¨æž„建下一个镜åƒ
之å‰é‡çŽ°é—®é¢˜ã€‚是的,这需è¦èŠ±è´¹ä¸€äº›æ—¶é—´ï¼Œä½†ä¸ç”¨æ‹…心,它比大多数人想象的è¦å¿«å¾—多。
-多äºäº†â€œbinary search二进制æœç´¢â€ï¼Œè¿™å°†å¼•å¯¼ä½ åœ¨æºä»£ç ç®¡ç†ç³»ç»Ÿä¸­æ‰¾åˆ°å¯¼è‡´å›žå½’çš„æ交。
+多äºäº†â€œbinary search二分æœç´¢â€ï¼Œè¿™å°†å¼•å¯¼ä½ åœ¨æºä»£ç ç®¡ç†ç³»ç»Ÿä¸­æ‰¾åˆ°å¯¼è‡´å›žå½’çš„æ交。
一旦你找到它,就在网上æœç´¢å…¶ä¸»é¢˜ã€æ交ID和缩短的æ交ID(æ交IDçš„å‰12个字符)。
如果有的è¯ï¼Œè¿™å°†å¼•å¯¼æ‚¨æ‰¾åˆ°å…³äºŽå®ƒçš„现有报告。
@@ -823,10 +818,10 @@ Linux 首席开å‘者 Linus Torvalds 认为 Linux 内核永远ä¸åº”æ¶åŒ–,这
当处ç†å›žå½’问题时,请确ä¿ä½ æ‰€é¢ä¸´çš„问题真的是由内核引起的,而ä¸æ˜¯ç”±å…¶ä»–东西
引起的,如上文所述。
-在整个过程中,请记ä½ï¼šåªæœ‰å½“旧内核和新内核的é…置相似时,问题æ‰ç®—回归。最好
-的方法是:把é…置文件(``.config``)从旧的工作内核直接å¤åˆ¶åˆ°ä½ å°è¯•çš„æ¯ä¸ªæ–°å†…
-核版本。之åŽè¿è¡Œ ``make oldnoconfig`` æ¥è°ƒæ•´å®ƒä»¥é€‚应新版本的需è¦ï¼Œè€Œä¸å¯ç”¨
-任何新的功能,因为那些功能也å¯èƒ½å¯¼è‡´å›žå½’。
+在整个过程中,请记ä½ï¼šåªæœ‰å½“旧内核和新内核的é…置相似时,问题æ‰ç®—回归。这å¯ä»¥
+通过 ``make olddefconfig`` æ¥å®žçŽ°ï¼Œè¯¦ç»†è§£é‡Šå‚è§
+Documentation/admin-guide/reporting-regressions.rst ;它还æ供了大é‡å…¶ä»–您
+å¯èƒ½å¸Œæœ›äº†è§£çš„有关回归的信æ¯ã€‚
撰写并å‘é€æŠ¥å‘Š
@@ -959,11 +954,19 @@ Linux 首席开å‘者 Linus Torvalds 认为 Linux 内核永远ä¸åº”æ¶åŒ–,这
**éžå¸¸ä¸¥é‡çš„缺陷** :确ä¿åœ¨ä¸»é¢˜æˆ–å·¥å•æ ‡é¢˜ä»¥åŠç¬¬ä¸€æ®µä¸­æ˜Žæ˜¾æ ‡å‡º severeness
(éžå¸¸ä¸¥é‡çš„)。
-**回归** :如果问题是一个回归,请在邮件的主题或缺陷跟踪器的标题中添加
-[REGRESSION]。如果您没有进行二分,请至少注明您测试的最新主线版本(比如 5.7)
-和出现问题的最新版本(比如 5.8)。如果您æˆåŠŸåœ°è¿›è¡Œäº†äºŒåˆ†ï¼Œè¯·æ³¨æ˜Žå¯¼è‡´å›žå½’
-çš„æ交ID和主题。也请添加该å˜æ›´çš„作者到你的报告中;如果您需è¦å°†æ‚¨çš„缺陷æ交
-到缺陷跟踪器中,请将报告以ç§äººé‚®ä»¶çš„å½¢å¼è½¬å‘给他,并注明报告æ交地点。
+**回归** :报告的主题应以“[REGRESSION]â€å¼€å¤´ã€‚
+
+如果您æˆåŠŸç”¨äºŒåˆ†æ³•å®šä½äº†é—®é¢˜ï¼Œè¯·ä½¿ç”¨å¼•å…¥å›žå½’之更改的标题作为主题的第二部分。
+请在报告中写明“罪é­ç¥¸é¦–â€çš„æ交ID。如果未能æˆåŠŸäºŒåˆ†ï¼Œè¯·åœ¨æŠ¥å‘Šä¸­è®²æ˜Žæœ€åŽä¸€ä¸ª
+正常工作的版本(例如5.7)和最先å‘生问题的版本(例如5.8-rc1)。
+
+通过邮件å‘é€æŠ¥å‘Šæ—¶ï¼Œè¯·æŠ„é€Linux回归邮件列表(regressions@lists.linux.dev)。
+如果报告需è¦æ交到æŸä¸ªweb追踪器,请继续æ交;并在æ交åŽï¼Œé€šè¿‡é‚®ä»¶å°†æŠ¥å‘Šè½¬å‘
+至回归列表;抄é€ç›¸å…³å­ç³»ç»Ÿçš„维护人员和邮件列表。请确ä¿æŠ¥å‘Šæ˜¯å†…è”转å‘的,ä¸è¦
+把它作为附件。å¦å¤–请在顶部添加一个简短的说明,在那里写上工å•çš„网å€ã€‚
+
+在邮寄或转å‘报告时,如果æˆåŠŸäºŒåˆ†ï¼Œéœ€è¦å°†â€œç½ªé­ç¥¸é¦–â€çš„作者添加到收件人中;åŒæ—¶
+抄é€signed-off-by链中的æ¯ä¸ªäººï¼Œæ‚¨å¯ä»¥åœ¨æ交消æ¯çš„末尾找到。
**安全问题** :对于这ç§é—®é¢˜ï¼Œä½ å°†å¿…须评估:如果细节被公开披露,是å¦ä¼šå¯¹å…¶ä»–
用户产生短期风险。如果ä¸ä¼šï¼Œåªéœ€æŒ‰ç…§æ‰€è¿°ç»§ç»­æŠ¥å‘Šé—®é¢˜ã€‚如果有此风险,你需è¦
@@ -980,7 +983,7 @@ Linux 首席开å‘者 Linus Torvalds 认为 Linux 内核永远ä¸åº”æ¶åŒ–,这
报告,请将报告的文本转å‘到这些地å€ï¼›ä½†è¯·åœ¨æŠ¥å‘Šçš„顶部加上注释,表明您æ交了
报告,并附上工å•é“¾æŽ¥ã€‚
-更多信æ¯è¯·å‚è§â€œDocumentation/translations/zh_CN/admin-guide/security-bugs.rstâ€ã€‚
+更多信æ¯è¯·å‚è§ Documentation/translations/zh_CN/admin-guide/security-bugs.rst 。
å‘布报告åŽçš„责任
@@ -1173,14 +1176,18 @@ FLOSS 问题报告的人看,询问他们的æ„è§ã€‚åŒæ—¶å¾æ±‚他们关于å¦
报告回归
~~~~~~~~~~
- *å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸ­çš„问题报告(stable@vger.kernel.org)。
- 大致æ述问题,并解释如何å¤çŽ°ã€‚讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ­£å¸¸
- 的版本。然åŽç­‰å¾…进一步的指示。*
+ *å‘Linux稳定版邮件列表å‘é€ä¸€ä¸ªç®€çŸ­çš„问题报告(stable@vger.kernel.org)并
+ 抄é€Linux回归邮件列表(regressions@lists.linux.dev);如果你怀疑是由æŸ
+ å­ç³»ç»Ÿå¼•èµ·çš„,请抄é€å…¶ç»´æŠ¤äººå‘˜å’Œå­ç³»ç»Ÿé‚®ä»¶åˆ—表。大致æ述问题,并解释如
+ 何å¤çŽ°ã€‚讲清楚首个出现问题的版本和最åŽä¸€ä¸ªå·¥ä½œæ­£å¸¸çš„版本。然åŽç­‰å¾…进一
+ 步的指示。*
当报告在稳定版或长期支æŒå†…核线内å‘生的回归(例如在从5.10.4更新到5.10.5时),
-一份简短的报告足以快速报告问题。因此åªéœ€è¦ç²—略的æ述。
+一份简短的报告足以快速报告问题。因此åªéœ€å‘稳定版和回归邮件列表å‘é€ç²—略的æè¿°ï¼›
+ä¸è¿‡å¦‚果你怀疑æŸå­ç³»ç»Ÿå¯¼è‡´æ­¤é—®é¢˜çš„è¯ï¼Œè¯·ä¸€å¹¶æŠ„é€å…¶ç»´æŠ¤äººå‘˜å’Œå­ç³»ç»Ÿé‚®ä»¶åˆ—表,
+这会加快进程。
-但是请注æ„,如果您能够指明引入问题的确切版本,这将对开å‘人员有很大帮助。因此
+请注æ„,如果您能够指明引入问题的确切版本,这将对开å‘人员有很大帮助。因此
如果有时间的è¯ï¼Œè¯·å°è¯•ä½¿ç”¨æ™®é€šå†…核找到该版本。让我们å‡è®¾å‘行版å‘布Linux内核
5.10.5到5.10.8çš„æ›´æ–°æ—¶å‘生了故障。那么按照上é¢çš„指示,去检查该版本线中的最新
内核,比如5.10.9。如果问题出现,请å°è¯•æ™®é€š5.10.5,以确ä¿ä¾›åº”商应用的补ä¸ä¸ä¼š
@@ -1190,7 +1197,9 @@ FLOSS 问题报告的人看,询问他们的æ„è§ã€‚åŒæ—¶å¾æ±‚他们关于å¦
å‰ä¸€æ®µåŸºæœ¬ç²—略地概述了“二分â€æ–¹æ³•ã€‚一旦报告出æ¥ï¼Œæ‚¨å¯èƒ½ä¼šè¢«è¦æ±‚åšä¸€ä¸ªæ­£ç¡®çš„
报告,因为它å…许精确地定ä½å¯¼è‡´é—®é¢˜çš„确切更改(然åŽå¾ˆå®¹æ˜“被æ¢å¤ä»¥å¿«é€Ÿä¿®å¤é—®é¢˜ï¼‰ã€‚
因此如果时间å…许,考虑立å³è¿›è¡Œé€‚当的二分。有关如何详细信æ¯ï¼Œè¯·å‚阅“对回归的
-特别关照â€éƒ¨åˆ†å’Œæ–‡æ¡£â€œDocumentation/translations/zh_CN/admin-guide/bug-bisect.rstâ€ã€‚
+特别关照â€éƒ¨åˆ†å’Œæ–‡æ¡£ Documentation/translations/zh_CN/admin-guide/bug-bisect.rst 。
+如果æˆåŠŸäºŒåˆ†çš„è¯ï¼Œè¯·å°†â€œç½ªé­ç¥¸é¦–â€çš„作者添加到收件人中;åŒæ—¶æŠ„é€æ‰€æœ‰åœ¨
+signed-off-by链中的人,您å¯ä»¥åœ¨æ交消æ¯çš„末尾找到。
“报告仅在旧内核版本线中å‘生的问题â€çš„å‚考
@@ -1207,7 +1216,7 @@ FLOSS 问题报告的人看,询问他们的æ„è§ã€‚åŒæ—¶å¾æ±‚他们关于å¦
å³ä½¿æ˜¯å¾®å°çš„ã€çœ‹ä¼¼æ˜Žæ˜¾çš„代ç å˜åŒ–,有时也会带æ¥æ–°çš„ã€å®Œå…¨æ„想ä¸åˆ°çš„问题。稳
定版和长期支æŒå†…核的维护者éžå¸¸æ¸…楚这一点,因此他们åªå¯¹è¿™äº›å†…核进行符åˆ
-“Documentation/translations/zh_CN/process/stable-kernel-rules.rstâ€ä¸­æ‰€åˆ—出的
+Documentation/translations/zh_CN/process/stable-kernel-rules.rst 中所列出的
规则的修改。
å¤æ‚或有风险的修改ä¸ç¬¦åˆæ¡ä»¶ï¼Œå› æ­¤åªèƒ½åº”用于主线。其他的修å¤å¾ˆå®¹æ˜“被回溯到
@@ -1333,3 +1342,27 @@ FLOSS 问题报告的人看,询问他们的æ„è§ã€‚åŒæ—¶å¾æ±‚他们关于å¦
å‘ Linux 内核开å‘者报告问题是很难的:这个文档的长度和å¤æ‚性以åŠå­—里行间的内
涵都说明了这一点。但目å‰å°±æ˜¯è¿™æ ·äº†ã€‚这篇文字的主è¦ä½œè€…希望通过记录现状æ¥ä¸º
以åŽæ”¹å–„è¿™ç§çŠ¶å†µæ‰“下一些基础。
+
+
+..
+ end-of-content
+..
+ This English version of this document is maintained by Thorsten Leemhuis
+ <linux@leemhuis.info>. If you spot a typo or small mistake, feel free to
+ let him know directly and he'll fix it. For translation problems, please
+ contact with translators. You are free to do the same in a mostly informal
+ way if you want to contribute changes to the text, but for copyright
+ reasons please CC linux-doc@vger.kernel.org and "sign-off" your
+ contribution as Documentation/process/submitting-patches.rst outlines in
+ the section "Sign your work - the Developer's Certificate of Origin".
+..
+ This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
+ of the file. 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.
diff --git a/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst b/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst
new file mode 100644
index 000000000000..c0461ee855bc
--- /dev/null
+++ b/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst
@@ -0,0 +1,370 @@
+.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
+.. ã€é‡åˆ†å‘ä¿¡æ¯å‚è§æœ¬æ–‡ä»¶ç»“尾】
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/admin-guide/reporting-regressions.rst
+
+:译者:
+
+ å´æƒ³æˆ Wu XiangCheng <bobwxc@email.cn>
+
+
+============
+报告回归问题
+============
+
+“*我们拒ç»å‡ºçŽ°å›žå½’*â€æ˜¯Linux内核开å‘的首è¦è§„则;Linuxçš„å‘起者和领军开å‘者Linus
+Torvalds立下了此规则并确ä¿å®ƒè¢«è½å®žã€‚
+
+本文档æ述了这æ¡è§„则对用户的æ„义,以åŠLinux内核开å‘模型如何确ä¿è§£å†³æ‰€æœ‰è¢«æŠ¥å‘Š
+的回归;关于内核开å‘者如何处ç†çš„æ–¹é¢å‚è§ Documentation/process/handling-regressions.rst 。
+
+
+本文é‡ç‚¹ï¼ˆäº¦å³â€œå¤ªé•¿ä¸çœ‹â€ï¼‰
+==========================
+
+#. 如果æŸç¨‹åºåœ¨åŽŸå…ˆçš„Linux内核上è¿è¡Œè‰¯å¥½ï¼Œä½†åœ¨è¾ƒæ–°ç‰ˆæœ¬ä¸Šæ•ˆæžœæ›´å·®ã€æˆ–者根本ä¸
+ 能用,那么你就碰è§å›žå½’问题了。注æ„,新内核需è¦ä½¿ç”¨ç±»ä¼¼é…置编译;更多相关细
+ 节å‚è§ä¸‹æ–¹ã€‚
+
+#. 按照 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 中
+ 所说的报告你的问题,该文档已ç»åŒ…å«äº†æ‰€æœ‰å…³äºŽå›žå½’çš„é‡è¦æ–¹é¢ï¼Œä¸ºäº†æ–¹ä¾¿èµ·è§ä¹Ÿ
+ å¤åˆ¶åˆ°äº†ä¸‹é¢ã€‚两个é‡ç‚¹ï¼šåœ¨æŠ¥å‘Šä¸»é¢˜ä¸­ä½¿ç”¨â€œ[REGRESSION]â€å¼€å¤´å¹¶æŠ„é€æˆ–转å‘到
+ `回归邮件列表 <https://lore.kernel.org/regressions/>`_
+ (regressions@lists.linux.dev)。
+
+#. å¯é€‰ä½†æ˜¯å»ºè®®ï¼šåœ¨å‘é€æˆ–转å‘报告时,指明该回归å‘生的起点,以便Linux内核回归
+ 追踪机器人“regzbotâ€å¯ä»¥è¿½è¸ªæ­¤é—®é¢˜::
+
+ #regzbot introduced v5.13..v5.14-rc1
+
+
+与用户相关的所有Linux内核回归细节
+=================================
+
+
+基本é‡ç‚¹
+--------
+
+
+什么是“回归â€ä»¥åŠä»€ä¹ˆæ˜¯â€œæ— å›žå½’规则â€ï¼Ÿ
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+如果æŸç¨‹åº/实例在原先的Linux内核上è¿è¡Œè‰¯å¥½ï¼Œä½†åœ¨è¾ƒæ–°ç‰ˆæœ¬ä¸Šæ•ˆæžœæ›´å·®ã€æˆ–者根本
+ä¸èƒ½ç”¨ï¼Œé‚£ä¹ˆä½ å°±ç¢°è§å›žå½’问题了。“无回归规则â€ä¸å…许出现这ç§æƒ…况。如果å¶ç„¶å‘
+生了,导致问题的开å‘者应当迅速修å¤é—®é¢˜ã€‚
+
+也就是说,若Linux 5.13中的WiFi驱动程åºè¿è¡Œè‰¯å¥½ï¼Œä½†æ˜¯åœ¨5.14版本上å´ä¸èƒ½ç”¨ã€é€Ÿ
+度明显å˜æ…¢æˆ–出现错误,那就出现了回归。如果æŸæ­£å¸¸å·¥ä½œçš„应用程åºçªç„¶åœ¨æ–°å†…核上
+出现ä¸ç¨³å®šï¼Œè¿™ä¹Ÿæ˜¯å›žå½’;这些问题å¯èƒ½æ˜¯ç”±äºŽprocfsã€sysfs或Linuxæ供给用户空间
+软件的许多其他接å£ä¹‹ä¸€çš„å˜åŒ–。但请记ä½ï¼Œå‰è¿°ä¾‹å­ä¸­çš„5.14需è¦ä½¿ç”¨ç±»ä¼¼äºŽ5.13çš„
+é…置构建。这å¯ä»¥ç”¨ ``make olddefconfig`` 实现,详细解释è§ä¸‹ã€‚
+
+注æ„本节第一å¥è¯ä¸­çš„“实例â€ï¼šå³ä½¿å¼€å‘者需è¦éµå¾ªâ€œæ— å›žå½’â€è§„则,但ä»å¯è‡ªç”±åœ°æ”¹
+å˜å†…核的任何方é¢ï¼Œç”šè‡³æ˜¯å¯¼å‡ºåˆ°ç”¨æˆ·ç©ºé—´çš„API或ABI,åªè¦åˆ«ç ´å现有的应用程åºæˆ–
+用例。
+
+还需注æ„,“无回归â€è§„则åªé™åˆ¶å†…æ ¸æ供给用户空间的接å£ã€‚它ä¸é€‚用于内核内部接
+å£ï¼Œæ¯”如一些外部开å‘的驱动程åºç”¨æ¥æ’入钩å­åˆ°å†…核的模å—API。
+
+如何报告回归?
+~~~~~~~~~~~~~~
+
+åªéœ€æŒ‰ç…§ Documentation/translations/zh_CN/admin-guide/reporting-issues.rst 中
+所说的报告你的问题,该文档已ç»åŒ…å«äº†è¦ç‚¹ã€‚下é¢å‡ ç‚¹æ¦‚述了一下åªåœ¨å›žå½’中é‡è¦çš„
+æ–¹é¢ï¼š
+
+ * 在检查å¯åŠ å…¥è®¨è®ºçš„现有报告时,别忘了æœç´¢ `Linux回归邮件列表
+ <https://lore.kernel.org/regressions/>`_ å’Œ `regzbot网页界é¢
+ <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。
+
+ * 在报告主题的开头加上“[REGRESSION]â€ã€‚
+
+ * 在你的报告中明确最åŽä¸€ä¸ªæ­£å¸¸å·¥ä½œçš„内核版本和首个出问题的版本。如若å¯èƒ½ï¼Œ
+ 用二分法å°è¯•æ‰¾å‡ºå¯¼è‡´å›žå½’çš„å˜æ›´ï¼Œæ›´å¤šç»†èŠ‚è§ä¸‹ã€‚
+
+ * 记得把报告å‘到Linux回归邮件列表(regressions@lists.linux.dev)。
+
+ * 如果通过邮件报告回归,请抄é€å›žå½’列表。
+
+ * 如果你使用æŸäº›ç¼ºé™·è¿½è¸ªå™¨æŠ¥å‘Šå›žå½’,请通过邮件转å‘å·²æ交的报告到回归列表,
+ 并抄é€ç»´æŠ¤è€…以åŠå‡ºé—®é¢˜çš„相关å­ç³»ç»Ÿçš„邮件列表。
+
+ 如果是稳定版或长期支æŒç‰ˆç³»åˆ—(如v5.15.3…v5.15.5)的回归,请记得抄é€
+ `Linux稳定版邮件列表 <https://lore.kernel.org/stable/>`_ (stable@vger.kernel.org)。
+
+ 如果你æˆåŠŸåœ°æ‰§è¡Œäº†äºŒåˆ†ï¼Œè¯·æŠ„é€è‚‡äº‹æ交的信æ¯ä¸­æ‰€æœ‰ç­¾äº†â€œSigned-off-by:â€çš„人。
+
+在抄é€ä½ çš„报告到列表时,也请记得通知å‰è¿°çš„Linux内核回归追踪机器人。åªéœ€åœ¨é‚®ä»¶
+中包å«å¦‚下片段::
+
+ #regzbot introduced: v5.13..v5.14-rc1
+
+Regzbot会就将你的邮件视为在æŸä¸ªç‰¹å®šç‰ˆæœ¬åŒºé—´çš„回归报告。上例中å³linux v5.13ä»
+然正常,而Linux 5.14-rc1是首个您é‡åˆ°é—®é¢˜çš„版本。如果你执行了二分以查找导致回
+å½’çš„æ交,请使用指定肇事æ交的id代替::
+
+ #regzbot introduced: 1f2e3d4c5d
+
+添加这样的“regzbot命令â€å¯¹ä½ æ˜¯æœ‰å¥½å¤„的,它会确ä¿æŠ¥å‘Šä¸ä¼šè¢«å¿½ç•¥ã€‚如果你çœç•¥äº†
+它,Linux内核的回归跟踪者会把你的回归告诉regzbot,åªè¦ä½ å‘é€äº†ä¸€ä¸ªå‰¯æœ¬åˆ°å›žå½’
+邮件列表。但是回归跟踪者åªæœ‰ä¸€ä¸ªäººï¼Œæœ‰æ—¶ä¸å¾—ä¸ä¼‘æ¯æˆ–甚至å¶å°”享å—å¯ä»¥è¿œç¦»ç”µè„‘
+的时光(å¬èµ·æ¥å¾ˆç–¯ç‹‚)。因此,ä¾èµ–此人手动将回归添加到 `已追踪且尚未解决的
+Linux内核回归列表 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 和
+regzbotå‘é€çš„æ¯å‘¨å›žå½’报告,å¯èƒ½ä¼šå‡ºçŽ°å»¶è¿Ÿã€‚ 这样的延误会导致Linus Torvalds
+在决定“继续开å‘还是å‘布新版本?â€æ—¶å¿½ç•¥ä¸¥é‡çš„回归。
+
+真的修å¤äº†æ‰€æœ‰çš„回归å—?
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+几乎所有都是,åªè¦å¼•èµ·é—®é¢˜çš„å˜æ›´ï¼ˆè‚‡äº‹æ交)被å¯é å®šä½ã€‚也有些回归å¯ä»¥ä¸ç”¨è¿™
+样,但通常是必须的。
+
+è°éœ€è¦æ‰¾å‡ºå›žå½’的根本原因?
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+å—å½±å“代ç åŒºåŸŸçš„å¼€å‘者应该自行å°è¯•å®šä½é—®é¢˜æ‰€åœ¨ã€‚但仅é ä»–们的努力往往是ä¸å¯
+能åšåˆ°çš„,很多问题åªå‘生在开å‘者的无法接触的其他特定外部环境中——例如特定的
+硬件平å°ã€å›ºä»¶ã€Linuxå‘行版ã€ç³»ç»Ÿçš„é…置或应用程åºã€‚这就是为什么最终往往是报
+告者定ä½è‚‡äº‹æ交;有时用户甚至需è¦å†è¿è¡Œé¢å¤–测试以查明确切的根本原因。开å‘
+者应该æ供建议和å¯èƒ½çš„帮助,以使普通用户更容易完æˆè¯¥æµç¨‹ã€‚
+
+如何找到罪é­ç¥¸é¦–?
+~~~~~~~~~~~~~~~~~~
+
+如 Documentation/translations/zh_CN/admin-guide/reporting-issues.rst (简è¦ï¼‰
+和 Documentation/translations/zh_CN/admin-guide/bug-bisect.rst (详细)中所
+述,执行二分。å¬èµ·æ¥å·¥ä½œé‡å¾ˆå¤§ï¼Œä½†å¤§éƒ¨åˆ†æƒ…况下很快就能找到罪é­ç¥¸é¦–。如果这很
+困难或å¯é åœ°é‡çŽ°é—®é¢˜å¾ˆè€—时,请考虑与其他å—å½±å“的用户åˆä½œï¼Œä¸€èµ·ç¼©å°æœç´¢èŒƒå›´ã€‚
+
+当出现回归时我å¯ä»¥å‘è°å¯»æ±‚建议?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+å‘é€é‚®ä»¶åˆ°å›žå½’邮件列表(regressions@lists.linux.dev)åŒæ—¶æŠ„é€Linux内核的回归
+跟踪者(regressions@leemhuis.info);如果问题需è¦ä¿å¯†å¤„ç†ï¼Œå¯ä»¥çœç•¥åˆ—表。
+
+
+关于回归的更多细节
+------------------
+
+
+“无回归规则â€çš„目标是什么?
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+用户应该放心å‡çº§å†…核版本,而ä¸å¿…担心有程åºå¯èƒ½å´©æºƒã€‚这符åˆå†…核开å‘者的利益,
+å¯ä»¥ä½¿æ›´æ–°æœ‰å¸å¼•åŠ›ï¼šä»–们ä¸å¸Œæœ›ç”¨æˆ·åœç•™åœ¨åœæ­¢ç»´æŠ¤æˆ–超过一年åŠçš„稳定/长期Linux
+版本系列上。这也符åˆæ‰€æœ‰äººçš„利益,因为 `那些系列å¯èƒ½å«æœ‰å·²çŸ¥çš„缺陷ã€å®‰å…¨é—®é¢˜
+或其他åŽç»­ç‰ˆæœ¬å·²ç»ä¿®å¤çš„问题
+<http://www.kroah.com/log/blog/2018/08/24/what-stable-kernel-should-i-use/>`_ 。
+此外,内核开å‘者希望使用户测试最新的预å‘行版或常规å‘行版å˜å¾—简å•è€Œæœ‰å¸å¼•åŠ›ã€‚
+è¿™åŒæ ·ç¬¦åˆæ‰€æœ‰äººçš„利益,如果新版本出æ¥åŽå¾ˆå¿«å°±æœ‰ç›¸å…³æŠ¥å‘Šï¼Œä¼šä½¿è¿½è¸ªå’Œä¿®å¤é—®é¢˜
+更容易。
+
+实际中“无回归â€è§„则真的å¯è¡Œå—?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+è¿™ä¸æ˜¯å¥çŽ©ç¬‘è¯ï¼Œè¯·è§Linux创建者和主è¦å¼€å‘人员Linus Torvalds在邮件列表中的许
+多å‘言,其中一些在 Documentation/process/handling-regressions.rst 中被引用。
+
+此规则的例外情况æžä¸ºç½•è§ï¼›ä¹‹å‰å½“å¼€å‘者认为æŸä¸ªç‰¹å®šçš„情况有必è¦æ´å¼•ä¾‹å¤–时,
+基本都被è¯æ˜Žé”™äº†ã€‚
+
+è°æ¥ç¡®ä¿â€œæ— å›žå½’â€è¢«è½å®žï¼Ÿ
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+照看和支撑树的å­ç³»ç»Ÿç»´æŠ¤è€…应该关心这一点——例如,Linus Torvalds之于主线,
+Greg Kroah-Hartman等人之于å„ç§ç¨³å®š/长期系列。
+
+他们都得到了别人的帮助,以确ä¿å›žå½’报告ä¸ä¼šè¢«é—æ¼ã€‚其中之一是Thorsten
+Leemhuis,他目å‰æ‹…ä»»Linux内核的“回归跟踪者â€ï¼›ä¸ºäº†åšå¥½è¿™é¡¹å·¥ä½œï¼Œä»–使用了
+regzbot——Linux内核回归跟踪机器人。所以这就是为什么è¦æŠ„é€æˆ–转å‘你的报告到
+回归邮件列表æ¥é€šçŸ¥è¿™äº›äººï¼Œå·²ç»æœ€å¥½åœ¨ä½ çš„邮件中包å«â€œregzbot命令â€æ¥ç«‹å³è¿½è¸ªå®ƒã€‚
+
+回归通常多久能修å¤ï¼Ÿ
+~~~~~~~~~~~~~~~~~~~~
+
+å¼€å‘者应该尽快修å¤ä»»ä½•è¢«æŠ¥å‘Šçš„回归,以æä¾›åŠæ—¶ä¸ºå—å½±å“的用户æ供解决方案,并
+防止更多用户é‡åˆ°é—®é¢˜ï¼›ç„¶è€Œï¼Œå¼€å‘人员需è¦èŠ±è¶³å¤Ÿçš„时间和注æ„力确ä¿å›žå½’ä¿®å¤ä¸ä¼š
+造æˆé¢å¤–çš„æŸå®³ã€‚
+
+因此,答案å–决于å„ç§å› ç´ ï¼Œå¦‚回归的影å“ã€å­˜åœ¨æ—¶é•¿æˆ–出现于哪个Linux版本系列。
+但最终,大多数的回归应该在两周内修å¤ã€‚
+
+当问题å¯ä»¥é€šè¿‡å‡çº§æŸäº›è½¯ä»¶è§£å†³æ—¶ï¼Œæ˜¯å›žå½’å—?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+基本都是。如果开å‘人员告诉您其他情况,请咨询上述回归跟踪者。
+
+当新内核å˜æ…¢æˆ–能耗增加,是回归å—?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+是的,但有一些差别。在微型基准测试中å˜æ…¢5%ä¸å¤ªå¯èƒ½è¢«è§†ä¸ºå›žå½’,除éžå®ƒä¹Ÿä¼šå¯¹
+广泛基准测试的结果产生超过1%çš„å½±å“。如果有疑问,请寻求建议。
+
+当更新Linux时外部内核模å—崩溃了,是回归å—?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ä¸ï¼Œå› ä¸ºâ€œæ— å›žå½’â€è§„则仅é™äºŽLinux内核æ供给用户空间的接å£å’ŒæœåŠ¡ã€‚因此,它ä¸åŒ…括
+构建或è¿è¡Œå¤–部开å‘的内核模å—,因为它们在内核空间中è¿è¡Œä¸ŽæŒ‚进内核使用的内部接
+å£å¶å°”会å˜åŒ–。
+
+如何处ç†å®‰å…¨ä¿®å¤å¼•èµ·çš„回归?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+在æžä¸ºç½•è§çš„情况下,安全问题无法在ä¸å¼•èµ·å›žå½’的情况下修å¤ï¼›è¿™äº›ä¿®å¤éƒ½è¢«æ”¾å¼ƒäº†ï¼Œ
+因为它们终究会引起问题。幸è¿çš„是这ç§ä¸¤éš¾å¢ƒåœ°åŸºæœ¬éƒ½å¯ä»¥é¿å…,å—å½±å“区域的主è¦
+å¼€å‘者以åŠLinus Torvalds本人通常都会努力在ä¸å¼•å…¥å›žå½’的情况下解决安全问题。
+
+如果你ä»ç„¶é¢ä¸´æ­¤ç§æƒ…况,请查看邮件列表档案是å¦æœ‰äººå°½åŠ›é¿å…过回归。如果没有,
+请报告它;如有疑问,请如上所述寻求建议。
+
+当修å¤å›žå½’æ—¶ä¸å¯é¿å…会引入å¦ä¸€ä¸ªï¼Œå¦‚何处ç†ï¼Ÿ
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+很é—憾这ç§äº‹ç¡®å®žä¼šå‡ºçŽ°ï¼Œä½†å¹¸è¿çš„是并ä¸ç»å¸¸å‡ºçŽ°ï¼›å¦‚æžœå‘生了,å—å½±å“代ç åŒºçš„资
+深开å‘者应当调查该问题以找到é¿å…回归的解决方法,至少é¿å…它们的影å“。如果你é‡
+到这样的情况,如上所述:检查之å‰çš„讨论是å¦æœ‰äººå·²ç»å°½äº†æœ€å¤§åŠªåŠ›ï¼Œå¦‚有疑问请寻
+求建议。
+
+å°æ示:如果人们在æ¯ä¸ªå¼€å‘周期中定期给出主线预å‘布(å³v5.15-rc1或-rc3)以供
+测试,则å¯ä»¥é¿å…è¿™ç§æƒ…况。为了更好地解释,å¯ä»¥è®¾æƒ³ä¸€ä¸ªåœ¨Linux v5.14å’Œv5.15-rc1
+之间集æˆçš„更改,该更改导致了回归,但åŒæ—¶æ˜¯åº”用于5.15-rc1的其他改进的强ä¾èµ–。
+如果有人在5.15å‘布之å‰å°±å‘现并报告了这个问题,那么所有更改都å¯ä»¥ç›´æŽ¥æ’¤é”€ï¼Œä»Ž
+而解决回归问题。而就在几天或几周åŽï¼Œæ­¤è§£å†³æ–¹æ¡ˆå˜æˆäº†ä¸å¯èƒ½ï¼Œå› ä¸ºä¸€äº›è½¯ä»¶å¯èƒ½
+å·²ç»å¼€å§‹ä¾èµ–于åŽç»­æ›´æ”¹ä¹‹ä¸€ï¼šæ’¤é”€æ‰€æœ‰æ›´æ”¹å°†å¯¼è‡´ä¸Šè¿°ç”¨æˆ·è½¯ä»¶å‡ºçŽ°å›žå½’,这是ä¸å¯
+接å—的。
+
+若我所ä¾èµ–的功能在数月å‰è¢«ç§»é™¤äº†ï¼Œæ˜¯å›žå½’å—?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+是的,但如å‰èŠ‚所述,通常很难修å¤æ­¤ç±»å›žå½’。因此需è¦é€æ¡ˆå¤„ç†ã€‚这也是定期测试主
+线预å‘布对所有人有好处的å¦ä¸€ä¸ªåŽŸå› ã€‚
+
+如果我似乎是唯一å—å½±å“的人,是å¦ä»é€‚用“无回归â€è§„则?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+适用,但仅é™äºŽå®žé™…使用:Linuxå¼€å‘人员希望能够自由地å–消那些åªèƒ½åœ¨é˜æ¥¼å’Œåšç‰©
+馆中找到的硬件的支æŒã€‚
+
+请注æ„,有时为了å–得进展,ä¸å¾—ä¸å‡ºçŽ°å›žå½’——åŽè€…也是防止Linuxåœæ»žä¸å‰æ‰€å¿…需
+的。因此如果回归所影å“的用户很少,那么为了他们和其他人更大的利益,还是让事情
+过去å§ã€‚尤其是存在æŸç§è§„é¿å›žå½’的简å•æ–¹æ³•ï¼Œä¾‹å¦‚更新一些软件或者使用专门为此目
+的创建的内核å‚数。
+
+回归规则是å¦ä¹Ÿé€‚用于staging树中的代ç ï¼Ÿ
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ä¸ï¼Œå‚è§ `适用于所有staging代ç é…置选项的帮助文本
+<https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/staging/Kconfig>`_ ,
+其早已声明::
+
+ 请注æ„:这些驱动正在积æžå¼€å‘中,å¯èƒ½æ— æ³•æ­£å¸¸å·¥ä½œï¼Œå¹¶å¯èƒ½åŒ…å«ä¼šåœ¨ä¸ä¹…çš„
+ å°†æ¥å‘生å˜åŒ–的用户接å£ã€‚
+
+虽然stagingå¼€å‘人员通常åšæŒâ€œæ— å›žå½’â€çš„原则,但有时为了å–得进展也会è¿èƒŒå®ƒã€‚这就
+是为什么当stagingæ ‘çš„WiFi驱动被基本推倒é‡æ¥æ—¶ï¼Œæœ‰äº›ç”¨æˆ·ä¸å¾—ä¸å¤„ç†å›žå½’(通常å¯
+以忽略)。
+
+为什么较新版本必须“使用相似é…置编译â€ï¼Ÿ
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+因为Linux内核开å‘人员有时会集æˆå·²çŸ¥çš„会导致回归的å˜æ›´ï¼Œä½†ä½¿å®ƒä»¬æˆä¸ºå¯é€‰çš„,并
+在内核的默认é…置下ç¦ç”¨å®ƒä»¬ã€‚这一技巧å…许进步,å¦åˆ™â€œæ— å›žå½’â€è§„则将导致åœæ»žã€‚
+
+例如,试想一个新的å¯ä»¥é˜»æ­¢æ¶æ„软件滥用æŸä¸ªå†…核的接å£çš„安全特性,åŒæ—¶åˆéœ€è¦æ»¡è¶³
+å¦ä¸€ä¸ªå¾ˆç½•è§çš„应用程åºã€‚上述的方法å¯ä½¿ä¸¤æ–¹éƒ½æ»¡æ„:使用这些应用程åºçš„人å¯ä»¥å…³é—­
+新的安全功能,而其他ä¸ä¼šé‡åˆ°éº»çƒ¦çš„人å¯ä»¥å¯ç”¨å®ƒã€‚
+
+如何创建与旧内核相似的é…置?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+用一个已知良好的内核å¯åŠ¨æœºå™¨ï¼Œå¹¶ç”¨ ``make olddefconfig`` é…置新版的Linux。这
+会让内核的构建脚本从正在è¿è¡Œçš„内核中摘录é…置文件(“.configâ€æ–‡ä»¶ï¼‰ï¼Œä½œä¸ºå³å°†ç¼–
+译的新版本的基础é…置;åŒæ—¶å°†æ‰€æœ‰æ–°çš„é…置选项设为默认值,以ç¦ç”¨å¯èƒ½å¯¼è‡´å›žå½’çš„
+新功能。
+
+如何报告在预编译的普通内核中å‘现的回归?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+您需è¦ç¡®ä¿æ–°çš„内核是用与旧版相似的é…置编译(è§ä¸Šæ–‡ï¼‰ï¼Œå› ä¸ºé‚£äº›æž„建它们的人å¯
+能å¯ç”¨äº†ä¸€äº›å·²çŸ¥çš„与新内核ä¸å…¼å®¹çš„特性。如有疑问,请å‘内核的æ供者报告问题并
+寻求建议。
+
+
+用“regzbotâ€è¿½è¸ªå›žå½’的更多信æ¯
+-----------------------------
+
+什么是回归追踪?为啥我需è¦å…³å¿ƒå®ƒï¼Ÿ
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+åƒâ€œæ— å›žå½’â€è¿™æ ·çš„规则需è¦æœ‰äººæ¥ç¡®ä¿å®ƒä»¬è¢«éµå®ˆï¼Œå¦åˆ™ä¼šè¢«æœ‰æ„/æ— æ„打破。历å²è¯
+明了这一点对于Linux内核开å‘也适用。这就是为什么Linux内核的回归跟踪者Thorsten
+Leemhuis,,和å¦ä¸€äº›äººå°½åŠ›å…³æ³¨æ‰€æœ‰çš„回归直到他们解决。他们从未为此获得报酬,
+因此这项工作是在尽最大努力的基础上完æˆçš„。
+
+为什么/如何使用机器人追踪Linux内核回归?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+由于Linux内核开å‘过程的分布å¼å’Œæ¾æ•£ç»“构,完全手动跟踪回归已ç»è¢«è¯æ˜Žæ˜¯ç›¸å½“å›°éš¾
+的。因此Linux内核的回归跟踪者开å‘了regzbotæ¥ä¿ƒè¿›è¿™é¡¹å·¥ä½œï¼Œå…¶é•¿æœŸç›®æ ‡æ˜¯å°½å¯èƒ½ä¸º
+所有相关人员自动化回归跟踪。
+
+Regzbot通过监视跟踪的回归报告的回å¤æ¥å·¥ä½œã€‚此外,它还查找用“Link:â€æ ‡ç­¾å¼•ç”¨è¿™
+些报告的补ä¸ï¼›å¯¹è¿™äº›è¡¥ä¸çš„回å¤ä¹Ÿä¼šè¢«è·Ÿè¸ªã€‚结åˆè¿™äº›æ•°æ®ï¼Œå¯ä»¥å¾ˆå¥½åœ°äº†è§£å½“å‰ä¿®
+å¤è¿‡ç¨‹çš„状æ€ã€‚
+
+如何查看regzbot当å‰è¿½è¸ªçš„回归?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+å‚è§ `regzbot在线 <https://linux-regtracking.leemhuis.info/regzbot/>`_ 。
+
+何ç§é—®é¢˜å¯ä»¥ç”±regzbot追踪?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+该机器人åªä¸ºäº†è·Ÿè¸ªå›žå½’,因此请ä¸è¦è®©regzbot涉åŠå¸¸è§„问题。但是对于Linux内核的
+回归跟踪者æ¥è¯´ï¼Œè®©regzbot跟踪严é‡é—®é¢˜ä¹Ÿå¯ä»¥ï¼Œå¦‚有关挂起ã€æŸåæ•°æ®æˆ–内部错误
+(Panicã€Oopsã€BUG()ã€warning…)的报告。
+
+如何修改被追踪回归的相关信æ¯ï¼Ÿ
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+在直接或间接回å¤æŠ¥å‘Šé‚®ä»¶æ—¶ä½¿ç”¨â€œregzbot命令â€å³å¯ã€‚最简å•çš„方法是:在“已å‘é€â€æ–‡
+件夹或邮件列表存档中找到报告,然åŽä½¿ç”¨é‚®ä»¶å®¢æˆ·ç«¯çš„“全部回å¤â€åŠŸèƒ½å¯¹å…¶è¿›è¡Œå›žå¤ã€‚
+在该邮件中的独立段è½ä¸­å¯ä½¿ç”¨ä»¥ä¸‹å‘½ä»¤ä¹‹ä¸€ï¼ˆå³ä½¿ç”¨ç©ºè¡Œå°†è¿™äº›å‘½ä»¤ä¸­çš„一个或多个与
+其余邮件文本分隔开)。
+
+ * 更新回归引入起点,例如在执行二分之åŽ::
+
+ #regzbot introduced: 1f2e3d4c5d
+
+ * 设置或更新标题::
+
+ #regzbot title: foo
+
+ * 监视讨论或bugzilla.kernel.org上有关讨论或修å¤çš„å·¥å•::
+
+ #regzbot monitor: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
+ #regzbot monitor: https://bugzilla.kernel.org/show_bug.cgi?id=123456789
+
+ * 标记一个有更多相关细节的地方,例如有关但主题ä¸åŒçš„邮件列表帖å­æˆ–缺陷追踪器中的工å•::
+
+ #regzbot link: https://bugzilla.kernel.org/show_bug.cgi?id=123456789
+
+ * 标记回归已失效::
+
+ #regzbot invalid: wasn't a regression, problem has always existed
+
+Regzbot还支æŒå…¶ä»–一些主è¦ç”±å¼€å‘人员或回归追踪人员使用的命令。命令的更多细节请
+å‚考 `å…¥é—¨æŒ‡å— <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/getting_started.md>`_
+å’Œ `å‚考手册 <https://gitlab.com/knurd42/regzbot/-/blob/main/docs/reference.md>`_ 。
+
+..
+ 正文结æŸ
+..
+ 如本文件开头所述,本文以GPL-2.0+或CC-BY-4.0许å¯å‘行。如您想仅在CC-BY-4.0许
+ å¯ä¸‹é‡åˆ†å‘本文,请用“Linux内核开å‘者â€ä½œä¸ºä½œè€…,并用如下链接作为æ¥æºï¼š
+ https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/translations/zh_CN/admin-guide/reporting-regressions.rst
+..
+ 注æ„:本RST文件内容åªæœ‰åœ¨æ¥è‡ªLinux内核æºä»£ç æ—¶æ˜¯ä½¿ç”¨CC-BY-4.0许å¯çš„,因为ç»
+ 过处ç†çš„版本(如ç»å†…核的构建系统)å¯èƒ½åŒ…å«æ¥è‡ªä½¿ç”¨æ›´ä¸¥æ ¼è®¸å¯è¯çš„文件的内容。
diff --git a/Documentation/translations/zh_CN/core-api/cachetlb.rst b/Documentation/translations/zh_CN/core-api/cachetlb.rst
index 6fee45fe5e80..b4a76ec75daa 100644
--- a/Documentation/translations/zh_CN/core-api/cachetlb.rst
+++ b/Documentation/translations/zh_CN/core-api/cachetlb.rst
@@ -5,6 +5,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
:校译:
@@ -278,6 +279,11 @@ HyperSparc cpu就是这样一个具有这ç§å±žæ€§çš„cpu。
CPU上,因为它将cpu存储到页é¢ä¸Šï¼Œä½¿å…¶å˜è„。åŒæ ·ï¼Œè¯·çœ‹
sparc64关于如何处ç†è¿™ä¸ªé—®é¢˜çš„例å­ã€‚
+ ``void flush_dcache_folio(struct folio *folio)``
+
+ 该函数的调用情形与flush_dcache_page()相åŒã€‚它å…许架构针对刷新整个
+ folio页é¢è¿›è¡Œä¼˜åŒ–,而ä¸æ˜¯ä¸€æ¬¡åˆ·æ–°ä¸€é¡µã€‚
+
``void copy_to_user_page(struct vm_area_struct *vma, struct page *page,
unsigned long user_vaddr, void *dst, void *src, int len)``
``void copy_from_user_page(struct vm_area_struct *vma, struct page *page,
diff --git a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst
index 85a264287426..4772a900c37a 100644
--- a/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst
+++ b/Documentation/translations/zh_CN/core-api/cpu_hotplug.rst
@@ -4,6 +4,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
:校译:
@@ -15,12 +16,13 @@
内核中的CPU热拔æ’
=================
-:时间: 2016年12月
+:时间: 2021年9月
:作者: Sebastian Andrzej Siewior <bigeasy@linutronix.de>,
- Rusty Russell <rusty@rustcorp.com.au>,
- Srivatsa Vaddagiri <vatsa@in.ibm.com>,
- Ashok Raj <ashok.raj@intel.com>,
- Joel Schopp <jschopp@austin.ibm.com>
+ Rusty Russell <rusty@rustcorp.com.au>,
+ Srivatsa Vaddagiri <vatsa@in.ibm.com>,
+ Ashok Raj <ashok.raj@intel.com>,
+ Joel Schopp <jschopp@austin.ibm.com>,
+ Thomas Gleixner <tglx@linutronix.de>
简介
====
@@ -139,7 +141,7 @@ CPU的热拔æ’å作
下线情况
--------
-一旦CPU被逻辑关闭,注册的热æ’拔状æ€çš„清除回调将被调用,从 ``CPUHP_ONLINE`` 开始,在
+一旦CPU被逻辑关闭,注册的热æ’拔状æ€çš„清除回调将被调用,从 ``CPUHP_ONLINE`` 开始,到
``CPUHP_OFFLINE`` 状æ€ç»“æŸã€‚这包括:
* 如果任务因暂åœæ“作而被冻结,那么 *cpuhp_tasks_frozen* 将被设置为true。
@@ -154,82 +156,399 @@ CPU的热拔æ’å作
* 一旦所有的æœåŠ¡è¢«è¿ç§»ï¼Œå†…核会调用一个特定的例程 ``__cpu_disable()`` æ¥è¿›è¡Œç‰¹å®šçš„清
ç†ã€‚
-使用热æ’æ‹”API
--------------
+CPU热æ’æ‹”API
+============
+
+CPU热拔æ’状æ€æœº
+---------------
+
+CPU热æ’拔使用一个从CPUHP_OFFLINE到CPUHP_ONLINE的线性状æ€ç©ºé—´çš„普通状æ€æœºã€‚æ¯ä¸ªçŠ¶æ€éƒ½
+有一个startup和teardown的回调。
+
+当一个CPU上线时,将按顺åºè°ƒç”¨startup回调,直到达到CPUHP_ONLINE状æ€ã€‚当设置状æ€çš„回调
+或将实例添加到多实例状æ€æ—¶ï¼Œä¹Ÿå¯ä»¥è°ƒç”¨å®ƒä»¬ã€‚
+
+当一个CPU下线时,将按相å的顺åºä¾æ¬¡è°ƒç”¨teardown回调,直到达到CPUHP_OFFLINE状æ€ã€‚当删
+除状æ€çš„回调或从多实例状æ€ä¸­åˆ é™¤å®žä¾‹æ—¶ï¼Œä¹Ÿå¯ä»¥è°ƒç”¨å®ƒä»¬ã€‚
+
+如果æŸä¸ªä½¿ç”¨åœºæ™¯åªéœ€è¦ä¸€ä¸ªæ–¹å‘的热æ’æ‹”æ“作回调(CPU上线或CPU下线),则在设置状æ€æ—¶ï¼Œ
+å¯ä»¥å°†å¦ä¸€ä¸ªä¸éœ€è¦çš„回调设置为NULL。
+
+状æ€ç©ºé—´è¢«åˆ’分æˆä¸‰ä¸ªé˜¶æ®µ:
+
+* PREPARE阶段
+
+ PREPARE阶段涵盖了从CPUHP_OFFLINE到CPUHP_BRINGUP_CPU之间的状æ€ç©ºé—´ã€‚
+
+ 在该阶段中,startup回调在CPU上线æ“作å¯åŠ¨CPU之å‰è¢«è°ƒç”¨ï¼Œteardown回调在CPU下线æ“作使
+ CPU功能失效之åŽè¢«è°ƒç”¨ã€‚
+
+ 这些回调是在控制CPU上调用的,因为它们显然ä¸èƒ½åœ¨çƒ­æ’拔的CPU上è¿è¡Œï¼Œæ­¤æ—¶çƒ­æ’拔的CPUè¦
+ 么还没有å¯åŠ¨ï¼Œè¦ä¹ˆå·²ç»åŠŸèƒ½å¤±æ•ˆã€‚
+
+ startup回调用于设置CPUæˆåŠŸä¸Šçº¿æ‰€éœ€è¦çš„资æºã€‚teardown回调用于释放资æºæˆ–在热æ’拔的CPU
+ 功能失效åŽï¼Œå°†å¾…处ç†çš„工作转移到在线的CPU上。
+
+ å…许startup回调失败。如果回调失败,CPU上线æ“作被中止,CPUå°†å†æ¬¡è¢«é™åˆ°ä¹‹å‰çš„状æ€ï¼ˆé€š
+ 常是CPUHP_OFFLINE)。
+
+ 本阶段中的teardown回调ä¸å…许失败。
+
+* STARTING阶段
+
+ STARTING阶段涵盖了CPUHP_BRINGUP_CPU + 1到CPUHP_AP_ONLINE之间的状æ€ç©ºé—´ã€‚
+
+ 该阶段中的startup回调是在早期CPU设置代ç ä¸­çš„CPU上线æ“作期间,ç¦ç”¨ä¸­æ–­çš„情况下在热拔
+ æ’çš„CPU上被调用。teardown回调是在CPU完全关闭å‰ä¸ä¹…çš„CPU下线æ“作期间,ç¦ç”¨ä¸­æ–­çš„情况
+ 下在热拔æ’çš„CPU上被调用。
+
+ 该阶段中的回调ä¸å…许失败。
+
+ 回调用于低级别的硬件åˆå§‹åŒ–/关机和核心å­ç³»ç»Ÿã€‚
+
+* ONLINE阶段
+
+ ONLINE阶段涵盖了CPUHP_AP_ONLINE + 1到CPUHP_ONLINE之间的状æ€ç©ºé—´ã€‚
+
+ 该阶段中的startup回调是在CPU上线时在热æ’拔的CPU上调用的。teardown回调是在CPU下线æ“
+ 作时在热æ’æ‹”CPU上调用的。
+
+ 回调是在æ¯ä¸ªCPU热æ’拔线程的上下文中调用的,该线程绑定在热æ’拔的CPU上。回调是在å¯ç”¨
+ 中断和抢å çš„情况下调用的。
+
+ å…许回调失败。如果回调失败,CPU热æ’æ‹”æ“作被中止,CPUå°†æ¢å¤åˆ°ä¹‹å‰çš„状æ€ã€‚
+
+CPU 上线/下线æ“作
+-----------------
+
+一个æˆåŠŸçš„上线æ“作如下::
+
+ [CPUHP_OFFLINE]
+ [CPUHP_OFFLINE + 1]->startup() -> æˆåŠŸ
+ [CPUHP_OFFLINE + 2]->startup() -> æˆåŠŸ
+ [CPUHP_OFFLINE + 3] -> 略过,因为startup == NULL
+ ...
+ [CPUHP_BRINGUP_CPU]->startup() -> æˆåŠŸ
+ === PREPARE阶段结æŸ
+ [CPUHP_BRINGUP_CPU + 1]->startup() -> æˆåŠŸ
+ ...
+ [CPUHP_AP_ONLINE]->startup() -> æˆåŠŸ
+ === STARTUP阶段结æŸ
+ [CPUHP_AP_ONLINE + 1]->startup() -> æˆåŠŸ
+ ...
+ [CPUHP_ONLINE - 1]->startup() -> æˆåŠŸ
+ [CPUHP_ONLINE]
+
+一个æˆåŠŸçš„下线æ“作如下::
+
+ [CPUHP_ONLINE]
+ [CPUHP_ONLINE - 1]->teardown() -> æˆåŠŸ
+ ...
+ [CPUHP_AP_ONLINE + 1]->teardown() -> æˆåŠŸ
+ === STARTUP阶段开始
+ [CPUHP_AP_ONLINE]->teardown() -> æˆåŠŸ
+ ...
+ [CPUHP_BRINGUP_ONLINE - 1]->teardown()
+ ...
+ === PREPARE阶段开始
+ [CPUHP_BRINGUP_CPU]->teardown()
+ [CPUHP_OFFLINE + 3]->teardown()
+ [CPUHP_OFFLINE + 2] -> 略过,因为teardown == NULL
+ [CPUHP_OFFLINE + 1]->teardown()
+ [CPUHP_OFFLINE]
+
+一个失败的上线æ“作如下::
+
+ [CPUHP_OFFLINE]
+ [CPUHP_OFFLINE + 1]->startup() -> æˆåŠŸ
+ [CPUHP_OFFLINE + 2]->startup() -> æˆåŠŸ
+ [CPUHP_OFFLINE + 3] -> 略过,因为startup == NULL
+ ...
+ [CPUHP_BRINGUP_CPU]->startup() -> æˆåŠŸ
+ === PREPARE阶段结æŸ
+ [CPUHP_BRINGUP_CPU + 1]->startup() -> æˆåŠŸ
+ ...
+ [CPUHP_AP_ONLINE]->startup() -> æˆåŠŸ
+ === STARTUP阶段结æŸ
+ [CPUHP_AP_ONLINE + 1]->startup() -> æˆåŠŸ
+ ---
+ [CPUHP_AP_ONLINE + N]->startup() -> 失败
+ [CPUHP_AP_ONLINE + (N - 1)]->teardown()
+ ...
+ [CPUHP_AP_ONLINE + 1]->teardown()
+ === STARTUP阶段开始
+ [CPUHP_AP_ONLINE]->teardown()
+ ...
+ [CPUHP_BRINGUP_ONLINE - 1]->teardown()
+ ...
+ === PREPARE阶段开始
+ [CPUHP_BRINGUP_CPU]->teardown()
+ [CPUHP_OFFLINE + 3]->teardown()
+ [CPUHP_OFFLINE + 2] -> 略过,因为teardown == NULL
+ [CPUHP_OFFLINE + 1]->teardown()
+ [CPUHP_OFFLINE]
+
+一个失败的下线æ“作如下::
+
+ [CPUHP_ONLINE]
+ [CPUHP_ONLINE - 1]->teardown() -> æˆåŠŸ
+ ...
+ [CPUHP_ONLINE - N]->teardown() -> 失败
+ [CPUHP_ONLINE - (N - 1)]->startup()
+ ...
+ [CPUHP_ONLINE - 1]->startup()
+ [CPUHP_ONLINE]
+
+递归失败ä¸èƒ½è¢«åˆç†åœ°å¤„ç†ã€‚
+请看下é¢çš„例å­ï¼Œç”±äºŽä¸‹çº¿æ“作失败而导致的递归失败::
+
+ [CPUHP_ONLINE]
+ [CPUHP_ONLINE - 1]->teardown() -> æˆåŠŸ
+ ...
+ [CPUHP_ONLINE - N]->teardown() -> 失败
+ [CPUHP_ONLINE - (N - 1)]->startup() -> æˆåŠŸ
+ [CPUHP_ONLINE - (N - 2)]->startup() -> 失败
+
+CPU热æ’拔状æ€æœºåœ¨æ­¤åœæ­¢ï¼Œä¸”ä¸å†å°è¯•å›žæ»šï¼Œå› ä¸ºè¿™å¯èƒ½ä¼šå¯¼è‡´æ­»å¾ªçŽ¯::
+
+ [CPUHP_ONLINE - (N - 1)]->teardown() -> æˆåŠŸ
+ [CPUHP_ONLINE - N]->teardown() -> 失败
+ [CPUHP_ONLINE - (N - 1)]->startup() -> æˆåŠŸ
+ [CPUHP_ONLINE - (N - 2)]->startup() -> 失败
+ [CPUHP_ONLINE - (N - 1)]->teardown() -> æˆåŠŸ
+ [CPUHP_ONLINE - N]->teardown() -> 失败
+
+周而å¤å§‹ï¼Œä¸æ–­é‡å¤ã€‚在这ç§æƒ…况下,CPU留在该状æ€ä¸­::
+
+ [CPUHP_ONLINE - (N - 1)]
+
+这至少å¯ä»¥è®©ç³»ç»Ÿå–得进展,让用户有机会进行调试,甚至解决这个问题。
+
+分é…一个状æ€
+------------
+
+有两ç§æ–¹å¼åˆ†é…一个CPU热æ’拔状æ€:
+
+* é™æ€åˆ†é…
+
+ 当å­ç³»ç»Ÿæˆ–驱动程åºæœ‰ç›¸å¯¹äºŽå…¶ä»–CPU热æ’拔状æ€çš„排åºè¦æ±‚时,必须使用é™æ€åˆ†é…。例如,
+ 在CPU上线æ“作期间,PERF核心startup回调必须在PERF驱动startup回调之å‰è¢«è°ƒç”¨ã€‚在CPU
+ 下线æ“作中,驱动teardown回调必须在核心teardown回调之å‰è°ƒç”¨ã€‚é™æ€åˆ†é…的状æ€ç”±
+ cpuhp_state枚举中的常é‡æ述,å¯ä»¥åœ¨include/linux/cpuhotplug.h中找到。
+
+ 在适当的ä½ç½®å°†çŠ¶æ€æ’入枚举中,这样就满足了排åºè¦æ±‚。状æ€å¸¸é‡å¿…须被用于状æ€çš„设置
+ 和移除。
+
+ 当状æ€å›žè°ƒä¸æ˜¯åœ¨è¿è¡Œæ—¶è®¾ç½®çš„,并且是kernel/cpu.c中CPU热æ’拔状æ€æ•°ç»„åˆå§‹åŒ–的一部分
+ 时,也需è¦é™æ€åˆ†é…。
+
+* 动æ€åˆ†é…
+
+ 当对状æ€å›žè°ƒæ²¡æœ‰æŽ’åºè¦æ±‚时,动æ€åˆ†é…是首选方法。状æ€ç¼–å·ç”±setup函数分é…,并在æˆåŠŸ
+ åŽè¿”回给调用者。
+
+ åªæœ‰PREPAREå’ŒONLINE阶段æ供了一个动æ€åˆ†é…范围。STARTING阶段则没有,因为该部分的大多
+ 数回调都有明确的排åºè¦æ±‚。
+
+CPU热æ’拔状æ€çš„设置
+-------------------
+
+核心代ç æ供了以下函数用æ¥è®¾ç½®çŠ¶æ€ï¼š
+
+* cpuhp_setup_state(state, name, startup, teardown)
+* cpuhp_setup_state_nocalls(state, name, startup, teardown)
+* cpuhp_setup_state_cpuslocked(state, name, startup, teardown)
+* cpuhp_setup_state_nocalls_cpuslocked(state, name, startup, teardown)
+
+对于一个驱动程åºæˆ–å­ç³»ç»Ÿæœ‰å¤šä¸ªå®žä¾‹ï¼Œå¹¶ä¸”æ¯ä¸ªå®žä¾‹éƒ½éœ€è¦è°ƒç”¨ç›¸åŒçš„CPU hotplug状æ€å›ž
+调的情况,CPU hotplug核心æ供多实例支æŒã€‚与驱动程åºç‰¹å®šçš„实例列表相比,其优势在于
+与实例相关的函数完全针对CPU hotplugæ“作进行åºåˆ—化,并在添加和删除时æ供状æ€å›žè°ƒçš„
+自动调用。è¦è®¾ç½®è¿™æ ·ä¸€ä¸ªå¤šå®žä¾‹çŠ¶æ€ï¼Œå¯ä»¥ä½¿ç”¨ä»¥ä¸‹å‡½æ•°ï¼š
+
+* cpuhp_setup_state_multi(state, name, startup, teardown)
+
+@stateå‚æ•°è¦ä¹ˆæ˜¯é™æ€åˆ†é…的状æ€ï¼Œè¦ä¹ˆæ˜¯åŠ¨æ€åˆ†é…状æ€ï¼ˆPUHP_PREPARE_DYN,CPUHP_ONLINE_DYN)
+的常é‡ä¹‹ä¸€ï¼Œ 具体å–决于应该分é…动æ€çŠ¶æ€çš„状æ€é˜¶æ®µï¼ˆPREPARE,ONLINE)。
+
+@nameå‚数用于sysfs输出和检测。命å惯例是"subsys:mode"或"subsys/driver:mode",
+例如 "perf:mode"或"perf/x86:mode"。常è§çš„modeå称有:
+
+======== ============================================
+prepare 对应PREPARE阶段中的状æ€
+
+dead 对应PREPARE阶段中ä¸æä¾›startup回调的状æ€
+
+starting 对应STARTING阶段中的状æ€
+
+dying 对应STARTING阶段中ä¸æä¾›startup回调的状æ€
+
+online 对应ONLINE阶段中的状æ€
+
+offline 对应ONLINE阶段中ä¸æä¾›startup回调的状æ€
+======== ============================================
+
+由于@nameå‚æ•°åªç”¨äºŽsysfs和检测,如果其他modeæ述符比常è§çš„æ述符更好地æ述状æ€çš„性质,
+也å¯ä»¥ä½¿ç”¨ã€‚
+
+@nameå‚数的示例:"perf/online", "perf/x86:prepare", "RCU/tree:dying", "sched/waitempty"
+
+@startupå‚数是一个指å‘回调的函数指针,在CPU上线æ“作时被调用。若应用ä¸éœ€è¦startup
+回调,则将该指针设为NULL。
+
+@teardownå‚数是一个指å‘回调的函数指针,在CPU下线æ“作时调用。若应用ä¸éœ€è¦teardown
+回调,则将该指针设为NULL。
+
+这些函数在处ç†å·²æ³¨å†Œå›žè°ƒçš„æ–¹å¼ä¸Šæœ‰æ‰€ä¸åŒ:
+
+ * cpuhp_setup_state_nocalls(), cpuhp_setup_state_nocalls_cpuslocked()和
+ cpuhp_setup_state_multi()åªæ³¨å†Œå›žè°ƒã€‚
+
+ * cpuhp_setup_state()å’Œcpuhp_setup_state_cpuslocked()注册回调,并对当å‰çŠ¶æ€å¤§äºŽæ–°
+ 安装状æ€çš„所有在线CPU调用@startup回调(如果ä¸æ˜¯NULL)。根æ®çŠ¶æ€é˜¶æ®µï¼Œå›žè°ƒè¦ä¹ˆåœ¨
+ 当å‰çš„CPU上调用(PREPARE阶段),è¦ä¹ˆåœ¨CPU的热æ’拔线程中调用æ¯ä¸ªåœ¨çº¿CPU(ONLINE阶段)。
+
+ 如果CPU N的回调失败,那么CPU 0...N-1çš„teardown回调被调用以回滚æ“作。状æ€è®¾ç½®å¤±è´¥ï¼Œ
+ 状æ€çš„回调没有被注册,在动æ€åˆ†é…的情况下,分é…的状æ€è¢«é‡Šæ”¾ã€‚
+
+状æ€è®¾ç½®å’Œå›žè°ƒè°ƒç”¨æ˜¯é’ˆå¯¹CPU热拔æ’æ“作进行åºåˆ—化的。如果设置函数必须从CPU热æ’拔的读
+é”定区域调用,那么必须使用_cpuslocked()å˜ä½“。这些函数ä¸èƒ½åœ¨CPU热拔æ’回调中使用。
+
+函数返回值:
+ ======== ==========================================================
+ 0 é™æ€åˆ†é…的状æ€è®¾ç½®æˆåŠŸ
+
+ >0 动æ€åˆ†é…的状æ€è®¾ç½®æˆåŠŸ
+
+ 返回的数值是被分é…的状æ€ç¼–å·ã€‚如果状æ€å›žè°ƒåŽæ¥å¿…须被移除,
+ 例如模å—移除,那么这个数值必须由调用者ä¿å­˜ï¼Œå¹¶ä½œä¸ºçŠ¶æ€ç§»
+ 除函数的@stateå‚数。对于多实例状æ€ï¼ŒåŠ¨æ€åˆ†é…的状æ€ç¼–å·ä¹Ÿ
+ 需è¦ä½œä¸ºå®žä¾‹æ·»åŠ /删除æ“作的@stateå‚数。
+
+ <0 æ“作失败
+ ======== ==========================================================
+
+移除CPU热拔æ’状æ€
+-----------------
+
+为了移除一个之å‰è®¾ç½®å¥½çš„状æ€ï¼Œæ供了如下函数:
+
+* cpuhp_remove_state(state)
+* cpuhp_remove_state_nocalls(state)
+* cpuhp_remove_state_nocalls_cpuslocked(state)
+* cpuhp_remove_multi_state(state)
+
+@stateå‚æ•°è¦ä¹ˆæ˜¯é™æ€åˆ†é…的状æ€ï¼Œè¦ä¹ˆæ˜¯ç”±cpuhp_setup_state*()在动æ€èŒƒå›´å†…分é…
+的状æ€ç¼–å·ã€‚如果状æ€åœ¨åŠ¨æ€èŒƒå›´å†…,则状æ€ç¼–å·è¢«é‡Šæ”¾ï¼Œå¯å†æ¬¡è¿›è¡ŒåŠ¨æ€åˆ†é…。
+
+这些函数在处ç†å·²æ³¨å†Œå›žè°ƒçš„æ–¹å¼ä¸Šæœ‰æ‰€ä¸åŒ:
+
+ * cpuhp_remove_state_nocalls(), cpuhp_remove_state_nocalls_cpuslocked()
+ å’Œ cpuhp_remove_multi_state()åªåˆ é™¤å›žè°ƒã€‚
+
+ * cpuhp_remove_state()删除回调,并调用所有当å‰çŠ¶æ€å¤§äºŽè¢«åˆ é™¤çŠ¶æ€çš„在线CPUçš„
+ teardown回调(如果ä¸æ˜¯NULL)。根æ®çŠ¶æ€é˜¶æ®µï¼Œå›žè°ƒè¦ä¹ˆåœ¨å½“å‰çš„CPU上调用
+ (PREPARE阶段),è¦ä¹ˆåœ¨CPU的热æ’拔线程中调用æ¯ä¸ªåœ¨çº¿CPU(ONLINE阶段)。
+
+ 为了完æˆç§»é™¤å·¥ä½œï¼Œteardown回调ä¸èƒ½å¤±è´¥ã€‚
+
+状æ€ç§»é™¤å’Œå›žè°ƒè°ƒç”¨æ˜¯é’ˆå¯¹CPU热拔æ’æ“作进行åºåˆ—化的。如果移除函数必须从CPU hotplug
+读å–é”定区域调用,那么必须使用_cpuslocked()å˜ä½“。这些函数ä¸èƒ½ä»ŽCPU热æ’拔的回调中使用。
+
+如果一个多实例的状æ€è¢«ç§»é™¤ï¼Œé‚£ä¹ˆè°ƒç”¨è€…必须先移除所有的实例。
+
+多实例状æ€å®žä¾‹ç®¡ç†
+------------------
+
+一旦多实例状æ€è¢«å»ºç«‹ï¼Œå®žä¾‹å°±å¯ä»¥è¢«æ·»åŠ åˆ°çŠ¶æ€ä¸­ï¼š
-一旦一个CPU下线或上线,就有å¯èƒ½æ”¶åˆ°é€šçŸ¥ã€‚这对æŸäº›éœ€è¦æ ¹æ®å¯ç”¨CPUæ•°é‡æ‰§è¡ŒæŸç§è®¾ç½®æˆ–清
-ç†åŠŸèƒ½çš„驱动程åºæ¥è¯´å¯èƒ½å¾ˆé‡è¦::
+ * cpuhp_state_add_instance(state, node)
+ * cpuhp_state_add_instance_nocalls(state, node)
- #include <linux/cpuhotplug.h>
+@stateå‚数是一个é™æ€åˆ†é…的状æ€æˆ–ç”±cpuhp_setup_state_multi()在动æ€èŒƒå›´å†…分é…的状
+æ€ç¼–å·ã€‚
- ret = cpuhp_setup_state(CPUHP_AP_ONLINE_DYN, "X/Y:online",
- Y_online, Y_prepare_down);
+@nodeå‚数是一个指å‘hlist_node的指针,它被嵌入到实例的数æ®ç»“构中。这个指针被交给
+多实例状æ€çš„回调,å¯ä»¥è¢«å›žè°ƒç”¨æ¥é€šè¿‡container_of()检索到实例。
-*X* 是å­ç³»ç»Ÿï¼Œ *Y* 是特定的驱动程åºã€‚ *Y_online* 回调将在所有在线CPU的注册过程中被调用。
-如果在线回调期间å‘生错误, *Y_prepare_down* 回调将在所有之å‰è°ƒç”¨è¿‡åœ¨çº¿å›žè°ƒçš„CPU上调
-用。注册完æˆåŽï¼Œä¸€æ—¦æœ‰CPU上线, *Y_online* 回调将被调用,当CPU关闭时, *Y_prepare_down*
-将被调用。所有之å‰åœ¨ *Y_online* 中分é…的资æºéƒ½åº”该在 *Y_prepare_down* 中释放。如果在
-注册过程中å‘生错误,返回值 *ret* 为负值。å¦åˆ™ä¼šè¿”回一个正值,其中包å«åŠ¨æ€åˆ†é…状æ€
-( *CPUHP_AP_ONLINE_DYN* )的分é…热拔æ’。对于预定义的状æ€ï¼Œå®ƒå°†è¿”回0。
+这些函数在处ç†å·²æ³¨å†Œå›žè°ƒçš„æ–¹å¼ä¸Šæœ‰æ‰€ä¸åŒ:
-该回调å¯ä»¥é€šè¿‡è°ƒç”¨ ``cpuhp_remove_state()`` æ¥åˆ é™¤ã€‚如果是动æ€åˆ†é…的状æ€
-( *CPUHP_AP_ONLINE_DYN* ),则使用返回的状æ€ã€‚在移除热æ’拔状æ€çš„过程中,将调用拆解回调。
+ * cpuhp_state_add_instance_nocalls()åªå°†å®žä¾‹æ·»åŠ åˆ°å¤šå®žä¾‹çŠ¶æ€çš„节点列表中。
-多个实例
-~~~~~~~~
+ * cpuhp_state_add_instance()为所有当å‰çŠ¶æ€å¤§äºŽ@state的在线CPU添加实例并调用与
+ @state相关的startup回调(如果ä¸æ˜¯NULL)。该回调åªå¯¹å°†è¦æ·»åŠ çš„实例进行调用。
+ æ ¹æ®çŠ¶æ€é˜¶æ®µï¼Œå›žè°ƒè¦ä¹ˆåœ¨å½“å‰çš„CPU上调用(PREPARE阶段),è¦ä¹ˆåœ¨CPU的热æ’拔线
+ 程中调用æ¯ä¸ªåœ¨çº¿CPU(ONLINE阶段)。
-如果一个驱动程åºæœ‰å¤šä¸ªå®žä¾‹ï¼Œå¹¶ä¸”æ¯ä¸ªå®žä¾‹éƒ½éœ€è¦ç‹¬ç«‹æ‰§è¡Œå›žè°ƒï¼Œé‚£ä¹ˆå¾ˆå¯èƒ½åº”该使用
-``multi-state`` 。首先需è¦æ³¨å†Œä¸€ä¸ªå¤šçŠ¶æ€çš„状æ€::
+ 如果CPU N的回调失败,那么CPU 0 ... N-1çš„teardown回调被调用以回滚æ“作,该函数
+ 失败,实例ä¸ä¼šè¢«æ·»åŠ åˆ°å¤šå®žä¾‹çŠ¶æ€çš„节点列表中。
- ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online,
- Y_online, Y_prepare_down);
- Y_hp_online = ret;
+è¦ä»ŽçŠ¶æ€çš„节点列表中删除一个实例,å¯ä»¥ä½¿ç”¨è¿™äº›å‡½æ•°:
-``cpuhp_setup_state_multi()`` 的行为与 ``cpuhp_setup_state()`` 类似,åªæ˜¯å®ƒ
-为多状æ€å‡†å¤‡äº†å›žè°ƒï¼Œä½†ä¸è°ƒç”¨å›žè°ƒã€‚这是一个一次性的设置。
-一旦分é…了一个新的实例,你需è¦æ³¨å†Œè¿™ä¸ªæ–°å®žä¾‹::
+ * cpuhp_state_remove_instance(state, node)
+ * cpuhp_state_remove_instance_nocalls(state, node)
- ret = cpuhp_state_add_instance(Y_hp_online, &d->node);
+å‚数与上述cpuhp_state_add_instance*()å˜ä½“相åŒã€‚
-这个函数将把这个实例添加到你先å‰åˆ†é…çš„ ``Y_hp_online`` 状æ€ï¼Œå¹¶åœ¨æ‰€æœ‰åœ¨çº¿çš„
-CPU上调用先å‰æ³¨å†Œçš„回调( ``Y_online`` )。 *node* 元素是你的æ¯ä¸ªå®žä¾‹æ•°æ®ç»“æž„
-中的一个 ``struct hlist_node`` æˆå‘˜ã€‚
+这些函数在处ç†å·²æ³¨å†Œå›žè°ƒçš„æ–¹å¼ä¸Šæœ‰æ‰€ä¸åŒ:
-在移除该实例时::
+ * cpuhp_state_remove_instance_nocalls()åªä»ŽçŠ¶æ€çš„节点列表中删除实例。
- cpuhp_state_remove_instance(Y_hp_online, &d->node)
+ * cpuhp_state_remove_instance()删除实例并调用与@state相关的回调(如果ä¸æ˜¯NULL),
+ 用于所有当å‰çŠ¶æ€å¤§äºŽ@state的在线CPU。 该回调åªå¯¹å°†è¦è¢«ç§»é™¤çš„实例进行调用。
+ æ ¹æ®çŠ¶æ€é˜¶æ®µï¼Œå›žè°ƒè¦ä¹ˆåœ¨å½“å‰çš„CPU上调用(PREPARE阶段),è¦ä¹ˆåœ¨CPU的热æ’æ‹”
+ 线程中调用æ¯ä¸ªåœ¨çº¿CPU(ONLINE阶段)。
-应该被调用,这将在所有在线CPU上调用拆分回调。
+ 为了完æˆç§»é™¤å·¥ä½œï¼Œteardown回调ä¸èƒ½å¤±è´¥ã€‚
-手动设置
-~~~~~~~~
+节点列表的添加/删除æ“作和回调调用是针对CPU热拔æ’æ“作进行åºåˆ—化。这些函数ä¸èƒ½åœ¨
+CPU hotplug回调和CPU hotplug读å–é”定区域内使用。
-通常情况下,在注册或移除状æ€æ—¶è°ƒç”¨setupå’Œteamdown回调是很方便的,因为通常在CPU上线
-(下线)和驱动的åˆå§‹è®¾ç½®ï¼ˆå…³é—­ï¼‰æ—¶éœ€è¦æ‰§è¡Œè¯¥æ“作。然而,æ¯ä¸ªæ³¨å†Œå’Œåˆ é™¤åŠŸèƒ½ä¹Ÿæœ‰ä¸€ä¸ª
-_nocallsçš„åŽç¼€ï¼Œå¦‚æžœä¸å¸Œæœ›è°ƒç”¨å›žè°ƒï¼Œåˆ™ä¸è°ƒç”¨æ‰€æ供的回调。在手动设置(或关闭)期间,
-应该使用 ``get_online_cpus()`` å’Œ ``put_online_cpus()`` 函数æ¥æŠ‘制CPU热æ’æ‹”æ“作。
+样例
+----
+在STARTING阶段设置和å–消é™æ€åˆ†é…的状æ€ï¼Œä»¥èŽ·å–上线和下线æ“作的通知::
-事件的顺åº
-----------
+ ret = cpuhp_setup_state(CPUHP_SUBSYS_STARTING, "subsys:starting", subsys_cpu_starting, subsys_cpu_dying);
+ if (ret < 0)
+ return ret;
+ ....
+ cpuhp_remove_state(CPUHP_SUBSYS_STARTING);
-热æ’拔状æ€è¢«å®šä¹‰åœ¨ ``include/linux/cpuhotplug.h``:
+在ONLINE阶段设置和å–消动æ€åˆ†é…的状æ€ï¼Œä»¥èŽ·å–下线æ“作的通知::
-* ``CPUHP_OFFLINE`` ... ``CPUHP_AP_OFFLINE`` 状æ€æ˜¯åœ¨CPUå¯åŠ¨å‰è°ƒç”¨çš„。
+ state = cpuhp_setup_state(CPUHP_ONLINE_DYN, "subsys:offline", NULL, subsys_cpu_offline);
+ if (state < 0)
+ return state;
+ ....
+ cpuhp_remove_state(state);
-* ``CPUHP_AP_OFFLINE`` ... ``CPUHP_AP_ONLINE`` 状æ€æ˜¯åœ¨CPU被å¯åŠ¨åŽè¢«è°ƒç”¨çš„。
- 中断是关闭的,调度程åºè¿˜æ²¡æœ‰åœ¨è¿™ä¸ªCPU上活动。从 ``CPUHP_AP_OFFLINE`` 开始,
- 回调被调用到目标CPU上。
+在ONLINE阶段设置和å–消动æ€åˆ†é…的状æ€ï¼Œä»¥èŽ·å–有关上线æ“作的通知,而无需调用回调::
-* ``CPUHP_AP_ONLINE_DYN`` å’Œ ``CPUHP_AP_ONLINE_DYN_END`` 之间的状æ€è¢«ä¿ç•™
- 给动æ€åˆ†é…。
+ state = cpuhp_setup_state_nocalls(CPUHP_ONLINE_DYN, "subsys:online", subsys_cpu_online, NULL);
+ if (state < 0)
+ return state;
+ ....
+ cpuhp_remove_state_nocalls(state);
-* 这些状æ€åœ¨CPU关闭时以相å的顺åºè°ƒç”¨ï¼Œä»Ž ``CPUHP_ONLINE`` 开始,在 ``CPUHP_OFFLINE``
- åœæ­¢ã€‚这里的回调是在将被关闭的CPU上调用的,直到 ``CPUHP_AP_OFFLINE`` 。
+在ONLINE阶段设置ã€ä½¿ç”¨å’Œå–消动æ€åˆ†é…的多实例状æ€ï¼Œä»¥èŽ·å¾—上线和下线æ“作的通知::
-通过 ``CPUHP_AP_ONLINE_DYN`` 动æ€åˆ†é…的状æ€é€šå¸¸å·²ç»è¶³å¤Ÿäº†ã€‚然而,如果在å¯åŠ¨æˆ–关闭
-期间需è¦æ›´æ—©çš„调用,那么应该获得一个显å¼çŠ¶æ€ã€‚如果热拔æ’事件需è¦ç›¸å¯¹äºŽå¦ä¸€ä¸ªçƒ­æ‹”æ’事
-件的特定排åºï¼Œä¹Ÿå¯èƒ½éœ€è¦ä¸€ä¸ªæ˜¾å¼çŠ¶æ€ã€‚
+ state = cpuhp_setup_state_multi(CPUHP_ONLINE_DYN, "subsys:online", subsys_cpu_online, subsys_cpu_offline);
+ if (state < 0)
+ return state;
+ ....
+ ret = cpuhp_state_add_instance(state, &inst1->node);
+ if (ret)
+ return ret;
+ ....
+ ret = cpuhp_state_add_instance(state, &inst2->node);
+ if (ret)
+ return ret;
+ ....
+ cpuhp_remove_instance(state, &inst1->node);
+ ....
+ cpuhp_remove_instance(state, &inst2->node);
+ ....
+ remove_multi_state(state);
测试热拔æ’状æ€
==============
diff --git a/Documentation/translations/zh_CN/core-api/index.rst b/Documentation/translations/zh_CN/core-api/index.rst
index 26d9913fc8b6..7ca44629860c 100644
--- a/Documentation/translations/zh_CN/core-api/index.rst
+++ b/Documentation/translations/zh_CN/core-api/index.rst
@@ -28,6 +28,7 @@
printk-basics
printk-formats
workqueue
+ watch_queue
symbol-namespaces
æ•°æ®ç»“构和低级实用程åº
diff --git a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst
index 7d077742f758..9174fce12c1b 100644
--- a/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst
+++ b/Documentation/translations/zh_CN/core-api/irq/irq-domain.rst
@@ -5,6 +5,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
.. _cn_irq-domain.rst:
@@ -52,8 +53,18 @@ irq_domain和一个hwirqå·ä½œä¸ºå‚数。 如果hwirq的映射还ä¸å­˜åœ¨ï¼Œé‚
一个新的Linux irq_desc,将其与hwirqå…³è”èµ·æ¥ï¼Œå¹¶è°ƒç”¨.map()回调,这样驱动
程åºå°±å¯ä»¥æ‰§è¡Œä»»ä½•å¿…è¦çš„硬件设置。
-当接收到一个中断时,应该使用irq_find_mapping()函数从hwirqå·ä¸­æ‰¾åˆ°
-Linux IRQå·ã€‚
+一旦建立了映射,å¯ä»¥é€šè¿‡å¤šç§æ–¹æ³•æ£€ç´¢æˆ–使用它:
+
+- irq_resolve_mapping()返回一个指å‘给定域和hwirqå·çš„irq_desc结构指针,
+ 如果没有映射则返回NULL。
+
+- irq_find_mapping()返回给定域和hwirqçš„Linux IRQå·ï¼Œå¦‚果没有映射则返回0。
+
+- irq_linear_revmap()现与irq_find_mapping()相åŒï¼Œå·²è¢«åºŸå¼ƒã€‚
+
+- generic_handle_domain_irq()处ç†ä¸€ä¸ªç”±åŸŸå’Œhwirqå·æ述的中断。
+
+请注æ„,irq域的查找必须å‘生在与RCU读临界区兼容的上下文中。
在调用irq_find_mapping()之å‰ï¼Œè‡³å°‘è¦è°ƒç”¨ä¸€æ¬¡irq_create_mapping()函数,
以å…æ述符ä¸èƒ½è¢«åˆ†é…。
@@ -119,7 +130,8 @@ irq_domain_add_tree()å’Œirq_domain_create_tree()在功能上是等价的,除äº
Linux IRQå·ç¼–入硬件本身,这样就ä¸éœ€è¦æ˜ å°„了。 调用irq_create_direct_mapping()
会分é…一个Linux IRQå·ï¼Œå¹¶è°ƒç”¨.map()回调,这样驱动就å¯ä»¥å°†Linux IRQå·ç¼–入硬件中。
-大多数驱动程åºä¸èƒ½ä½¿ç”¨è¿™ä¸ªæ˜ å°„。
+大多数驱动程åºæ— æ³•ä½¿ç”¨æ­¤æ˜ å°„,现在它由CONFIG_IRQ_DOMAIN_NOMAP选项控制。
+请ä¸è¦å¼•å…¥æ­¤API的新用户。
传统映射类型
------------
@@ -128,7 +140,6 @@ Linux IRQå·ç¼–入硬件本身,这样就ä¸éœ€è¦æ˜ å°„了。 调用irq_create
irq_domain_add_simple()
irq_domain_add_legacy()
- irq_domain_add_legacy_isa()
irq_domain_create_simple()
irq_domain_create_legacy()
@@ -137,6 +148,9 @@ Linux IRQå·ç¼–入硬件本身,这样就ä¸éœ€è¦æ˜ å°„了。 调用irq_create
一组用于IRQå·çš„定义(#define),这些定义被传递给struct设备注册。 在这ç§æƒ…况下,
ä¸èƒ½åŠ¨æ€åˆ†é…Linux IRQå·ï¼Œåº”该使用传统映射。
+顾åæ€ä¹‰ï¼Œ\*_legacy()系列函数已被废弃,åªæ˜¯ä¸ºäº†æ–¹ä¾¿å¯¹å¤è€å¹³å°çš„支æŒè€Œå­˜åœ¨ã€‚
+ä¸åº”该增加新的用户。当\*_simple()系列函数的使用导致é—留行为时,他们也是如此。
+
传统映射å‡è®¾å·²ç»ä¸ºæŽ§åˆ¶å™¨åˆ†é…了一个连续的IRQå·èŒƒå›´ï¼Œå¹¶ä¸”å¯ä»¥é€šè¿‡å‘hwirqå·æ·»åŠ ä¸€
个固定的å移æ¥è®¡ç®—IRQå·ï¼Œå之亦然。 缺点是需è¦ä¸­æ–­æŽ§åˆ¶å™¨ç®¡ç†IRQ分é…,并且需è¦ä¸ºæ¯
个hwirq分é…一个irq_desc,å³ä½¿å®ƒæ²¡æœ‰è¢«ä½¿ç”¨ã€‚
diff --git a/Documentation/translations/zh_CN/core-api/kernel-api.rst b/Documentation/translations/zh_CN/core-api/kernel-api.rst
index 962d31d019d7..c22662679065 100644
--- a/Documentation/translations/zh_CN/core-api/kernel-api.rst
+++ b/Documentation/translations/zh_CN/core-api/kernel-api.rst
@@ -5,6 +5,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
.. _cn_kernel-api.rst:
@@ -282,6 +283,8 @@ kernel/acct.c
该API在以下内核代ç ä¸­:
+include/linux/bio.h
+
block/blk-core.c
block/blk-core.c
diff --git a/Documentation/translations/zh_CN/core-api/mm-api.rst b/Documentation/translations/zh_CN/core-api/mm-api.rst
index 0ea43dc67953..a732b0eebf16 100644
--- a/Documentation/translations/zh_CN/core-api/mm-api.rst
+++ b/Documentation/translations/zh_CN/core-api/mm-api.rst
@@ -5,6 +5,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
:校译:
@@ -66,12 +67,24 @@ mm/vmalloc.c
该API在以下内核代ç ä¸­:
-mm/readahead.c
+文件映射
+--------
mm/filemap.c
+预读
+----
+
+mm/readahead.c
+
+回写
+----
+
mm/page-writeback.c
+截断
+----
+
mm/truncate.c
include/linux/pagemap.h
@@ -105,6 +118,14 @@ mm/mempolicy.c
include/linux/mm_types.h
+include/linux/mm_inline.h
+
+include/linux/page-flags.h
+
include/linux/mm.h
+include/linux/page_ref.h
+
include/linux/mmzone.h
+
+mm/util.c
diff --git a/Documentation/translations/zh_CN/core-api/printk-basics.rst b/Documentation/translations/zh_CN/core-api/printk-basics.rst
index d574de3167c8..59c6efb3fc41 100644
--- a/Documentation/translations/zh_CN/core-api/printk-basics.rst
+++ b/Documentation/translations/zh_CN/core-api/printk-basics.rst
@@ -6,6 +6,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
.. _cn_printk-basics.rst:
@@ -107,6 +108,4 @@ pr_debug()å’Œpr_devel(),除éžå®šä¹‰äº† ``DEBUG`` (或者在pr_debug()的情å†
该API在以下内核代ç ä¸­:
-kernel/printk/printk.c
-
include/linux/printk.h
diff --git a/Documentation/translations/zh_CN/core-api/printk-formats.rst b/Documentation/translations/zh_CN/core-api/printk-formats.rst
index ce39c788cf5a..bd36d35eba4e 100644
--- a/Documentation/translations/zh_CN/core-api/printk-formats.rst
+++ b/Documentation/translations/zh_CN/core-api/printk-formats.rst
@@ -5,6 +5,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
.. _cn_printk-formats.rst:
@@ -548,7 +549,7 @@ nodemask_pr_args()æ¥æ–¹ä¾¿æ‰“å°cpumaskå’Œnodemask。
::
- %pGp referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff
+ %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff)
%pGg GFP_USER|GFP_DMA32|GFP_NOWARN
%pGv read|exec|mayread|maywrite|mayexec|denywrite
diff --git a/Documentation/translations/zh_CN/core-api/watch_queue.rst b/Documentation/translations/zh_CN/core-api/watch_queue.rst
new file mode 100644
index 000000000000..23b17ae2e4e2
--- /dev/null
+++ b/Documentation/translations/zh_CN/core-api/watch_queue.rst
@@ -0,0 +1,313 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/core-api/watch_queue.rst
+
+:翻译:
+
+周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
+
+:校译:
+
+å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+å´æƒ³æˆ Wu Xiangcheng <bobwxc@email.cn>
+
+
+============
+通用通知机制
+============
+
+通用通知机制是建立在标准管é“驱动之上的,它å¯ä»¥æœ‰æ•ˆåœ°å°†æ¥è‡ªå†…核的通知消æ¯æ‹¼æŽ¥åˆ°ç”¨
+户空间打开的管é“中。这å¯ä»¥ä¸Žä»¥ä¸‹æ–¹é¢ç»“åˆä½¿ç”¨::
+
+ * Key/keyring 通知
+
+通知缓冲区å¯ä»¥é€šè¿‡ä»¥ä¸‹æ–¹å¼å¯ç”¨ï¼š
+
+ “General setupâ€/“General notification queueâ€
+ (CONFIG_WATCH_QUEUE)
+
+文档包å«ä»¥ä¸‹ç« èŠ‚:
+
+.. contents:: :local:
+
+
+概述
+====
+
+该设施以一ç§ç‰¹æ®Šæ¨¡å¼æ‰“开的管é“å½¢å¼å‡ºçŽ°ï¼Œç®¡é“的内部环形缓冲区用于ä¿å­˜å†…核生æˆçš„消
+æ¯ã€‚然åŽé€šè¿‡read()读出这些消æ¯ã€‚在此类管é“上ç¦ç”¨æ‹¼æŽ¥ä»¥åŠç±»ä¼¼çš„æ“作,因为它们希望
+在æŸäº›æƒ…况下将其添加的内容还原到环中-è¿™å¯èƒ½æœ€ç»ˆä¼šä¸Žé€šçŸ¥æ¶ˆæ¯é‡å ã€‚
+
+管é“的所有者必须告诉内核它想通过该管é“观察哪些æºã€‚åªæœ‰è¿žæŽ¥åˆ°è¯¥ç®¡é“上的æºæ‰ä¼šå°†æ¶ˆ
+æ¯æ’入其中。请注æ„,一个æºå¯èƒ½ç»‘定到多个管é“,并åŒæ—¶å°†æ¶ˆæ¯æ’入到所有管é“中。
+
+还å¯ä»¥å°†è¿‡æ»¤å™¨æ”¾ç½®åœ¨ç®¡é“上,以便在ä¸æ„Ÿå…´è¶£æ—¶å¯ä»¥å¿½ç•¥æŸäº›æºç±»åž‹å’Œå­äº‹ä»¶ã€‚
+
+如果环中没有å¯ç”¨çš„æ’槽,或者没有预分é…的消æ¯ç¼“冲区å¯ç”¨ï¼Œåˆ™å°†ä¸¢å¼ƒæ¶ˆæ¯ã€‚在这两ç§æƒ…
+况下,read()都会在读å–缓冲区中当å‰çš„最åŽä¸€æ¡æ¶ˆæ¯åŽï¼Œå°†WATCH_META_LOSS_NOTIFICATION
+æ’入到输出缓冲区中。
+
+请注æ„,当生æˆä¸€ä¸ªé€šçŸ¥æ—¶ï¼Œå†…æ ¸ä¸ä¼šç­‰å¾…消费者收集它,而是继续执行。这æ„味ç€å¯ä»¥åœ¨
+æŒæœ‰è‡ªæ—‹é”çš„åŒæ—¶ç”Ÿæˆé€šçŸ¥ï¼Œå¹¶ä¸”还å¯ä»¥ä¿æŠ¤å†…æ ¸ä¸è¢«ç”¨æˆ·ç©ºé—´æ•…障无é™æœŸåœ°é˜»ç¢ã€‚
+
+
+消æ¯ç»“æž„
+========
+
+通知消æ¯ç”±ä¸€ä¸ªç®€çŸ­çš„头部开始::
+
+ struct watch_notification {
+ __u32 type:24;
+ __u32 subtype:8;
+ __u32 info;
+ };
+
+“typeâ€è¡¨ç¤ºé€šçŸ¥è®°å½•çš„æ¥æºï¼Œâ€œsubtypeâ€è¡¨ç¤ºè¯¥æ¥æºçš„记录类型(è§ä¸‹æ–‡è§‚测æºç« èŠ‚)。该类
+型也å¯ä»¥æ˜¯â€œWATCH_TYPE_METAâ€ã€‚这是一个由观测队列本身在内部生æˆçš„特殊记录类型。有两
+个å­ç±»åž‹ï¼š
+
+ * WATCH_META_REMOVAL_NOTIFICATION
+ * WATCH_META_LOSS_NOTIFICATION
+
+第一个表示安装了观察的对象已被删除或销æ¯ï¼Œç¬¬äºŒä¸ªè¡¨ç¤ºæŸäº›æ¶ˆæ¯å·²ä¸¢å¤±ã€‚
+
+“infoâ€è¡¨ç¤ºä¸€ç³»åˆ—东西,包括:
+
+ * 消æ¯çš„长度,以字节为å•ä½ï¼ŒåŒ…括头(带有WATCH_INFO_LENGTH的掩ç ï¼Œå¹¶æŒ‰
+ WATCH_INFO_LENGTH__SHIFT移ä½ï¼‰ã€‚这表示记录的大å°ï¼Œå¯èƒ½åœ¨8到127字节之间。
+
+ * 观测ID(带有WATCH_INFO_ID掩ç ï¼Œå¹¶æŒ‰WATCH_INFO_ID__SHIFT移ä½ï¼‰ã€‚这表示观测的主
+ å«ID,å¯èƒ½åœ¨0到255之间。多个观测组å¯ä»¥å…±äº«ä¸€ä¸ªé˜Ÿåˆ—,这æ供了一ç§åŒºåˆ†å®ƒä»¬çš„方法。
+
+ * 特定类型的字段(WATCH_INFO_TYPE_INFO)。这是由通知生产者设置的,以指示类型和
+ å­ç±»åž‹çš„æŸäº›ç‰¹å®šå«ä¹‰ã€‚
+
+除长度外,信æ¯ä¸­çš„所有内容都å¯ä»¥ç”¨äºŽè¿‡æ»¤ã€‚
+
+头部åŽé¢å¯ä»¥æœ‰è¡¥å……ä¿¡æ¯ã€‚此格å¼æ˜¯ç”±ç±»åž‹å’Œå­ç±»åž‹å†³å®šçš„。
+
+
+观测列表(通知æºï¼‰API
+=====================
+
+“观测列表“是订阅通知æºçš„观测者的列表。列表å¯ä»¥é™„加到对象(比如键或超级å—),也å¯
+以是全局的(比如对于设备事件)。从用户空间的角度æ¥çœ‹ï¼Œä¸€ä¸ªéžå…¨å±€çš„观测列表通常是
+通过引用它所属的对象æ¥å¼•ç”¨çš„(比如使用KEYCTL_NOTIFY并给它一个密钥åºåˆ—å·æ¥è§‚测特定
+的密钥)。
+
+为了管ç†è§‚测列表,æ供了以下函数:
+
+ * ::
+
+ void init_watch_list(struct watch_list *wlist,
+ void (*release_watch)(struct watch *wlist));
+
+ åˆå§‹åŒ–一个观测列表。 如果 ``release_watch`` ä¸æ˜¯NULL,那么这表示当watch_list对
+ 象被销æ¯æ—¶ï¼Œåº”该调用函数æ¥ä¸¢å¼ƒè§‚测列表对被观测对象的任何引用。
+
+ * ``void remove_watch_list(struct watch_list *wlist);``
+
+ 这将删除订阅watch_list的所有观测,并释放它们,然åŽé”€æ¯watch_list对象本身。
+
+
+观测队列(通知输出)API
+=======================
+
+“观测队列â€æ˜¯ç”±åº”用程åºåˆ†é…的用以记录通知的缓冲区,其工作原ç†å®Œå…¨éšè—在管é“设备驱
+动中,但必须获得对它的引用æ‰èƒ½è®¾ç½®è§‚测。å¯ä»¥é€šè¿‡ä»¥ä¸‹æ–¹å¼è¿›è¡Œç®¡ç†ï¼š
+
+ * ``struct watch_queue *get_watch_queue(int fd);``
+
+ 由于观测队列在内核中通过实现缓冲区的管é“的文件æ述符表示,用户空间必须通过系
+ 统调用传递该文件æ述符,这å¯ä»¥ç”¨äºŽä»Žç³»ç»Ÿè°ƒç”¨ä¸­æŸ¥æ‰¾æŒ‡å‘观测队列的ä¸é€æ˜ŽæŒ‡é’ˆã€‚
+
+ * ``void put_watch_queue(struct watch_queue *wqueue);``
+
+ 该函数用以丢弃从 ``get_watch_queue()`` 获得的引用。
+
+
+观测订阅API
+===========
+
+“观测â€æ˜¯è§‚测列表上的订阅,表示观测队列,从而表示应写入通知记录的缓冲区。观测队列
+对象还å¯ä»¥æºå¸¦è¯¥å¯¹è±¡çš„过滤规则,由用户空间设置。watch结构体的æŸäº›éƒ¨åˆ†å¯ä»¥ç”±é©±åŠ¨ç¨‹
+åºè®¾ç½®::
+
+ struct watch {
+ union {
+ u32 info_id; /* 在info字段中进行ORè¿ç®—çš„ID */
+ ...
+ };
+ void *private; /* 被观测对象的ç§æœ‰æ•°æ® */
+ u64 id; /* 内部标识符 */
+ ...
+ };
+
+``info_id`` 值是从用户空间获得并按WATCH_INFO_ID__SHIFT移ä½çš„8ä½æ•°å­—。当通知写入关
+è”的观测队列缓冲区时,这将与struct watch_notification::infoçš„WATCH_INFO_ID字段进
+行或è¿ç®—。
+
+``private`` 字段是与watch_list相关è”的驱动程åºæ•°æ®ï¼Œå¹¶ç”± ``watch_list::release_watch()``
+函数清除。
+
+``id`` 字段是æºçš„ID。使用ä¸åŒIDå‘布的通知将被忽略。
+
+æ供以下函数æ¥ç®¡ç†è§‚测:
+
+ * ``void init_watch(struct watch *watch, struct watch_queue *wqueue);``
+
+ åˆå§‹åŒ–一个观测对象,把它的指针设置到观察队列中,使用适当的é™åˆ¶æ¥é¿å…æ­»é”。
+
+ * ``int add_watch_to_object(struct watch *watch, struct watch_list *wlist);``
+
+ 将观测订阅到观测列表(通知æºï¼‰ã€‚watch结构体中的driver-settable字段必须在调用
+ 它之å‰è®¾ç½®ã€‚
+
+ * ::
+
+ int remove_watch_from_object(struct watch_list *wlist,
+ struct watch_queue *wqueue,
+ u64 id, false);
+
+ 从观测列表中删除一个观测,该观测必须与指定的观测队列(``wqueue``)和对象标识
+ 符(``id``)匹é…。通知(``WATCH_META_REMOVAL_NOTIFICATION``)被å‘é€åˆ°è§‚测队列
+ 表示该观测已被删除。
+
+ * ``int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);``
+
+ 从观测列表中删除所有观测。预计这将被称为销æ¯å‰çš„准备工作,届时新的观测将无法
+ 访问观测列表。通知(``WATCH_META_REMOVAL_NOTIFICATION``)被å‘é€åˆ°æ¯ä¸ªè®¢é˜…观测
+ 的观测队列,以表明该观测已被删除。
+
+
+通知å‘布API
+===========
+
+è¦å°†é€šçŸ¥å‘布到观测列表以便订阅的观测å¯ä»¥çœ‹åˆ°ï¼Œåº”使用以下函数::
+
+ void post_watch_notification(struct watch_list *wlist,
+ struct watch_notification *n,
+ const struct cred *cred,
+ u64 id);
+
+应预先设置通知格å¼ï¼Œå¹¶åº”传入一个指å‘头部(``n``)的指针。通知å¯èƒ½å¤§äºŽæ­¤å€¼ï¼Œå¹¶ä¸”缓
+冲槽为å•ä½çš„大å°åœ¨ ``n->info & WATCH_INFO_LENGTH`` 中注明。
+
+``cred`` 结构体表示æºï¼ˆå¯¹è±¡ï¼‰çš„è¯ä¹¦ï¼Œå¹¶ä¼ é€’ç»™LSM,例如SELinux,以å…许或ç¦æ­¢æ ¹æ®è¯¥é˜Ÿ
+列(对象)的è¯ä¹¦åœ¨æ¯ä¸ªå•ç‹¬é˜Ÿåˆ—中记录注释。
+
+``id`` 是æºå¯¹è±¡ID(如密钥上的åºåˆ—å·ï¼‰ã€‚åªæœ‰è®¾ç½®ç›¸åŒID的观测æ‰èƒ½çœ‹åˆ°è¿™ä¸ªé€šçŸ¥ã€‚
+
+
+观测æº
+======
+
+任何特定的缓冲区都å¯ä»¥ä»Žå¤šä¸ªæºèŽ·å–ä¿¡æ¯ã€‚ 这些æºåŒ…括:
+
+ * WATCH_TYPE_KEY_NOTIFY
+
+ è¿™ç§ç±»åž‹çš„通知表示密钥和密钥环的å˜åŒ–,包括密钥环内容或密钥属性的å˜åŒ–。
+
+ 更多信æ¯è¯·å‚è§Documentation/security/keys/core.rst。
+
+
+事件过滤
+========
+
+当创建观测队列åŽï¼Œæˆ‘们å¯ä»¥åº”用一组过滤器以é™åˆ¶æŽ¥æ”¶çš„事件::
+
+ struct watch_notification_filter filter = {
+ ...
+ };
+ ioctl(fd, IOC_WATCH_QUEUE_SET_FILTER, &filter)
+
+过滤器的æ述的类型å˜é‡æ˜¯::
+
+ struct watch_notification_filter {
+ __u32 nr_filters;
+ __u32 __reserved;
+ struct watch_notification_type_filter filters[];
+ };
+
+其中“nr_filtersâ€è¡¨ç¤ºfilters[]数组中过滤器的数é‡ï¼Œè€Œâ€œ__reservedâ€åº”为0。
+“filterâ€æ•°ç»„有以下类型的元素::
+
+ struct watch_notification_type_filter {
+ __u32 type;
+ __u32 info_filter;
+ __u32 info_mask;
+ __u32 subtype_filter[8];
+ };
+
+其中:
+
+ * ``type`` 是过滤的事件类型,应类似于“WATCH_TYPE_KEY_NOTIFYâ€ã€‚
+
+ * ``info_filter`` 与 ``info_mask`` 充当通知记录的信æ¯å­—段的过滤器,åªæœ‰åœ¨ä»¥ä¸‹æƒ…
+ 况,通知æ‰ä¼šå†™å…¥ç¼“冲区::
+
+ (watch.info & info_mask) == info_filter
+
+ 例如,这å¯ä»¥ç”¨äºŽå¿½ç•¥ä¸åœ¨ä¸€ä¸ªæŒ‚载树上的观测点的事件。
+
+ * ``subtype_filter`` 是一个ä½æŽ©ç ï¼Œè¡¨ç¤ºæ„Ÿå…´è¶£çš„å­ç±»åž‹ã€‚subtype_filter[0]çš„
+ bit[0]对应å­ç±»åž‹0,bit[1]对应å­ç±»åž‹1,以此类推。
+
+è‹¥ioctl()çš„å‚数为NULL,则过滤器将被移除,并且æ¥è‡ªè§‚测æºçš„所有事件都将通过。
+
+
+用户空间代ç ç¤ºä¾‹
+================
+
+缓冲区的创建如下所示::
+
+ pipe2(fds, O_TMPFILE);
+ ioctl(fds[1], IOC_WATCH_QUEUE_SET_SIZE, 256);
+
+它å¯ä»¥è¢«è®¾ç½®æˆæŽ¥æ”¶å¯†é’¥çŽ¯å˜åŒ–的通知::
+
+ keyctl(KEYCTL_WATCH_KEY, KEY_SPEC_SESSION_KEYRING, fds[1], 0x01);
+
+然åŽï¼Œè¿™äº›é€šçŸ¥å¯ä»¥è¢«å¦‚下方å¼æ‰€ä½¿ç”¨::
+
+ static void consumer(int rfd, struct watch_queue_buffer *buf)
+ {
+ unsigned char buffer[128];
+ ssize_t buf_len;
+
+ while (buf_len = read(rfd, buffer, sizeof(buffer)),
+ buf_len > 0
+ ) {
+ void *p = buffer;
+ void *end = buffer + buf_len;
+ while (p < end) {
+ union {
+ struct watch_notification n;
+ unsigned char buf1[128];
+ } n;
+ size_t largest, len;
+
+ largest = end - p;
+ if (largest > 128)
+ largest = 128;
+ memcpy(&n, p, largest);
+
+ len = (n->info & WATCH_INFO_LENGTH) >>
+ WATCH_INFO_LENGTH__SHIFT;
+ if (len == 0 || len > largest)
+ return;
+
+ switch (n.n.type) {
+ case WATCH_TYPE_META:
+ got_meta(&n.n);
+ case WATCH_TYPE_KEY_NOTIFY:
+ saw_key_change(&n.n);
+ break;
+ }
+
+ p += len;
+ }
+ }
+ }
diff --git a/Documentation/translations/zh_CN/core-api/workqueue.rst b/Documentation/translations/zh_CN/core-api/workqueue.rst
index e372fa5cf101..f6567cf9d3fb 100644
--- a/Documentation/translations/zh_CN/core-api/workqueue.rst
+++ b/Documentation/translations/zh_CN/core-api/workqueue.rst
@@ -6,6 +6,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
.. _cn_workqueue.rst:
@@ -178,10 +179,6 @@ workqueue将自动创建与属性相匹é…çš„åŽå¤‡å·¥ä½œè€…池。调节并å‘æ°
这个标志对于未绑定的wqæ¥è¯´æ˜¯æ²¡æœ‰æ„义的。
-请注æ„,标志 ``WQ_NON_REENTRANT`` ä¸å†å­˜åœ¨ï¼Œå› ä¸ºçŽ°åœ¨æ‰€æœ‰çš„工作
-队列都是ä¸å¯é€†çš„——任何工作项都ä¿è¯åœ¨ä»»ä½•æ—¶é—´å†…最多被整个系统的一
-个工作者执行。
-
``max_active``
--------------
@@ -328,6 +325,22 @@ And with cmwq with ``@max_active`` >= 3, ::
工作项函数在堆栈追踪中应该是微ä¸è¶³é“的。
+ä¸å¯é‡å…¥æ¡ä»¶
+============
+
+工作队列ä¿è¯ï¼Œå¦‚果在工作项排队åŽæ»¡è¶³ä»¥ä¸‹æ¡ä»¶ï¼Œåˆ™å·¥ä½œé¡¹ä¸èƒ½é‡å…¥ï¼š
+
+
+ 1. 工作函数没有被改å˜ã€‚
+ 2. 没有人将该工作项排到å¦ä¸€ä¸ªå·¥ä½œé˜Ÿåˆ—中。
+ 3. 该工作项尚未被é‡æ–°å¯åŠ¨ã€‚
+
+æ¢è¨€ä¹‹ï¼Œå¦‚果上述æ¡ä»¶æˆç«‹ï¼Œåˆ™ä¿è¯åœ¨ä»»ä½•ç»™å®šæ—¶é—´æœ€å¤šç”±ä¸€ä¸ªç³»ç»ŸèŒƒå›´å†…的工作程åºæ‰§è¡Œ
+该工作项。
+
+请注æ„,在self函数中将工作项é‡æ–°æŽ’队(到åŒä¸€é˜Ÿåˆ—)ä¸ä¼šç ´å这些æ¡ä»¶ï¼Œå› æ­¤å¯ä»¥å®‰å…¨
+地执行此æ“作。å¦åˆ™åœ¨ç ´å工作函数内部的æ¡ä»¶æ—¶éœ€è¦å°å¿ƒã€‚
+
内核内è”文档å‚考
================
diff --git a/Documentation/translations/zh_CN/core-api/xarray.rst b/Documentation/translations/zh_CN/core-api/xarray.rst
index ff2d9bcb7c34..fb19324966ce 100644
--- a/Documentation/translations/zh_CN/core-api/xarray.rst
+++ b/Documentation/translations/zh_CN/core-api/xarray.rst
@@ -6,6 +6,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ 周彬彬 Binbin Zhou <zhoubinbin@loongson.cn>
:校译:
@@ -254,7 +255,8 @@ __xa_set_mark() å’Œ __xa_clear_mark() 函数也适用于你查找一个æ¡ç›®å¹¶
高级API是基于xa_state的。这是一个ä¸é€æ˜Žçš„æ•°æ®ç»“构,你使用XA_STATE()å®åœ¨å †æ ˆä¸­å£°æ˜Žã€‚这个å®åˆå§‹åŒ–了
xa_state,准备开始在XArray上移动。它被用作一个游标æ¥ä¿æŒåœ¨XArray中的ä½ç½®ï¼Œå¹¶è®©ä½ æŠŠå„ç§æ“作组åˆåœ¨ä¸€
-起,而ä¸å¿…æ¯æ¬¡éƒ½ä»Žå¤´å¼€å§‹ã€‚
+起,而ä¸å¿…æ¯æ¬¡éƒ½ä»Žå¤´å¼€å§‹ã€‚xa_state的内容å—rcu_read_lock()或xas_lock()çš„ä¿æŠ¤ã€‚如果需è¦åˆ é™¤ä¿æŠ¤çŠ¶æ€
+和树的这些é”中的任何一个,你必须调用xas_pause()以便将æ¥çš„调用ä¸ä¼šä¾èµ–于状æ€ä¸­æœªå—ä¿æŠ¤çš„部分。
xa_state也被用æ¥å­˜å‚¨é”™è¯¯(store errors)。你å¯ä»¥è°ƒç”¨xas_error()æ¥æ£€ç´¢é”™è¯¯ã€‚所有的æ“作在进行之å‰éƒ½
会检查xa_state是å¦å¤„于错误状æ€ï¼Œæ‰€ä»¥ä½ æ²¡æœ‰å¿…è¦åœ¨æ¯æ¬¡è°ƒç”¨ä¹‹åŽæ£€æŸ¥é”™è¯¯ï¼›ä½ å¯ä»¥è¿žç»­è¿›è¡Œå¤šæ¬¡è°ƒç”¨ï¼Œåªåœ¨
diff --git a/Documentation/translations/zh_CN/dev-tools/kasan.rst b/Documentation/translations/zh_CN/dev-tools/kasan.rst
index 23db9d419047..fe76cbe77ad6 100644
--- a/Documentation/translations/zh_CN/dev-tools/kasan.rst
+++ b/Documentation/translations/zh_CN/dev-tools/kasan.rst
@@ -11,34 +11,65 @@
概述
----
-KernelAddressSANitizer(KASAN)是一ç§åŠ¨æ€å†…存安全错误检测工具,主è¦åŠŸèƒ½æ˜¯
-检查内存越界访问和使用已释放内存的问题。KASAN有三ç§æ¨¡å¼:
+Kernel Address SANitizer(KASAN)是一ç§åŠ¨æ€å†…存安全错误检测工具,主è¦åŠŸèƒ½æ˜¯
+检查内存越界访问和使用已释放内存的问题。
-1. 通用KASAN(与用户空间的ASan类似)
-2. 基于软件标签的KASAN(与用户空间的HWASan类似)
-3. 基于硬件标签的KASAN(基于硬件内存标签)
+KASAN有三ç§æ¨¡å¼:
-由于通用KASAN的内存开销较大,通用KASAN主è¦ç”¨äºŽè°ƒè¯•ã€‚基于软件标签的KASAN
-å¯ç”¨äºŽdogfood测试,因为它具有较低的内存开销,并å…许将其用于实际工作é‡ã€‚
-基于硬件标签的KASAN具有较低的内存和性能开销,因此å¯ç”¨äºŽç”Ÿäº§ã€‚åŒæ—¶å¯ç”¨äºŽ
-检测现场内存问题或作为安全缓解措施。
+1. 通用KASAN
+2. 基于软件标签的KASAN
+3. 基于硬件标签的KASAN
-软件KASAN模å¼ï¼ˆ#1å’Œ#2)使用编译时工具在æ¯æ¬¡å†…存访问之å‰æ’入有效性检查,
-因此需è¦ä¸€ä¸ªæ”¯æŒå®ƒçš„编译器版本。
+用CONFIG_KASAN_GENERICå¯ç”¨çš„通用KASAN,是用于调试的模å¼ï¼Œç±»ä¼¼äºŽç”¨æˆ·ç©º
+é—´çš„ASan。这ç§æ¨¡å¼åœ¨è®¸å¤šCPU架构上都被支æŒï¼Œä½†å®ƒæœ‰æ˜Žæ˜¾çš„性能和内存开销。
-通用KASAN在GCCå’ŒClangå—支æŒã€‚GCC需è¦8.3.0或更高版本。任何å—支æŒçš„Clang
-版本都是兼容的,但从Clang 11æ‰å¼€å§‹æ”¯æŒæ£€æµ‹å…¨å±€å˜é‡çš„越界访问。
+基于软件标签的KASAN或SW_TAGS KASAN,通过CONFIG_KASAN_SW_TAGSå¯ç”¨ï¼Œ
+å¯ä»¥ç”¨äºŽè°ƒè¯•å’Œè‡ªæˆ‘测试,类似于用户空间HWASan。这ç§æ¨¡å¼åªæ”¯æŒarm64,但其
+适度的内存开销å…许在内存å—é™çš„设备上用真实的工作负载进行测试。
-基于软件标签的KASAN模å¼ä»…在Clang中å—支æŒã€‚
+基于硬件标签的KASAN或HW_TAGS KASAN,用CONFIG_KASAN_HW_TAGSå¯ç”¨ï¼Œè¢«
+用作现场内存错误检测器或作为安全缓解的模å¼ã€‚è¿™ç§æ¨¡å¼åªåœ¨æ”¯æŒMTE(内存标签
+扩展)的arm64 CPU上工作,但它的内存和性能开销很低,因此å¯ä»¥åœ¨ç”Ÿäº§ä¸­ä½¿ç”¨ã€‚
-硬件KASAN模å¼ï¼ˆ#3)ä¾èµ–硬件æ¥æ‰§è¡Œæ£€æŸ¥ï¼Œä½†ä»éœ€è¦æ”¯æŒå†…存标签指令的编译器
-版本。GCC 10+å’ŒClang 11+支æŒæ­¤æ¨¡å¼ã€‚
+关于æ¯ç§KASAN模å¼çš„内存和性能影å“的细节,请å‚è§ç›¸åº”çš„Kconfig选项的æ述。
-两ç§è½¯ä»¶KASAN模å¼éƒ½é€‚用于SLUBå’ŒSLAB内存分é…器,而基于硬件标签的KASANç›®å‰
-仅支æŒSLUB。
+通用模å¼å’ŒåŸºäºŽè½¯ä»¶æ ‡ç­¾çš„模å¼é€šå¸¸è¢«ç§°ä¸ºè½¯ä»¶æ¨¡å¼ã€‚基于软件标签的模å¼å’ŒåŸºäºŽ
+硬件标签的模å¼è¢«ç§°ä¸ºåŸºäºŽæ ‡ç­¾çš„模å¼ã€‚
-ç›®å‰x86_64ã€armã€arm64ã€xtensaã€s390ã€riscv架构支æŒé€šç”¨KASAN模å¼ï¼Œä»…
-arm64架构支æŒåŸºäºŽæ ‡ç­¾çš„KASAN模å¼ã€‚
+支æŒ
+----
+
+体系架构
+~~~~~~~~
+
+在x86_64ã€armã€arm64ã€powerpcã€riscvã€s390å’Œxtensa上支æŒé€šç”¨KASAN,
+而基于标签的KASAN模å¼åªåœ¨arm64上支æŒã€‚
+
+编译器
+~~~~~~
+
+软件KASAN模å¼ä½¿ç”¨ç¼–译时工具在æ¯ä¸ªå†…存访问之å‰æ’入有效性检查,因此需è¦ä¸€ä¸ª
+æ供支æŒçš„编译器版本。基于硬件标签的模å¼ä¾é ç¡¬ä»¶æ¥æ‰§è¡Œè¿™äº›æ£€æŸ¥ï¼Œä½†ä»ç„¶éœ€è¦
+一个支æŒå†…存标签指令的编译器版本。
+
+通用KASAN需è¦GCC 8.3.0版本或更高版本,或者内核支æŒçš„任何Clang版本。
+
+基于软件标签的KASAN需è¦GCC 11+或者内核支æŒçš„任何Clang版本。
+
+基于硬件标签的KASAN需è¦GCC 10+或Clang 12+。
+
+内存类型
+~~~~~~~~
+
+通用KASAN支æŒåœ¨æ‰€æœ‰çš„slabã€page_allocã€vmapã€vmallocã€å †æ ˆå’Œå…¨å±€å†…å­˜
+中查找错误。
+
+基于软件标签的KASAN支æŒslabã€page_allocã€vmalloc和堆栈内存。
+
+基于硬件标签的KASAN支æŒslabã€page_allocå’Œä¸å¯æ‰§è¡Œçš„vmalloc内存。
+
+对于slab,两ç§è½¯ä»¶KASAN模å¼éƒ½æ”¯æŒSLUBå’ŒSLAB分é…器,而基于硬件标签的
+KASANåªæ”¯æŒSLUB。
用法
----
@@ -53,7 +84,7 @@ arm64架构支æŒåŸºäºŽæ ‡ç­¾çš„KASAN模å¼ã€‚
对于软件模å¼ï¼Œè¿˜å¯ä»¥åœ¨ ``CONFIG_KASAN_OUTLINE`` å’Œ ``CONFIG_KASAN_INLINE``
之间进行选择。outlineå’Œinline是编译器æ’桩类型。å‰è€…产生较å°çš„二进制文件,
-而åŽè€…å¿«1.1-2å€ã€‚
+而åŽè€…å¿«2å€ã€‚
è¦å°†å—å½±å“çš„slab对象的allocå’Œfree堆栈跟踪包å«åˆ°æŠ¥å‘Šä¸­ï¼Œè¯·å¯ç”¨
``CONFIG_STACKTRACE`` 。è¦åŒ…括å—å½±å“物ç†é¡µé¢çš„分é…和释放堆栈跟踪的è¯ï¼Œ
@@ -172,21 +203,29 @@ KASANå—通用 ``panic_on_warn`` 命令行å‚æ•°çš„å½±å“。å¯ç”¨è¯¥åŠŸèƒ½åŽï¼
默认情况下,KASANåªä¸ºç¬¬ä¸€æ¬¡æ— æ•ˆå†…存访问打å°é”™è¯¯æŠ¥å‘Šã€‚使用 ``kasan_multi_shot`` ,
KASAN会针对æ¯ä¸ªæ— æ•ˆè®¿é—®æ‰“å°æŠ¥å‘Šã€‚这有效地ç¦ç”¨äº†KASAN报告的 ``panic_on_warn`` 。
+å¦å¤–,独立于 ``panic_on_warn`` , ``kasan.fault=`` 引导å‚æ•°å¯ä»¥ç”¨æ¥æŽ§åˆ¶æ慌和报
+告行为:
+
+- ``kasan.fault=report`` 或 ``=panic`` 控制是åªæ‰“å°KASAN报告还是åŒæ—¶ä½¿å†…æ ¸ææ…Œ
+ (默认: ``report`` )。å³ä½¿å¯ç”¨äº† ``kasan_multi_shot`` ,也会å‘生内核æ慌。
+
基于硬件标签的KASAN模å¼ï¼ˆè¯·å‚阅下é¢æœ‰å…³å„ç§æ¨¡å¼çš„部分)旨在在生产中用作安全缓解
-措施。因此,它支æŒå…许ç¦ç”¨KASAN或控制其功能的引导å‚数。
+措施。因此,它支æŒå…许ç¦ç”¨KASAN或控制其功能的附加引导å‚数。
- ``kasan=off`` 或 ``=on`` 控制KASAN是å¦å¯ç”¨ (默认: ``on`` )。
-- ``kasan.mode=sync`` 或 ``=async`` 控制KASAN是å¦é…置为åŒæ­¥æˆ–异步执行模å¼(默认:
- ``sync`` )。åŒæ­¥æ¨¡å¼ï¼šå½“标签检查错误å‘生时,立å³æ£€æµ‹åˆ°é”™è¯¯è®¿é—®ã€‚异步模å¼ï¼š
- 延迟错误访问检测。当标签检查错误å‘生时,信æ¯å­˜å‚¨åœ¨ç¡¬ä»¶ä¸­ï¼ˆåœ¨arm64çš„
+- ``kasan.mode=sync`` 〠``=async`` 或 ``=asymm`` 控制KASAN是å¦é…ç½®
+ 为åŒæ­¥æˆ–异步执行模å¼(默认:``sync`` )。
+ åŒæ­¥æ¨¡å¼ï¼šå½“标签检查错误å‘生时,立å³æ£€æµ‹åˆ°é”™è¯¯è®¿é—®ã€‚
+ 异步模å¼ï¼šå»¶è¿Ÿé”™è¯¯è®¿é—®æ£€æµ‹ã€‚当标签检查错误å‘生时,信æ¯å­˜å‚¨åœ¨ç¡¬ä»¶ä¸­ï¼ˆåœ¨arm64çš„
TFSR_EL1寄存器中)。内核会定期检查硬件,并且仅在这些检查期间报告标签错误。
+ éžå¯¹ç§°æ¨¡å¼ï¼šè¯»å–æ—¶åŒæ­¥æ£€æµ‹ä¸è‰¯è®¿é—®ï¼Œå†™å…¥æ—¶å¼‚步检测。
+
+- ``kasan.vmalloc=off`` 或 ``=on`` ç¦ç”¨æˆ–å¯ç”¨vmalloc分é…的标记(默认:``on`` )。
- ``kasan.stacktrace=off`` 或 ``=on`` ç¦ç”¨æˆ–å¯ç”¨allocå’Œfree堆栈跟踪收集
(默认: ``on`` )。
-- ``kasan.fault=report`` 或 ``=panic`` 控制是åªæ‰“å°KASAN报告还是åŒæ—¶ä½¿å†…æ ¸ææ…Œ
- (默认: ``report`` )。å³ä½¿å¯ç”¨äº† ``kasan_multi_shot`` ,也会å‘生内核æ慌。
实施细则
--------
@@ -244,7 +283,6 @@ KASAN会针对æ¯ä¸ªæ— æ•ˆè®¿é—®æ‰“å°æŠ¥å‘Šã€‚这有效地ç¦ç”¨äº†KASAN报告ç
基于软件标签的KASAN使用0xFF作为匹é…所有指针标签(ä¸æ£€æŸ¥é€šè¿‡å¸¦æœ‰0xFF指针标签
的指针进行的访问)。值0xFE当å‰ä¿ç•™ç”¨äºŽæ ‡è®°å·²é‡Šæ”¾çš„内存区域。
-基于软件标签的KASANç›®å‰ä»…支æŒå¯¹Slabå’Œpage_alloc内存进行标记。
基于硬件标签的KASAN模å¼
~~~~~~~~~~~~~~~~~~~~~~~
@@ -262,8 +300,6 @@ KASAN会针对æ¯ä¸ªæ— æ•ˆè®¿é—®æ‰“å°æŠ¥å‘Šã€‚这有效地ç¦ç”¨äº†KASAN报告ç
基于硬件标签的KASAN使用0xFF作为匹é…所有指针标签(ä¸æ£€æŸ¥é€šè¿‡å¸¦æœ‰0xFF指针标签的
指针进行的访问)。值0xFE当å‰ä¿ç•™ç”¨äºŽæ ‡è®°å·²é‡Šæ”¾çš„内存区域。
-基于硬件标签的KASANç›®å‰ä»…支æŒå¯¹Slabå’Œpage_alloc内存进行标记。
-
如果硬件ä¸æ”¯æŒMTE(ARMv8.5之å‰ï¼‰ï¼Œåˆ™ä¸ä¼šå¯ç”¨åŸºäºŽç¡¬ä»¶æ ‡ç­¾çš„KASAN。在这ç§æƒ…况下,
所有KASAN引导å‚数都将被忽略。
@@ -275,6 +311,8 @@ KASAN会针对æ¯ä¸ªæ— æ•ˆè®¿é—®æ‰“å°æŠ¥å‘Šã€‚这有效地ç¦ç”¨äº†KASAN报告ç
å½±å­å†…å­˜
--------
+本节的内容åªé€‚用于软件KASAN模å¼ã€‚
+
内核将内存映射到地å€ç©ºé—´çš„几个ä¸åŒéƒ¨åˆ†ã€‚内核虚拟地å€çš„范围很大:没有足够的真实
内存æ¥æ”¯æŒå†…æ ¸å¯ä»¥è®¿é—®çš„æ¯ä¸ªåœ°å€çš„真实影å­åŒºåŸŸã€‚因此,KASANåªä¸ºåœ°å€ç©ºé—´çš„æŸäº›
部分映射真实的影å­ã€‚
@@ -297,7 +335,7 @@ CONFIG_KASAN_VMALLOC
~~~~~~~~~~~~~~~~~~~~
使用 ``CONFIG_KASAN_VMALLOC`` ,KASANå¯ä»¥ä»¥æ›´å¤§çš„内存使用为代价覆盖vmalloc
-空间。目å‰ï¼Œè¿™åœ¨x86ã€riscvã€s390å’Œpowerpc上å—支æŒã€‚
+空间。目å‰ï¼Œè¿™åœ¨arm64ã€x86ã€riscvã€s390å’Œpowerpc上å—支æŒã€‚
这通过连接到vmallocå’Œvmap并动æ€åˆ†é…真实的影å­å†…å­˜æ¥æ”¯æŒæ˜ å°„。
@@ -349,10 +387,10 @@ KASAN连接到vmap基础架构以懒清ç†æœªä½¿ç”¨çš„å½±å­å†…存。
``kasan_disable_current()``/``kasan_enable_current()`` 部分注释这部分代ç ã€‚
这也会ç¦ç”¨é€šè¿‡å‡½æ•°è°ƒç”¨å‘生的间接访问的报告。
-对于基于标签的KASAN模å¼ï¼ˆåŒ…括硬件模å¼ï¼‰ï¼Œè¦ç¦ç”¨è®¿é—®æ£€æŸ¥ï¼Œè¯·ä½¿ç”¨
-``kasan_reset_tag()`` 或 ``page_kasan_tag_reset()`` 。请注æ„,通过
-``page_kasan_tag_reset()`` 临时ç¦ç”¨è®¿é—®æ£€æŸ¥éœ€è¦é€šè¿‡ ``page_kasan_tag``
-/ ``page_kasan_tag_set`` ä¿å­˜å’Œæ¢å¤æ¯é¡µKASAN标签。
+对于基于标签的KASAN模å¼ï¼Œè¦ç¦ç”¨è®¿é—®æ£€æŸ¥ï¼Œè¯·ä½¿ç”¨ ``kasan_reset_tag()`` 或
+``page_kasan_tag_reset()`` 。请注æ„,通过 ``page_kasan_tag_reset()``
+临时ç¦ç”¨è®¿é—®æ£€æŸ¥éœ€è¦é€šè¿‡ ``page_kasan_tag`` / ``page_kasan_tag_set`` ä¿
+存和æ¢å¤æ¯é¡µKASAN标签。
测试
~~~~
@@ -381,11 +419,10 @@ KASAN连接到vmap基础架构以懒清ç†æœªä½¿ç”¨çš„å½±å­å†…存。
当由于缺少KASAN报告而导致测试失败时::
- # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:629
- Expected kasan_data->report_expected == kasan_data->report_found, but
- kasan_data->report_expected == 1
- kasan_data->report_found == 0
- not ok 28 - kmalloc_double_kzfree
+ # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:974
+ KASAN failure expected in "kfree_sensitive(ptr)", but none occurred
+ not ok 44 - kmalloc_double_kzfree
+
最åŽæ‰“å°æ‰€æœ‰KASAN测试的累积状æ€ã€‚æˆåŠŸ::
diff --git a/Documentation/translations/zh_CN/dev-tools/sparse.rst b/Documentation/translations/zh_CN/dev-tools/sparse.rst
index 556282437aad..0664c634bc4f 100644
--- a/Documentation/translations/zh_CN/dev-tools/sparse.rst
+++ b/Documentation/translations/zh_CN/dev-tools/sparse.rst
@@ -106,3 +106,5 @@ __releases - 指定的é”在函数进入时被æŒæœ‰ï¼Œä½†åœ¨é€€å‡ºæ—¶ä¸è¢«æŒ
make çš„å¯é€‰å˜é‡ CHECKFLAGS å¯ä»¥ç”¨æ¥å‘ sparse 工具传递å‚数。编译系统会自
åŠ¨å‘ sparse 工具传递 -Wbitwise å‚数。
+
+注æ„sparse定义了__CHECKER__预处ç†å™¨ç¬¦å·ã€‚ \ No newline at end of file
diff --git a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst
index b7a1d13da6c6..d6f2c65ed511 100644
--- a/Documentation/translations/zh_CN/dev-tools/testing-overview.rst
+++ b/Documentation/translations/zh_CN/dev-tools/testing-overview.rst
@@ -107,3 +107,28 @@ Documentation/dev-tools/kcov.rst 是能够构建在内核之中,用于在æ¯ä¸
之åŽä½ å°±èƒ½ç¡®ä¿è¿™äº›é”™è¯¯åœ¨æµ‹è¯•è¿‡ç¨‹ä¸­éƒ½ä¸ä¼šå‘生了。
一些工具与KUnitå’Œkselftest集æˆï¼Œå¹¶ä¸”在检测到问题时会自动打断测试。
+
+é™æ€åˆ†æžå·¥å…·
+============
+
+除了测试è¿è¡Œä¸­çš„内核,我们还å¯ä»¥ä½¿ç”¨**é™æ€åˆ†æž**工具直接分æžå†…核的æºä»£
+ç ï¼ˆ**在编译时**)。内核中常用的工具å…许人们检查整个æºä»£ç æ ‘或其中的特
+定文件。它们使得在开å‘过程中更容易å‘现和修å¤é—®é¢˜ã€‚
+
+ Sparseå¯ä»¥é€šè¿‡æ‰§è¡Œç±»åž‹æ£€æŸ¥ã€é”检查ã€å€¼èŒƒå›´æ£€æŸ¥æ¥å¸®åŠ©æµ‹è¯•å†…核,此外还
+ å¯ä»¥åœ¨æ£€æŸ¥ä»£ç æ—¶æŠ¥å‘Šå„ç§é”™è¯¯å’Œè­¦å‘Šã€‚关于如何使用它的细节,请å‚阅
+ Documentation/translations/zh_CN/dev-tools/sparse.rst。
+
+ Smatch扩展了Sparse,并æ供了对编程逻辑错误的é¢å¤–检查,如开关语å¥ä¸­
+ 缺少断点,错误检查中未使用的返回值,忘记在错误路径的返回中设置错误代
+ ç ç­‰ã€‚Smatch也有针对更严é‡é—®é¢˜çš„测试,如整数溢出ã€ç©ºæŒ‡é’ˆè§£é™¤å¼•ç”¨å’Œå†…
+ 存泄æ¼ã€‚è§é¡¹ç›®é¡µé¢http://smatch.sourceforge.net/。
+
+ Coccinelle是我们å¯ä»¥ä½¿ç”¨çš„å¦ä¸€ä¸ªé™æ€åˆ†æžå™¨ã€‚Coccinelleç»å¸¸è¢«ç”¨æ¥
+ 帮助æºä»£ç çš„é‡æž„和并行演化,但它也å¯ä»¥å¸®åŠ©é¿å…常è§ä»£ç æ¨¡å¼ä¸­å‡ºçŽ°çš„æŸ
+ 些错误。å¯ç”¨çš„测试类型包括API测试ã€å†…核迭代器的正确使用测试ã€è‡ªç”±æ“
+ 作的åˆç†æ€§æ£€æŸ¥ã€é”定行为的分æžï¼Œä»¥åŠå·²çŸ¥çš„有助于ä¿æŒå†…核使用一致性的
+ 进一步测试。详情请è§Documentation/dev-tools/coccinelle.rst。
+
+ ä¸è¿‡è¦æ³¨æ„的是,é™æ€åˆ†æžå·¥å…·å­˜åœ¨**å‡é˜³æ€§**的问题。在试图修å¤é”™è¯¯å’Œè­¦
+ 告之å‰ï¼Œéœ€è¦ä»”细评估它们。
diff --git a/Documentation/translations/zh_CN/devicetree/index.rst b/Documentation/translations/zh_CN/devicetree/index.rst
index 23d0b6fccd58..3fc355fe0037 100644
--- a/Documentation/translations/zh_CN/devicetree/index.rst
+++ b/Documentation/translations/zh_CN/devicetree/index.rst
@@ -1,7 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst
-:Original: Documentation/Devicetree/index.rst
+:Original: Documentation/devicetree/index.rst
:翻译:
diff --git a/Documentation/translations/zh_CN/devicetree/of_unittest.rst b/Documentation/translations/zh_CN/devicetree/of_unittest.rst
index abd94e771ef8..11eb08ca8866 100644
--- a/Documentation/translations/zh_CN/devicetree/of_unittest.rst
+++ b/Documentation/translations/zh_CN/devicetree/of_unittest.rst
@@ -1,7 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst
-:Original: Documentation/Devicetree/of_unittest.rst
+:Original: Documentation/devicetree/of_unittest.rst
:翻译:
diff --git a/Documentation/translations/zh_CN/devicetree/usage-model.rst b/Documentation/translations/zh_CN/devicetree/usage-model.rst
index accdc33475a0..c6aee82c7e6e 100644
--- a/Documentation/translations/zh_CN/devicetree/usage-model.rst
+++ b/Documentation/translations/zh_CN/devicetree/usage-model.rst
@@ -1,7 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst
-:Original: Documentation/Devicetree/usage-model.rst
+:Original: Documentation/devicetree/usage-model.rst
:翻译:
diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
index 82ec84470c0b..ccfb9b8329c2 100644
--- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
+++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst
@@ -14,7 +14,7 @@ Linux内核æºæ–‡ä»¶å¯ä»¥åŒ…å«kernel-docæ ¼å¼çš„结构化文档注释,用ä»
实际有ç€æ˜Žæ˜¾çš„ä¸åŒã€‚内核æºåŒ…å«æˆåƒä¸Šä¸‡ä¸ªkernel-doc注释。请åšæŒéµå¾ª
此处æ述的风格。
-.. note:: kernel-doc无法包å«Rust代ç ï¼šè¯·å‚考 Documentation/rust/docs.rst 。
+.. note:: kernel-doc无法包å«Rust代ç ï¼šè¯·å‚考 Documentation/rust/general-information.rst 。
从注释中æå–kernel-doc结构,并从中生æˆé€‚当的 `Sphinx C 域`_ 函数和带有锚点的
类型æ述。这些注释将被过滤以生æˆç‰¹æ®Škernel-doc高亮和交å‰å¼•ç”¨ã€‚详è§ä¸‹æ–‡ã€‚
diff --git a/Documentation/translations/zh_CN/iio/iio_configfs.rst b/Documentation/translations/zh_CN/iio/iio_configfs.rst
index d5460e951804..eccaf1c644b4 100644
--- a/Documentation/translations/zh_CN/iio/iio_configfs.rst
+++ b/Documentation/translations/zh_CN/iio/iio_configfs.rst
@@ -37,10 +37,10 @@ configfsè½»æ¾é…置的对象(例如:设备,触å‘器)。
3. 软件触å‘器
=============
-IIO默认configfs组之一是“触å‘器â€ç»„。 挂载configfsåŽå¯ä»¥è‡ªåŠ¨è®¿é—®å®ƒï¼Œå¹¶ä¸”å¯
+IIO默认configfs组之一是“触å‘器â€ç»„。挂载configfsåŽå¯ä»¥è‡ªåŠ¨è®¿é—®å®ƒï¼Œå¹¶ä¸”å¯
以在/config/iio/triggers下找到。
-IIO软件触å‘器为创建多ç§è§¦å‘器类型æ供了支æŒã€‚ 通常在include/linux/iio
+IIO软件触å‘器为创建多ç§è§¦å‘器类型æ供了支æŒã€‚通常在include/linux/iio
/sw_trigger.h:中的接å£ä¸‹å°†æ–°çš„触å‘器类型实现为å•ç‹¬çš„内核模å—:
::
@@ -76,10 +76,10 @@ IIO软件触å‘器为创建多ç§è§¦å‘器类型æ供了支æŒã€‚ 通常在incl
.ops = &iio_trig_sample_ops,
};
-module_iio_sw_trigger_driver(iio_trig_sample);
+ module_iio_sw_trigger_driver(iio_trig_sample);
-æ¯ç§è§¦å‘器类型在/config/iio/triggers下都有其自己的目录。 加载iio-trig-sample
-模å—将创建“ trig-sampleâ€è§¦å‘器类型目录/config/iio/triggers/trig-sample.
+æ¯ç§è§¦å‘器类型在/config/iio/triggers下都有其自己的目录。加载iio-trig-sample
+模å—将创建“trig-sampleâ€è§¦å‘器类型目录/config/iio/triggers/trig-sample.
我们支æŒä»¥ä¸‹ä¸­æ–­æºï¼ˆè§¦å‘器类型)
@@ -102,3 +102,5 @@ module_iio_sw_trigger_driver(iio_trig_sample);
----------------------------
"hrtimerâ€è§¦å‘器类型没有æ¥è‡ª/config dir的任何å¯é…置属性。
+它确实引入了触å‘目录的sampling_frequency属性。
+该属性以Hz为å•ä½è®¾ç½®è½®è¯¢é¢‘率,精度为mHz。 \ No newline at end of file
diff --git a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst
index f2bc154c5bcc..9112949b993c 100644
--- a/Documentation/translations/zh_CN/kernel-hacking/hacking.rst
+++ b/Documentation/translations/zh_CN/kernel-hacking/hacking.rst
@@ -81,7 +81,7 @@
过硬件中断)的“软件中断â€å°†è¿è¡Œï¼ˆ ``kernel/softirq.c`` )。
此处完æˆäº†è®¸å¤šçœŸæ­£çš„中断处ç†å·¥ä½œã€‚在å‘SMP过渡的早期,åªæœ‰â€œbottom halves下åŠ
-部â€ï¼ˆBHs)机制,无法利用多个CPU的优势。在从那些一团糟的就电脑切æ¢è¿‡æ¥åŽä¸ä¹…,
+部â€ï¼ˆBHs)机制,无法利用多个CPU的优势。在从那些一团糟的旧电脑切æ¢è¿‡æ¥åŽä¸ä¹…,
我们放弃了这个é™åˆ¶ï¼Œè½¬è€Œä½¿ç”¨â€œè½¯ä¸­æ–­â€ã€‚
``include/linux/interrupt.h`` 列出了ä¸åŒçš„软中断。定时器软中断是一个éžå¸¸é‡è¦
@@ -95,8 +95,7 @@
.. warning::
- “taskletâ€è¿™ä¸ªå字是误导性的:它们与“任务â€æ— å…³ï¼Œå¯èƒ½æ›´å¤šä¸Žå½“æ—¶
- 阿列克谢·库兹涅ä½å¤«äº«ç”¨çš„糟糕ä¼ç‰¹åŠ æœ‰å…³ã€‚
+ “taskletâ€è¿™ä¸ªå字是误导性的:它们与“任务â€æ— å…³ã€‚
ä½ å¯ä»¥ä½¿ç”¨ :c:func:`in_softirq()` å®ï¼ˆ ``include/linux/preempt.h`` )æ¥ç¡®è®¤
是å¦å¤„于软中断(或å­ä»»åŠ¡ï¼‰ä¸­ã€‚
@@ -247,7 +246,7 @@ Provide mechanism not policyâ€ã€‚
与 :c:func:`put_user()` å’Œ :c:func:`get_user()` ä¸åŒï¼Œå®ƒä»¬è¿”回未å¤åˆ¶çš„
æ•°æ®é‡ï¼ˆå³0ä»ç„¶æ„味ç€æˆåŠŸï¼‰ã€‚
-ã€æ˜¯çš„,这个愚蠢的接å£çœŸå¿ƒè®©æˆ‘尴尬。ç«çˆ†çš„å£æ°´ä»—大概æ¯å¹´éƒ½ä¼šå‘生。
+ã€æ˜¯çš„,这个讨厌的接å£çœŸå¿ƒè®©æˆ‘尴尬。ç«çˆ†çš„å£æ°´ä»—大概æ¯å¹´éƒ½ä¼šå‘生。
—— Rusty Russell】
这些函数å¯ä»¥éšå¼ç¡çœ ã€‚它ä¸åº”该在用户上下文之外调用(没有æ„义)ã€è°ƒç”¨æ—¶ç¦ç”¨ä¸­æ–­
@@ -538,9 +537,9 @@ Documentation/core-api/symbol-namespaces.rst 。
Linus和其他开å‘人员有时会更改开å‘内核中的函数或结构体å称;这样åšä¸ä»…是为了
让æ¯ä¸ªäººéƒ½ä¿æŒè­¦æƒ•ï¼Œè¿˜å映了一个é‡å¤§çš„更改(例如,ä¸èƒ½å†åœ¨æ‰“开中断的情况下
-调用,或者执行é¢å¤–的检查,或者ä¸æ‰§è¡Œä»¥å‰æ•èŽ·çš„检查)。通常这会附带一个linux
-内核邮件列表中相当全é¢çš„注释;请æœç´¢å­˜æ¡£ä»¥æŸ¥çœ‹ã€‚简å•åœ°å¯¹æ–‡ä»¶è¿›è¡Œå…¨å±€æ›¿æ¢é€šå¸¸
-会让事情å˜å¾— **更糟** 。
+调用,或者执行é¢å¤–的检查,或者ä¸æ‰§è¡Œä»¥å‰æ•èŽ·çš„检查)。通常这会附带å‘é€ä¸€ä¸ª
+相当全é¢çš„注释到相应的内核邮件列表中;请æœç´¢å­˜æ¡£ä»¥æŸ¥çœ‹ã€‚简å•åœ°å¯¹æ–‡ä»¶è¿›è¡Œå…¨å±€
+替æ¢é€šå¸¸åªä¼šè®©äº‹æƒ…å˜å¾— **更糟** 。
åˆå§‹åŒ–结构体æˆå‘˜
------------------
@@ -610,7 +609,7 @@ C++
为了让你的东西更正å¼ã€è¡¥ä¸æ›´æ•´æ´ï¼Œè¿˜æœ‰ä¸€äº›å·¥ä½œè¦åšï¼š
-- æžæ¸…楚你在è°çš„地界儿上干活。查看æºæ–‡ä»¶çš„顶部〠``MAINTAINERS`` 文件以åŠ
+- æžæ¸…楚你修改的代ç å±žäºŽè°ã€‚查看æºæ–‡ä»¶çš„根目录〠``MAINTAINERS`` 文件以åŠ
``CREDITS`` 文件的最åŽä¸€éƒ¨åˆ†ã€‚你应该和此人å调,确ä¿ä½ æ²¡æœ‰é‡æ–°å‘明轮å­ï¼Œ
或者å°è¯•ä¸€äº›å·²ç»è¢«æ‹’ç»çš„东西。
@@ -629,12 +628,12 @@ C++
“obj-$(CONFIG_xxx) += xxx.oâ€ã€‚语法记录在
Documentation/kbuild/makefiles.rst 。
-- 如果你åšäº†ä¸€äº›æœ‰æ„义的事情,那å¯ä»¥æŠŠè‡ªå·±æ”¾è¿› ``CREDITS`` ,通常ä¸æ­¢ä¸€ä¸ª
- 文件(无论如何你的å字都应该在æºæ–‡ä»¶çš„顶部)。维护人员æ„味ç€æ‚¨å¸Œæœ›åœ¨å¯¹
- å­ç³»ç»Ÿè¿›è¡Œæ›´æ”¹æ—¶å¾—到询问,并了解缺陷;这æ„味ç€å¯¹æŸéƒ¨åˆ†ä»£ç åšå‡ºæ›´å¤šæ‰¿è¯ºã€‚
+- 如果你认为自己åšäº†ä¸€äº›æœ‰æ„义的事情,å¯ä»¥æŠŠè‡ªå·±æ”¾è¿› ``CREDITS`` ,通常ä¸
+ 止一个文件(无论如何你的å字都应该在æºæ–‡ä»¶çš„顶部)。 ``MAINTAINERS``
+ æ„味ç€æ‚¨å¸Œæœ›åœ¨å¯¹å­ç³»ç»Ÿè¿›è¡Œæ›´æ”¹æ—¶å¾—到询问,并了解缺陷;这æ„味ç€å¯¹æŸéƒ¨åˆ†
+ 代ç åšå‡ºæ›´å¤šæ‰¿è¯ºã€‚
-- 最åŽï¼Œåˆ«å¿˜è®°åŽ»é˜…读 Documentation/process/submitting-patches.rst ,
- 也许还有 Documentation/process/submitting-drivers.rst 。
+- 最åŽï¼Œåˆ«å¿˜è®°åŽ»é˜…读 Documentation/process/submitting-patches.rst。
Kernel 仙女棒
===============
diff --git a/Documentation/translations/zh_CN/locking/index.rst b/Documentation/translations/zh_CN/locking/index.rst
index 700df8a2bb70..f0b10707668d 100644
--- a/Documentation/translations/zh_CN/locking/index.rst
+++ b/Documentation/translations/zh_CN/locking/index.rst
@@ -14,17 +14,18 @@
.. toctree::
:maxdepth: 1
+ mutex-design
+ spinlocks
+
TODOList:
* locktypes
* lockdep-design
* lockstat
* locktorture
- * mutex-design
* rt-mutex-design
* rt-mutex
* seqlock
- * spinlocks
* ww-mutex-design
* preempt-locking
* pi-futex
diff --git a/Documentation/translations/zh_CN/locking/mutex-design.rst b/Documentation/translations/zh_CN/locking/mutex-design.rst
new file mode 100644
index 000000000000..6aad54372a6c
--- /dev/null
+++ b/Documentation/translations/zh_CN/locking/mutex-design.rst
@@ -0,0 +1,145 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/locking/mutex-design.rst
+
+:翻译:
+
+ å”艺舟 Tang Yizhou <tangyeechou@gmail.com>
+
+================
+通用互斥é”å­ç³»ç»Ÿ
+================
+
+:åˆç¨¿:
+
+ Ingo Molnar <mingo@redhat.com>
+
+:æ›´æ–°:
+
+ Davidlohr Bueso <davidlohr@hp.com>
+
+什么是互斥é”?
+--------------
+
+在Linux内核中,互斥é”(mutex)指的是一个特殊的加é”原语,它在共享内存系统上
+强制ä¿è¯åºåˆ—化,而ä¸ä»…仅是指在学术界或类似的ç†è®ºæ•™ç§‘书中出现的通用术语“相互
+排斥â€ã€‚互斥é”是一ç§ç¡çœ é”,它的行为类似于二进制信å·é‡ï¼ˆsemaphores),在
+2006年被引入时[1],作为åŽè€…的替代å“。这ç§æ–°çš„æ•°æ®ç»“æž„æ供了许多优点,包括更
+简å•çš„接å£ï¼Œä»¥åŠåœ¨å½“时更少的代ç é‡ï¼ˆè§ç¼ºé™·ï¼‰ã€‚
+
+[1] https://lwn.net/Articles/164802/
+
+实现
+----
+
+互斥é”由“struct mutexâ€è¡¨ç¤ºï¼Œåœ¨include/linux/mutex.h中定义,并在
+kernel/locking/mutex.c中实现。这些é”使用一个原å­å˜é‡ï¼ˆ->owner)æ¥è·Ÿè¸ª
+它们生命周期内的é”状æ€ã€‚字段owner实际上包å«çš„是指å‘当å‰é”所有者的
+`struct task_struct *` 指针,因此如果无人æŒæœ‰é”,则它的值为空(NULL)。
+由于task_struct的指针至少按L1_CACHE_BYTES对é½ï¼Œä½Žä½ï¼ˆ3)被用æ¥å­˜å‚¨é¢å¤–
+的状æ€ï¼ˆä¾‹å¦‚,等待者列表éžç©ºï¼‰ã€‚在其最基本的形å¼ä¸­ï¼Œå®ƒè¿˜åŒ…括一个等待队列和
+一个确ä¿å¯¹å…¶åºåˆ—化访问的自旋é”。此外,CONFIG_MUTEX_SPIN_ON_OWNER=yçš„
+系统使用一个自旋MCSé”(->osq,译注:MCS是两个人åçš„åˆå¹¶ç¼©å†™ï¼‰ï¼Œåœ¨ä¸‹æ–‡çš„
+(ii)中æ述。
+
+准备获得一把自旋é”时,有三ç§å¯èƒ½ç»è¿‡çš„路径,å–决于é”的状æ€ï¼š
+
+(i) 快速路径:试图通过调用cmpxchg()修改é”的所有者为当å‰ä»»åŠ¡ï¼Œä»¥æ­¤åŽŸå­åŒ–地
+ 获å–é”。这åªåœ¨æ— ç«žäº‰çš„情况下有效(cmpxchg()检查值是å¦ä¸º0,所以3个状æ€
+ 比特必须为0)。如果é”处在竞争状æ€ï¼Œä»£ç è¿›å…¥ä¸‹ä¸€ä¸ªå¯èƒ½çš„路径。
+
+(ii) 中速路径:也就是ä¹è§‚自旋,当é”的所有者正在è¿è¡Œå¹¶ä¸”没有其它优先级更高的
+ 任务(need_resched,需è¦é‡æ–°è°ƒåº¦ï¼‰å‡†å¤‡è¿è¡Œæ—¶ï¼Œå½“å‰ä»»åŠ¡è¯•å›¾è‡ªæ—‹æ¥èŽ·å¾—
+ é”。原ç†æ˜¯ï¼Œå¦‚æžœé”的所有者正在è¿è¡Œï¼Œå®ƒå¾ˆå¯èƒ½ä¸ä¹…就会释放é”。互斥é”自旋体
+ 使用MCSé”排队,这样åªæœ‰ä¸€ä¸ªè‡ªæ—‹ä½“å¯ä»¥ç«žäº‰äº’æ–¥é”。
+
+ MCSé”(由Mellor-Crummeyå’ŒScottæ出)是一个简å•çš„自旋é”,它具有一些
+ ç†æƒ³çš„特性,比如公平,以åŠæ¯ä¸ªCPU在试图获得é”时在一个本地å˜é‡ä¸Šè‡ªæ—‹ã€‚
+ 它é¿å…了常è§çš„“检测-设置â€è‡ªæ—‹é”实现导致的(CPU核间)缓存行回弹
+ (cacheline bouncing)这ç§æ˜‚贵的开销。一个类MCSé”是为实现ç¡çœ é”çš„
+ ä¹è§‚自旋而专门定制的。这ç§å®šåˆ¶MCSé”的一个é‡è¦ç‰¹æ€§æ˜¯ï¼Œå®ƒæœ‰ä¸€ä¸ªé¢å¤–的属性,
+ 当自旋体需è¦é‡æ–°è°ƒåº¦æ—¶ï¼Œå®ƒä»¬èƒ½å¤Ÿé€€å‡ºMCS自旋é”队列。这进一步有助于é¿å…
+ 以下场景:需è¦é‡æ–°è°ƒåº¦çš„MCS自旋体将继续自旋等待自旋体所有者,å³å°†èŽ·å¾—
+ MCSé”æ—¶å´ç›´æŽ¥è¿›å…¥æ…¢é€Ÿè·¯å¾„。
+
+(iii) 慢速路径:最åŽçš„手段,如果ä»ç„¶æ— æ³•èŽ·å¾—é”,该任务会被添加到等待队列中,
+ 休眠直到被解é”路径唤醒。在通常情况下,它以TASK_UNINTERRUPTIBLE状æ€
+ 阻塞。
+
+虽然从形å¼ä¸Šçœ‹ï¼Œå†…核互斥é”是å¯ç¡çœ çš„é”,路径(ii)使它实际上æˆä¸ºæ··åˆç±»åž‹ã€‚通过
+简å•åœ°ä¸ä¸­æ–­ä¸€ä¸ªä»»åŠ¡å¹¶å¿™ç€ç­‰å¾…几个周期,而ä¸æ˜¯ç«‹å³ç¡çœ ï¼Œè¿™ç§é”å·²ç»è¢«è®¤ä¸ºæ˜¾è‘—
+改善一些工作负载的性能。注æ„,这ç§æŠ€æœ¯ä¹Ÿè¢«ç”¨äºŽè¯»å†™ä¿¡å·é‡ï¼ˆrw-semaphores)。
+
+语义
+----
+
+互斥é”å­ç³»ç»Ÿæ£€æŸ¥å¹¶å¼ºåˆ¶æ‰§è¡Œä»¥ä¸‹è§„则:
+
+ - æ¯æ¬¡åªæœ‰ä¸€ä¸ªä»»åŠ¡å¯ä»¥æŒæœ‰è¯¥äº’æ–¥é”。
+ - åªæœ‰é”的所有者å¯ä»¥è§£é”该互斥é”。
+ - ä¸å…许多次解é”。
+ - ä¸å…许递归加é”/解é”。
+ - 互斥é”åªèƒ½é€šè¿‡API进行åˆå§‹åŒ–(è§ä¸‹æ–‡ï¼‰ã€‚
+ - 一个任务ä¸èƒ½åœ¨æŒæœ‰äº’æ–¥é”的情况下退出。
+ - æŒæœ‰é”的内存区域ä¸å¾—被释放。
+ - 被æŒæœ‰çš„é”ä¸èƒ½è¢«é‡æ–°åˆå§‹åŒ–。
+ - 互斥é”ä¸èƒ½ç”¨äºŽç¡¬ä»¶æˆ–软件中断上下文,如å°ä»»åŠ¡ï¼ˆtasklet)和定时器。
+
+当CONFIG DEBUG_MUTEXES被å¯ç”¨æ—¶ï¼Œè¿™äº›è¯­ä¹‰å°†è¢«å®Œå…¨å¼ºåˆ¶æ‰§è¡Œã€‚此外,互斥é”
+调试代ç è¿˜å®žçŽ°äº†ä¸€äº›å…¶å®ƒç‰¹æ€§ï¼Œä½¿é”的调试更容易ã€æ›´å¿«é€Ÿï¼š
+
+ - 当打å°åˆ°è°ƒè¯•è¾“出时,总是使用互斥é”的符å·å称。
+ - 加é”点跟踪,函数å符å·åŒ–查找,系统æŒæœ‰çš„全部é”的列表,打å°å‡ºå®ƒä»¬ã€‚
+ - 所有者跟踪。
+ - 检测自我递归的é”并打å°æ‰€æœ‰ç›¸å…³ä¿¡æ¯ã€‚
+ - 检测多任务环形ä¾èµ–æ­»é”,并打å°æ‰€æœ‰å—å½±å“çš„é”和任务(并且åªé™äºŽè¿™äº›ä»»åŠ¡ï¼‰ã€‚
+
+
+接å£
+----
+é™æ€å®šä¹‰äº’æ–¥é”::
+
+ DEFINE_MUTEX(name);
+
+动æ€åˆå§‹åŒ–互斥é”::
+
+ mutex_init(mutex);
+
+以ä¸å¯ä¸­æ–­æ–¹å¼ï¼ˆuninterruptible)获å–互斥é”::
+
+ void mutex_lock(struct mutex *lock);
+ void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
+ int mutex_trylock(struct mutex *lock);
+
+以å¯ä¸­æ–­æ–¹å¼ï¼ˆinterruptible)获å–互斥é”::
+
+ int mutex_lock_interruptible_nested(struct mutex *lock,
+ unsigned int subclass);
+ int mutex_lock_interruptible(struct mutex *lock);
+
+当原å­å˜é‡å‡ä¸º0时,以å¯ä¸­æ–­æ–¹å¼ï¼ˆinterruptible)获å–互斥é”::
+
+ int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
+
+释放互斥é”::
+
+ void mutex_unlock(struct mutex *lock);
+
+检测是å¦å·²ç»èŽ·å–互斥é”::
+
+ int mutex_is_locked(struct mutex *lock);
+
+缺陷
+----
+
+与它最åˆçš„设计和目的ä¸åŒï¼Œ'struct mutex' 是内核中最大的é”之一。例如:在
+x86-64上它是32字节,而 'struct semaphore' 是24字节,rw_semaphore是
+40字节。更大的结构体大å°æ„味ç€æ›´å¤šçš„CPU缓存和内存å ç”¨ã€‚
+
+
+何时使用互斥é”
+--------------
+
+总是优先选择互斥é”而ä¸æ˜¯ä»»ä½•å…¶å®ƒé”原语,除éžäº’æ–¥é”的严格语义ä¸åˆé€‚,和/或临界区
+阻止é”被共享。
diff --git a/Documentation/translations/zh_CN/process/5.Posting.rst b/Documentation/translations/zh_CN/process/5.Posting.rst
index 4ee7de13f373..6a469e1c7deb 100644
--- a/Documentation/translations/zh_CN/process/5.Posting.rst
+++ b/Documentation/translations/zh_CN/process/5.Posting.rst
@@ -19,8 +19,7 @@
内核开å‘社区已ç»å‘展出一套用于å‘布补ä¸çš„约定和过程;éµå¾ªè¿™äº›çº¦å®šå’Œè¿‡ç¨‹å°†ä½¿
å‚与其中的æ¯ä¸ªäººçš„生活更加轻æ¾ã€‚本文档试图æ述这些约定的部分细节;更多信æ¯
也å¯åœ¨ä»¥ä¸‹æ–‡æ¡£ä¸­æ‰¾åˆ°
-:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`,
-:ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>`
+:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
和 :ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`。
何时寄é€
diff --git a/Documentation/translations/zh_CN/process/8.Conclusion.rst b/Documentation/translations/zh_CN/process/8.Conclusion.rst
index 4707f0101964..643b88af97bb 100644
--- a/Documentation/translations/zh_CN/process/8.Conclusion.rst
+++ b/Documentation/translations/zh_CN/process/8.Conclusion.rst
@@ -19,7 +19,6 @@
:ref:`Documentation/translations/zh_CN/process/howto.rst <cn_process_howto>`
文件是一个é‡è¦çš„起点;
:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
-和 :ref:`Documentation/translations/zh_CN/process/submitting-drivers.rst <cn_submittingdrivers>`
也是所有内核开å‘人员都应该阅读的内容。许多内部内核API都是使用kerneldoc机制
记录的;“make htmldocsâ€æˆ–“make pdfdocsâ€å¯ç”¨äºŽä»¥HTML或PDFæ ¼å¼ç”Ÿæˆè¿™äº›æ–‡æ¡£
(尽管æŸäº›å‘行版æ供的tex版本会é‡åˆ°å†…部é™åˆ¶ï¼Œæ— æ³•æ­£ç¡®å¤„ç†æ–‡æ¡£ï¼‰ã€‚
diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst
index 1334cdb32a3c..1455190dc087 100644
--- a/Documentation/translations/zh_CN/process/howto.rst
+++ b/Documentation/translations/zh_CN/process/howto.rst
@@ -96,7 +96,6 @@ Linux内核代ç ä¸­åŒ…å«æœ‰å¤§é‡çš„文档。这些文档对于学习如何与
的代ç ã€‚
:ref:`Documentation/translations/zh_CN/process/submitting-patches.rst <cn_submittingpatches>`
- :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
这两份文档明确æ述如何创建和å‘é€è¡¥ä¸ï¼Œå…¶ä¸­åŒ…括(但ä¸ä»…é™äºŽ):
- 邮件内容
diff --git a/Documentation/translations/zh_CN/process/index.rst b/Documentation/translations/zh_CN/process/index.rst
index 39e9c88fbaa6..a683dbea0c83 100644
--- a/Documentation/translations/zh_CN/process/index.rst
+++ b/Documentation/translations/zh_CN/process/index.rst
@@ -40,7 +40,6 @@
.. toctree::
:maxdepth: 1
- submitting-drivers
submit-checklist
stable-api-nonsense
stable-kernel-rules
diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst
deleted file mode 100644
index 98341e7cd812..000000000000
--- a/Documentation/translations/zh_CN/process/submitting-drivers.rst
+++ /dev/null
@@ -1,160 +0,0 @@
-.. _cn_submittingdrivers:
-
-.. include:: ../disclaimer-zh_CN.rst
-
-:Original: :ref:`Documentation/process/submitting-drivers.rst
- <submittingdrivers>`
-
-如果想评论或更新本文的内容,请直接è”系原文档的维护者。如果你使用英文
-交æµæœ‰å›°éš¾çš„è¯ï¼Œä¹Ÿå¯ä»¥å‘中文版维护者求助。如果本翻译更新ä¸åŠæ—¶æˆ–者翻
-译存在问题,请è”系中文版维护者::
-
- 中文版维护者: æŽé˜³ Li Yang <leoyang.li@nxp.com>
- 中文版翻译者: æŽé˜³ Li Yang <leoyang.li@nxp.com>
- 中文版校译者: é™ˆç¦ Maggie Chen <chenqi@beyondsoft.com>
- çŽ‹èª Wang Cong <xiyou.wangcong@gmail.com>
- å¼ å· Zhang Wei <wezhang@outlook.com>
-
-å¦‚ä½•å‘ Linux 内核æ交驱动程åº
-=============================
-
-这篇文档将会解释如何å‘ä¸åŒçš„内核æºç æ ‘æ交设备驱动程åºã€‚请注æ„,如果你感
-兴趣的是显å¡é©±åŠ¨ç¨‹åºï¼Œä½ ä¹Ÿè®¸åº”该访问 XFree86 项目(https://www.xfree86.org/)
-å’Œï¼æˆ– X.org 项目 (https://x.org)。
-
-å¦è¯·å‚阅 Documentation/translations/zh_CN/process/submitting-patches.rst 文档。
-
-
-分é…设备å·
-----------
-
-å—设备和字符设备的主设备å·ä¸Žä»Žè®¾å¤‡å·æ˜¯ç”± Linux 命åç¼–å·åˆ†é…æƒå¨ LANANA(
-现在是 Torben Mathiasen)负责分é…。申请的网å€æ˜¯ https://www.lanana.org/。
-å³ä½¿ä¸å‡†å¤‡æ交到主æµå†…核的设备驱动也需è¦åœ¨è¿™é‡Œåˆ†é…设备å·ã€‚有关详细信æ¯ï¼Œ
-请å‚阅 Documentation/admin-guide/devices.rst。
-
-如果你使用的ä¸æ˜¯å·²ç»åˆ†é…的设备å·ï¼Œé‚£ä¹ˆå½“ä½ æ交设备驱动的时候,它将会被强
-制分é…一个新的设备å·ï¼Œå³ä¾¿è¿™ä¸ªè®¾å¤‡å·å’Œä½ ä¹‹å‰å‘给客户的截然ä¸åŒã€‚
-
-设备驱动的æ交对象
-------------------
-
-Linux 2.0:
- 此内核æºç æ ‘ä¸æŽ¥å—新的驱动程åºã€‚
-
-Linux 2.2:
- 此内核æºç æ ‘ä¸æŽ¥å—新的驱动程åºã€‚
-
-Linux 2.4:
- 如果所属的代ç é¢†åŸŸåœ¨å†…核的 MAINTAINERS 文件中列有一个总维护者,
- 那么请将驱动程åºæ交给他。如果此维护者没有回应或者你找ä¸åˆ°æ°å½“çš„
- 维护者,那么请è”ç³» Willy Tarreau <w@1wt.eu>。
-
-Linux 2.6:
- 除了éµå¾ªå’Œ 2.4 版内核åŒæ ·çš„规则外,你还需è¦åœ¨ linux-kernel 邮件
- 列表上跟踪最新的 API å˜åŒ–ã€‚å‘ Linux 2.6 内核æ交驱动的顶级è”系人
- 是 Andrew Morton <akpm@linux-foundation.org>。
-
-决定设备驱动能å¦è¢«æŽ¥å—çš„æ¡ä»¶
-----------------------------
-
-许å¯ï¼š 代ç å¿…须使用 GNU 通用公开许å¯è¯ (GPL) æ交给 Linux,但是
- 我们并ä¸è¦æ±‚ GPL 是唯一的许å¯ã€‚你或许会希望åŒæ—¶ä½¿ç”¨å¤šç§
- 许å¯è¯å‘布,如果希望驱动程åºå¯ä»¥è¢«å…¶ä»–å¼€æºç¤¾åŒºï¼ˆæ¯”如BSD)
- 使用。请å‚考 include/linux/module.h 文件中所列出的å¯è¢«
- 接å—共存的许å¯ã€‚
-
-版æƒï¼š 版æƒæ‰€æœ‰è€…å¿…é¡»åŒæ„使用 GPL 许å¯ã€‚最好æ交者和版æƒæ‰€æœ‰è€…
- 是相åŒä¸ªäººæˆ–实体。å¦åˆ™ï¼Œå¿…需列出授æƒä½¿ç”¨ GPL 的版æƒæ‰€æœ‰
- 人或实体,以备验è¯ä¹‹éœ€ã€‚
-
-接å£ï¼š 如果你的驱动程åºä½¿ç”¨çŽ°æˆçš„接å£å¹¶ä¸”和其他åŒç±»çš„驱动程åºè¡Œ
- 为相似,而ä¸æ˜¯åŽ»å‘明无谓的新接å£ï¼Œé‚£ä¹ˆå®ƒå°†ä¼šæ›´å®¹æ˜“被接å—。
- 如果你需è¦ä¸€ä¸ª Linux å’Œ NT 的通用驱动接å£ï¼Œé‚£ä¹ˆè¯·åœ¨ç”¨
- 户空间实现它。
-
-代ç ï¼š 请使用 Documentation/process/coding-style.rst 中所æè¿°çš„ Linux 代ç é£Ž
- 格。如果你的æŸäº›ä»£ç æ®µï¼ˆä¾‹å¦‚那些与 Windows 驱动程åºåŒ…å…±
- 享的代ç æ®µï¼‰éœ€è¦ä½¿ç”¨å…¶ä»–æ ¼å¼ï¼Œè€Œä½ å´åªå¸Œæœ›ç»´æŠ¤ä¸€ä»½ä»£ç ï¼Œ
- 那么请将它们很好地区分出æ¥ï¼Œå¹¶ä¸”注明原因。
-
-å¯ç§»æ¤æ€§ï¼š 请注æ„,指针并ä¸æ°¸è¿œæ˜¯ 32 ä½çš„,ä¸æ˜¯æ‰€æœ‰çš„计算机都使用å°
- å°¾æ¨¡å¼ (little endian) 存储数æ®ï¼Œä¸æ˜¯æ‰€æœ‰çš„人都拥有浮点
- å•å…ƒï¼Œä¸è¦éšä¾¿åœ¨ä½ çš„驱动程åºé‡ŒåµŒå…¥ x86 汇编指令。åªèƒ½åœ¨
- x86 上è¿è¡Œçš„驱动程åºä¸€èˆ¬æ˜¯ä¸å—欢迎的。虽然你å¯èƒ½åªæœ‰ x86
- 硬件,很难测试驱动程åºåœ¨å…¶ä»–å¹³å°ä¸Šæ˜¯å¦å¯ç”¨ï¼Œä½†æ˜¯ç¡®ä¿ä»£ç 
- å¯ä»¥è¢«è½»æ¾åœ°ç§»æ¤å´æ˜¯å¾ˆç®€å•çš„。
-
-清晰度: åšåˆ°æ‰€æœ‰äººéƒ½èƒ½ä¿®è¡¥è¿™ä¸ªé©±åŠ¨ç¨‹åºå°†ä¼šå¾ˆæœ‰å¥½å¤„,因为这样你将
- 会直接收到修å¤çš„è¡¥ä¸è€Œä¸æ˜¯ bug 报告。如果你æ交一个试图
- éšè—硬件工作机ç†çš„驱动程åºï¼Œé‚£ä¹ˆå®ƒå°†ä¼šè¢«æ‰”进废纸篓。
-
-电æºç®¡ç†ï¼š 因为 Linux 正在被很多移动设备和桌é¢ç³»ç»Ÿä½¿ç”¨ï¼Œæ‰€ä»¥ä½ çš„驱
- 动程åºä¹Ÿå¾ˆæœ‰å¯èƒ½è¢«ä½¿ç”¨åœ¨è¿™äº›è®¾å¤‡ä¸Šã€‚它应该支æŒæœ€åŸºæœ¬çš„电
- æºç®¡ç†ï¼Œå³åœ¨éœ€è¦çš„情况下实现系统级休眠和唤醒è¦ç”¨åˆ°çš„
- .suspend å’Œ .resume 函数。你应该检查你的驱动程åºæ˜¯å¦èƒ½æ­£
- 确地处ç†ä¼‘眠与唤醒,如果实在无法确认,请至少把 .suspend
- 函数定义æˆè¿”回 -ENOSYS(功能未实现)错误。你还应该å°è¯•ç¡®
- ä¿ä½ çš„驱动在什么都ä¸å¹²çš„情况下将耗电é™åˆ°æœ€ä½Žã€‚è¦èŽ·å¾—驱动
- 程åºæµ‹è¯•çš„指导,请å‚阅
- Documentation/power/drivers-testing.rst。有关驱动程åºç”µ
- æºç®¡ç†é—®é¢˜ç›¸å¯¹å…¨é¢çš„概述,请å‚阅
- Documentation/driver-api/pm/devices.rst。
-
-管ç†ï¼š 如果一个驱动程åºçš„作者还在进行有效的维护,那么通常除了那
- 些明显正确且ä¸éœ€è¦ä»»ä½•æ£€æŸ¥çš„è¡¥ä¸ä»¥å¤–,其他所有的补ä¸éƒ½ä¼š
- 被转å‘给作者。如果你希望æˆä¸ºé©±åŠ¨ç¨‹åºçš„è”系人和更新者,最
- 好在代ç æ³¨é‡Šä¸­å†™æ˜Žå¹¶ä¸”在 MAINTAINERS 文件中加入这个驱动
- 程åºçš„æ¡ç›®ã€‚
-
-ä¸å½±å“设备驱动能å¦è¢«æŽ¥å—çš„æ¡ä»¶
-------------------------------
-
-供应商: 由硬件供应商æ¥ç»´æŠ¤é©±åŠ¨ç¨‹åºé€šå¸¸æ˜¯ä¸€ä»¶å¥½äº‹ã€‚ä¸è¿‡ï¼Œå¦‚æžœæºç 
- 树里已ç»æœ‰å…¶ä»–人æ供了å¯ç¨³å®šå·¥ä½œçš„驱动程åºï¼Œé‚£ä¹ˆè¯·ä¸è¦æœŸ
- 望“我是供应商â€ä¼šæˆä¸ºå†…核改用你的驱动程åºçš„ç†ç”±ã€‚ç†æƒ³çš„情
- 况是:供应商与现有驱动程åºçš„作者åˆä½œï¼Œæž„建一个统一完美的
- 驱动程åºã€‚
-
-作者: 驱动程åºæ˜¯ç”±å¤§çš„ Linux å…¬å¸ç ”å‘还是由你个人编写,并ä¸å½±
- å“其是å¦èƒ½è¢«å†…核接å—。没有人对内核æºç æ ‘享有特æƒã€‚åªè¦ä½ 
- 充分了解内核社区,你就会å‘现这一点。
-
-
-资æºåˆ—表
---------
-
-Linux 内核主æºç æ ‘:
- ftp.??.kernel.org:/pub/linux/kernel/...
- ?? == 你的国家代ç ï¼Œä¾‹å¦‚ "cn"ã€"us"ã€"uk"ã€"fr" 等等
-
-Linux 内核邮件列表:
- linux-kernel@vger.kernel.org
- [å¯é€šè¿‡å‘majordomo@vger.kernel.orgå‘邮件æ¥è®¢é˜…]
-
-Linux 设备驱动程åºï¼Œç¬¬ä¸‰ç‰ˆï¼ˆæŽ¢è®¨ 2.6.10 版内核):
- https://lwn.net/Kernel/LDD3/ (å…费版)
-
-LWN.net:
- æ¯å‘¨å†…核开å‘æ´»åŠ¨æ‘˜è¦ - https://lwn.net/
-
- 2.6 版中 API çš„å˜æ›´ï¼š
-
- https://lwn.net/Articles/2.6-kernel-api/
-
- 将旧版内核的驱动程åºç§»æ¤åˆ° 2.6 版:
-
- https://lwn.net/Articles/driver-porting/
-
-内核新手(KernelNewbies):
- 为新的内核开å‘者æ供文档和帮助
- https://kernelnewbies.org/
-
-Linux USB项目:
- http://www.linux-usb.org/
-
-写内核驱动的“ä¸è¦â€ï¼ˆArjan van de Ven著):
- http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf
-
-内核清æ´å·¥ (Kernel Janitor):
- https://kernelnewbies.org/KernelJanitors
diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst
index a9570165582a..ebb7f37575c1 100644
--- a/Documentation/translations/zh_CN/process/submitting-patches.rst
+++ b/Documentation/translations/zh_CN/process/submitting-patches.rst
@@ -23,9 +23,7 @@
以下文档å«æœ‰å¤§é‡ç®€æ´çš„建议, 具体请è§ï¼š
:ref:`Documentation/process <development_process_main>`
åŒæ ·ï¼Œ:ref:`Documentation/translations/zh_CN/process/submit-checklist.rst <cn_submitchecklist>`
-给出在æ交代ç å‰éœ€è¦æ£€æŸ¥çš„项目的列表。如果你在æ交一个驱动程åºï¼Œé‚£ä¹ˆ
-åŒæ—¶é˜…读一下:
-:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
+给出在æ交代ç å‰éœ€è¦æ£€æŸ¥çš„项目的列表。
其中许多步骤æ述了Git版本控制系统的默认行为;如果您使用Gitæ¥å‡†å¤‡è¡¥ä¸ï¼Œ
您将å‘现它为您完æˆçš„大部分机械工作,尽管您ä»ç„¶éœ€è¦å‡†å¤‡å’Œè®°å½•ä¸€ç»„åˆç†çš„
diff --git a/Documentation/translations/zh_CN/riscv/index.rst b/Documentation/translations/zh_CN/riscv/index.rst
index 614cde0c0997..131e405aa857 100644
--- a/Documentation/translations/zh_CN/riscv/index.rst
+++ b/Documentation/translations/zh_CN/riscv/index.rst
@@ -19,7 +19,6 @@ RISC-V 体系结构
boot-image-header
vm-layout
- pmu
patch-acceptance
diff --git a/Documentation/translations/zh_CN/riscv/pmu.rst b/Documentation/translations/zh_CN/riscv/pmu.rst
deleted file mode 100644
index 7ec801026c4d..000000000000
--- a/Documentation/translations/zh_CN/riscv/pmu.rst
+++ /dev/null
@@ -1,235 +0,0 @@
-.. include:: ../disclaimer-zh_CN.rst
-
-:Original: Documentation/riscv/pmu.rst
-
-:翻译:
-
- å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
-
-.. _cn_riscv_pmu:
-
-========================
-RISC-Vå¹³å°ä¸Šå¯¹PMUs的支æŒ
-========================
-
-Alan Kao <alankao@andestech.com>, Mar 2018
-
-简介
-------------
-
-截止本文撰写时,在The RISC-V ISA Privileged Version 1.10中æ到的 perf_event
-相关特性如下:
-(详情请查阅手册)
-
-* [m|s]counteren
-* mcycle[h], cycle[h]
-* minstret[h], instret[h]
-* mhpeventx, mhpcounterx[h]
-
-仅有以上这些功能,移æ¤perf需è¦åšå¾ˆå¤šå·¥ä½œï¼Œç©¶å…¶åŽŸå› æ˜¯ç¼ºå°‘以下通用架构的性能
-监测特性:
-
-* å¯ç”¨/åœç”¨è®¡æ•°å™¨
- 在我们这里,计数器一直在自由è¿è¡Œã€‚
-* 计数器溢出引起的中断
- 规范中没有这ç§åŠŸèƒ½ã€‚
-* 中断指示器
- ä¸å¯èƒ½æ‰€æœ‰çš„计数器都有很多的中断端å£ï¼Œæ‰€ä»¥éœ€è¦ä¸€ä¸ªä¸­æ–­æŒ‡ç¤ºå™¨è®©è½¯ä»¶æ¥åˆ¤æ–­
- 哪个计数器刚好溢出。
-* 写入计数器
- 由于内核ä¸èƒ½ä¿®æ”¹è®¡æ•°å™¨ï¼Œæ‰€ä»¥ä¼šæœ‰ä¸€ä¸ªSBIæ¥æ”¯æŒè¿™ä¸ªåŠŸèƒ½[1]。 å¦å¤–,一些厂商
- 考虑实现M-S-Uåž‹å·æœºå™¨çš„硬件扩展æ¥ç›´æŽ¥å†™å…¥è®¡æ•°å™¨ã€‚
-
-这篇文档旨在为开å‘者æ供一个在内核中支æŒPMU的简è¦æŒ‡å—。下é¢çš„章节简è¦è§£é‡Šäº†
-perf' 机制和待办事项。
-
-ä½ å¯ä»¥åœ¨è¿™é‡ŒæŸ¥çœ‹ä»¥å‰çš„讨论[1][2]。 å¦å¤–,查看附录中的相关内核结构体å¯èƒ½ä¼šæœ‰
-帮助。
-
-
-1. åˆå§‹åŒ–
----------
-
-*riscv_pmu* 是一个类型为 *struct riscv_pmu* 的全局指针,它包å«äº†æ ¹æ®perf内部
-约定的å„ç§æ–¹æ³•å’ŒPMU-specificå‚数。人们应该声明这样的实例æ¥ä»£è¡¨PMU。 默认情况
-下, *riscv_pmu* 指å‘一个常é‡ç»“构体 *riscv_base_pmu* ,它对基准QEMU模型有éžå¸¸
-基础的支æŒã€‚
-
-
-然åŽä»–/她å¯ä»¥å°†å®žä¾‹çš„指针分é…ç»™ *riscv_pmu* ,这样就å¯ä»¥åˆ©ç”¨å·²ç»å®žçŽ°çš„最å°é€»
-辑,或者创建他/她自己的 *riscv_init_platform_pmu* 实现。
-
-æ¢å¥è¯è¯´ï¼ŒçŽ°æœ‰çš„ *riscv_base_pmu* æºåªæ˜¯æ供了一个å‚考实现。 å¼€å‘者å¯ä»¥çµæ´»åœ°
-决定多少部分å¯ç”¨ï¼Œåœ¨æœ€æžç«¯çš„情况下,他们å¯ä»¥æ ¹æ®è‡ªå·±çš„需è¦å®šåˆ¶æ¯ä¸€ä¸ªå‡½æ•°ã€‚
-
-
-2. Event Initialization
------------------------
-
-当用户å¯åŠ¨perf命令æ¥ç›‘控一些事件时,首先会被用户空间的perf工具解释为多个
-*perf_event_open* 系统调用,然åŽè¿›ä¸€æ­¥è°ƒç”¨ä¸Šä¸€æ­¥åˆ†é…çš„ *event_init* æˆå‘˜å‡½æ•°
-的主体。 在 *riscv_base_pmu* 的情况下,就是 *riscv_event_init* 。
-
-该功能的主è¦ç›®çš„是将用户æ供的事件翻译æˆæ˜ å°„图,从而å¯ä»¥ç›´æŽ¥å¯¹HW-related的控
-制寄存器或计数器进行æ“作。该翻译基于 *riscv_pmu* 中æ供的映射和方法。
-
-注æ„,有些功能也å¯ä»¥åœ¨è¿™ä¸ªé˜¶æ®µå®Œæˆ:
-
-(1) 中断设置,这个在下一节说;
-(2) 特é™çº§è®¾ç½®(仅用户空间ã€ä»…内核空间ã€ä¸¤è€…都有)ï¼›
-(3) æžæž„函数设置。 通常应用 *riscv_destroy_event* å³å¯ï¼›
-(4) 对éžé‡‡æ ·äº‹ä»¶çš„调整,这将被函数应用,如 *perf_adjust_period* ,通常如下::
-
- if (!is_sampling_event(event)) {
- hwc->sample_period = x86_pmu.max_period;
- hwc->last_period = hwc->sample_period;
- local64_set(&hwc->period_left, hwc->sample_period);
- }
-
-
-在 *riscv_base_pmu* 的情况下,目å‰åªæ供了(3)。
-
-
-3. 中断
--------
-
-3.1. 中断åˆå§‹åŒ–
-
-è¿™ç§æƒ…况ç»å¸¸å‡ºçŽ°åœ¨ *event_init* 方案的开头。通常情况下,这应该是一个代ç æ®µï¼Œå¦‚::
-
- int x86_reserve_hardware(void)
- {
- int err = 0;
-
- if (!atomic_inc_not_zero(&pmc_refcount)) {
- mutex_lock(&pmc_reserve_mutex);
- if (atomic_read(&pmc_refcount) == 0) {
- if (!reserve_pmc_hardware())
- err = -EBUSY;
- else
- reserve_ds_buffers();
- }
- if (!err)
- atomic_inc(&pmc_refcount);
- mutex_unlock(&pmc_reserve_mutex);
- }
-
- return err;
- }
-
-而神奇的是 *reserve_pmc_hardware* ,它通常åšåŽŸå­æ“作,使实现的IRQå¯ä»¥ä»ŽæŸä¸ªå…¨å±€å‡½
-数指针访问。 而 *release_pmc_hardware* 的作用正好相å,它用在上一节æ到的事件分é…
-器中。
-
- (注:从所有架构的实现æ¥çœ‹ï¼Œ*reserve/release* 对总是IRQ设置,所以 *pmc_hardware*
- 似乎有些误导。 它并ä¸å¤„ç†äº‹ä»¶å’Œç‰©ç†è®¡æ•°å™¨ä¹‹é—´çš„绑定,这一点将在下一节介ç»ã€‚)
-
-3.2. IRQ结构体
-
-基本上,一个IRQè¿è¡Œä»¥ä¸‹ä¼ªä»£ç ::
-
- for each hardware counter that triggered this overflow
-
- get the event of this counter
-
- // following two steps are defined as *read()*,
- // check the section Reading/Writing Counters for details.
- count the delta value since previous interrupt
- update the event->count (# event occurs) by adding delta, and
- event->hw.period_left by subtracting delta
-
- if the event overflows
- sample data
- set the counter appropriately for the next overflow
-
- if the event overflows again
- too frequently, throttle this event
- fi
- fi
-
- end for
-
- 然而截至目å‰ï¼Œæ²¡æœ‰ä¸€ä¸ªRISC-V的实现为perf设计了中断,所以具体的实现è¦åœ¨æœªæ¥å®Œæˆã€‚
-
-4. Reading/Writing 计数
------------------------
-
-它们看似差ä¸å¤šï¼Œä½†perf对待它们的æ€åº¦å´æˆªç„¶ä¸åŒã€‚ 对于读,在 *struct pmu* 中有一个
-*read* 接å£ï¼Œä½†å®ƒçš„作用ä¸ä»…仅是读。 æ ¹æ®ä¸Šä¸‹æ–‡ï¼Œ*read* 函数ä¸ä»…è¦è¯»å–计数器的内容
-(event->count),还è¦æ›´æ–°å·¦å‘¨æœŸåˆ°ä¸‹ä¸€ä¸ªä¸­æ–­ï¼ˆevent->hw.period_left)。
-
- 但 perf 的核心ä¸éœ€è¦ç›´æŽ¥å†™è®¡æ•°å™¨ã€‚ 写计数器éšè—在以下两点的抽象化之åŽï¼Œ
- 1) *pmu->start* ,从字é¢ä¸Šçœ‹å°±æ˜¯å¼€å§‹è®¡æ•°ï¼Œæ‰€ä»¥å¿…须把计数器设置æˆä¸€ä¸ªåˆé€‚的值,以
- 便下一次中断;
- 2)在IRQ里é¢ï¼Œåº”该把计数器设置æˆåŒæ ·çš„åˆç†å€¼ã€‚
-
-在RISC-V中,读æ“作ä¸æ˜¯é—®é¢˜ï¼Œä½†å†™æ“作就需è¦è´¹äº›åŠ›æ°”了,因为S模å¼ä¸å…许写计数器。
-
-
-5. add()/del()/start()/stop()
------------------------------
-
-基本æ€æƒ³: add()/del() å‘PMU添加/删除事件,start()/stop() å¯åŠ¨/åœæ­¢PMU中æŸä¸ªäº‹ä»¶
-的计数器。 所有这些函数都使用相åŒçš„å‚æ•°: *struct perf_event *event* å’Œ *int flag* 。
-
-把 perf 看作一个状æ€æœºï¼Œé‚£ä¹ˆä½ ä¼šå‘现这些函数作为这些状æ€ä¹‹é—´çš„状æ€è½¬æ¢è¿‡ç¨‹ã€‚
-定义了三ç§çŠ¶æ€ï¼ˆevent->hw.state):
-
-* PERF_HES_STOPPED: 计数åœæ­¢
-* PERF_HES_UPTODATE: event->count是最新的
-* PERF_HES_ARCH: ä¾èµ–于体系结构的用法,。。。我们现在并ä¸éœ€è¦å®ƒã€‚
-
-这些状æ€è½¬æ¢çš„正常æµç¨‹å¦‚下:
-
-* 用户å¯åŠ¨ä¸€ä¸ª perf 事件,导致调用 *event_init* 。
-* 当被上下文切æ¢è¿›æ¥çš„时候,*add* 会被 perf core 调用,并带有一个标志 PERF_EF_START,
- 也就是说事件被添加åŽåº”该被å¯åŠ¨ã€‚ 在这个阶段,如果有的è¯ï¼Œä¸€èˆ¬äº‹ä»¶ä¼šè¢«ç»‘定到一个物
- ç†è®¡æ•°å™¨ä¸Šã€‚当状æ€å˜ä¸ºPERF_HES_STOPPEDå’ŒPERF_HES_UPTODATE,因为现在已ç»åœæ­¢äº†,
- (软件)事件计数ä¸éœ€è¦æ›´æ–°ã€‚
-
- - 然åŽè°ƒç”¨ *start* ,并å¯ç”¨è®¡æ•°å™¨ã€‚
- 通过PERF_EF_RELOAD标志,它å‘计数器写入一个适当的值(详细情况请å‚考上一节)。
- 如果标志ä¸åŒ…å«PERF_EF_RELOAD,则ä¸ä¼šå†™å…¥ä»»ä½•å†…容。
- 现在状æ€è¢«é‡ç½®ä¸ºnone,因为它既没有åœæ­¢ä¹Ÿæ²¡æœ‰æ›´æ–°ï¼ˆè®¡æ•°å·²ç»å¼€å§‹ï¼‰ã€‚
-
-*当被上下文切æ¢å‡ºæ¥æ—¶è¢«è°ƒç”¨ã€‚ 然åŽï¼Œå®ƒæ£€æŸ¥å‡ºPMU中的所有事件,并调用 *stop* æ¥æ›´æ–°å®ƒä»¬
- 的计数。
-
- - *stop* 被 *del* å’Œperf核心调用,标志为PERF_EF_UPDATE,它ç»å¸¸ä»¥ç›¸åŒçš„逻辑和 *read*
- 共用åŒä¸€ä¸ªå­ç¨‹åºã€‚
- 状æ€åˆä¸€æ¬¡å˜ä¸ºPERF_HES_STOPPEDå’ŒPERF_HES_UPTODATE。
-
- - 这两对程åºçš„生命周期: *add* å’Œ *del* 在任务切æ¢æ—¶è¢«åå¤è°ƒç”¨ï¼›*start* å’Œ *stop* 在
- perf核心需è¦å¿«é€Ÿåœæ­¢å’Œå¯åŠ¨æ—¶ä¹Ÿä¼šè¢«è°ƒç”¨ï¼Œæ¯”如在调整中断周期时。
-
-ç›®å‰çš„实现已ç»è¶³å¤Ÿäº†ï¼Œå°†æ¥å¯ä»¥å¾ˆå®¹æ˜“地扩展到功能。
-
-A. 相关结构体
--------------
-
-* struct pmu: include/linux/perf_event.h
-* struct riscv_pmu: arch/riscv/include/asm/perf_event.h
-
- 两个结构体都被设计为åªè¯»ã€‚
-
- *struct pmu* 定义了一些函数指针接å£ï¼Œå®ƒä»¬å¤§å¤šä»¥ *struct perf_event* 作为主å‚数,根æ®
- perf的内部状æ€æœºå¤„ç†perf事件(详情请查看kernel/events/core.c)。
-
- *struct riscv_pmu* 定义了PMU的具体å‚数。 命åéµå¾ªæ‰€æœ‰å…¶å®ƒæž¶æž„的惯例。
-
-* struct perf_event: include/linux/perf_event.h
-* struct hw_perf_event
-
- 表示 perf 事件的通用结构体,以åŠç¡¬ä»¶ç›¸å…³çš„细节。
-
-* struct riscv_hw_events: arch/riscv/include/asm/perf_event.h
-
- ä¿å­˜äº‹ä»¶çŠ¶æ€çš„结构有两个固定æˆå‘˜ã€‚
- 事件的数é‡å’Œäº‹ä»¶çš„数组。
-
-å‚考文献
---------
-
-[1] https://github.com/riscv/riscv-linux/pull/124
-
-[2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA
diff --git a/Documentation/translations/zh_CN/riscv/vm-layout.rst b/Documentation/translations/zh_CN/riscv/vm-layout.rst
index 585cb89317a3..91884e2dfff8 100644
--- a/Documentation/translations/zh_CN/riscv/vm-layout.rst
+++ b/Documentation/translations/zh_CN/riscv/vm-layout.rst
@@ -6,6 +6,7 @@
:翻译:
å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+ Binbin Zhou <zhoubinbin@loongson.cn>
============================
RISC-V Linux上的虚拟内存布局
@@ -65,3 +66,39 @@ RISC-V Linux Kernel SV39
ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF
ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel
__________________|____________|__________________|_________|____________________________________________________________
+
+
+RISC-V Linux Kernel SV48
+------------------------
+
+::
+
+ ========================================================================================================================
+ å¼€å§‹åœ°å€ | å移 | 结æŸåœ°å€ | å¤§å° | 虚拟内存区域æè¿°
+ ========================================================================================================================
+ | | | |
+ 0000000000000000 | 0 | 00007fffffffffff | 128 TB | 用户空间虚拟内存,æ¯ä¸ªå†…存管ç†å™¨ä¸åŒ
+ __________________|____________|__________________|_________|___________________________________________________________
+ | | | |
+ 0000800000000000 | +128 TB | ffff7fffffffffff | ~16M TB | ... 巨大的ã€å‡ ä¹Ž64ä½å®½çš„直到内核映射的-128TB地方
+ | | | | 开始å移的éžç»å…¸è™šæ‹Ÿå†…存地å€ç©ºæ´žã€‚
+ | | | |
+ __________________|____________|__________________|_________|___________________________________________________________
+ |
+ | 内核空间的虚拟内存,在所有进程之间共享:
+ ____________________________________________________________|___________________________________________________________
+ | | | |
+ ffff8d7ffee00000 | -114.5 TB | ffff8d7ffeffffff | 2 MB | fixmap
+ ffff8d7fff000000 | -114.5 TB | ffff8d7fffffffff | 16 MB | PCI io
+ ffff8d8000000000 | -114.5 TB | ffff8f7fffffffff | 2 TB | vmemmap
+ ffff8f8000000000 | -112.5 TB | ffffaf7fffffffff | 32 TB | vmalloc/ioremap space
+ ffffaf8000000000 | -80.5 TB | ffffef7fffffffff | 64 TB | 直接映射所有物ç†å†…å­˜
+ ffffef8000000000 | -16.5 TB | fffffffeffffffff | 16.5 TB | kasan
+ __________________|____________|__________________|_________|____________________________________________________________
+ |
+ | 从此处开始,与39-bit布局相åŒï¼š
+ ____________________________________________________________|____________________________________________________________
+ | | | |
+ ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | modules, BPF
+ ffffffff80000000 | -2 GB | ffffffffffffffff | 2 GB | kernel
+ __________________|____________|__________________|_________|____________________________________________________________
diff --git a/Documentation/translations/zh_CN/scheduler/sched-stats.rst b/Documentation/translations/zh_CN/scheduler/sched-stats.rst
index 1c68c3d1c283..c5e0be663837 100644
--- a/Documentation/translations/zh_CN/scheduler/sched-stats.rst
+++ b/Documentation/translations/zh_CN/scheduler/sched-stats.rst
@@ -57,8 +57,8 @@ cpu<N> 1 2 3 4 5 6 7 8 9
接下æ¥çš„三个统计数æ®æ述了调度延迟:
- 7) 本处ç†å™¨è¿è¡Œä»»åŠ¡çš„总时间,å•ä½æ˜¯jiffies
- 8) 本处ç†å™¨ä»»åŠ¡ç­‰å¾…è¿è¡Œçš„时间,å•ä½æ˜¯jiffies
+ 7) 本处ç†å™¨è¿è¡Œä»»åŠ¡çš„总时间,å•ä½æ˜¯çº³ç§’
+ 8) 本处ç†å™¨ä»»åŠ¡ç­‰å¾…è¿è¡Œçš„时间,å•ä½æ˜¯çº³ç§’
9) 本CPUè¿è¡Œäº†#个时间片
域统计数æ®
@@ -146,8 +146,8 @@ domain<N> <cpumask> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
schedstats还添加了一个新的/proc/<pid>/schedstat文件,æ¥æ供一些进程级的
相åŒä¿¡æ¯ã€‚这个文件中,有三个字段与该进程相关:
- 1) 在CPU上è¿è¡ŒèŠ±è´¹çš„时间
- 2) 在è¿è¡Œé˜Ÿåˆ—上等待的时间
+ 1) 在CPU上è¿è¡ŒèŠ±è´¹çš„时间(å•ä½æ˜¯çº³ç§’)
+ 2) 在è¿è¡Œé˜Ÿåˆ—上等待的时间(å•ä½æ˜¯çº³ç§’)
3) 在CPU上è¿è¡Œäº†#个时间片
å¯ä»¥å¾ˆå®¹æ˜“地编写一个程åºï¼Œåˆ©ç”¨è¿™äº›é¢å¤–的字段æ¥æŠ¥å‘Šä¸€ä¸ªç‰¹å®šçš„进程或一组进程在
diff --git a/Documentation/translations/zh_CN/vm/free_page_reporting.rst b/Documentation/translations/zh_CN/vm/free_page_reporting.rst
index 31d6c34b956b..14336a3aa5f4 100644
--- a/Documentation/translations/zh_CN/vm/free_page_reporting.rst
+++ b/Documentation/translations/zh_CN/vm/free_page_reporting.rst
@@ -1,6 +1,6 @@
.. include:: ../disclaimer-zh_CN.rst
-:Original: Documentation/vm/_free_page_reporting.rst
+:Original: Documentation/vm/free_page_reporting.rst
:翻译:
diff --git a/Documentation/translations/zh_CN/vm/frontswap.rst b/Documentation/translations/zh_CN/vm/frontswap.rst
index 3eb07870e2ef..98aa6f581ea7 100644
--- a/Documentation/translations/zh_CN/vm/frontswap.rst
+++ b/Documentation/translations/zh_CN/vm/frontswap.rst
@@ -1,4 +1,4 @@
-:Original: Documentation/vm/_free_page_reporting.rst
+:Original: Documentation/vm/free_page_reporting.rst
:翻译:
diff --git a/Documentation/translations/zh_CN/vm/highmem.rst b/Documentation/translations/zh_CN/vm/highmem.rst
index 018838e58c3e..200321774646 100644
--- a/Documentation/translations/zh_CN/vm/highmem.rst
+++ b/Documentation/translations/zh_CN/vm/highmem.rst
@@ -50,55 +50,55 @@
临时虚拟映射
============
-内核包å«å‡ ç§åˆ›å»ºä¸´æ—¶æ˜ å°„的方法。:
+内核包å«å‡ ç§åˆ›å»ºä¸´æ—¶æ˜ å°„的方法。下é¢çš„列表按照使用的优先顺åºæ˜¾ç¤ºäº†å®ƒä»¬ã€‚
-* vmap(). è¿™å¯ä»¥ç”¨æ¥å°†å¤šä¸ªç‰©ç†é¡µé•¿æœŸæ˜ å°„到一个连续的虚拟空间。它需è¦synchronization
- æ¥è§£é™¤æ˜ å°„。
+* kmap_local_page()。这个函数是用æ¥è¦æ±‚短期映射的。它å¯ä»¥ä»Žä»»ä½•ä¸Šä¸‹æ–‡ï¼ˆåŒ…括中断)中调用,
+ 但是映射åªèƒ½åœ¨èŽ·å–它们的上下文中使用。
-* kmap(). è¿™å…许对å•ä¸ªé¡µé¢è¿›è¡ŒçŸ­æœŸæ˜ å°„。它需è¦synchronization,但在一定程度上被摊销。
- 当以嵌套方å¼ä½¿ç”¨æ—¶ï¼Œå®ƒä¹Ÿå¾ˆå®¹æ˜“出现死é”,因此ä¸å»ºè®®åœ¨æ–°ä»£ç ä¸­ä½¿ç”¨å®ƒã€‚
+ 在å¯è¡Œçš„情况下,这个函数应该比其他所有的函数优先使用。
-* kmap_atomic(). è¿™å…许对å•ä¸ªé¡µé¢è¿›è¡Œéžå¸¸çŸ­çš„时间映射。由于映射被é™åˆ¶åœ¨å‘布它的CPU上,
- 它表现得很好,但å‘布任务因此被è¦æ±‚留在该CPU上直到它完æˆï¼Œä»¥å…其他任务å–代它的映射。
-
- kmap_atomic() 也å¯ä»¥ç”±ä¸­æ–­ä¸Šä¸‹æ–‡ä½¿ç”¨ï¼Œå› ä¸ºå®ƒä¸ç¡çœ ï¼Œè€Œä¸”调用者å¯èƒ½åœ¨è°ƒç”¨kunmap_atomic()
- 之åŽæ‰ç¡çœ ã€‚
-
- å¯ä»¥å‡è®¾k[un]map_atomic()ä¸ä¼šå¤±è´¥ã€‚
+ 这些映射是线程本地和CPU本地的,这æ„味ç€æ˜ å°„åªèƒ½ä»Žè¿™ä¸ªçº¿ç¨‹ä¸­è®¿é—®ï¼Œå¹¶ä¸”当映射处于活动状
+ æ€æ—¶ï¼Œè¯¥çº¿ç¨‹ä¸ŽCPU绑定。å³ä½¿çº¿ç¨‹è¢«æŠ¢å äº†ï¼ˆå› ä¸ºæŠ¢å æ°¸è¿œä¸ä¼šè¢«å‡½æ•°ç¦ç”¨ï¼‰ï¼ŒCPU也ä¸èƒ½é€šè¿‡
+ CPU-hotplug从系统中拔出,直到映射被处ç†æŽ‰ã€‚
+ 在本地的kmap区域中采å–pagefaults是有效的,除éžèŽ·å–本地映射的上下文由于其他原因ä¸å…许
+ 这样åšã€‚
-使用kmap_atomic
-===============
+ kmap_local_page()总是返回一个有效的虚拟地å€ï¼Œå¹¶ä¸”å‡å®škunmap_local()ä¸ä¼šå¤±è´¥ã€‚
-何时何地使用 kmap_atomic() 是很直接的。当代ç æƒ³è¦è®¿é—®ä¸€ä¸ªå¯èƒ½ä»Žé«˜å†…存(è§__GFP_HIGHMEM)
-分é…的页é¢çš„内容时,例如在页缓存中的页é¢ï¼Œå°±ä¼šä½¿ç”¨å®ƒã€‚该API有两个函数,它们的使用方å¼ä¸Ž
-下é¢ç±»ä¼¼::
+ 嵌套kmap_local_page()å’Œkmap_atomic()映射在一定程度上是å…许的(最多到KMAP_TYPE_NR),
+ 但是它们的调用必须严格排åºï¼Œå› ä¸ºæ˜ å°„的实现是基于堆栈的。关于如何管ç†åµŒå¥—映射的细节,
+ 请å‚è§kmap_local_page() kdocs(包å«åœ¨ "函数 "部分)。
- /* 找到感兴趣的页é¢ã€‚ */
- struct page *page = find_get_page(mapping, offset);
-
- /* 获得对该页内容的访问æƒã€‚ */
- void *vaddr = kmap_atomic(page);
+* kmap_atomic(). è¿™å…许对å•ä¸ªé¡µé¢è¿›è¡Œéžå¸¸çŸ­çš„时间映射。由于映射被é™åˆ¶åœ¨å‘布它的CPU上,
+ 它表现得很好,但å‘布的任务因此被è¦æ±‚留在该CPU上直到它完æˆï¼Œä»¥å…其他任务å–代它的映射。
- /* 对该页的内容åšä¸€äº›å¤„ç†ã€‚ */
- memset(vaddr, 0, PAGE_SIZE);
+ kmap_atomic()也å¯ä»¥è¢«ä¸­æ–­ä¸Šä¸‹æ–‡ä½¿ç”¨ï¼Œå› ä¸ºå®ƒä¸ç¡çœ ï¼Œè°ƒç”¨è€…也å¯èƒ½åœ¨è°ƒç”¨kunmap_atomic()
+ åŽæ‰ç¡çœ ã€‚
- /* 解除该页é¢çš„映射。 */
- kunmap_atomic(vaddr);
+ 内核中对kmap_atomic()çš„æ¯æ¬¡è°ƒç”¨éƒ½ä¼šåˆ›å»ºä¸€ä¸ªä¸å¯æŠ¢å çš„段,并ç¦ç”¨ç¼ºé¡µå¼‚常。这å¯èƒ½æ˜¯
+ 未预期延迟的æ¥æºä¹‹ä¸€ã€‚因此用户应该选择kmap_local_page()而ä¸æ˜¯kmap_atomic()。
-注æ„,kunmap_atomic()调用的是kmap_atomic()调用的结果而ä¸æ˜¯å‚数。
+ å‡è®¾k[un]map_atomic()ä¸ä¼šå¤±è´¥ã€‚
-如果你需è¦æ˜ å°„两个页é¢ï¼Œå› ä¸ºä½ æƒ³ä»Žä¸€ä¸ªé¡µé¢å¤åˆ¶åˆ°å¦ä¸€ä¸ªé¡µé¢ï¼Œä½ éœ€è¦ä¿æŒkmap_atomic调用严
-格嵌套,如::
+* kmap()。这应该被用æ¥å¯¹å•ä¸ªé¡µé¢è¿›è¡ŒçŸ­æ—¶é—´çš„映射,对抢å æˆ–è¿ç§»æ²¡æœ‰é™åˆ¶ã€‚它会带æ¥å¼€é”€ï¼Œ
+ 因为映射空间是å—é™åˆ¶çš„,并且å—到全局é”çš„ä¿æŠ¤ï¼Œä»¥å®žçŽ°åŒæ­¥ã€‚当ä¸å†éœ€è¦æ˜ å°„时,必须用
+ kunmap()释放该页被映射的地å€ã€‚
- vaddr1 = kmap_atomic(page1);
- vaddr2 = kmap_atomic(page2);
+ 映射å˜åŒ–必须广播到所有CPU(核)上,kmap()还需è¦åœ¨kmap的池被回绕(TLB项用光了,需è¦ä»Žç¬¬
+ 一项å¤ç”¨ï¼‰æ—¶è¿›è¡Œå…¨å±€TLB无效化,当映射空间被完全利用时,它å¯èƒ½ä¼šé˜»å¡žï¼Œç›´åˆ°æœ‰ä¸€ä¸ªå¯ç”¨çš„
+ 槽出现。因此,kmap()åªèƒ½ä»Žå¯æŠ¢å çš„上下文中调用。
- memcpy(vaddr1, vaddr2, PAGE_SIZE);
+ 如果一个映射必须æŒç»­ç›¸å¯¹è¾ƒé•¿çš„时间,上述所有的工作都是必è¦çš„,但是内核中大部分的
+ 高内存映射都是短暂的,而且åªåœ¨ä¸€ä¸ªåœ°æ–¹ä½¿ç”¨ã€‚è¿™æ„味ç€åœ¨è¿™ç§æƒ…况下,kmap()çš„æˆæœ¬å¤§
+ 多被浪费了。kmap()并ä¸æ˜¯ä¸ºé•¿æœŸæ˜ å°„而设计的,但是它已ç»æœç€è¿™ä¸ªæ–¹å‘å‘展了,在较新
+ 的代ç ä¸­å¼ºçƒˆä¸é¼“励使用它,å‰é¢çš„函数集应该是首选。
- kunmap_atomic(vaddr2);
- kunmap_atomic(vaddr1);
+ 在64ä½ç³»ç»Ÿä¸­ï¼Œè°ƒç”¨kmap_local_page()ã€kmap_atomic()å’Œkmap()没有实际作用,因为64ä½
+ 地å€ç©ºé—´è¶³ä»¥æ°¸ä¹…映射所有物ç†å†…存页é¢ã€‚
+* vmap()。这å¯ä»¥ç”¨æ¥å°†å¤šä¸ªç‰©ç†é¡µé•¿æœŸæ˜ å°„到一个连续的虚拟空间。它需è¦å…¨å±€åŒæ­¥æ¥è§£é™¤
+ 映射。
临时映射的æˆæœ¬
==============
@@ -126,3 +126,12 @@ i386 PAE
一般的建议是,你ä¸è¦åœ¨32ä½æœºå™¨ä¸Šä½¿ç”¨è¶…过8GiB的空间--尽管更多的空间å¯èƒ½å¯¹ä½ å’Œä½ çš„工作
é‡æœ‰ç”¨ï¼Œä½†ä½ å‡ ä¹Žæ˜¯é ä½ è‡ªå·±--ä¸è¦æŒ‡æœ›å†…核开å‘者真的会很关心事情的进展情况。
+
+函数
+====
+
+该API在以下内核代ç ä¸­:
+
+include/linux/highmem.h
+
+include/linux/highmem-internal.h
diff --git a/Documentation/translations/zh_CN/vm/index.rst b/Documentation/translations/zh_CN/vm/index.rst
index a1c6d529b6ff..c77a56553845 100644
--- a/Documentation/translations/zh_CN/vm/index.rst
+++ b/Documentation/translations/zh_CN/vm/index.rst
@@ -12,11 +12,27 @@
Linux内存管ç†æ–‡æ¡£
=================
-这是一个关于Linux内存管ç†ï¼ˆmm)å­ç³»ç»Ÿå†…部的文档集,其中有ä¸åŒå±‚次的细节,包括注释
-和邮件列表的回å¤ï¼Œç”¨äºŽé˜è¿°æ•°æ®ç»“构和算法的基本情况。如果你正在寻找关于简å•åˆ†é…内存的建
-议,请å‚阅(Documentation/translations/zh_CN/core-api/memory-allocation.rst)。
-对于控制和调整指å—,请å‚阅(Documentation/admin-guide/mm/index)。
-TODO:待引用文档集被翻译完毕åŽè¯·åŠæ—¶ä¿®æ”¹æ­¤å¤„)
+这是一份关于了解Linux的内存管ç†å­ç³»ç»Ÿçš„指å—。如果你正在寻找关于简å•åˆ†é…内存的
+建议,请å‚阅内存分é…指å—
+(Documentation/translations/zh_CN/core-api/memory-allocation.rst)。
+关于控制和调整的指å—,请看管ç†æŒ‡å—
+(Documentation/translations/zh_CN/admin-guide/mm/index.rst)。
+
+
+.. toctree::
+ :maxdepth: 1
+
+ highmem
+
+该处剩余文档待原始文档有内容åŽç¿»è¯‘。
+
+
+é—留文档
+========
+
+这是一个关于Linux内存管ç†ï¼ˆMM)å­ç³»ç»Ÿå†…部的旧文档的集åˆï¼Œå…¶ä¸­æœ‰ä¸åŒå±‚次的细节,
+包括注释和邮件列表的回å¤ï¼Œç”¨äºŽé˜è¿°æ•°æ®ç»“构和算法的æ述。它应该被很好地整åˆåˆ°ä¸Šè¿°
+结构化的文档中,如果它已ç»å®Œæˆäº†å®ƒçš„使命,å¯ä»¥åˆ é™¤ã€‚
.. toctree::
:maxdepth: 1
@@ -25,7 +41,6 @@ TODO:待引用文档集被翻译完毕åŽè¯·åŠæ—¶ä¿®æ”¹æ­¤å¤„)
balance
damon/index
free_page_reporting
- highmem
ksm
frontswap
hmm
@@ -36,10 +51,12 @@ TODO:待引用文档集被翻译完毕åŽè¯·åŠæ—¶ä¿®æ”¹æ­¤å¤„)
numa
overcommit-accounting
page_frags
+ page_migration
page_owner
page_table_check
remap_file_pages
split_page_table_lock
+ vmalloced-kernel-stacks
z3fold
zsmalloc
@@ -47,8 +64,6 @@ TODOLIST:
* arch_pgtable_helpers
* free_page_reporting
* hugetlbfs_reserv
-* page_migration
* slub
* transhuge
* unevictable-lru
-* vmalloced-kernel-stacks
diff --git a/Documentation/translations/zh_CN/vm/page_frags.rst b/Documentation/translations/zh_CN/vm/page_frags.rst
index ad27fed33634..38ecddb9e1c0 100644
--- a/Documentation/translations/zh_CN/vm/page_frags.rst
+++ b/Documentation/translations/zh_CN/vm/page_frags.rst
@@ -1,4 +1,4 @@
-:Original: Documentation/vm/page_frag.rst
+:Original: Documentation/vm/page_frags.rst
:翻译:
diff --git a/Documentation/translations/zh_CN/vm/page_migration.rst b/Documentation/translations/zh_CN/vm/page_migration.rst
new file mode 100644
index 000000000000..566880a41ea0
--- /dev/null
+++ b/Documentation/translations/zh_CN/vm/page_migration.rst
@@ -0,0 +1,228 @@
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/vm/index.rst
+
+:翻译:
+
+ å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+========
+页é¢è¿ç§»
+========
+
+页é¢è¿ç§»å…许在进程è¿è¡Œæ—¶åœ¨NUMA系统的节点之间移动页é¢çš„物ç†ä½ç½®ã€‚è¿™æ„味ç€è¿›ç¨‹æ‰€çœ‹åˆ°çš„虚拟地
+å€å¹¶æ²¡æœ‰æ”¹å˜ã€‚然而,系统会é‡æ–°å®‰æŽ’这些页é¢çš„物ç†ä½ç½®ã€‚
+
+也å¯ä»¥å‚è§ :ref: `<å¼‚æž„å†…å­˜ç®¡ç† (HMM)>` 以了解将页é¢è¿ç§»åˆ°è®¾å¤‡ç§æœ‰å†…存或从设备ç§æœ‰å†…存中è¿ç§»ã€‚
+
+页é¢è¿ç§»çš„主è¦ç›®çš„是通过将页é¢ç§»åˆ°è®¿é—®è¯¥å†…存的进程所è¿è¡Œçš„处ç†å™¨é™„è¿‘æ¥å‡å°‘内存访问的延迟。
+
+页é¢è¿ç§»å…许进程通过MF_MOVEå’ŒMF_MOVE_ALL选项手动é‡æ–°å®šä½å…¶é¡µé¢æ‰€åœ¨çš„节点,åŒæ—¶é€šè¿‡
+mbind()设置一个新的内存策略。一个进程的页é¢ä¹Ÿå¯ä»¥é€šè¿‡sys_migrate_pages()函数调用从å¦
+一个进程é‡æ–°å®šä½ã€‚migrate_pages()函数调用接收两组节点,并将一个进程ä½äºŽæ—§èŠ‚点上的页é¢ç§»
+动到目标节点上。页é¢è¿ç§»åŠŸèƒ½ç”±Andi Kleençš„numactl包æä¾›(需è¦0.9.3以上的版本,其仓库
+地å€https://github.com/numactl/numactl.git)。numactlæ供了libnuma,它为页é¢è¿ç§»
+æ供了与其他NUMA功能类似的接å£ã€‚执行 cat ``/proc/<pid>/numa_maps`` å…许轻æ¾æŸ¥çœ‹è¿›
+程的页é¢ä½ç½®ã€‚å‚è§proc(5)手册中的numa_maps文档。
+
+如果调度程åºå°†ä¸€ä¸ªè¿›ç¨‹é‡æ–°å®‰ç½®åˆ°ä¸€ä¸ªé¥è¿œçš„节点上的处ç†å™¨ï¼Œæ‰‹åŠ¨è¿ç§»æ˜¯å¾ˆæœ‰ç”¨çš„。批é‡è°ƒåº¦ç¨‹åº
+或管ç†å‘˜å¯ä»¥æ£€æµ‹åˆ°è¿™ç§æƒ…况,并将进程的页é¢ç§»åˆ°æ–°å¤„ç†å™¨é™„近。内核本身åªæ供手动的页è¿ç§»æ”¯æŒã€‚
+自动的页é¢è¿ç§»å¯ä»¥é€šè¿‡ç”¨æˆ·ç©ºé—´çš„进程移动页é¢æ¥å®žçŽ°ã€‚一个特殊的函数调用 "move_pages" å…许
+在一个进程中移动å•ä¸ªé¡µé¢ã€‚例如,NUMA分æžå™¨å¯ä»¥èŽ·å¾—一个显示频ç¹çš„节点外访问的日志,并å¯ä»¥ä½¿
+用这个结果将页é¢ç§»åŠ¨åˆ°æ›´æœ‰åˆ©çš„ä½ç½®ã€‚
+
+较大型的设备通常使用cpusets将系统分割æˆè‹¥å¹²ä¸ªèŠ‚点。Paul Jackson为cpusetsé…备了当任务被
+转移到å¦ä¸€ä¸ªcpuset时移动页é¢çš„能力(è§:ref:`CPUSETS <cpusets>`)。Cpusetså…许进程定
+ä½çš„自动化。如果一个任务被移到一个新的cpuset上,那么它的所有页é¢ä¹Ÿä¼šéšä¹‹ç§»åŠ¨ï¼Œè¿™æ ·è¿›ç¨‹çš„
+性能就ä¸ä¼šæ€¥å‰§ä¸‹é™ã€‚如果cpusetå…许的内存节点å‘生å˜åŒ–,cpuset中的进程页也会被移动。
+
+页é¢è¿ç§»å…许为所有è¿ç§»æŠ€æœ¯ä¿ç•™ä¸€ç»„节点中页é¢çš„相对ä½ç½®ï¼Œè¿™å°†ä¿ç•™ç”Ÿæˆçš„特定内存分é…模å¼å³ä½¿
+进程已被è¿ç§»ã€‚为了ä¿ç•™å†…存延迟,这一点是必è¦çš„。è¿ç§»åŽçš„进程将以类似的性能è¿è¡Œã€‚
+
+页é¢è¿ç§»åˆ†å‡ ä¸ªæ­¥éª¤è¿›è¡Œã€‚首先为那些试图从内核中使用migrate_pages()的进程åšä¸€ä¸ªé«˜å±‚次的
+æ述(对于用户空间的使用,å¯ä»¥å‚考上é¢æ到的Andi Kleençš„numactl包),然åŽå¯¹ä½Žæ°´å¹³çš„细
+节工作åšä¸€ä¸ªä½Žæ°´å¹³æ述。
+
+在内核中使用 migrate_pages()
+============================
+
+1. 从LRU中移除页é¢ã€‚
+
+ è¦è¿ç§»çš„页é¢åˆ—表是通过扫æ页é¢å¹¶æŠŠå®ƒä»¬ç§»åˆ°åˆ—表中æ¥ç”Ÿæˆçš„。这是通过调用 isolate_lru_page()
+ æ¥å®Œæˆçš„。调用isolate_lru_page()增加了对该页的引用,这样在页é¢è¿ç§»å‘生时它就ä¸ä¼š
+ 消失。它还å¯ä»¥é˜²æ­¢äº¤æ¢å™¨æˆ–其他扫æ器é‡åˆ°è¯¥é¡µã€‚
+
+
+2. 我们需è¦æœ‰ä¸€ä¸ªnew_page_t类型的函数,å¯ä»¥ä¼ é€’ç»™migrate_pages()。这个函数应该计算
+ 出如何在给定的旧页é¢ä¸­åˆ†é…正确的新页é¢ã€‚
+
+3. migrate_pages()函数被调用,它试图进行è¿ç§»ã€‚它将调用该函数为æ¯ä¸ªè¢«è€ƒè™‘è¿ç§»çš„页é¢åˆ†
+ é…新的页é¢ã€‚
+
+migrate_pages()如何工作
+=======================
+
+migrate_pages()对它的页é¢åˆ—表进行了多次处ç†ã€‚如果当时对一个页é¢çš„所有引用都å¯ä»¥è¢«ç§»é™¤ï¼Œ
+那么这个页é¢å°±ä¼šè¢«ç§»åŠ¨ã€‚该页已ç»é€šè¿‡isolate_lru_page()从LRU中移除,并且refcount被
+增加,以便在页é¢è¿ç§»å‘生时ä¸é‡Šæ”¾è¯¥é¡µã€‚
+
+步骤:
+
+1. é”定è¦è¿ç§»çš„页é¢ã€‚
+
+2. ç¡®ä¿å›žå†™å·²ç»å®Œæˆã€‚
+
+3. é”定我们è¦è¿ç§»åˆ°çš„新页é¢ã€‚é”定它是为了在è¿ç§»è¿‡ç¨‹ä¸­ç«‹å³é˜»æ­¢å¯¹è¿™ä¸ªï¼ˆå°šæœªæ›´æ–°çš„)页é¢çš„
+ 访问。
+
+4. 所有对该页的页表引用都被转æ¢ä¸ºè¿ç§»æ¡ç›®ã€‚这就å‡å°‘了一个页é¢çš„mapcount。如果产生的
+ mapcountä¸æ˜¯é›¶ï¼Œé‚£ä¹ˆæˆ‘们就ä¸è¿ç§»è¯¥é¡µã€‚所有试图访问该页的用户空间进程现在将等待页
+ é¢é”或者等待è¿ç§»é¡µè¡¨é¡¹è¢«ç§»é™¤ã€‚
+
+5. i_pagesçš„é”被æŒæœ‰ã€‚这将导致所有试图通过映射访问该页的进程在自旋é”上阻塞。
+
+6. 检查该页的Refcount,如果还有引用,我们就退出。å¦åˆ™ï¼Œæˆ‘们知é“我们是唯一引用这个页
+ é¢çš„人。
+
+7. 检查基数树,如果它ä¸åŒ…å«æŒ‡å‘这个页é¢çš„指针,那么我们就退出,因为其他人修改了基数树。
+
+8. 新的页é¢è¦ç”¨æ—§çš„页é¢çš„一些设置进行预处ç†ï¼Œè¿™æ ·è®¿é—®æ–°çš„页é¢å°±ä¼šå‘现一个具有正确设置
+ 的页é¢ã€‚
+
+9. 基数树被改å˜ä»¥æŒ‡å‘新的页é¢ã€‚
+
+10. 旧页的引用计数被删除,因为地å€ç©ºé—´çš„引用已ç»æ¶ˆå¤±ã€‚对新页的引用被建立,因为新页被
+ 地å€ç©ºé—´å¼•ç”¨ã€‚
+
+11. i_pagesé”被放弃。这样一æ¥ï¼Œåœ¨æ˜ å°„中的查找åˆå˜å¾—å¯èƒ½äº†ã€‚进程将从在é”上自旋到在
+ 被é”的新页上ç¡çœ ã€‚
+
+12. 页é¢å†…容被å¤åˆ¶åˆ°æ–°çš„页é¢ä¸Šã€‚
+
+13. 剩余的页é¢æ ‡å¿—被å¤åˆ¶åˆ°æ–°çš„页é¢ä¸Šã€‚
+
+14. 旧的页é¢æ ‡å¿—被清除,以表明该页é¢ä¸å†æ供任何信æ¯ã€‚
+
+15. 新页é¢ä¸Šçš„回写队列被触å‘了。
+
+16. 如果è¿ç§»æ¡ç›®è¢«æ’入到页表中,那么就用真正的ptes替æ¢å®ƒä»¬ã€‚这样åšå°†ä½¿é‚£äº›å°šæœªç­‰å¾…页
+ é”的用户空间进程能够访问。
+
+17. 页é¢é”从新旧页é¢ä¸Šè¢«æ’¤é”€ã€‚等待页é”的进程将é‡åšä»–们的缺页异常,并将到达新的页é¢ã€‚
+
+18. 新的页é¢è¢«ç§»åˆ°LRU中,å¯ä»¥è¢«äº¤æ¢å™¨ç­‰å†æ¬¡æ‰«æ。
+
+éžLRU页é¢è¿ç§»
+=============
+
+尽管è¿ç§»æœ€åˆçš„目的是为了å‡å°‘NUMA的内存访问延迟,但压缩也使用è¿ç§»æ¥åˆ›å»ºé«˜é˜¶é¡µé¢ã€‚
+
+ç›®å‰å®žçŽ°çš„问题是,它被设计为åªè¿ç§»*LRU*页。然而,有一些潜在的éžLRU页é¢å¯ä»¥åœ¨é©±åŠ¨ä¸­
+被è¿ç§»ï¼Œä¾‹å¦‚,zsmalloc,virtio-balloon页é¢ã€‚
+
+对于virtio-balloon页é¢ï¼Œè¿ç§»ä»£ç è·¯å¾„çš„æŸäº›éƒ¨åˆ†å·²ç»è¢«é’©ä½ï¼Œå¹¶æ·»åŠ äº†virtio-balloon
+的特定函数æ¥æ‹¦æˆªè¿ç§»é€»è¾‘。这对一个驱动æ¥è¯´å¤ªç‰¹æ®Šäº†ï¼Œæ‰€ä»¥å…¶ä»–想让自己的页é¢å¯ç§»åŠ¨çš„驱
+动就必须在è¿ç§»è·¯å¾„中添加自己的特定钩å­ã€‚
+
+为了克æœè¿™ä¸ªé—®é¢˜ï¼ŒVM支æŒéžLRU页é¢è¿ç§»ï¼Œå®ƒä¸ºéžLRUå¯ç§»åŠ¨é¡µé¢æ供了通用函数,而在è¿ç§»
+路径中没有特定的驱动程åºé’©å­ã€‚
+
+如果一个驱动程åºæƒ³è®©å®ƒçš„页é¢å¯ç§»åŠ¨ï¼Œå®ƒåº”该定义三个函数,这些函数是
+struct address_space_operations的函数指针。
+
+1. ``bool (*isolate_page) (struct page *page, isolate_mode_t mode);``
+
+ VM对驱动的isolate_page()函数的期望是,如果驱动æˆåŠŸéš”离了该页,则返回*true*。
+ 返回trueåŽï¼ŒVM会将该页标记为PG_isolated,这样多个CPU的并å‘隔离就会跳过该
+ 页进行隔离。如果驱动程åºä¸èƒ½éš”离该页,它应该返回*false*。
+
+ 一旦页é¢è¢«æˆåŠŸéš”离,VM就会使用page.lru字段,因此驱动程åºä¸åº”期望ä¿ç•™è¿™äº›å­—段的值。
+
+2. ``int (*migratepage) (struct address_space *mapping,``
+| ``struct page *newpage, struct page *oldpage, enum migrate_mode);``
+
+ 隔离åŽï¼Œè™šæ‹Ÿæœºç”¨éš”离的页é¢è°ƒç”¨é©±åŠ¨çš„migratepage()。migratepage()的功能是将旧页
+ 的内容移动到新页,并设置struct page newpage的字段。请记ä½ï¼Œå¦‚果你æˆåŠŸè¿ç§»äº†æ—§é¡µ
+ 并返回MIGRATEPAGE_SUCCESS,你应该通过page_lock下的__ClearPageMovable()å‘虚
+ 拟机表明旧页ä¸å†å¯ç§»åŠ¨ã€‚如果驱动暂时ä¸èƒ½è¿ç§»è¯¥é¡µï¼Œé©±åŠ¨å¯ä»¥è¿”回-EAGAIN。在-EAGAIN
+ 时,VM会在短时间内é‡è¯•é¡µé¢è¿ç§»ï¼Œå› ä¸ºVMå°†-EAGAINç†è§£ä¸º "临时è¿ç§»å¤±è´¥"。在返回除
+ -EAGAIN以外的任何错误时,VM将放弃页é¢è¿ç§»è€Œä¸é‡è¯•ã€‚
+
+ 在migratepage()函数中,驱动程åºä¸åº”该接触page.lru字段。
+
+3. ``void (*putback_page)(struct page *);``
+
+ 如果在隔离页上è¿ç§»å¤±è´¥ï¼ŒVM应该将隔离页返回给驱动,因此VM用隔离页调用驱动的
+ putback_page()。在这个函数中,驱动应该把隔离页放回自己的数æ®ç»“构中。
+
+éžLRUå¯ç§»åŠ¨é¡µæ ‡å¿—
+
+ 有两个页é¢æ ‡å¿—用于支æŒéžLRUå¯ç§»åŠ¨é¡µé¢ã€‚
+
+ * PG_movable
+
+ 驱动应该使用下é¢çš„函数æ¥ä½¿é¡µé¢åœ¨page_lock下å¯ç§»åŠ¨ã€‚::
+
+ void __SetPageMovable(struct page *page, struct address_space *mapping)
+
+ 它需è¦address_spaceçš„å‚æ•°æ¥æ³¨å†Œå°†è¢«VM调用的migration family函数。确切地说,
+ PG_movableä¸æ˜¯struct page的一个真正的标志。相å,VMå¤ç”¨äº†page->mapping的低
+ ä½æ¥è¡¨ç¤ºå®ƒ::
+
+ #define PAGE_MAPPING_MOVABLE 0x2
+ page->mapping = page->mapping | PAGE_MAPPING_MOVABLE;
+
+ 所以驱动ä¸åº”该直接访问page->mapping。相å,驱动应该使用page_mapping(),它å¯
+ 以在页é¢é”下å±è”½æŽ‰page->mapping的低2ä½ï¼Œä»Žè€ŒèŽ·å¾—正确的struct address_space。
+
+ 对于éžLRUå¯ç§»åŠ¨é¡µé¢çš„测试,VM支æŒ__PageMovable()函数。然而,它并ä¸èƒ½ä¿è¯è¯†åˆ«
+ éžLRUå¯ç§»åŠ¨é¡µé¢ï¼Œå› ä¸ºpage->mapping字段与struct page中的其他å˜é‡æ˜¯ç»Ÿä¸€çš„。如
+ 果驱动程åºåœ¨è¢«è™šæ‹Ÿæœºéš”离åŽé‡Šæ”¾äº†é¡µé¢ï¼Œå°½ç®¡page->mapping设置了PAGE_MAPPING_MOVABLE,
+ 但它并没有一个稳定的值(看看__ClearPageMovable)。但是__PageMovable()在页
+ é¢è¢«éš”离åŽï¼Œæ— è®ºé¡µé¢æ˜¯LRU还是éžLRUå¯ç§»åŠ¨çš„,调用它开销都很低,因为LRU页é¢åœ¨
+ page->mapping中ä¸å¯èƒ½æœ‰PAGE_MAPPING_MOVABLE设置。在用pfn扫æ中的lock_page()
+ 进行更大开销的检查æ¥é€‰æ‹©å—害者之å‰ï¼Œå®ƒä¹Ÿå¾ˆé€‚åˆåªæ˜¯çž¥ä¸€çœ¼æ¥æµ‹è¯•éžLRUå¯ç§»åŠ¨çš„页é¢ã€‚
+
+ 为了ä¿è¯éžLRUçš„å¯ç§»åŠ¨é¡µé¢ï¼ŒVMæ供了PageMovable()函数。与__PageMovable()ä¸
+ åŒï¼ŒPageMovable()在lock_page()下验è¯page->mappingå’Œ
+ mapping->a_ops->isolate_page。lock_page()å¯ä»¥é˜²æ­¢çªç„¶ç ´åpage->mapping。
+
+ 使用__SetPageMovable()的驱动应该在释放页é¢ä¹‹å‰é€šè¿‡page_lock()下的
+ __ClearMovablePage()清除该标志。
+
+ * PG_isolated
+
+ 为了防止几个CPUåŒæ—¶è¿›è¡Œéš”离,VM在lock_page()下将隔离的页é¢æ ‡è®°ä¸ºPG_isolated。
+ 因此,如果一个CPUé‡åˆ°PG_isolatedéžLRUå¯ç§»åŠ¨é¡µé¢ï¼Œå®ƒå¯ä»¥è·³è¿‡å®ƒã€‚驱动程åºä¸éœ€è¦
+ æ“作这个标志,因为VM会自动设置/清除它。请记ä½ï¼Œå¦‚果驱动程åºçœ‹åˆ°PG_isolated页,
+ è¿™æ„味ç€è¯¥é¡µå·²ç»è¢«VM隔离,所以它ä¸åº”该碰page.lru字段。PG_isolated标志与
+ PG_reclaim标志是åŒä¹‰çš„,所以驱动程åºä¸åº”该为自己的目的使用PG_isolated。
+
+监测è¿ç§»
+========
+
+以下事件(计数器)å¯ç”¨äºŽç›‘控页é¢è¿ç§»ã€‚
+
+1. PGMIGRATE_SUCCESS: 正常的页é¢è¿ç§»æˆåŠŸã€‚æ¯ä¸ªè®¡æ•°å™¨æ„味ç€ä¸€ä¸ªé¡µé¢è¢«è¿ç§»äº†ã€‚如果该
+ 页是一个éžTHPå’Œéžhugetlb页,那么这个计数器会增加1。如果该页é¢æ˜¯ä¸€ä¸ªTHP或hugetlb
+ 页é¢ï¼Œé‚£ä¹ˆè¿™ä¸ªè®¡æ•°å™¨ä¼šéšç€THP或hugetlbå­é¡µé¢çš„æ•°é‡è€Œå¢žåŠ ã€‚例如,è¿ç§»ä¸€ä¸ªæœ‰4KB大å°
+ 的基础页(å­é¡µï¼‰çš„2MB THP,将导致这个计数器增加512。
+
+2. PGMIGRATE_FAIL: 正常的页é¢è¿ç§»å¤±è´¥ã€‚与上é¢PGMIGRATE_SUCCESS的计数规则相åŒï¼šå¦‚
+ 果是THP或hugetlb,这个计数将被å­é¡µçš„æ•°é‡å¢žåŠ ã€‚
+
+3. THP_MIGRATION_SUCCESS: 一个THP被è¿ç§»è€Œæ²¡æœ‰è¢«åˆ†å‰²ã€‚
+
+4. THP_MIGRATION_FAIL: 一个THPä¸èƒ½è¢«è¿ç§»ï¼Œä¹Ÿä¸èƒ½è¢«åˆ†å‰²ã€‚
+
+5. THP_MIGRATION_SPLIT: 一个THP被è¿ç§»äº†ï¼Œä½†ä¸æ˜¯è¿™æ ·çš„:首先,这个THP必须被分割。
+ 在拆分之åŽï¼Œå¯¹å®ƒçš„å­é¡µé¢è¿›è¡Œäº†è¿ç§»é‡è¯•ã€‚
+
+THP_MIGRATION_* 事件也会更新相应的PGMIGRATE_SUCCESS或PGMIGRATE_FAIL事件。
+例如,一个THPè¿ç§»å¤±è´¥å°†å¯¼è‡´THP_MIGRATION_FAILå’ŒPGMIGRATE_FAIL增加。
+
+Christoph Lameter,2006年5月8日。
+
+Minchan Kim,2016年3月28日。
diff --git a/Documentation/translations/zh_CN/vm/page_owner.rst b/Documentation/translations/zh_CN/vm/page_owner.rst
index 9e951fabba9d..7bd740bc5bf4 100644
--- a/Documentation/translations/zh_CN/vm/page_owner.rst
+++ b/Documentation/translations/zh_CN/vm/page_owner.rst
@@ -96,21 +96,82 @@ page owner在默认情况下是ç¦ç”¨çš„。所以,如果你想使用它,你é
默认情况下, ``page_owner_sort`` 是根æ®buf的时间æ¥æŽ’åºçš„。如果你想
按buf的页数排åºï¼Œè¯·ä½¿ç”¨-må‚数。详细的å‚数是:
- 基本函数:
+ 基本函数::
- Sort:
+ 排åº:
-a 按内存分é…时间排åº
-m 按总内存排åº
-p 按pid排åºã€‚
-P 按tgid排åºã€‚
+ -n 按任务命令å称排åºã€‚
-r 按内存释放时间排åºã€‚
-s 按堆栈跟踪排åºã€‚
-t 按时间排åºï¼ˆé»˜è®¤ï¼‰ã€‚
-
- 其它函数:
-
- Cull:
- -c 通过比较堆栈跟踪而ä¸æ˜¯æ€»å—æ¥è¿›è¡Œå‰”除。
-
- Filter:
+ --sort <order> 指定排åºé¡ºåºã€‚排åºçš„语法是[+|-]key[,[+|-]key[,...]]。从
+ **标准格å¼æŒ‡å®šå™¨**那一节选择一个键。"+"是å¯é€‰çš„,因为默认的方å‘是数字或
+ è¯æ³•çš„增加。å…许混åˆä½¿ç”¨ç¼©å†™å’Œå®Œæ•´æ ¼å¼çš„键。
+
+ 例å­:
+ ./page_owner_sort <input> <output> --sort=n,+pid,-tgid
+ ./page_owner_sort <input> <output> --sort=at
+
+ 其它函数::
+
+ 剔除:
+ --cull <rules>
+ 指定剔除规则。剔除的语法是key[,key[,...]]。从**标准格å¼æŒ‡å®šå™¨**
+ 部分选择一个多字æ¯é”®ã€‚
+ <rules>是一个以逗å·åˆ†éš”的列表形å¼çš„å•ä¸€å‚数,它æ供了一ç§æŒ‡å®šå•ä¸ªå‰”除规则的
+ 方法。 识别的关键字在下é¢çš„**标准格å¼æŒ‡å®šå™¨**部分有æ述。<规则>å¯ä»¥é€šè¿‡é”®çš„
+ åºåˆ—k1,k2,...æ¥æŒ‡å®šï¼Œåœ¨ä¸‹é¢çš„标准排åºé”®éƒ¨åˆ†æœ‰æ述。å…许混åˆä½¿ç”¨ç®€å†™å’Œå®Œæ•´å½¢
+ å¼çš„键。
+
+ Examples:
+ ./page_owner_sort <input> <output> --cull=stacktrace
+ ./page_owner_sort <input> <output> --cull=st,pid,name
+ ./page_owner_sort <input> <output> --cull=n,f
+
+ 过滤:
-f 过滤掉内存已被释放的å—çš„ä¿¡æ¯ã€‚
+
+ 选择:
+ --pid <pidlist> 按pid选择。这将选择进程IDå·å‡ºçŽ°åœ¨<pidlist>中的å—。
+ --tgid <tgidlist> 按tgid选择。这将选择其线程组IDå·å‡ºçŽ°åœ¨<tgidlist>
+ 中的å—。
+ --name <cmdlist> 按任务命令å称选择。这将选择其任务命令å称出现在
+ <cmdlist>中的区å—。
+
+ <pidlist>, <tgidlist>, <cmdlist>是以逗å·åˆ†éš”的列表形å¼çš„å•ä¸ªå‚数,
+ 它æ供了一ç§æŒ‡å®šå•ä¸ªé€‰æ‹©è§„则的方法。
+
+
+ 例å­:
+ ./page_owner_sort <input> <output> --pid=1
+ ./page_owner_sort <input> <output> --tgid=1,2,3
+ ./page_owner_sort <input> <output> --name name1,name2
+
+标准格å¼æŒ‡å®šå™¨
+==============
+::
+
+ --sort的选项:
+
+ 短键 é•¿é”® æè¿°
+ p pid 进程ID
+ tg tgid 线程组ID
+ n name 任务命令å称
+ st stacktrace 页é¢åˆ†é…的堆栈跟踪
+ T txt å—的全文
+ ft free_ts 页é¢é‡Šæ”¾æ—¶çš„时间戳
+ at alloc_ts 页é¢è¢«åˆ†é…时的时间戳
+ ator allocator 页é¢çš„内存分é…器
+
+ --curl的选项:
+
+ 短键 é•¿é”® æè¿°
+ p pid 进程ID
+ tg tgid 线程组ID
+ n name 任务命令å称
+ f free 该页是å¦å·²ç»é‡Šæ”¾
+ st stacktrace 页é¢åˆ†é…的堆栈跟踪
+ ator allocator 页é¢çš„内存分é…器
diff --git a/Documentation/translations/zh_CN/vm/vmalloced-kernel-stacks.rst b/Documentation/translations/zh_CN/vm/vmalloced-kernel-stacks.rst
new file mode 100644
index 000000000000..ad23f274f6d7
--- /dev/null
+++ b/Documentation/translations/zh_CN/vm/vmalloced-kernel-stacks.rst
@@ -0,0 +1,133 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/vm/vmalloced-kernel-stacks.rst
+
+:翻译:
+
+ å¸å»¶è…¾ Yanteng Si <siyanteng@loongson.cn>
+
+:校译:
+
+====================
+支æŒè™šæ‹Ÿæ˜ å°„的内核栈
+====================
+
+:作者: Shuah Khan <skhan@linuxfoundation.org>
+
+.. contents:: :local:
+
+概览
+----
+
+è¿™æ˜¯ä»‹ç» `虚拟映射内核栈功能 <https://lwn.net/Articles/694348/>` 的代ç 
+和原始补ä¸ç³»åˆ—çš„ä¿¡æ¯æ±‡æ€»ã€‚
+
+简介
+----
+
+内核堆栈溢出通常难以调试,并使内核容易被(æ¶æ„)利用。问题å¯èƒ½åœ¨ç¨åŽçš„时间出现,使其难以
+隔离和究其根本原因。
+
+带有ä¿æŠ¤é¡µçš„虚拟映射内核堆栈如果溢出,会被立å³æ•èŽ·ï¼Œè€Œä¸ä¼šæ”¾ä»»å…¶å¯¼è‡´éš¾ä»¥è¯Šæ–­çš„æŸ
+å。
+
+HAVE_ARCH_VMAP_STACKå’ŒVMAP_STACKé…置选项能够支æŒå¸¦æœ‰ä¿æŠ¤é¡µçš„虚拟映射堆栈。
+当堆栈溢出时,这个特性会引å‘å¯é çš„异常。溢出åŽå †æ ˆè·Ÿè¸ªçš„å¯ç”¨æ€§ä»¥åŠå¯¹æº¢å‡ºæœ¬èº«çš„
+å“应å–决于架构。
+
+.. note::
+ 截至本文撰写时, arm64, powerpc, riscv, s390, um, å’Œ x86 支æŒVMAP_STACK。
+
+HAVE_ARCH_VMAP_STACK
+--------------------
+
+能够支æŒè™šæ‹Ÿæ˜ å°„内核栈的架构应该å¯ç”¨è¿™ä¸ªboolé…置选项。è¦æ±‚是:
+
+- vmalloc空间必须大到足以容纳许多内核堆栈。这å¯èƒ½æŽ’除了许多32ä½æž¶æž„。
+- vmalloc空间的堆栈需è¦å¯é åœ°å·¥ä½œã€‚例如,如果vmap页表是按需创建的,当堆栈指å‘
+ 具有未填充页表的虚拟地å€æ—¶ï¼Œè¿™ç§æœºåˆ¶éœ€è¦å·¥ä½œï¼Œæˆ–者架构代ç ï¼ˆswitch_to()å’Œ
+ switch_mm(),很å¯èƒ½ï¼‰éœ€è¦ç¡®ä¿å †æ ˆçš„页表项在å¯èƒ½æœªå¡«å……的堆栈上è¿è¡Œä¹‹å‰å·²ç»å¡«
+ 充。
+- 如果堆栈溢出到一个ä¿æŠ¤é¡µï¼Œå°±åº”该å‘生一些åˆç†çš„事情。“åˆç†â€çš„定义是çµæ´»çš„,但
+ 在没有记录任何东西的情况下立å³é‡å¯æ˜¯ä¸å‹å¥½çš„。
+
+VMAP_STACK
+----------
+
+VMAP_STACK boolé…置选项在å¯ç”¨æ—¶åˆ†é…虚拟映射的任务栈。这个选项ä¾èµ–于
+HAVE_ARCH_VMAP_STACK。
+
+- 如果你想使用带有ä¿æŠ¤é¡µçš„虚拟映射的内核堆栈,请å¯ç”¨è¯¥é€‰é¡¹ã€‚这将导致内核栈溢出
+ 被立å³æ•èŽ·ï¼Œè€Œä¸æ˜¯éš¾ä»¥è¯Šæ–­çš„æŸå。
+
+.. note::
+
+ 使用KASAN的这个功能需è¦æž¶æž„支æŒç”¨çœŸå®žçš„å½±å­å†…å­˜æ¥æ”¯æŒè™šæ‹Ÿæ˜ å°„,并且
+ å¿…é¡»å¯ç”¨KASAN_VMALLOC。
+
+.. note::
+
+ å¯ç”¨VMAP_STACK时,无法在堆栈分é…çš„æ•°æ®ä¸Šè¿è¡ŒDMA。
+
+内核é…置选项和ä¾èµ–性ä¸æ–­å˜åŒ–。请å‚考最新的代ç åº“:
+
+`Kconfig <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/Kconfig>`
+
+分é…方法
+--------
+
+当一个新的内核线程被创建时,线程堆栈是由页级分é…器分é…的虚拟连续的内存页组æˆã€‚è¿™
+些页é¢è¢«æ˜ å°„到有PAGE_KERNELä¿æŠ¤çš„连续的内核虚拟空间。
+
+alloc_thread_stack_node()调用__vmalloc_node_range()æ¥åˆ†é…带有PAGE_KERNEL
+ä¿æŠ¤çš„栈。
+
+- 分é…的堆栈被缓存起æ¥ï¼Œä»¥åŽä¼šè¢«æ–°çš„线程é‡ç”¨ï¼Œæ‰€ä»¥åœ¨åˆ†é…/释放堆栈给任务时,è¦æ‰‹åŠ¨
+ 进行memcg核算。因此,__vmalloc_node_range被调用时没有__GFP_ACCOUNT。
+- vm_struct被缓存起æ¥ï¼Œä»¥ä¾¿èƒ½å¤Ÿæ‰¾åˆ°åœ¨ä¸­æ–­ä¸Šä¸‹æ–‡ä¸­å¯åŠ¨çš„空闲线程。 free_thread_stack()
+ å¯ä»¥åœ¨ä¸­æ–­ä¸Šä¸‹æ–‡ä¸­è°ƒç”¨ã€‚
+- 在arm64上,所有VMAP的堆栈都需è¦æœ‰ç›¸åŒçš„对é½æ–¹å¼ï¼Œä»¥ç¡®ä¿VMAP的堆栈溢出检测正常
+ 工作。架构特定的vmap堆栈分é…器照顾到了这个细节。
+- 这并ä¸æ¶‰åŠä¸­æ–­å †æ ˆ--å‚考原始补ä¸
+
+线程栈分é…是由clone()ã€fork()ã€vfork()ã€kernel_thread()通过kernel_clone()
+å¯åŠ¨çš„。留点æ示在这,以便æœç´¢ä»£ç åº“,了解线程栈何时以åŠå¦‚何分é…。
+
+大é‡çš„代ç æ˜¯åœ¨:
+`kernel/fork.c <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/kernel/fork.c>`.
+
+task_struct中的stack_vm_area指针å¯ä»¥è·Ÿè¸ªè™šæ‹Ÿåˆ†é…的堆栈,一个éžç©ºçš„stack_vm_area
+指针å¯ä»¥è¡¨æ˜Žè™šæ‹Ÿæ˜ å°„的内核堆栈已ç»å¯ç”¨ã€‚
+
+::
+
+ struct vm_struct *stack_vm_area;
+
+堆栈溢出处ç†
+------------
+
+å‰å®ˆæŠ¤é¡µå’ŒåŽå®ˆæŠ¤é¡µæœ‰åŠ©äºŽæ£€æµ‹å †æ ˆæº¢å‡ºã€‚当堆栈溢出到守护页时,处ç†ç¨‹åºå¿…é¡»å°å¿ƒä¸è¦å†
+次溢出堆栈。当处ç†ç¨‹åºè¢«è°ƒç”¨æ—¶ï¼Œå¾ˆå¯èƒ½åªç•™ä¸‹å¾ˆå°‘的堆栈空间。
+
+在x86上,这是通过处ç†è¡¨æ˜Žå†…核堆栈溢出的åŒå¼‚常堆栈的缺页异常æ¥å®žçŽ°çš„。
+
+用守护页测试VMAP分é…
+--------------------
+
+我们如何确ä¿VMAP_STACK在分é…时确实有å‰å®ˆæŠ¤é¡µå’ŒåŽå®ˆæŠ¤é¡µçš„ä¿æŠ¤ï¼Ÿä¸‹é¢çš„ lkdtm 测试
+å¯ä»¥å¸®åŠ©æ£€æµ‹ä»»ä½•å›žå½’。
+
+::
+
+ void lkdtm_STACK_GUARD_PAGE_LEADING()
+ void lkdtm_STACK_GUARD_PAGE_TRAILING()
+
+结论
+----
+
+- vmalloced堆栈的percpu缓存似乎比高阶堆栈分é…è¦å¿«ä¸€äº›ï¼Œè‡³å°‘在缓存命中时是这样。
+- THREAD_INFO_IN_TASK完全摆脱了arch-specific thread_info,并简å•åœ°å°†
+ thread_info(仅包å«æ ‡å¿—)和'int cpu'嵌入task_struct中。
+- 一旦任务死亡,线程栈就å¯ä»¥è¢«é‡Šæ”¾ï¼ˆæ— éœ€ç­‰å¾…RCU),然åŽï¼Œå¦‚果使用vmapped栈,就
+ å¯ä»¥å°†æ•´ä¸ªæ ˆç¼“存起æ¥ï¼Œä»¥ä¾¿åœ¨åŒä¸€cpu上é‡å¤ä½¿ç”¨ã€‚
diff --git a/Documentation/translations/zh_CN/vm/zsmalloc.rst b/Documentation/translations/zh_CN/vm/zsmalloc.rst
index 29e9c70a8eb6..45a9b7ab2a51 100644
--- a/Documentation/translations/zh_CN/vm/zsmalloc.rst
+++ b/Documentation/translations/zh_CN/vm/zsmalloc.rst
@@ -1,4 +1,4 @@
-:Original: Documentation/vm/zs_malloc.rst
+:Original: Documentation/vm/zsmalloc.rst
:翻译:
diff --git a/Documentation/translations/zh_TW/process/5.Posting.rst b/Documentation/translations/zh_TW/process/5.Posting.rst
index 5578bca403e6..280a8832ecc0 100644
--- a/Documentation/translations/zh_TW/process/5.Posting.rst
+++ b/Documentation/translations/zh_TW/process/5.Posting.rst
@@ -22,8 +22,7 @@
內核開發社å€å·²ç¶“發展出一套用於發布補ä¸çš„約定和éŽç¨‹ï¼›éµå¾ªé€™äº›ç´„定和éŽç¨‹å°‡ä½¿
åƒèˆ‡å…¶ä¸­çš„æ¯å€‹äººçš„生活更加輕鬆。本文檔試圖æ述這些約定的部分細節;更多信æ¯
也å¯åœ¨ä»¥ä¸‹æ–‡æª”中找到
-:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>`,
-:ref:`Documentation/translations/zh_TW/process/submitting-drivers.rst <tw_submittingdrivers>`
+:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>`
和 :ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>`。
何時郵寄
diff --git a/Documentation/translations/zh_TW/process/8.Conclusion.rst b/Documentation/translations/zh_TW/process/8.Conclusion.rst
index 7572b17667d9..044fcc118bef 100644
--- a/Documentation/translations/zh_TW/process/8.Conclusion.rst
+++ b/Documentation/translations/zh_TW/process/8.Conclusion.rst
@@ -22,7 +22,6 @@
:ref:`Documentation/translations/zh_TW/process/howto.rst <tw_process_howto>`
文件是一個é‡è¦çš„起點;
:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>`
-和 :ref:`Documentation/translations/zh_TW/process/submitting-drivers.rst <tw_submittingdrivers>`
也是所有內核開發人員都應該閱讀的內容。許多內部內核API都是使用kerneldoc機制
記錄的;「make htmldocsã€æˆ–「make pdfdocsã€å¯ç”¨æ–¼ä»¥HTML或PDFæ ¼å¼ç”Ÿæˆé€™äº›æ–‡æª”
(儘管æŸäº›ç™¼è¡Œç‰ˆæ供的tex版本會é‡åˆ°å…§éƒ¨é™åˆ¶ï¼Œç„¡æ³•æ­£ç¢ºè™•ç†æ–‡æª”)。
diff --git a/Documentation/translations/zh_TW/process/howto.rst b/Documentation/translations/zh_TW/process/howto.rst
index 2043691b92e3..68ae4411285b 100644
--- a/Documentation/translations/zh_TW/process/howto.rst
+++ b/Documentation/translations/zh_TW/process/howto.rst
@@ -99,7 +99,6 @@ Linux內核代碼中包å«æœ‰å¤§é‡çš„文檔。這些文檔å°æ–¼å­¸ç¿’如何與
的代碼。
:ref:`Documentation/translations/zh_TW/process/submitting-patches.rst <tw_submittingpatches>`
- :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
這兩份文檔明確æ述如何創建和發é€è£œä¸ï¼Œå…¶ä¸­åŒ…括(但ä¸åƒ…é™æ–¼):
- 郵件內容
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index ec7ad14bfd13..c5c59b4fd595 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -43,7 +43,6 @@
.. toctree::
:maxdepth: 1
- submitting-drivers
submit-checklist
stable-api-nonsense
stable-kernel-rules
diff --git a/Documentation/translations/zh_TW/process/submitting-drivers.rst b/Documentation/translations/zh_TW/process/submitting-drivers.rst
deleted file mode 100644
index 2fdd742318ba..000000000000
--- a/Documentation/translations/zh_TW/process/submitting-drivers.rst
+++ /dev/null
@@ -1,164 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-.. _tw_submittingdrivers:
-
-.. include:: ../disclaimer-zh_TW.rst
-
-:Original: :ref:`Documentation/process/submitting-drivers.rst
- <submittingdrivers>`
-
-如果想評論或更新本文的內容,請直接è¯ç¹«åŽŸæ–‡æª”的維護者。如果你使用英文
-交æµæœ‰å›°é›£çš„話,也å¯ä»¥å‘中文版維護者求助。如果本翻譯更新ä¸åŠæ™‚或者翻
-譯存在å•é¡Œï¼Œè«‹è¯ç¹«ä¸­æ–‡ç‰ˆç¶­è­·è€…::
-
- 中文版維護者: æŽé™½ Li Yang <leoyang.li@nxp.com>
- 中文版翻譯者: æŽé™½ Li Yang <leoyang.li@nxp.com>
- 中文版校譯者: é™³ç¦ Maggie Chen <chenqi@beyondsoft.com>
- çŽ‹è° Wang Cong <xiyou.wangcong@gmail.com>
- å¼µå· Zhang Wei <wezhang@outlook.com>
- 胡皓文 Hu Haowen <src.res@email.cn>
-
-å¦‚ä½•å‘ Linux 內核æ交驅動程åº
-=============================
-
-這篇文檔將會解釋如何å‘ä¸åŒçš„內核æºç¢¼æ¨¹æ交設備驅動程åºã€‚請注æ„,如果你感
-興趣的是顯å¡é©…動程åºï¼Œä½ ä¹Ÿè¨±æ‡‰è©²è¨ªå• XFree86 é …ç›®(https://www.xfree86.org/)
-å’Œï¼æˆ– X.org é …ç›® (https://x.org)。
-
-å¦è«‹åƒé–± Documentation/translations/zh_TW/process/submitting-patches.rst 文檔。
-
-
-分é…設備號
-----------
-
-塊設備和字符設備的主設備號與從設備號是由 Linux 命å編號分é…æ¬Šå¨ LANANA(
-ç¾åœ¨æ˜¯ Torben Mathiasen)負責分é…。申請的網å€æ˜¯ https://www.lanana.org/。
-å³ä½¿ä¸æº–å‚™æ交到主æµå…§æ ¸çš„設備驅動也需è¦åœ¨é€™è£¡åˆ†é…設備號。有關詳細信æ¯ï¼Œ
-è«‹åƒé–± Documentation/admin-guide/devices.rst。
-
-如果你使用的ä¸æ˜¯å·²ç¶“分é…的設備號,那麼當你æ交設備驅動的時候,它將會被強
-制分é…一個新的設備號,å³ä¾¿é€™å€‹è¨­å‚™è™Ÿå’Œä½ ä¹‹å‰ç™¼çµ¦å®¢æˆ¶çš„截然ä¸åŒã€‚
-
-設備驅動的æ交å°è±¡
-------------------
-
-Linux 2.0:
- 此內核æºç¢¼æ¨¹ä¸æŽ¥å—新的驅動程åºã€‚
-
-Linux 2.2:
- 此內核æºç¢¼æ¨¹ä¸æŽ¥å—新的驅動程åºã€‚
-
-Linux 2.4:
- 如果所屬的代碼領域在內核的 MAINTAINERS 文件中列有一個總維護者,
- 那麼請將驅動程åºæ交給他。如果此維護者沒有回應或者你找ä¸åˆ°æ°ç•¶çš„
- 維護者,那麼請è¯ç¹« Willy Tarreau <w@1wt.eu>。
-
-Linux 2.6:
- 除了éµå¾ªå’Œ 2.4 版內核åŒæ¨£çš„è¦å‰‡å¤–,你還需è¦åœ¨ linux-kernel 郵件
- 列表上跟蹤最新的 API è®ŠåŒ–ã€‚å‘ Linux 2.6 內核æ交驅動的頂級è¯ç¹«äºº
- 是 Andrew Morton <akpm@linux-foundation.org>。
-
-決定設備驅動能å¦è¢«æŽ¥å—çš„æ¢ä»¶
-----------------------------
-
-許å¯ï¼š 代碼必須使用 GNU 通用公開許å¯è­‰ (GPL) æ交給 Linux,但是
- 我們並ä¸è¦æ±‚ GPL 是唯一的許å¯ã€‚你或許會希望åŒæ™‚使用多種
- 許å¯è­‰ç™¼å¸ƒï¼Œå¦‚果希望驅動程åºå¯ä»¥è¢«å…¶ä»–é–‹æºç¤¾å€ï¼ˆæ¯”如BSD)
- 使用。請åƒè€ƒ include/linux/module.h 文件中所列出的å¯è¢«
- 接å—共存的許å¯ã€‚
-
-版權: 版權所有者必須åŒæ„使用 GPL 許å¯ã€‚最好æ交者和版權所有者
- 是相åŒå€‹äººæˆ–實體。å¦å‰‡ï¼Œå¿…需列出授權使用 GPL 的版權所有
- 人或實體,以備驗證之需。
-
-接å£ï¼š 如果你的驅動程åºä½¿ç”¨ç¾æˆçš„接å£ä¸¦ä¸”和其他åŒé¡žçš„驅動程åºè¡Œ
- 爲相似,而ä¸æ˜¯åŽ»ç™¼æ˜Žç„¡è¬‚的新接å£ï¼Œé‚£éº¼å®ƒå°‡æœƒæ›´å®¹æ˜“被接å—。
- 如果你需è¦ä¸€å€‹ Linux å’Œ NT 的通用驅動接å£ï¼Œé‚£éº¼è«‹åœ¨ç”¨
- 戶空間實ç¾å®ƒã€‚
-
-代碼: 請使用 Documentation/process/coding-style.rst 中所æè¿°çš„ Linux 代碼風
- 格。如果你的æŸäº›ä»£ç¢¼æ®µï¼ˆä¾‹å¦‚那些與 Windows 驅動程åºåŒ…å…±
- 享的代碼段)需è¦ä½¿ç”¨å…¶ä»–æ ¼å¼ï¼Œè€Œä½ å»åªå¸Œæœ›ç¶­è­·ä¸€ä»½ä»£ç¢¼ï¼Œ
- 那麼請將它們很好地å€åˆ†å‡ºä¾†ï¼Œä¸¦ä¸”註明原因。
-
-å¯ç§»æ¤æ€§ï¼š 請注æ„,指é‡ä¸¦ä¸æ°¸é æ˜¯ 32 ä½çš„,ä¸æ˜¯æ‰€æœ‰çš„計算機都使用å°
- å°¾æ¨¡å¼ (little endian) 存儲數據,ä¸æ˜¯æ‰€æœ‰çš„人都æ“有浮點
- 單元,ä¸è¦éš¨ä¾¿åœ¨ä½ çš„驅動程åºé‡ŒåµŒå…¥ x86 彙編指令。åªèƒ½åœ¨
- x86 上é‹è¡Œçš„驅動程åºä¸€èˆ¬æ˜¯ä¸å—歡迎的。雖然你å¯èƒ½åªæœ‰ x86
- 硬體,很難測試驅動程åºåœ¨å…¶ä»–å¹³å°ä¸Šæ˜¯å¦å¯ç”¨ï¼Œä½†æ˜¯ç¢ºä¿ä»£ç¢¼
- å¯ä»¥è¢«è¼•é¬†åœ°ç§»æ¤å»æ˜¯å¾ˆç°¡å–®çš„。
-
-清晰度: åšåˆ°æ‰€æœ‰äººéƒ½èƒ½ä¿®è£œé€™å€‹é©…動程åºå°‡æœƒå¾ˆæœ‰å¥½è™•ï¼Œå› çˆ²é€™æ¨£ä½ å°‡
- 會直接收到修復的補ä¸è€Œä¸æ˜¯ bug 報告。如果你æ交一個試圖
- éš±è—硬體工作機ç†çš„驅動程åºï¼Œé‚£éº¼å®ƒå°‡æœƒè¢«æ‰”進廢紙ç°ã€‚
-
-é›»æºç®¡ç†ï¼š 因爲 Linux 正在被很多行動è£ç½®å’Œæ¡Œé¢ç³»çµ±ä½¿ç”¨ï¼Œæ‰€ä»¥ä½ çš„é©…
- 動程åºä¹Ÿå¾ˆæœ‰å¯èƒ½è¢«ä½¿ç”¨åœ¨é€™äº›è¨­å‚™ä¸Šã€‚它應該支æŒæœ€åŸºæœ¬çš„é›»
- æºç®¡ç†ï¼Œå³åœ¨éœ€è¦çš„情æ³ä¸‹å¯¦ç¾ç³»çµ±ç´šä¼‘眠和喚醒è¦ç”¨åˆ°çš„
- .suspend å’Œ .resume 函數。你應該檢查你的驅動程åºæ˜¯å¦èƒ½æ­£
- 確地處ç†ä¼‘眠與喚醒,如果實在無法確èªï¼Œè«‹è‡³å°‘把 .suspend
- 函數定義æˆè¿”回 -ENOSYS(功能未實ç¾ï¼‰éŒ¯èª¤ã€‚你還應該嘗試確
- ä¿ä½ çš„驅動在什麼都ä¸ä¹¾çš„情æ³ä¸‹å°‡è€—é›»é™åˆ°æœ€ä½Žã€‚è¦ç²å¾—é©…å‹•
- 程åºæ¸¬è©¦çš„指導,請åƒé–±
- Documentation/power/drivers-testing.rst。有關驅動程åºé›»
- æºç®¡ç†å•é¡Œç›¸å°å…¨é¢çš„概述,請åƒé–±
- Documentation/driver-api/pm/devices.rst。
-
-管ç†ï¼š 如果一個驅動程åºçš„作者還在進行有效的維護,那麼通常除了那
- 些明顯正確且ä¸éœ€è¦ä»»ä½•æª¢æŸ¥çš„補ä¸ä»¥å¤–,其他所有的補ä¸éƒ½æœƒ
- 被轉發給作者。如果你希望æˆçˆ²é©…動程åºçš„è¯ç¹«äººå’Œæ›´æ–°è€…,最
- 好在代碼注釋中寫明並且在 MAINTAINERS 文件中加入這個驅動
- 程åºçš„æ¢ç›®ã€‚
-
-ä¸å½±éŸ¿è¨­å‚™é©…動能å¦è¢«æŽ¥å—çš„æ¢ä»¶
-------------------------------
-
-供應商: 由硬體供應商來維護驅動程åºé€šå¸¸æ˜¯ä¸€ä»¶å¥½äº‹ã€‚ä¸éŽï¼Œå¦‚æžœæºç¢¼
- 樹里已經有其他人æ供了å¯ç©©å®šå·¥ä½œçš„驅動程åºï¼Œé‚£éº¼è«‹ä¸è¦æœŸ
- 望「我是供應商ã€æœƒæˆçˆ²å…§æ ¸æ”¹ç”¨ä½ çš„驅動程åºçš„ç†ç”±ã€‚ç†æƒ³çš„情
- æ³æ˜¯ï¼šä¾›æ‡‰å•†èˆ‡ç¾æœ‰é©…動程åºçš„作者åˆä½œï¼Œæ§‹å»ºä¸€å€‹çµ±ä¸€å®Œç¾Žçš„
- 驅動程åºã€‚
-
-作者: 驅動程åºæ˜¯ç”±å¤§çš„ Linux å…¬å¸ç ”發還是由你個人編寫,並ä¸å½±
- 響其是å¦èƒ½è¢«å…§æ ¸æŽ¥å—。沒有人å°å…§æ ¸æºç¢¼æ¨¹äº«æœ‰ç‰¹æ¬Šã€‚åªè¦ä½ 
- 充分了解內核社å€ï¼Œä½ å°±æœƒç™¼ç¾é€™ä¸€é»žã€‚
-
-
-資æºåˆ—表
---------
-
-Linux 內核主æºç¢¼æ¨¹ï¼š
- ftp.??.kernel.org:/pub/linux/kernel/...
- ?? == 你的國家代碼,例如 "cn"ã€"us"ã€"uk"ã€"fr" 等等
-
-Linux 內核郵件列表:
- linux-kernel@vger.kernel.org
- [å¯é€šéŽå‘majordomo@vger.kernel.org發郵件來訂閱]
-
-Linux 設備驅動程åºï¼Œç¬¬ä¸‰ç‰ˆï¼ˆæŽ¢è¨Ž 2.6.10 版內核):
- https://lwn.net/Kernel/LDD3/ (å…費版)
-
-LWN.net:
- æ¯å‘¨å…§æ ¸é–‹ç™¼æ´»å‹•æ‘˜è¦ - https://lwn.net/
-
- 2.6 版中 API 的變更:
-
- https://lwn.net/Articles/2.6-kernel-api/
-
- 將舊版內核的驅動程åºç§»æ¤åˆ° 2.6 版:
-
- https://lwn.net/Articles/driver-porting/
-
-內核新手(KernelNewbies):
- 爲新的內核開發者æ供文檔和幫助
- https://kernelnewbies.org/
-
-Linux USB項目:
- http://www.linux-usb.org/
-
-寫內核驅動的「ä¸è¦ã€ï¼ˆArjan van de Ven著):
- http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf
-
-內核清潔工 (Kernel Janitor):
- https://kernelnewbies.org/KernelJanitors
-
diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst
index c4fd48f5bd8b..3f77ef5d48a0 100644
--- a/Documentation/translations/zh_TW/process/submitting-patches.rst
+++ b/Documentation/translations/zh_TW/process/submitting-patches.rst
@@ -26,9 +26,7 @@
以下文檔å«æœ‰å¤§é‡ç°¡æ½”的建議, 具體請見:
:ref:`Documentation/process <development_process_main>`
åŒæ¨£ï¼Œ:ref:`Documentation/translations/zh_TW/process/submit-checklist.rst <tw_submitchecklist>`
-給出在æ交代碼å‰éœ€è¦æª¢æŸ¥çš„項目的列表。如果你在æ交一個驅動程åºï¼Œé‚£éº¼
-åŒæ™‚閱讀一下:
-:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
+給出在æ交代碼å‰éœ€è¦æª¢æŸ¥çš„項目的列表。
其中許多步驟æ述了Git版本控制系統的默èªè¡Œçˆ²ï¼›å¦‚果您使用Git來準備補ä¸ï¼Œ
您將發ç¾å®ƒçˆ²æ‚¨å®Œæˆçš„大部分機械工作,儘管您ä»ç„¶éœ€è¦æº–備和記錄一組åˆç†çš„
diff --git a/Documentation/virt/hyperv/clocks.rst b/Documentation/virt/hyperv/clocks.rst
new file mode 100644
index 000000000000..2da2879fad52
--- /dev/null
+++ b/Documentation/virt/hyperv/clocks.rst
@@ -0,0 +1,73 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Clocks and Timers
+=================
+
+arm64
+-----
+On arm64, Hyper-V virtualizes the ARMv8 architectural system counter
+and timer. Guest VMs use this virtualized hardware as the Linux
+clocksource and clockevents via the standard arm_arch_timer.c
+driver, just as they would on bare metal. Linux vDSO support for the
+architectural system counter is functional in guest VMs on Hyper-V.
+While Hyper-V also provides a synthetic system clock and four synthetic
+per-CPU timers as described in the TLFS, they are not used by the
+Linux kernel in a Hyper-V guest on arm64. However, older versions
+of Hyper-V for arm64 only partially virtualize the ARMv8
+architectural timer, such that the timer does not generate
+interrupts in the VM. Because of this limitation, running current
+Linux kernel versions on these older Hyper-V versions requires an
+out-of-tree patch to use the Hyper-V synthetic clocks/timers instead.
+
+x86/x64
+-------
+On x86/x64, Hyper-V provides guest VMs with a synthetic system clock
+and four synthetic per-CPU timers as described in the TLFS. Hyper-V
+also provides access to the virtualized TSC via the RDTSC and
+related instructions. These TSC instructions do not trap to
+the hypervisor and so provide excellent performance in a VM.
+Hyper-V performs TSC calibration, and provides the TSC frequency
+to the guest VM via a synthetic MSR. Hyper-V initialization code
+in Linux reads this MSR to get the frequency, so it skips TSC
+calibration and sets tsc_reliable. Hyper-V provides virtualized
+versions of the PIT (in Hyper-V Generation 1 VMs only), local
+APIC timer, and RTC. Hyper-V does not provide a virtualized HPET in
+guest VMs.
+
+The Hyper-V synthetic system clock can be read via a synthetic MSR,
+but this access traps to the hypervisor. As a faster alternative,
+the guest can configure a memory page to be shared between the guest
+and the hypervisor. Hyper-V populates this memory page with a
+64-bit scale value and offset value. To read the synthetic clock
+value, the guest reads the TSC and then applies the scale and offset
+as described in the Hyper-V TLFS. The resulting value advances
+at a constant 10 MHz frequency. In the case of a live migration
+to a host with a different TSC frequency, Hyper-V adjusts the
+scale and offset values in the shared page so that the 10 MHz
+frequency is maintained.
+
+Starting with Windows Server 2022 Hyper-V, Hyper-V uses hardware
+support for TSC frequency scaling to enable live migration of VMs
+across Hyper-V hosts where the TSC frequency may be different.
+When a Linux guest detects that this Hyper-V functionality is
+available, it prefers to use Linux's standard TSC-based clocksource.
+Otherwise, it uses the clocksource for the Hyper-V synthetic system
+clock implemented via the shared page (identified as
+"hyperv_clocksource_tsc_page").
+
+The Hyper-V synthetic system clock is available to user space via
+vDSO, and gettimeofday() and related system calls can execute
+entirely in user space. The vDSO is implemented by mapping the
+shared page with scale and offset values into user space. User
+space code performs the same algorithm of reading the TSC and
+appying the scale and offset to get the constant 10 MHz clock.
+
+Linux clockevents are based on Hyper-V synthetic timer 0. While
+Hyper-V offers 4 synthetic timers for each CPU, Linux only uses
+timer 0. Interrupts from stimer0 are recorded on the "HVS" line in
+/proc/interrupts. Clockevents based on the virtualized PIT and
+local APIC timer also work, but the Hyper-V synthetic timer is
+preferred.
+
+The driver for the Hyper-V synthetic system clock and timers is
+drivers/clocksource/hyperv_timer.c.
diff --git a/Documentation/virt/hyperv/index.rst b/Documentation/virt/hyperv/index.rst
new file mode 100644
index 000000000000..4a7a1b738bbe
--- /dev/null
+++ b/Documentation/virt/hyperv/index.rst
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+Hyper-V Enlightenments
+======================
+
+.. toctree::
+ :maxdepth: 1
+
+ overview
+ vmbus
+ clocks
diff --git a/Documentation/virt/hyperv/overview.rst b/Documentation/virt/hyperv/overview.rst
new file mode 100644
index 000000000000..cd493332c88a
--- /dev/null
+++ b/Documentation/virt/hyperv/overview.rst
@@ -0,0 +1,207 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+Overview
+========
+The Linux kernel contains a variety of code for running as a fully
+enlightened guest on Microsoft's Hyper-V hypervisor. Hyper-V
+consists primarily of a bare-metal hypervisor plus a virtual machine
+management service running in the parent partition (roughly
+equivalent to KVM and QEMU, for example). Guest VMs run in child
+partitions. In this documentation, references to Hyper-V usually
+encompass both the hypervisor and the VMM service without making a
+distinction about which functionality is provided by which
+component.
+
+Hyper-V runs on x86/x64 and arm64 architectures, and Linux guests
+are supported on both. The functionality and behavior of Hyper-V is
+generally the same on both architectures unless noted otherwise.
+
+Linux Guest Communication with Hyper-V
+--------------------------------------
+Linux guests communicate with Hyper-V in four different ways:
+
+* Implicit traps: As defined by the x86/x64 or arm64 architecture,
+ some guest actions trap to Hyper-V. Hyper-V emulates the action and
+ returns control to the guest. This behavior is generally invisible
+ to the Linux kernel.
+
+* Explicit hypercalls: Linux makes an explicit function call to
+ Hyper-V, passing parameters. Hyper-V performs the requested action
+ and returns control to the caller. Parameters are passed in
+ processor registers or in memory shared between the Linux guest and
+ Hyper-V. On x86/x64, hypercalls use a Hyper-V specific calling
+ sequence. On arm64, hypercalls use the ARM standard SMCCC calling
+ sequence.
+
+* Synthetic register access: Hyper-V implements a variety of
+ synthetic registers. On x86/x64 these registers appear as MSRs in
+ the guest, and the Linux kernel can read or write these MSRs using
+ the normal mechanisms defined by the x86/x64 architecture. On
+ arm64, these synthetic registers must be accessed using explicit
+ hypercalls.
+
+* VMbus: VMbus is a higher-level software construct that is built on
+ the other 3 mechanisms. It is a message passing interface between
+ the Hyper-V host and the Linux guest. It uses memory that is shared
+ between Hyper-V and the guest, along with various signaling
+ mechanisms.
+
+The first three communication mechanisms are documented in the
+`Hyper-V Top Level Functional Spec (TLFS)`_. The TLFS describes
+general Hyper-V functionality and provides details on the hypercalls
+and synthetic registers. The TLFS is currently written for the
+x86/x64 architecture only.
+
+.. _Hyper-V Top Level Functional Spec (TLFS): https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/tlfs/tlfs
+
+VMbus is not documented. This documentation provides a high-level
+overview of VMbus and how it works, but the details can be discerned
+only from the code.
+
+Sharing Memory
+--------------
+Many aspects are communication between Hyper-V and Linux are based
+on sharing memory. Such sharing is generally accomplished as
+follows:
+
+* Linux allocates memory from its physical address space using
+ standard Linux mechanisms.
+
+* Linux tells Hyper-V the guest physical address (GPA) of the
+ allocated memory. Many shared areas are kept to 1 page so that a
+ single GPA is sufficient. Larger shared areas require a list of
+ GPAs, which usually do not need to be contiguous in the guest
+ physical address space. How Hyper-V is told about the GPA or list
+ of GPAs varies. In some cases, a single GPA is written to a
+ synthetic register. In other cases, a GPA or list of GPAs is sent
+ in a VMbus message.
+
+* Hyper-V translates the GPAs into "real" physical memory addresses,
+ and creates a virtual mapping that it can use to access the memory.
+
+* Linux can later revoke sharing it has previously established by
+ telling Hyper-V to set the shared GPA to zero.
+
+Hyper-V operates with a page size of 4 Kbytes. GPAs communicated to
+Hyper-V may be in the form of page numbers, and always describe a
+range of 4 Kbytes. Since the Linux guest page size on x86/x64 is
+also 4 Kbytes, the mapping from guest page to Hyper-V page is 1-to-1.
+On arm64, Hyper-V supports guests with 4/16/64 Kbyte pages as
+defined by the arm64 architecture. If Linux is using 16 or 64
+Kbyte pages, Linux code must be careful to communicate with Hyper-V
+only in terms of 4 Kbyte pages. HV_HYP_PAGE_SIZE and related macros
+are used in code that communicates with Hyper-V so that it works
+correctly in all configurations.
+
+As described in the TLFS, a few memory pages shared between Hyper-V
+and the Linux guest are "overlay" pages. With overlay pages, Linux
+uses the usual approach of allocating guest memory and telling
+Hyper-V the GPA of the allocated memory. But Hyper-V then replaces
+that physical memory page with a page it has allocated, and the
+original physical memory page is no longer accessible in the guest
+VM. Linux may access the memory normally as if it were the memory
+that it originally allocated. The "overlay" behavior is visible
+only because the contents of the page (as seen by Linux) change at
+the time that Linux originally establishes the sharing and the
+overlay page is inserted. Similarly, the contents change if Linux
+revokes the sharing, in which case Hyper-V removes the overlay page,
+and the guest page originally allocated by Linux becomes visible
+again.
+
+Before Linux does a kexec to a kdump kernel or any other kernel,
+memory shared with Hyper-V should be revoked. Hyper-V could modify
+a shared page or remove an overlay page after the new kernel is
+using the page for a different purpose, corrupting the new kernel.
+Hyper-V does not provide a single "set everything" operation to
+guest VMs, so Linux code must individually revoke all sharing before
+doing kexec. See hv_kexec_handler() and hv_crash_handler(). But
+the crash/panic path still has holes in cleanup because some shared
+pages are set using per-CPU synthetic registers and there's no
+mechanism to revoke the shared pages for CPUs other than the CPU
+running the panic path.
+
+CPU Management
+--------------
+Hyper-V does not have a ability to hot-add or hot-remove a CPU
+from a running VM. However, Windows Server 2019 Hyper-V and
+earlier versions may provide guests with ACPI tables that indicate
+more CPUs than are actually present in the VM. As is normal, Linux
+treats these additional CPUs as potential hot-add CPUs, and reports
+them as such even though Hyper-V will never actually hot-add them.
+Starting in Windows Server 2022 Hyper-V, the ACPI tables reflect
+only the CPUs actually present in the VM, so Linux does not report
+any hot-add CPUs.
+
+A Linux guest CPU may be taken offline using the normal Linux
+mechanisms, provided no VMbus channel interrupts are assigned to
+the CPU. See the section on VMbus Interrupts for more details
+on how VMbus channel interrupts can be re-assigned to permit
+taking a CPU offline.
+
+32-bit and 64-bit
+-----------------
+On x86/x64, Hyper-V supports 32-bit and 64-bit guests, and Linux
+will build and run in either version. While the 32-bit version is
+expected to work, it is used rarely and may suffer from undetected
+regressions.
+
+On arm64, Hyper-V supports only 64-bit guests.
+
+Endian-ness
+-----------
+All communication between Hyper-V and guest VMs uses Little-Endian
+format on both x86/x64 and arm64. Big-endian format on arm64 is not
+supported by Hyper-V, and Linux code does not use endian-ness macros
+when accessing data shared with Hyper-V.
+
+Versioning
+----------
+Current Linux kernels operate correctly with older versions of
+Hyper-V back to Windows Server 2012 Hyper-V. Support for running
+on the original Hyper-V release in Windows Server 2008/2008 R2
+has been removed.
+
+A Linux guest on Hyper-V outputs in dmesg the version of Hyper-V
+it is running on. This version is in the form of a Windows build
+number and is for display purposes only. Linux code does not
+test this version number at runtime to determine available features
+and functionality. Hyper-V indicates feature/function availability
+via flags in synthetic MSRs that Hyper-V provides to the guest,
+and the guest code tests these flags.
+
+VMbus has its own protocol version that is negotiated during the
+initial VMbus connection from the guest to Hyper-V. This version
+number is also output to dmesg during boot. This version number
+is checked in a few places in the code to determine if specific
+functionality is present.
+
+Furthermore, each synthetic device on VMbus also has a protocol
+version that is separate from the VMbus protocol version. Device
+drivers for these synthetic devices typically negotiate the device
+protocol version, and may test that protocol version to determine
+if specific device functionality is present.
+
+Code Packaging
+--------------
+Hyper-V related code appears in the Linux kernel code tree in three
+main areas:
+
+1. drivers/hv
+
+2. arch/x86/hyperv and arch/arm64/hyperv
+
+3. individual device driver areas such as drivers/scsi, drivers/net,
+ drivers/clocksource, etc.
+
+A few miscellaneous files appear elsewhere. See the full list under
+"Hyper-V/Azure CORE AND DRIVERS" and "DRM DRIVER FOR HYPERV
+SYNTHETIC VIDEO DEVICE" in the MAINTAINERS file.
+
+The code in #1 and #2 is built only when CONFIG_HYPERV is set.
+Similarly, the code for most Hyper-V related drivers is built only
+when CONFIG_HYPERV is set.
+
+Most Hyper-V related code in #1 and #3 can be built as a module.
+The architecture specific code in #2 must be built-in. Also,
+drivers/hv/hv_common.c is low-level code that is common across
+architectures and must be built-in.
diff --git a/Documentation/virt/hyperv/vmbus.rst b/Documentation/virt/hyperv/vmbus.rst
new file mode 100644
index 000000000000..d2012d9022c5
--- /dev/null
+++ b/Documentation/virt/hyperv/vmbus.rst
@@ -0,0 +1,303 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+VMbus
+=====
+VMbus is a software construct provided by Hyper-V to guest VMs. It
+consists of a control path and common facilities used by synthetic
+devices that Hyper-V presents to guest VMs. The control path is
+used to offer synthetic devices to the guest VM and, in some cases,
+to rescind those devices. The common facilities include software
+channels for communicating between the device driver in the guest VM
+and the synthetic device implementation that is part of Hyper-V, and
+signaling primitives to allow Hyper-V and the guest to interrupt
+each other.
+
+VMbus is modeled in Linux as a bus, with the expected /sys/bus/vmbus
+entry in a running Linux guest. The VMbus driver (drivers/hv/vmbus_drv.c)
+establishes the VMbus control path with the Hyper-V host, then
+registers itself as a Linux bus driver. It implements the standard
+bus functions for adding and removing devices to/from the bus.
+
+Most synthetic devices offered by Hyper-V have a corresponding Linux
+device driver. These devices include:
+
+* SCSI controller
+* NIC
+* Graphics frame buffer
+* Keyboard
+* Mouse
+* PCI device pass-thru
+* Heartbeat
+* Time Sync
+* Shutdown
+* Memory balloon
+* Key/Value Pair (KVP) exchange with Hyper-V
+* Hyper-V online backup (a.k.a. VSS)
+
+Guest VMs may have multiple instances of the synthetic SCSI
+controller, synthetic NIC, and PCI pass-thru devices. Other
+synthetic devices are limited to a single instance per VM. Not
+listed above are a small number of synthetic devices offered by
+Hyper-V that are used only by Windows guests and for which Linux
+does not have a driver.
+
+Hyper-V uses the terms "VSP" and "VSC" in describing synthetic
+devices. "VSP" refers to the Hyper-V code that implements a
+particular synthetic device, while "VSC" refers to the driver for
+the device in the guest VM. For example, the Linux driver for the
+synthetic NIC is referred to as "netvsc" and the Linux driver for
+the synthetic SCSI controller is "storvsc". These drivers contain
+functions with names like "storvsc_connect_to_vsp".
+
+VMbus channels
+--------------
+An instance of a synthetic device uses VMbus channels to communicate
+between the VSP and the VSC. Channels are bi-directional and used
+for passing messages. Most synthetic devices use a single channel,
+but the synthetic SCSI controller and synthetic NIC may use multiple
+channels to achieve higher performance and greater parallelism.
+
+Each channel consists of two ring buffers. These are classic ring
+buffers from a university data structures textbook. If the read
+and writes pointers are equal, the ring buffer is considered to be
+empty, so a full ring buffer always has at least one byte unused.
+The "in" ring buffer is for messages from the Hyper-V host to the
+guest, and the "out" ring buffer is for messages from the guest to
+the Hyper-V host. In Linux, the "in" and "out" designations are as
+viewed by the guest side. The ring buffers are memory that is
+shared between the guest and the host, and they follow the standard
+paradigm where the memory is allocated by the guest, with the list
+of GPAs that make up the ring buffer communicated to the host. Each
+ring buffer consists of a header page (4 Kbytes) with the read and
+write indices and some control flags, followed by the memory for the
+actual ring. The size of the ring is determined by the VSC in the
+guest and is specific to each synthetic device. The list of GPAs
+making up the ring is communicated to the Hyper-V host over the
+VMbus control path as a GPA Descriptor List (GPADL). See function
+vmbus_establish_gpadl().
+
+Each ring buffer is mapped into contiguous Linux kernel virtual
+space in three parts: 1) the 4 Kbyte header page, 2) the memory
+that makes up the ring itself, and 3) a second mapping of the memory
+that makes up the ring itself. Because (2) and (3) are contiguous
+in kernel virtual space, the code that copies data to and from the
+ring buffer need not be concerned with ring buffer wrap-around.
+Once a copy operation has completed, the read or write index may
+need to be reset to point back into the first mapping, but the
+actual data copy does not need to be broken into two parts. This
+approach also allows complex data structures to be easily accessed
+directly in the ring without handling wrap-around.
+
+On arm64 with page sizes > 4 Kbytes, the header page must still be
+passed to Hyper-V as a 4 Kbyte area. But the memory for the actual
+ring must be aligned to PAGE_SIZE and have a size that is a multiple
+of PAGE_SIZE so that the duplicate mapping trick can be done. Hence
+a portion of the header page is unused and not communicated to
+Hyper-V. This case is handled by vmbus_establish_gpadl().
+
+Hyper-V enforces a limit on the aggregate amount of guest memory
+that can be shared with the host via GPADLs. This limit ensures
+that a rogue guest can't force the consumption of excessive host
+resources. For Windows Server 2019 and later, this limit is
+approximately 1280 Mbytes. For versions prior to Windows Server
+2019, the limit is approximately 384 Mbytes.
+
+VMbus messages
+--------------
+All VMbus messages have a standard header that includes the message
+length, the offset of the message payload, some flags, and a
+transactionID. The portion of the message after the header is
+unique to each VSP/VSC pair.
+
+Messages follow one of two patterns:
+
+* Unidirectional: Either side sends a message and does not
+ expect a response message
+* Request/response: One side (usually the guest) sends a message
+ and expects a response
+
+The transactionID (a.k.a. "requestID") is for matching requests &
+responses. Some synthetic devices allow multiple requests to be in-
+flight simultaneously, so the guest specifies a transactionID when
+sending a request. Hyper-V sends back the same transactionID in the
+matching response.
+
+Messages passed between the VSP and VSC are control messages. For
+example, a message sent from the storvsc driver might be "execute
+this SCSI command". If a message also implies some data transfer
+between the guest and the Hyper-V host, the actual data to be
+transferred may be embedded with the control message, or it may be
+specified as a separate data buffer that the Hyper-V host will
+access as a DMA operation. The former case is used when the size of
+the data is small and the cost of copying the data to and from the
+ring buffer is minimal. For example, time sync messages from the
+Hyper-V host to the guest contain the actual time value. When the
+data is larger, a separate data buffer is used. In this case, the
+control message contains a list of GPAs that describe the data
+buffer. For example, the storvsc driver uses this approach to
+specify the data buffers to/from which disk I/O is done.
+
+Three functions exist to send VMbus messages:
+
+1. vmbus_sendpacket(): Control-only messages and messages with
+ embedded data -- no GPAs
+2. vmbus_sendpacket_pagebuffer(): Message with list of GPAs
+ identifying data to transfer. An offset and length is
+ associated with each GPA so that multiple discontinuous areas
+ of guest memory can be targeted.
+3. vmbus_sendpacket_mpb_desc(): Message with list of GPAs
+ identifying data to transfer. A single offset and length is
+ associated with a list of GPAs. The GPAs must describe a
+ single logical area of guest memory to be targeted.
+
+Historically, Linux guests have trusted Hyper-V to send well-formed
+and valid messages, and Linux drivers for synthetic devices did not
+fully validate messages. With the introduction of processor
+technologies that fully encrypt guest memory and that allow the
+guest to not trust the hypervisor (AMD SNP-SEV, Intel TDX), trusting
+the Hyper-V host is no longer a valid assumption. The drivers for
+VMbus synthetic devices are being updated to fully validate any
+values read from memory that is shared with Hyper-V, which includes
+messages from VMbus devices. To facilitate such validation,
+messages read by the guest from the "in" ring buffer are copied to a
+temporary buffer that is not shared with Hyper-V. Validation is
+performed in this temporary buffer without the risk of Hyper-V
+maliciously modifying the message after it is validated but before
+it is used.
+
+VMbus interrupts
+----------------
+VMbus provides a mechanism for the guest to interrupt the host when
+the guest has queued new messages in a ring buffer. The host
+expects that the guest will send an interrupt only when an "out"
+ring buffer transitions from empty to non-empty. If the guest sends
+interrupts at other times, the host deems such interrupts to be
+unnecessary. If a guest sends an excessive number of unnecessary
+interrupts, the host may throttle that guest by suspending its
+execution for a few seconds to prevent a denial-of-service attack.
+
+Similarly, the host will interrupt the guest when it sends a new
+message on the VMbus control path, or when a VMbus channel "in" ring
+buffer transitions from empty to non-empty. Each CPU in the guest
+may receive VMbus interrupts, so they are best modeled as per-CPU
+interrupts in Linux. This model works well on arm64 where a single
+per-CPU IRQ is allocated for VMbus. Since x86/x64 lacks support for
+per-CPU IRQs, an x86 interrupt vector is statically allocated (see
+HYPERVISOR_CALLBACK_VECTOR) across all CPUs and explicitly coded to
+call the VMbus interrupt service routine. These interrupts are
+visible in /proc/interrupts on the "HYP" line.
+
+The guest CPU that a VMbus channel will interrupt is selected by the
+guest when the channel is created, and the host is informed of that
+selection. VMbus devices are broadly grouped into two categories:
+
+1. "Slow" devices that need only one VMbus channel. The devices
+ (such as keyboard, mouse, heartbeat, and timesync) generate
+ relatively few interrupts. Their VMbus channels are all
+ assigned to interrupt the VMBUS_CONNECT_CPU, which is always
+ CPU 0.
+
+2. "High speed" devices that may use multiple VMbus channels for
+ higher parallelism and performance. These devices include the
+ synthetic SCSI controller and synthetic NIC. Their VMbus
+ channels interrupts are assigned to CPUs that are spread out
+ among the available CPUs in the VM so that interrupts on
+ multiple channels can be processed in parallel.
+
+The assignment of VMbus channel interrupts to CPUs is done in the
+function init_vp_index(). This assignment is done outside of the
+normal Linux interrupt affinity mechanism, so the interrupts are
+neither "unmanaged" nor "managed" interrupts.
+
+The CPU that a VMbus channel will interrupt can be seen in
+/sys/bus/vmbus/devices/<deviceGUID>/ channels/<channelRelID>/cpu.
+When running on later versions of Hyper-V, the CPU can be changed
+by writing a new value to this sysfs entry. Because the interrupt
+assignment is done outside of the normal Linux affinity mechanism,
+there are no entries in /proc/irq corresponding to individual
+VMbus channel interrupts.
+
+An online CPU in a Linux guest may not be taken offline if it has
+VMbus channel interrupts assigned to it. Any such channel
+interrupts must first be manually reassigned to another CPU as
+described above. When no channel interrupts are assigned to the
+CPU, it can be taken offline.
+
+When a guest CPU receives a VMbus interrupt from the host, the
+function vmbus_isr() handles the interrupt. It first checks for
+channel interrupts by calling vmbus_chan_sched(), which looks at a
+bitmap setup by the host to determine which channels have pending
+interrupts on this CPU. If multiple channels have pending
+interrupts for this CPU, they are processed sequentially. When all
+channel interrupts have been processed, vmbus_isr() checks for and
+processes any message received on the VMbus control path.
+
+The VMbus channel interrupt handling code is designed to work
+correctly even if an interrupt is received on a CPU other than the
+CPU assigned to the channel. Specifically, the code does not use
+CPU-based exclusion for correctness. In normal operation, Hyper-V
+will interrupt the assigned CPU. But when the CPU assigned to a
+channel is being changed via sysfs, the guest doesn't know exactly
+when Hyper-V will make the transition. The code must work correctly
+even if there is a time lag before Hyper-V starts interrupting the
+new CPU. See comments in target_cpu_store().
+
+VMbus device creation/deletion
+------------------------------
+Hyper-V and the Linux guest have a separate message-passing path
+that is used for synthetic device creation and deletion. This
+path does not use a VMbus channel. See vmbus_post_msg() and
+vmbus_on_msg_dpc().
+
+The first step is for the guest to connect to the generic
+Hyper-V VMbus mechanism. As part of establishing this connection,
+the guest and Hyper-V agree on a VMbus protocol version they will
+use. This negotiation allows newer Linux kernels to run on older
+Hyper-V versions, and vice versa.
+
+The guest then tells Hyper-V to "send offers". Hyper-V sends an
+offer message to the guest for each synthetic device that the VM
+is configured to have. Each VMbus device type has a fixed GUID
+known as the "class ID", and each VMbus device instance is also
+identified by a GUID. The offer message from Hyper-V contains
+both GUIDs to uniquely (within the VM) identify the device.
+There is one offer message for each device instance, so a VM with
+two synthetic NICs will get two offers messages with the NIC
+class ID. The ordering of offer messages can vary from boot-to-boot
+and must not be assumed to be consistent in Linux code. Offer
+messages may also arrive long after Linux has initially booted
+because Hyper-V supports adding devices, such as synthetic NICs,
+to running VMs. A new offer message is processed by
+vmbus_process_offer(), which indirectly invokes vmbus_add_channel_work().
+
+Upon receipt of an offer message, the guest identifies the device
+type based on the class ID, and invokes the correct driver to set up
+the device. Driver/device matching is performed using the standard
+Linux mechanism.
+
+The device driver probe function opens the primary VMbus channel to
+the corresponding VSP. It allocates guest memory for the channel
+ring buffers and shares the ring buffer with the Hyper-V host by
+giving the host a list of GPAs for the ring buffer memory. See
+vmbus_establish_gpadl().
+
+Once the ring buffer is set up, the device driver and VSP exchange
+setup messages via the primary channel. These messages may include
+negotiating the device protocol version to be used between the Linux
+VSC and the VSP on the Hyper-V host. The setup messages may also
+include creating additional VMbus channels, which are somewhat
+mis-named as "sub-channels" since they are functionally
+equivalent to the primary channel once they are created.
+
+Finally, the device driver may create entries in /dev as with
+any device driver.
+
+The Hyper-V host can send a "rescind" message to the guest to
+remove a device that was previously offered. Linux drivers must
+handle such a rescind message at any time. Rescinding a device
+invokes the device driver "remove" function to cleanly shut
+down the device and remove it. Once a synthetic device is
+rescinded, neither Hyper-V nor Linux retains any state about
+its previous existence. Such a device might be re-added later,
+in which case it is treated as an entirely new device. See
+vmbus_onoffer_rescind().
diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst
index 492f0920b988..2f1cffa87b1b 100644
--- a/Documentation/virt/index.rst
+++ b/Documentation/virt/index.rst
@@ -14,6 +14,7 @@ Linux Virtualization Support
ne_overview
acrn/index
coco/sev-guest
+ hyperv/index
.. only:: html and subproject
diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 98a283930307..dca926762f1f 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -4667,7 +4667,7 @@ encrypted VMs.
Currently, this ioctl is used for issuing Secure Encrypted Virtualization
(SEV) commands on AMD Processors. The SEV commands are defined in
-Documentation/virt/kvm/amd-memory-encryption.rst.
+Documentation/virt/kvm/x86/amd-memory-encryption.rst.
4.111 KVM_MEMORY_ENCRYPT_REG_REGION
-----------------------------------
@@ -7679,7 +7679,7 @@ architecture-specific interfaces. This capability and the architecture-
specific interfaces must be consistent, i.e. if one says the feature
is supported, than the other should as well and vice versa. For arm64
see Documentation/virt/kvm/devices/vcpu.rst "KVM_ARM_VCPU_PVTIME_CTRL".
-For x86 see Documentation/virt/kvm/msr.rst "MSR_KVM_STEAL_TIME".
+For x86 see Documentation/virt/kvm/x86/msr.rst "MSR_KVM_STEAL_TIME".
8.25 KVM_CAP_S390_DIAG318
-------------------------
diff --git a/Documentation/virt/kvm/s390/s390-pv-boot.rst b/Documentation/virt/kvm/s390/s390-pv-boot.rst
index 73a6083cb5e7..96c48480a360 100644
--- a/Documentation/virt/kvm/s390/s390-pv-boot.rst
+++ b/Documentation/virt/kvm/s390/s390-pv-boot.rst
@@ -10,7 +10,7 @@ The memory of Protected Virtual Machines (PVMs) is not accessible to
I/O or the hypervisor. In those cases where the hypervisor needs to
access the memory of a PVM, that memory must be made accessible.
Memory made accessible to the hypervisor will be encrypted. See
-Documentation/virt/kvm/s390-pv.rst for details."
+Documentation/virt/kvm/s390/s390-pv.rst for details."
On IPL (boot) a small plaintext bootloader is started, which provides
information about the encrypted components and necessary metadata to
diff --git a/Documentation/virt/kvm/x86/hypercalls.rst b/Documentation/virt/kvm/x86/hypercalls.rst
index e56fa8b9cfca..10db7924720f 100644
--- a/Documentation/virt/kvm/x86/hypercalls.rst
+++ b/Documentation/virt/kvm/x86/hypercalls.rst
@@ -22,7 +22,7 @@ S390:
number in R1.
For further information on the S390 diagnose call as supported by KVM,
- refer to Documentation/virt/kvm/s390-diag.rst.
+ refer to Documentation/virt/kvm/s390/s390-diag.rst.
PowerPC:
It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers.
diff --git a/Documentation/virt/uml/user_mode_linux_howto_v2.rst b/Documentation/virt/uml/user_mode_linux_howto_v2.rst
index 863f67b72c05..af2a97429692 100644
--- a/Documentation/virt/uml/user_mode_linux_howto_v2.rst
+++ b/Documentation/virt/uml/user_mode_linux_howto_v2.rst
@@ -322,7 +322,7 @@ Shared Options
* ``v6=[0,1]`` to specify if a v6 connection is desired for all
transports which operate over IP. Additionally, for transports that
have some differences in the way they operate over v4 and v6 (for example
- EoL2TPv3), sets the correct mode of operation. In the absense of this
+ EoL2TPv3), sets the correct mode of operation. In the absence of this
option, the socket type is determined based on what do the src and dst
arguments resolve/parse to.
diff --git a/Documentation/vm/overcommit-accounting.rst b/Documentation/vm/overcommit-accounting.rst
index 1addb0c374a4..a4895d6fc1c2 100644
--- a/Documentation/vm/overcommit-accounting.rst
+++ b/Documentation/vm/overcommit-accounting.rst
@@ -1,5 +1,3 @@
-.. _overcommit_accounting:
-
=====================
Overcommit Accounting
=====================
diff --git a/Documentation/x86/orc-unwinder.rst b/Documentation/x86/orc-unwinder.rst
index 9a66a88be765..cdb257015bd9 100644
--- a/Documentation/x86/orc-unwinder.rst
+++ b/Documentation/x86/orc-unwinder.rst
@@ -140,7 +140,7 @@ Unwinder implementation details
Objtool generates the ORC data by integrating with the compile-time
stack metadata validation feature, which is described in detail in
-tools/objtool/Documentation/stack-validation.txt. After analyzing all
+tools/objtool/Documentation/objtool.txt. After analyzing all
the code paths of a .o file, it creates an array of orc_entry structs,
and a parallel array of instruction addresses associated with those
structs, and writes them to the .orc_unwind and .orc_unwind_ip sections
diff --git a/MAINTAINERS b/MAINTAINERS
index dfe5052aac91..bd82078d10bd 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6842,7 +6842,7 @@ L: dri-devel@lists.freedesktop.org
L: linux-tegra@vger.kernel.org
S: Supported
T: git git://anongit.freedesktop.org/tegra/linux.git
-F: Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt
+F: Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml
F: Documentation/devicetree/bindings/gpu/host1x/
F: drivers/gpu/drm/tegra/
F: drivers/gpu/host1x/
@@ -9326,6 +9326,7 @@ S: Supported
T: git git://git.kernel.org/pub/scm/linux/kernel/git/hyperv/linux.git
F: Documentation/ABI/stable/sysfs-bus-vmbus
F: Documentation/ABI/testing/debugfs-hyperv
+F: Documentation/virt/hyperv
F: Documentation/networking/device_drivers/ethernet/microsoft/netvsc.rst
F: arch/arm64/hyperv
F: arch/arm64/include/asm/hyperv-tlfs.h
@@ -19845,7 +19846,7 @@ M: Sowjanya Komatineni <skomatineni@nvidia.com>
L: linux-media@vger.kernel.org
L: linux-tegra@vger.kernel.org
S: Maintained
-F: Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt
+F: Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.yaml
F: drivers/staging/media/tegra-video/
TEGRA XUSB PADCTL DRIVER
@@ -20443,7 +20444,7 @@ F: tools/tracing/rtla/
TRADITIONAL CHINESE DOCUMENTATION
M: Hu Haowen <src.res@email.cn>
-L: linux-doc-tw-discuss@lists.sourceforge.net
+L: linux-doc-tw-discuss@lists.sourceforge.net (moderated for non-subscribers)
S: Maintained
W: https://github.com/srcres258/linux-doc
T: git git://github.com/srcres258/linux-doc.git doc-zh-tw
diff --git a/arch/m68k/q40/README b/arch/m68k/q40/README
index a4991d2d8af6..9760e9081f6f 100644
--- a/arch/m68k/q40/README
+++ b/arch/m68k/q40/README
@@ -30,11 +30,10 @@ drivers used by the Q40, apart from the very obvious (console etc.):
genrtc.c # RTC
char/joystick/* # most of this should work, not
# in default config.in
- block/q40ide.c # startup for ide
- ide* # see Documentation/ide/ide.rst
- floppy.c # normal PC driver, DMA emu in asm/floppy.h
+ block/floppy.c # normal PC driver, DMA emu in asm/floppy.h
# and arch/m68k/kernel/entry.S
# see drivers/block/README.fd
+ ata/pata_falcon.c
net/ne.c
video/q40fb.c
parport/*
diff --git a/include/linux/fscache.h b/include/linux/fscache.h
index b86265664879..720874e6ee94 100644
--- a/include/linux/fscache.h
+++ b/include/linux/fscache.h
@@ -379,7 +379,7 @@ void fscache_update_cookie(struct fscache_cookie *cookie, const void *aux_data,
*
* Request that the size of an object be changed.
*
- * See Documentation/filesystems/caching/netfs-api.txt for a complete
+ * See Documentation/filesystems/caching/netfs-api.rst for a complete
* description.
*/
static inline
diff --git a/include/linux/objtool.h b/include/linux/objtool.h
index 10bc88cc3bf6..62c54ffbeeaa 100644
--- a/include/linux/objtool.h
+++ b/include/linux/objtool.h
@@ -67,7 +67,7 @@ struct unwind_hint {
* It should only be used in special cases where you're 100% sure it won't
* affect the reliability of frame pointers and kernel stack traces.
*
- * For more information, see tools/objtool/Documentation/stack-validation.txt.
+ * For more information, see tools/objtool/Documentation/objtool.txt.
*/
#define STACK_FRAME_NON_STANDARD(func) \
static void __used __section(".discard.func_stack_frame_non_standard") \
diff --git a/include/linux/watch_queue.h b/include/linux/watch_queue.h
index 3b9a40ae8bdb..fc6bba20273b 100644
--- a/include/linux/watch_queue.h
+++ b/include/linux/watch_queue.h
@@ -4,7 +4,7 @@
* Copyright (C) 2020 Red Hat, Inc. All Rights Reserved.
* Written by David Howells (dhowells@redhat.com)
*
- * See Documentation/watch_queue.rst
+ * See Documentation/core-api/watch_queue.rst
*/
#ifndef _LINUX_WATCH_QUEUE_H
diff --git a/init/Kconfig b/init/Kconfig
index 7f75a61eb52e..26a544112732 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -414,7 +414,7 @@ config WATCH_QUEUE
with watches for key/keyring change notifications and device
notifications.
- See Documentation/watch_queue.rst
+ See Documentation/core-api/watch_queue.rst
config CROSS_MEMORY_ATTACH
bool "Enable process_vm_readv/writev syscalls"
diff --git a/kernel/watch_queue.c b/kernel/watch_queue.c
index 59ddb00d6944..a6f9bdd956c3 100644
--- a/kernel/watch_queue.c
+++ b/kernel/watch_queue.c
@@ -4,7 +4,7 @@
* Copyright (C) 2020 Red Hat, Inc. All Rights Reserved.
* Written by David Howells (dhowells@redhat.com)
*
- * See Documentation/watch_queue.rst
+ * See Documentation/core-api/watch_queue.rst
*/
#define pr_fmt(fmt) "watchq: " fmt
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index 2e24db4bff19..79a71eb96111 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -498,7 +498,7 @@ config STACK_VALIDATION
runtime stack traces are more reliable.
For more information, see
- tools/objtool/Documentation/stack-validation.txt.
+ tools/objtool/Documentation/objtool.txt.
config NOINSTR_VALIDATION
bool
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 76cfb96b59b6..5c5397eeb237 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -1,4 +1,4 @@
-#!/usr/bin/perl
+#!/usr/bin/env perl
# SPDX-License-Identifier: GPL-2.0
use strict;
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 7516949bb049..aea04365bc69 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -427,6 +427,13 @@ sub print_lineno {
print ".. LINENO " . $lineno . "\n";
}
}
+
+sub emit_warning {
+ my $location = shift;
+ my $msg = shift;
+ print STDERR "$location: warning: $msg";
+ ++$warnings;
+}
##
# dumps section contents to arrays/hashes intended for that purpose.
#
@@ -451,8 +458,7 @@ sub dump_section {
if (defined($sections{$name}) && ($sections{$name} ne "")) {
# Only warn on user specified duplicate section names.
if ($name ne $section_default) {
- print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
- ++$warnings;
+ emit_warning("${file}:$.", "duplicate section name '$name'\n");
}
$sections{$name} .= $contents;
} else {
@@ -1094,7 +1100,7 @@ sub dump_struct($$) {
if ($members) {
if ($identifier ne $declaration_name) {
- print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n";
+ emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n");
return;
}
@@ -1298,9 +1304,9 @@ sub dump_enum($$) {
if ($members) {
if ($identifier ne $declaration_name) {
if ($identifier eq "") {
- print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
+ emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
} else {
- print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n";
+ emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n");
}
return;
}
@@ -1316,7 +1322,7 @@ sub dump_enum($$) {
if (!$parameterdescs{$arg}) {
$parameterdescs{$arg} = $undescribed;
if (show_warnings("enum", $declaration_name)) {
- print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
+ emit_warning("${file}:$.", "Enum value '$arg' not described in enum '$declaration_name'\n");
}
}
$_members{$arg} = 1;
@@ -1325,7 +1331,7 @@ sub dump_enum($$) {
while (my ($k, $v) = each %parameterdescs) {
if (!exists($_members{$k})) {
if (show_warnings("enum", $declaration_name)) {
- print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
+ emit_warning("${file}:$.", "Excess enum value '$k' description in '$declaration_name'\n");
}
}
}
@@ -1367,7 +1373,7 @@ sub dump_typedef($$) {
$return_type =~ s/^\s+//;
if ($identifier ne $declaration_name) {
- print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+ emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
return;
}
@@ -1398,7 +1404,7 @@ sub dump_typedef($$) {
$declaration_name = $1;
if ($identifier ne $declaration_name) {
- print STDERR "${file}:$.: warning: expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n";
+ emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
return;
}
@@ -1554,9 +1560,7 @@ sub push_parameter($$$$$) {
$parameterdescs{$param} = $undescribed;
if (show_warnings($type, $declaration_name) && $param !~ /\./) {
- print STDERR
- "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
- ++$warnings;
+ emit_warning("${file}:$.", "Function parameter or member '$param' not described in '$declaration_name'\n");
}
}
@@ -1604,11 +1608,10 @@ sub check_sections($$$$$) {
}
if ($err) {
if ($decl_type eq "function") {
- print STDERR "${file}:$.: warning: " .
+ emit_warning("${file}:$.",
"Excess function parameter " .
"'$sects[$sx]' " .
- "description in '$decl_name'\n";
- ++$warnings;
+ "description in '$decl_name'\n");
}
}
}
@@ -1629,10 +1632,9 @@ sub check_return_section {
if (!defined($sections{$section_return}) ||
$sections{$section_return} eq "") {
- print STDERR "${file}:$.: warning: " .
+ emit_warning("${file}:$.",
"No description found for return value of " .
- "'$declaration_name'\n";
- ++$warnings;
+ "'$declaration_name'\n");
}
}
@@ -1714,12 +1716,12 @@ sub dump_function($$) {
create_parameterlist($args, ',', $file, $declaration_name);
} else {
- print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
+ emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
return;
}
if ($identifier ne $declaration_name) {
- print STDERR "${file}:$.: warning: expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n";
+ emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n");
return;
}
@@ -1801,8 +1803,8 @@ sub tracepoint_munge($) {
$tracepointargs = $1;
}
if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
- print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
- "$prototype\n";
+ emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
+ "$prototype\n");
} else {
$prototype = "static inline void trace_$tracepointname($tracepointargs)";
$identifier = "trace_$identifier";
@@ -2027,22 +2029,16 @@ sub process_name($$) {
}
if (!$is_kernel_comment) {
- print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n";
- print STDERR $_;
- ++$warnings;
+ emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
$state = STATE_NORMAL;
}
if (($declaration_purpose eq "") && $verbose) {
- print STDERR "${file}:$.: warning: missing initial short description on line:\n";
- print STDERR $_;
- ++$warnings;
+ emit_warning("${file}:$.", "missing initial short description on line:\n$_");
}
if ($identifier eq "" && $decl_type ne "enum") {
- print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n";
- print STDERR $_;
- ++$warnings;
+ emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
$state = STATE_NORMAL;
}
@@ -2050,9 +2046,7 @@ sub process_name($$) {
print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
}
} else {
- print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
- " - I thought it was a doc line\n";
- ++$warnings;
+ emit_warning("${file}:$.", "Cannot understand $_ on line $. - I thought it was a doc line\n");
$state = STATE_NORMAL;
}
}
@@ -2071,8 +2065,7 @@ sub process_body($$) {
$section =~ s/\.\.\.$//;
if ($verbose) {
- print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n";
- ++$warnings;
+ emit_warning("${file}:$.", "Variable macro arguments should be documented without dots\n");
}
}
@@ -2101,8 +2094,7 @@ sub process_body($$) {
if (($contents ne "") && ($contents ne "\n")) {
if (!$in_doc_sect && $verbose) {
- print STDERR "${file}:$.: warning: contents before sections\n";
- ++$warnings;
+ emit_warning("${file}:$.", "contents before sections\n");
}
dump_section($file, $section, $contents);
$section = $section_default;
@@ -2128,8 +2120,7 @@ sub process_body($$) {
}
# look for doc_com + <text> + doc_end:
if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
- print STDERR "${file}:$.: warning: suspicious ending line: $_";
- ++$warnings;
+ emit_warning("${file}:$.", "suspicious ending line: $_");
}
$prototype = "";
@@ -2173,8 +2164,7 @@ sub process_body($$) {
}
} else {
# i dont know - bad line? ignore.
- print STDERR "${file}:$.: warning: bad line: $_";
- ++$warnings;
+ emit_warning("${file}:$.", "bad line: $_");
}
}
@@ -2268,9 +2258,7 @@ sub process_inline($$) {
}
} elsif ($inline_doc_state == STATE_INLINE_NAME) {
$inline_doc_state = STATE_INLINE_ERROR;
- print STDERR "${file}:$.: warning: ";
- print STDERR "Incorrect use of kernel-doc format: $_";
- ++$warnings;
+ emit_warning("${file}:$.", "Incorrect use of kernel-doc format: $_");
}
}
}
@@ -2319,11 +2307,11 @@ sub process_file($) {
if ($initial_section_counter == $section_counter && $
output_mode ne "none") {
if ($output_selection == OUTPUT_INCLUDE) {
- print STDERR "${file}:1: warning: '$_' not found\n"
+ emit_warning("${file}:1", "'$_' not found\n")
for keys %function_table;
}
else {
- print STDERR "${file}:1: warning: no structured comments found\n";
+ emit_warning("${file}:1", "no structured comments found\n");
}
}
close IN_FILE;
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index f126ecbb0494..ec84fc62774e 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -25,6 +25,7 @@ my $need_sphinx = 0;
my $need_pip = 0;
my $need_virtualenv = 0;
my $rec_sphinx_upgrade = 0;
+my $verbose_warn_install = 1;
my $install = "";
my $virtenv_dir = "";
my $python_cmd = "";
@@ -103,10 +104,12 @@ sub check_missing(%)
next;
}
- if ($is_optional) {
- print "Warning: better to also install \"$prog\".\n";
- } else {
- print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
+ if ($verbose_warn_install) {
+ if ($is_optional) {
+ print "Warning: better to also install \"$prog\".\n";
+ } else {
+ print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
+ }
}
if (defined($map{$prog})) {
$install .= " " . $map{$prog};
@@ -386,7 +389,8 @@ sub give_debian_hints()
check_missing(\%map);
return if (!$need && !$optional);
- printf("You should run:\n\n\tsudo apt-get install $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo apt-get install $install\n");
}
sub give_redhat_hints()
@@ -458,10 +462,12 @@ sub give_redhat_hints()
if (!$old) {
# dnf, for Fedora 18+
- printf("You should run:\n\n\tsudo dnf install -y $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo dnf install -y $install\n");
} else {
# yum, for RHEL (and clones) or Fedora version < 18
- printf("You should run:\n\n\tsudo yum install -y $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo yum install -y $install\n");
}
}
@@ -509,7 +515,8 @@ sub give_opensuse_hints()
check_missing(\%map);
return if (!$need && !$optional);
- printf("You should run:\n\n\tsudo zypper install --no-recommends $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo zypper install --no-recommends $install\n");
}
sub give_mageia_hints()
@@ -553,7 +560,8 @@ sub give_mageia_hints()
check_missing(\%map);
return if (!$need && !$optional);
- printf("You should run:\n\n\tsudo $packager_cmd $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo $packager_cmd $install\n");
}
sub give_arch_linux_hints()
@@ -583,7 +591,8 @@ sub give_arch_linux_hints()
check_missing(\%map);
return if (!$need && !$optional);
- printf("You should run:\n\n\tsudo pacman -S $install\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n\tsudo pacman -S $install\n");
}
sub give_gentoo_hints()
@@ -610,7 +619,8 @@ sub give_gentoo_hints()
return if (!$need && !$optional);
- printf("You should run:\n\n");
+ printf("You should run:\n") if ($verbose_warn_install);
+ printf("\n");
my $imagemagick = "media-gfx/imagemagick svg png";
my $cairo = "media-gfx/graphviz cairo pdf";
@@ -700,7 +710,7 @@ sub check_distros()
sub deactivate_help()
{
- printf "\nIf you want to exit the virtualenv, you can use:\n";
+ printf "\n If you want to exit the virtualenv, you can use:\n";
printf "\tdeactivate\n";
}
@@ -720,6 +730,12 @@ sub get_virtenv()
next if (! -f $sphinx_cmd);
my $ver = get_sphinx_version($sphinx_cmd);
+
+ if (!$ver) {
+ $f =~ s#/bin/activate##;
+ print("Warning: virtual environment $f is not working.\nPython version upgrade? Remove it with:\n\n\trm -rf $f\n\n");
+ }
+
if ($need_sphinx && ($ver ge $min_version)) {
return ($f, $ver);
} elsif ($ver gt $cur_version) {
@@ -741,7 +757,7 @@ sub recommend_sphinx_upgrade()
# Get the highest version from sphinx_*/bin/sphinx-build and the
# corresponding command to activate the venv/virtenv
- $activate_cmd = get_virtenv();
+ ($activate_cmd, $venv_ver) = get_virtenv();
# Store the highest version from Sphinx existing virtualenvs
if (($activate_cmd ne "") && ($venv_ver gt $cur_version)) {
@@ -759,10 +775,14 @@ sub recommend_sphinx_upgrade()
# Either there are already a virtual env or a new one should be created
$need_pip = 1;
+ return if (!$latest_avail_ver);
+
# Return if the reason is due to an upgrade or not
if ($latest_avail_ver lt $rec_version) {
$rec_sphinx_upgrade = 1;
}
+
+ return $latest_avail_ver;
}
#
@@ -775,12 +795,13 @@ sub recommend_sphinx_version($)
{
my $virtualenv_cmd = shift;
- if ($latest_avail_ver lt $min_pdf_version) {
- print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
- }
-
# Version is OK. Nothing to do.
- return if ($cur_version && ($cur_version ge $rec_version));
+ if ($cur_version && ($cur_version ge $rec_version)) {
+ if ($cur_version lt $min_pdf_version) {
+ print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
+ }
+ return;
+ };
if (!$need_sphinx) {
# sphinx-build is present and its version is >= $min_version
@@ -820,13 +841,17 @@ sub recommend_sphinx_version($)
}
# Suggest newer versions if current ones are too old
- if ($latest_avail_ver && $cur_version ge $min_version) {
+ if ($latest_avail_ver && $latest_avail_ver ge $min_version) {
# If there's a good enough version, ask the user to enable it
if ($latest_avail_ver ge $rec_version) {
printf "\nNeed to activate Sphinx (version $latest_avail_ver) on virtualenv with:\n";
printf "\t. $activate_cmd\n";
deactivate_help();
+ if ($latest_avail_ver lt $min_pdf_version) {
+ print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
+ }
+
return;
}
@@ -848,7 +873,7 @@ sub recommend_sphinx_version($)
print "To upgrade Sphinx, use:\n\n";
}
} else {
- print "Sphinx needs to be installed either as a package or via pip/pypi with:\n";
+ print "\nSphinx needs to be installed either:\n1) via pip/pypi with:\n\n";
}
$python_cmd = find_python_no_venv();
@@ -858,6 +883,29 @@ sub recommend_sphinx_version($)
printf "\t. $virtenv_dir/bin/activate\n";
printf "\tpip install -r $requirement_file\n";
deactivate_help();
+
+ printf "\n2) As a package with:\n";
+
+ my $old_need = $need;
+ my $old_optional = $optional;
+ %missing = ();
+ $pdf = 0;
+ $optional = 0;
+ $install = "";
+ $verbose_warn_install = 0;
+
+ add_package("python-sphinx", 0);
+ check_python_module("sphinx_rtd_theme", 1);
+
+ check_distros();
+
+ $need = $old_need;
+ $optional = $old_optional;
+
+ printf "\n Please note that Sphinx >= 3.0 will currently produce false-positive\n";
+ printf " warning when the same name is used for more than one type (functions,\n";
+ printf " structs, enums,...). This is known Sphinx bug. For more details, see:\n";
+ printf "\thttps://github.com/sphinx-doc/sphinx/pull/8313\n";
}
sub check_needs()
@@ -897,7 +945,7 @@ sub check_needs()
}
}
- recommend_sphinx_upgrade();
+ my $venv_ver = recommend_sphinx_upgrade();
my $virtualenv_cmd;
diff --git a/tools/include/linux/objtool.h b/tools/include/linux/objtool.h
index 10bc88cc3bf6..62c54ffbeeaa 100644
--- a/tools/include/linux/objtool.h
+++ b/tools/include/linux/objtool.h
@@ -67,7 +67,7 @@ struct unwind_hint {
* It should only be used in special cases where you're 100% sure it won't
* affect the reliability of frame pointers and kernel stack traces.
*
- * For more information, see tools/objtool/Documentation/stack-validation.txt.
+ * For more information, see tools/objtool/Documentation/objtool.txt.
*/
#define STACK_FRAME_NON_STANDARD(func) \
static void __used __section(".discard.func_stack_frame_non_standard") \
diff --git a/tools/objtool/check.c b/tools/objtool/check.c
index b341f8a8c7c5..0cec74da7ffe 100644
--- a/tools/objtool/check.c
+++ b/tools/objtool/check.c
@@ -3297,7 +3297,7 @@ static struct instruction *next_insn_to_validate(struct objtool_file *file,
* Follow the branch starting at the given instruction, and recursively follow
* any other branches (jumps). Meanwhile, track the frame pointer state at
* each instruction and validate all the rules described in
- * tools/objtool/Documentation/stack-validation.txt.
+ * tools/objtool/Documentation/objtool.txt.
*/
static int validate_branch(struct objtool_file *file, struct symbol *func,
struct instruction *insn, struct insn_state state)