linux.git/Documentation/process/coding-style.rst, branch v6.6.131

coding-style: fix title of Greg K-H's talk

2023-03-23T18:04:08+00:00

The talk title was inadvertently mangled in 8c27ceff3604 ("docs: fix
locations of several documents that got moved").

Signed-off-by: Jakub Wilk 
Link: https://lore.kernel.org/r/20230322215311.6579-1-jwilk@jwilk.net
Signed-off-by: Jonathan Corbet

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

2022-09-29T19:20:53+00:00

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:49+00:00

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:02+00:00

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:17+00:00

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:02+00:00

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:54+00:00

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:35+00:00

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:43+00:00

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:21+00:00

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