user/sven/linux.git/Documentation/process/coding-style.rst, branch v6.3.3

coding-style.rst: document BUG() and WARN() rules ("do not crash the kernel")

2022-09-29T19:20:53Z

Linus notes [1] that the introduction of new code that uses VM_BUG_ON() is just as bad as BUG_ON(), because it will crash the kernel on distributions that enable CONFIG_DEBUG_VM (like Fedora): VM_BUG_ON() has the exact same semantics as BUG_ON. It is literally no different, the only difference is "we can make the code smaller because these are less important". [2] This resulted in a more generic discussion about usage of BUG() and friends. While there might be corner cases that still deserve a BUG_ON(), most BUG_ON() cases should simply use WARN_ON_ONCE() and implement a recovery path if reasonable: The only possible case where BUG_ON can validly be used is "I have some fundamental data corruption and cannot possibly return an error". [2] As a very good approximation is the general rule: "absolutely no new BUG_ON() calls _ever_" [2] ... not even if something really shouldn't ever happen and is merely for documenting that an invariant always has to hold. However, there are sill exceptions where BUG_ON() may be used: If you have a "this is major internal corruption, there's no way we can continue", then BUG_ON() is appropriate. [3] There is only one good BUG_ON(): Now, that said, there is one very valid sub-form of BUG_ON(): BUILD_BUG_ON() is absolutely 100% fine. [2] While WARN will also crash the machine with panic_on_warn set, that's exactly to be expected: So we have two very different cases: the "virtual machine with good logging where a dead machine is fine" - use 'panic_on_warn'. And the actual real hardware with real drivers, running real loads by users. [4] The basic idea is that warnings will similarly get reported by users and be found during testing. However, in contrast to a BUG(), there is a way to actually influence the expected behavior (e.g., panic_on_warn) and to eventually keep the machine alive to extract some debug info. Ingo notes that not all WARN_ON_ONCE cases need recovery. If we don't ever expect this code to trigger in any case, recovery code is not really helpful. I'd prefer to keep all these warnings 'simple' - i.e. no attempted recovery & control flow, unless we ever expect these to trigger. [5] There have been different rules floating around that were never properly documented. Let's try to clarify. [1] https://lkml.kernel.org/r/CAHk-=wiEAH+ojSpAgx_Ep=NKPWHU8AdO3V56BXcCsU97oYJ1EA@mail.gmail.com [2] https://lore.kernel.org/r/CAHk-=wg40EAZofO16Eviaj7mfqDhZ2gVEbvfsMf6gYzspRjYvw@mail.gmail.com [3] https://lkml.kernel.org/r/CAHk-=wit-DmhMfQErY29JSPjFgebx_Ld+pnerc4J2Ag990WwAA@mail.gmail.com [4] https://lore.kernel.org/r/CAHk-=wgF7K2gSSpy=m_=K3Nov4zaceUX9puQf1TjkTJLA2XC_g@mail.gmail.com [5] https://lore.kernel.org/r/YwIW+mVeZoTOxn%2F4@gmail.com Reviewed-by: John Hubbard Signed-off-by: David Hildenbrand Link: https://lore.kernel.org/r/20220923113426.52871-2-david@redhat.com Signed-off-by: Jonathan Corbet

coding-style.rst: trivial: fix location of driver model macros

2021-10-26T15:39:49Z

The dev_printk()-like functions moved to include/linux/dev_print.h in commit af628aae8640 ("device.h: move dev_printk()-like functions to dev_printk.h"). Signed-off-by: Trevor Woerner Reviewed-by: Shuah Khan Reviewed-by: Miguel Ojeda Link: https://lore.kernel.org/r/20210423184012.39300-1-twoerner@gmail.com Signed-off-by: Jonathan Corbet

docs: Explain the desired position of function attributes

2021-10-12T19:35:02Z

While discussing how to format the addition of various function attributes, some "unwritten rules" of ordering surfaced[1]. Capture as close as possible to Linus's preferences for future reference. (Though I note the dissent voiced by Joe Perches, Alexey Dobriyan, and others that would prefer all attributes live on a separate leading line.) [1] https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.com/ Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/20211005152611.4120605-1-keescook@chromium.org Signed-off-by: Jonathan Corbet

docs: Remove the Microsoft rhetoric

2021-02-11T16:42:17Z

There is no need to need to name Microsoft. The point is clear without that context. Signed-off-by: Yorick de Wid Link: https://lore.kernel.org/r/20210208150447.87104-1-ydewid@gmail.com Signed-off-by: Jonathan Corbet

coding-style.rst: Avoid comma statements

2021-02-04T21:40:02Z

