From c398488dab7d731f942da9f34981b536fe187e3f Mon Sep 17 00:00:00 2001 From: Xueshi Hu Date: Mon, 3 Jul 2023 18:20:44 +0800 Subject: [PATCH 1/6] docs: fix typo in zh_TW and zh_CN translation In zh_TW and zh_CN translation, "http://lwn.net/Articles" is incorrectly written as "http://lwn.net/Articles". This patch is generated by the following script: rg -l "lwn.net/Articles" | xargs sed -i 's/lwn.net\/articles/lwn.net\/Articles/g' Signed-off-by: Xueshi Hu Signed-off-by: Jonathan Corbet Message-ID: --- Documentation/translations/zh_CN/process/2.Process.rst | 2 +- Documentation/translations/zh_CN/process/3.Early-stage.rst | 2 +- Documentation/translations/zh_CN/process/4.Coding.rst | 2 +- Documentation/translations/zh_CN/process/7.AdvancedTopics.rst | 2 +- Documentation/translations/zh_TW/process/2.Process.rst | 2 +- Documentation/translations/zh_TW/process/3.Early-stage.rst | 2 +- Documentation/translations/zh_TW/process/4.Coding.rst | 2 +- Documentation/translations/zh_TW/process/7.AdvancedTopics.rst | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/translations/zh_CN/process/2.Process.rst b/Documentation/translations/zh_CN/process/2.Process.rst index 4a6ed0219494..e68c9de0f7f8 100644 --- a/Documentation/translations/zh_CN/process/2.Process.rst +++ b/Documentation/translations/zh_CN/process/2.Process.rst @@ -358,7 +358,7 @@ Andrew Morton 为有抱负的内核开发人员提供了如下建议 机器上始终完美运行”。通常的方法是和其他人一起解决问题（这可能需 要坚持！），但就是如此——这是内核开发的一部分。 -(http://lwn.net/articles/283982/) +(http://lwn.net/Articles/283982/) 在没有明显问题需要解决的情况下，通常建议开发人员查看当前的回归和开放缺陷 列表。从来都不缺少需要解决的问题；通过解决这些问题，开发人员将从该过程获得 diff --git a/Documentation/translations/zh_CN/process/3.Early-stage.rst b/Documentation/translations/zh_CN/process/3.Early-stage.rst index de53dd12e911..2caba4753b75 100644 --- a/Documentation/translations/zh_CN/process/3.Early-stage.rst +++ b/Documentation/translations/zh_CN/process/3.Early-stage.rst @@ -44,7 +44,7 @@ 试图向这些人传达用户需求是浪费时间。他们太“聪明”了，根本听不到少数 人的话。 -（http://lwn.net/articles/131776/） +（http://lwn.net/Articles/131776/） 实际情况却是不同的；与特定模块相比，内核开发人员更关心系统稳定性、长期维护 以及找到问题的正确解决方案。这个故事的寓意是把重点放在问题上——而不是具体的 diff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rst index 94f7f866f103..7cac9424f5d5 100644 --- a/Documentation/translations/zh_CN/process/4.Coding.rst +++ b/Documentation/translations/zh_CN/process/4.Coding.rst @@ -149,7 +149,7 @@ Linus对这个问题给出了最佳答案: 所以我们不会通过引入新问题来修复错误。这种方式是靠不住的，没人知道 是否真的有进展。是前进两步、后退一步，还是前进一步、后退两步？ -（http://lwn.net/articles/243460/） +（http://lwn.net/Articles/243460/） 特别不受欢迎的一种回归类型是用户空间ABI的任何变化。一旦接口被导出到用户空间， 就必须无限期地支持它。这一事实使得用户空间接口的创建特别具有挑战性：因为它们 diff --git a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst index 6d0dadae13b1..57beca02181c 100644 --- a/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_CN/process/7.AdvancedTopics.rst @@ -98,7 +98,7 @@ Git提供了一些强大的工具，可以让您重写开发历史。一个不 你可以给我发补丁，但当我从你那里拉取一个Git补丁时，我需要知道你清楚 自己在做什么，我需要能够相信事情而 *无需* 手动检查每个单独的更改。 -（http://lwn.net/articles/224135/）。 +（http://lwn.net/Articles/224135/）。 为了避免这种情况，请确保给定分支中的所有补丁都与相关主题紧密相关；“驱动程序 修复”分支不应更改核心内存管理代码。而且，最重要的是，不要使用Git树来绕过 diff --git a/Documentation/translations/zh_TW/process/2.Process.rst b/Documentation/translations/zh_TW/process/2.Process.rst index b01cdd3a39ae..9d465df1f6c3 100644 --- a/Documentation/translations/zh_TW/process/2.Process.rst +++ b/Documentation/translations/zh_TW/process/2.Process.rst @@ -361,7 +361,7 @@ Andrew Morton 爲有抱負的內核開發人員提供了如下建議 機器上始終完美運行」。通常的方法是和其他人一起解決問題（這可能需 要堅持！），但就是如此——這是內核開發的一部分。 -(http://lwn.net/articles/283982/) +(http://lwn.net/Articles/283982/) 在沒有明顯問題需要解決的情況下，通常建議開發人員查看當前的回歸和開放缺陷 列表。從來都不缺少需要解決的問題；通過解決這些問題，開發人員將從該過程獲得 diff --git a/Documentation/translations/zh_TW/process/3.Early-stage.rst b/Documentation/translations/zh_TW/process/3.Early-stage.rst index ab2a45fd65a4..076873ca0905 100644 --- a/Documentation/translations/zh_TW/process/3.Early-stage.rst +++ b/Documentation/translations/zh_TW/process/3.Early-stage.rst @@ -47,7 +47,7 @@ 試圖向這些人傳達用戶需求是浪費時間。他們太「聰明」了，根本聽不到少數 人的話。 -（http://lwn.net/articles/131776/） +（http://lwn.net/Articles/131776/） 實際情況卻是不同的；與特定模塊相比，內核開發人員更關心系統穩定性、長期維護 以及找到問題的正確解決方案。這個故事的寓意是把重點放在問題上——而不是具體的 diff --git a/Documentation/translations/zh_TW/process/4.Coding.rst b/Documentation/translations/zh_TW/process/4.Coding.rst index ccc3946227a0..7fc0344ed16b 100644 --- a/Documentation/translations/zh_TW/process/4.Coding.rst +++ b/Documentation/translations/zh_TW/process/4.Coding.rst @@ -152,7 +152,7 @@ Linus對這個問題給出了最佳答案: 所以我們不會通過引入新問題來修復錯誤。這種方式是靠不住的，沒人知道 是否真的有進展。是前進兩步、後退一步，還是前進一步、後退兩步？ -（http://lwn.net/articles/243460/） +（http://lwn.net/Articles/243460/） 特別不受歡迎的一種回歸類型是用戶空間ABI的任何變化。一旦接口被導出到用戶空間， 就必須無限期地支持它。這一事實使得用戶空間接口的創建特別具有挑戰性：因爲它們 diff --git a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst index 3de093d0f170..4fbc104a37ca 100644 --- a/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst +++ b/Documentation/translations/zh_TW/process/7.AdvancedTopics.rst @@ -101,7 +101,7 @@ Git提供了一些強大的工具，可以讓您重寫開發歷史。一個不 你可以給我發補丁，但當我從你那裡拉取一個Git補丁時，我需要知道你清楚 自己在做什麼，我需要能夠相信事情而 *無需* 手動檢查每個單獨的更改。 -（http://lwn.net/articles/224135/）。 +（http://lwn.net/Articles/224135/）。 爲了避免這種情況，請確保給定分支中的所有補丁都與相關主題緊密相關；「驅動程序 修復」分支不應更改核心內存管理代碼。而且，最重要的是，不要使用Git樹來繞過 From b45d8f3871574999002b79d551cac51a20bcfae6 Mon Sep 17 00:00:00 2001 From: Jakub Kicinski Date: Fri, 30 Jun 2023 10:15:50 -0700 Subject: [PATCH 2/6] docs: remove the tips on how to submit patches from MAINTAINERS Having "how to submit patches" in MAINTAINTERS seems out of place. We have a whole section of documentation about it, duplication is harmful and a lot of the text looks really out of date. Sections 1, 2 and 4 look really, really old and not applicable to the modern process. Section 3 is obvious but also we have build bots now. Section 5 is a bit outdated (diff -u?!). But I like the part about factoring out shared code, so add that to process docs. Section 6 is unnecessary? Section 7 is covered by more appropriate docs. Signed-off-by: Jakub Kicinski Reviewed-by: Randy Dunlap Reviewed-by: Dan Williams Reviewed-by: Kees Cook Signed-off-by: Jonathan Corbet Message-ID: <20230630171550.128296-1-kuba@kernel.org> --- Documentation/process/6.Followthrough.rst | 7 ++ MAINTAINERS | 80 +---------------------- 2 files changed, 9 insertions(+), 78 deletions(-) diff --git a/Documentation/process/6.Followthrough.rst b/Documentation/process/6.Followthrough.rst index a173cd5f93d2..66fa400c6d94 100644 --- a/Documentation/process/6.Followthrough.rst +++ b/Documentation/process/6.Followthrough.rst @@ -51,6 +51,13 @@ mind: working toward the creation of the best kernel they can; they are not trying to create discomfort for their employers' competitors. + - Be prepared for seemingly silly requests for coding style changes + and requests to factor out some of your code to shared parts of + the kernel. One job the maintainers do is to keep things looking + the same. Sometimes this means that the clever hack in your driver + to get around a problem actually needs to become a generalized + kernel feature ready for next time. + What all of this comes down to is that, when reviewers send you comments, you need to pay attention to the technical observations that they are making. Do not let their form of expression or your own pride keep that diff --git a/MAINTAINERS b/MAINTAINERS index a73486c4aa6e..f73316d4ff34 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1,81 +1,5 @@ -List of maintainers and how to submit kernel changes -==================================================== - -Please try to follow the guidelines below. This will make things -easier on the maintainers. Not all of these guidelines matter for every -trivial patch so apply some common sense. - -Tips for patch submitters -------------------------- - -1. Always *test* your changes, however small, on at least 4 or - 5 people, preferably many more. - -2. Try to release a few ALPHA test versions to the net. Announce - them onto the kernel channel and await results. This is especially - important for device drivers, because often that's the only way - you will find things like the fact version 3 firmware needs - a magic fix you didn't know about, or some clown changed the - chips on a board and not its name. (Don't laugh! Look at the - SMC etherpower for that.) - -3. Make sure your changes compile correctly in multiple - configurations. In particular check that changes work both as a - module and built into the kernel. - -4. When you are happy with a change make it generally available for - testing and await feedback. - -5. Make a patch available to the relevant maintainer in the list. Use - ``diff -u`` to make the patch easy to merge. Be prepared to get your - changes sent back with seemingly silly requests about formatting - and variable names. These aren't as silly as they seem. One - job the maintainers (and especially Linus) do is to keep things - looking the same. Sometimes this means that the clever hack in - your driver to get around a problem actually needs to become a - generalized kernel feature ready for next time. - - PLEASE check your patch with the automated style checker - (scripts/checkpatch.pl) to catch trivial style violations. - See Documentation/process/coding-style.rst for guidance here. - - PLEASE CC: the maintainers and mailing lists that are generated - by ``scripts/get_maintainer.pl.`` The results returned by the - script will be best if you have git installed and are making - your changes in a branch derived from Linus' latest git tree. - See Documentation/process/submitting-patches.rst for details. - - PLEASE try to include any credit lines you want added with the - patch. It avoids people being missed off by mistake and makes - it easier to know who wants adding and who doesn't. - - PLEASE document known bugs. If it doesn't work for everything - or does something very odd once a month document it. - - PLEASE remember that submissions must be made under the terms - of the Linux Foundation certificate of contribution and should - include a Signed-off-by: line. The current version of this - "Developer's Certificate of Origin" (DCO) is listed in the file - Documentation/process/submitting-patches.rst. - -6. Make sure you have the right to send any changes you make. If you - do changes at work you may find your employer owns the patch - not you. - -7. When sending security related changes or reports to a maintainer - please Cc: security@kernel.org, especially if the maintainer - does not respond. Please keep in mind that the security team is - a small set of people who can be efficient only when working on - verified bugs. Please only Cc: this list when you have identified - that the bug would present a short-term risk to other users if it - were publicly disclosed. For example, reports of address leaks do - not represent an immediate threat and are better handled publicly, - and ideally, should come with a patch proposal. Please do not send - automated reports to this list either. Such bugs will be handled - better and faster in the usual public places. See - Documentation/process/security-bugs.rst for details. - -8. Happy hacking. +List of maintainers +=================== Descriptions of section entries and preferred order --------------------------------------------------- From 57ada2358fae8c3df0f810c3a7196f074da01c98 Mon Sep 17 00:00:00 2001 From: Olaf Hering Date: Fri, 30 Jun 2023 16:53:02 +0200 Subject: [PATCH 3/6] Fix documentation of panic_on_warn The kernel cmdline option panic_on_warn expects an integer, it is not a plain option as documented. A number of uses in the tree figured this already, and use panic_on_warn=1 for their purpose. Adjust a comment which otherwise may mislead people in the future. Fixes: 9e3961a09798 ("kernel: add panic_on_warn") Signed-off-by: Olaf Hering Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/kernel-parameters.txt | 2 +- tools/testing/selftests/rcutorture/bin/kvm.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index b0e4195808b4..de0eb6fd8d03 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -4064,7 +4064,7 @@ extra details on the taint flags that users can pick to compose the bitmask to assign to panic_on_taint. - panic_on_warn panic() instead of WARN(). Useful to cause kdump + panic_on_warn=1 panic() instead of WARN(). Useful to cause kdump on a WARN(). parkbd.port= [HW] Parallel port number the keyboard adapter is diff --git a/tools/testing/selftests/rcutorture/bin/kvm.sh b/tools/testing/selftests/rcutorture/bin/kvm.sh index 62f3b0f56e4d..d3cdc2d33d4b 100755 --- a/tools/testing/selftests/rcutorture/bin/kvm.sh +++ b/tools/testing/selftests/rcutorture/bin/kvm.sh @@ -655,4 +655,4 @@ fi # Control buffer size: --bootargs trace_buf_size=3k # Get trace-buffer dumps on all oopses: --bootargs ftrace_dump_on_oops # Ditto, but dump only the oopsing CPU: --bootargs ftrace_dump_on_oops=orig_cpu -# Heavy-handed way to also dump on warnings: --bootargs panic_on_warn +# Heavy-handed way to also dump on warnings: --bootargs panic_on_warn=1 From 29e31a8ee811f5d85274f0381f13cd6fe650aea4 Mon Sep 17 00:00:00 2001 From: David Heidelberg Date: Sun, 25 Jun 2023 12:33:04 +0200 Subject: [PATCH 4/6] Documentation: ACPI: fix typo in ssdt-overlays.rst Signed-off-by: David Heidelberg Signed-off-by: Jonathan Corbet Message-ID: <20230625103305.115484-1-david@ixit.cz> --- Documentation/admin-guide/acpi/ssdt-overlays.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/admin-guide/acpi/ssdt-overlays.rst b/Documentation/admin-guide/acpi/ssdt-overlays.rst index b5fbf54dca19..5ea9f4a3b76e 100644 --- a/Documentation/admin-guide/acpi/ssdt-overlays.rst +++ b/Documentation/admin-guide/acpi/ssdt-overlays.rst @@ -103,7 +103,7 @@ allows a persistent, OS independent way of storing the user defined SSDTs. There is also work underway to implement EFI support for loading user defined SSDTs and using this method will make it easier to convert to the EFI loading mechanism when that will arrive. To enable it, the -CONFIG_EFI_CUSTOM_SSDT_OVERLAYS shoyld be chosen to y. +CONFIG_EFI_CUSTOM_SSDT_OVERLAYS should be chosen to y. In order to load SSDTs from an EFI variable the ``"efivar_ssdt=..."`` kernel command line parameter can be used (the name has a limitation of 16 characters). From 1e6115f50bca20417e9d4d95ce99e36d6f145fa4 Mon Sep 17 00:00:00 2001 From: Changyuan Lyu Date: Sat, 24 Jun 2023 09:58:57 -0700 Subject: [PATCH 5/6] Documentation: KVM: SEV: add a missing backtick ``ENOTTY` -> ``ENOTTY``. Signed-off-by: Changyuan Lyu Signed-off-by: Jonathan Corbet Message-ID: <20230624165858.21777-1-changyuanl@google.com> --- Documentation/virt/kvm/x86/amd-memory-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/virt/kvm/x86/amd-memory-encryption.rst b/Documentation/virt/kvm/x86/amd-memory-encryption.rst index 487b6328b3e7..995780088eb2 100644 --- a/Documentation/virt/kvm/x86/amd-memory-encryption.rst +++ b/Documentation/virt/kvm/x86/amd-memory-encryption.rst @@ -57,7 +57,7 @@ information, see the SEV Key Management spec [api-spec]_ The main ioctl to access SEV is KVM_MEMORY_ENCRYPT_OP. If the argument to KVM_MEMORY_ENCRYPT_OP is NULL, the ioctl returns 0 if SEV is enabled -and ``ENOTTY` if it is disabled (on some older versions of Linux, +and ``ENOTTY`` if it is disabled (on some older versions of Linux, the ioctl runs normally even with a NULL argument, and therefore will likely return ``EFAULT``). If non-NULL, the argument to KVM_MEMORY_ENCRYPT_OP must be a struct kvm_sev_cmd:: From e27cb89a22ada4e3e7bee1567a8daa1fb2260b78 Mon Sep 17 00:00:00 2001 From: Jakub Kicinski Date: Wed, 21 Jun 2023 15:35:25 -0700 Subject: [PATCH 6/6] scripts: kernel-doc: support private / public marking for enums Enums benefit from private markings, too. For netlink attribute name enums always end with a pair of __$n_MAX and $n_MAX members. Documenting them feels a bit tedious. Signed-off-by: Jakub Kicinski Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20230621223525.2722703-1-kuba@kernel.org> --- scripts/kernel-doc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 2486689ffc7b..66b554897899 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1301,6 +1301,9 @@ sub dump_enum($$) { my $file = shift; my $members; + # ignore members marked private: + $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; + $x =~ s/\/\*\s*private:.*}/}/gosi; $x =~ s@/\*.*?\*/@@gos; # strip comments. # strip #define macros inside enums