Commas are not how statements are terminated. Always use semicolons and braces if necessary. Signed-off-by: Joe Perches Link: https://lore.kernel.org/r/2a97b738bba335434461a5a918053a49c1fb6af4.1598331148.git.joe@perches.com Signed-off-by: Jonathan Corbet

Merge tag 'docs-5.9' of git://git.lwn.net/linux

2020-08-05T05:47:54Z

Pull documentation updates from Jonathan Corbet: "It's been a busy cycle for documentation - hopefully the busiest for a while to come. Changes include: - Some new Chinese translations - Progress on the battle against double words words and non-HTTPS URLs - Some block-mq documentation - More RST conversions from Mauro. At this point, that task is essentially complete, so we shouldn't see this kind of churn again for a while. Unless we decide to switch to asciidoc or something...:) - Lots of typo fixes, warning fixes, and more" * tag 'docs-5.9' of git://git.lwn.net/linux: (195 commits) scripts/kernel-doc: optionally treat warnings as errors docs: ia64: correct typo mailmap: add entry for doc/zh_CN: add cpu-load Chinese version Documentation/admin-guide: tainted-kernels: fix spelling mistake MAINTAINERS: adjust kprobes.rst entry to new location devices.txt: document rfkill allocation PCI: correct flag name docs: filesystems: vfs: correct flag name docs: filesystems: vfs: correct sync_mode flag names docs: path-lookup: markup fixes for emphasis docs: path-lookup: more markup fixes docs: path-lookup: fix HTML entity mojibake CREDITS: Replace HTTP links with HTTPS ones docs: process: Add an example for creating a fixes tag doc/zh_CN: add Chinese translation prefer section doc/zh_CN: add clearing-warn-once Chinese version doc/zh_CN: add admin-guide index doc:it_IT: process: coding-style.rst: Correct __maybe_unused compiler label futex: MAINTAINERS: Re-add selftests directory ...

CodingStyle: Inclusive Terminology

2020-07-04T06:54:35Z

Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist. Link: http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.stgit@dwillia2-desk3.amr.corp.intel.com Acked-by: Randy Dunlap Acked-by: Dave Airlie Acked-by: SeongJae Park Acked-by: Christian Brauner Acked-by: James Bottomley Acked-by: Daniel Vetter Acked-by: Andy Lutomirski Acked-by: Laura Abbott Acked-by: Gustavo A. R. Silva Reviewed-by: Matthias Brugger Reviewed-by: Mark Brown Signed-off-by: Stephen Hemminger Signed-off-by: Theodore Ts'o Signed-off-by: Shuah Khan Signed-off-by: Dan Carpenter Signed-off-by: Kees Cook Signed-off-by: Olof Johansson Signed-off-by: Jonathan Corbet Signed-off-by: Chris Mason Signed-off-by: Greg Kroah-Hartman Signed-off-by: Dan Williams

Replace HTTP links with HTTPS ones: Documentation/process

2020-06-26T17:19:43Z

Rationale: Reduces attack surface on kernel devs opening the links for MITM as HTTPS traffic is much harder to manipulate. Deterministic algorithm: For each file: If not .svg: For each line: If doesn't contain `\bxmlns\b`: For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`: If both the HTTP and HTTPS versions return 200 OK and serve the same content: Replace HTTP with HTTPS. Signed-off-by: Alexander A. Klimov Acked-by: Miguel Ojeda Link: https://lore.kernel.org/r/20200621133630.46435-1-grandmaster@al2klimov.de Signed-off-by: Jonathan Corbet

Documentation/CodingStyle: Fix duplicate "are" typo

2020-06-10T17:38:21Z

The improved paragraph about line lengths contains a sentence with a duplicate word: there is one "are" at the end of a line, followed by a second one at the beginning of the next line. Drop the first one, as that one is part of the longest line. Fixes: bdc48fa11e46f867 ("checkpatch/coding-style: deprecate 80-column warning") Signed-off-by: Geert Uytterhoeven Signed-off-by: Linus Torvalds

checkpatch/coding-style: deprecate 80-column warning

2020-05-31T18:00:42Z

Yes, staying withing 80 columns is certainly still _preferred_. But it's not the hard limit that the checkpatch warnings imply, and other concerns can most certainly dominate. Increase the default limit to 100 characters. Not because 100 characters is some hard limit either, but that's certainly a "what are you doing" kind of value and less likely to be about the occasional slightly longer lines. Miscellanea: - to avoid unnecessary whitespace changes in files, checkpatch will no longer emit a warning about line length when scanning files unless --strict is also used - Add a bit to coding-style about alignment to open parenthesis Signed-off-by: Joe Perches Signed-off-by: Linus Torvalds