docs/process: fix typos

Fix typos in documentation.

Signed-off-by: Andrew Kreimer <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <20240907122534.15998-1-algonell@g

docs/process: fix typos

Fix typos in documentation.

Signed-off-by: Andrew Kreimer <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>

show more ...

net: drop special comment style

As we discussed in the room at netdevconf earlier this week,
drop the requirement for special comment style for netdev.

For checkpatch, the general check accepts bot

net: drop special comment style

As we discussed in the room at netdevconf earlier this week,
drop the requirement for special comment style for netdev.

For checkpatch, the general check accepts both right now, so
simply drop the special request there as well.

Acked-by: Stephen Hemminger <[email protected]>
Signed-off-by: Johannes Berg <[email protected]>
Acked-by: Jakub Kicinski <[email protected]>
Signed-off-by: David S. Miller <[email protected]>

show more ...

Docs: Move clang-format from process/ to dev-tools/

'clang-format' is on 'Other material' section of 'process/index', but it
may fit more under 'dev-tools/' directory. Move it.

Signed-off-by: Seon

Docs: Move clang-format from process/ to dev-tools/

'clang-format' is on 'Other material' section of 'process/index', but it
may fit more under 'dev-tools/' directory. Move it.

Signed-off-by: SeongJae Park <[email protected]>
Acked-by: Miguel Ojeda <[email protected]>
Acked-by: Federico Vaga <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

Documentation: coding-style: ask function-like macros to evaluate parameters

Patch series "codingstyle: avoid unused parameters for a function-like
macro", v7.

A function-like macro could result in

Documentation: coding-style: ask function-like macros to evaluate parameters

Patch series "codingstyle: avoid unused parameters for a function-like
macro", v7.

A function-like macro could result in build warnings such as "unused
variable." This patchset updates the guidance to recommend always using a
static inline function instead and also provides checkpatch support for
this new rule.


This patch (of 2):

Recent commit 77292bb8ca69c80 ("crypto: scomp - remove memcpy if
sg_nents is 1 and pages are lowmem") leads to warnings on xtensa
and loongarch,
In file included from crypto/scompress.c:12:
include/crypto/scatterwalk.h: In function 'scatterwalk_pagedone':
include/crypto/scatterwalk.h:76:30: warning: variable 'page' set but not used [-Wunused-but-set-variable]
76 | struct page *page;
| ^~~~
crypto/scompress.c: In function 'scomp_acomp_comp_decomp':
>> crypto/scompress.c:174:38: warning: unused variable 'dst_page' [-Wunused-variable]
174 | struct page *dst_page = sg_page(req->dst);
|

The reason is that flush_dcache_page() is implemented as a noop
macro on these platforms as below,

#define flush_dcache_page(page) do { } while (0)

The driver code, for itself, seems be quite innocent and placing
maybe_unused seems pointless,

struct page *dst_page = sg_page(req->dst);

for (i = 0; i < nr_pages; i++)
flush_dcache_page(dst_page + i);

And it should be independent of architectural implementation
differences.

Let's provide guidance on coding style for requesting parameter
evaluation or proposing the migration to a static inline
function.

Link: https://lkml.kernel.org/r/[email protected]
Link: https://lkml.kernel.org/r/[email protected]
Signed-off-by: Barry Song <[email protected]>
Suggested-by: Max Filippov <[email protected]>
Reviewed-by: Mark Brown <[email protected]>
Acked-by: Joe Perches <[email protected]>
Cc: Chris Zankel <[email protected]>
Cc: Huacai Chen <[email protected]>
Cc: Herbert Xu <[email protected]>
Cc: Guenter Roeck <[email protected]>
Cc: Stephen Rothwell <[email protected]>
Cc: Andy Whitcroft <[email protected]>
Cc: Dwaipayan Ray <[email protected]>
Cc: Joe Perches <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: Lukas Bulwahn <[email protected]>
Cc: Xining Xu <[email protected]>
Cc: Charlemagne Lasse <[email protected]>
Cc: Jeff Johnson <[email protected]>
Signed-off-by: Andrew Morton <[email protected]>

show more ...

Documentation: coding-style: Update syntax highlighting for code-blocks

Use c and elisp instead of none in code-blocks

Signed-off-by: Thorsten Blum <[email protected]>
Signed-off-by: Jonatha

Documentation: coding-style: Update syntax highlighting for code-blocks

Use c and elisp instead of none in code-blocks

Signed-off-by: Thorsten Blum <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

Documentation: coding-style: Fix indentation in code-blocks

- Remove spaces in C code-blocks to align error labels consistently
- Replace tab characters with spaces in emacs-lisp code blocks

Signed

Documentation: coding-style: Fix indentation in code-blocks

- Remove spaces in C code-blocks to align error labels consistently
- Replace tab characters with spaces in emacs-lisp code blocks

Signed-off-by: Thorsten Blum <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

coding-style: Add guidance to prefer dev_dbg

During review, it was suggested that drivers only emit messages when
something is wrong or it is a debug message. Document this as a formal
recommendatio

coding-style: Add guidance to prefer dev_dbg

During review, it was suggested that drivers only emit messages when
something is wrong or it is a debug message. Document this as a formal
recommendation.

https://lore.kernel.org/linux-usb/2024012525-alienate-frown-916b@gregkh/

Signed-off-by: Abhishek Pandit-Subedi <[email protected]>
Acked-by: Greg Kroah-Hartman <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/20240125165311.1.I8d9c88e747e233917e527c7dad1feb8a18f070e2@changeid

show more ...

Add .editorconfig file for basic formatting

EditorConfig is a specification to define the most basic code formatting
stuff, and it's supported by many editors and IDEs, either directly or
via plugin

Add .editorconfig file for basic formatting

EditorConfig is a specification to define the most basic code formatting
stuff, and it's supported by many editors and IDEs, either directly or
via plugins, including VSCode/VSCodium, Vim, emacs and more.

It allows to define formatting style related to indentation, charset,
end of lines and trailing whitespaces. It also allows to apply different
formats for different files based on wildcards, so for example it is
possible to apply different configs to *.{c,h}, *.py and *.rs.

In linux project, defining a .editorconfig might help to those people
that work on different projects with different indentation styles, so
they cannot define a global style. Now they will directly see the
correct indentation on every fresh clone of the project.

See https://editorconfig.org

Co-developed-by: Danny Lin <[email protected]>
Signed-off-by: Danny Lin <[email protected]>
Signed-off-by: Íñigo Huguet <[email protected]>
Acked-by: Mickaël Salaün <[email protected]>
Reviewed-by: Vincent Mailhol <[email protected]>
Tested-by: Vincent Mailhol <[email protected]>
Signed-off-by: Masahiro Yamada <[email protected]>

show more ...

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

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

Signed-off-by: Jakub Wilk <jwilk@jwi

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

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

Signed-off-by: Jakub Wilk <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

Linus notes [1] that the introduction of new code that uses VM_BUG_ON()
is just as bad as BUG_ON(), because it will cras

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

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%[email protected]

Reviewed-by: John Hubbard <[email protected]>
Signed-off-by: David Hildenbrand <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

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

The dev_printk()-like functions moved to include/linux/dev_print.h in
commit af628aae8640 ("device.h: move dev_printk()-like functions

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

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 <[email protected]>
Reviewed-by: Shuah Khan <[email protected]>
Reviewed-by: Miguel Ojeda <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Explain the desired position of function attributes

While discussing how to format the addition of various function
attributes, some "unwritten rules" of ordering surfaced[1]. Capture as
close

docs: Explain the desired position of function attributes

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 <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Remove the Microsoft rhetoric

There is no need to need to name Microsoft. The point is clear without that context.

Signed-off-by: Yorick de Wid <[email protected]>
Link: https://lore.kernel.or

docs: Remove the Microsoft rhetoric

There is no need to need to name Microsoft. The point is clear without that context.

Signed-off-by: Yorick de Wid <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

coding-style.rst: Avoid comma statements

Commas are not how statements are terminated.
Always use semicolons and braces if necessary.

Signed-off-by: Joe Perches <[email protected]>
Link: https://lore

coding-style.rst: Avoid comma statements

Commas are not how statements are terminated.
Always use semicolons and braces if necessary.

Signed-off-by: Joe Perches <[email protected]>
Link: https://lore.kernel.org/r/2a97b738bba335434461a5a918053a49c1fb6af4.1598331148.git.joe@perches.com
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

CodingStyle: Inclusive Terminology

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 black

CodingStyle: Inclusive Terminology

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 <[email protected]>
Acked-by: Dave Airlie <[email protected]>
Acked-by: SeongJae Park <[email protected]>
Acked-by: Christian Brauner <[email protected]>
Acked-by: James Bottomley <[email protected]>
Acked-by: Daniel Vetter <[email protected]>
Acked-by: Andy Lutomirski <[email protected]>
Acked-by: Laura Abbott <[email protected]>
Acked-by: Gustavo A. R. Silva <[email protected]>
Reviewed-by: Matthias Brugger <[email protected]>
Reviewed-by: Mark Brown <[email protected]>
Signed-off-by: Stephen Hemminger <[email protected]>
Signed-off-by: Theodore Ts'o <[email protected]>
Signed-off-by: Shuah Khan <[email protected]>
Signed-off-by: Dan Carpenter <[email protected]>
Signed-off-by: Kees Cook <[email protected]>
Signed-off-by: Olof Johansson <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Signed-off-by: Chris Mason <[email protected]>
Signed-off-by: Greg Kroah-Hartman <[email protected]>
Signed-off-by: Dan Williams <[email protected]>

show more ...

Replace HTTP links with HTTPS ones: Documentation/process

Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.

Deterministic al

Replace HTTP links with HTTPS ones: Documentation/process

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 <[email protected]>
Acked-by: Miguel Ojeda <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation/CodingStyle: Fix duplicate "are" typo

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

Documentation/CodingStyle: Fix duplicate "are" typo

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 <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

checkpatch/coding-style: deprecate 80-column warning

Yes, staying withing 80 columns is certainly still _preferred_. But
it's not the hard limit that the checkpatch warnings imply, and other
concer

checkpatch/coding-style: deprecate 80-column warning

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 <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

Documentation: bring process docs up to date

The guide to the kernel dev process documentation, for example, contains
references to older kernels and their timelines. In addition, one of the
"long t

Documentation: bring process docs up to date

The guide to the kernel dev process documentation, for example, contains
references to older kernels and their timelines. In addition, one of the
"long term support kernels" listed have since reached EOL, and a new one
has been named. This patch brings information/tables up to date.

Additionally, some very trivial grammatical errors, unclear sentences,
and potentially unsavory diction have been edited.

Signed-off-by: Tony Fischetti <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

treewide: Use sizeof_field() macro

Replace all the occurrences of FIELD_SIZEOF() with sizeof_field() except
at places where these are defined. Later patches will remove the unused
definition of FIEL

treewide: Use sizeof_field() macro

Replace all the occurrences of FIELD_SIZEOF() with sizeof_field() except
at places where these are defined. Later patches will remove the unused
definition of FIELD_SIZEOF().

This patch is generated using following script:

EXCLUDE_FILES="include/linux/stddef.h|include/linux/kernel.h"

git grep -l -e "\bFIELD_SIZEOF\b" | while read file;
do

if [[ "$file" =~ $EXCLUDE_FILES ]]; then
continue
fi
sed -i -e 's/\bFIELD_SIZEOF\b/sizeof_field/g' $file;
done

Signed-off-by: Pankaj Bharadiya <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Co-developed-by: Kees Cook <[email protected]>
Signed-off-by: Kees Cook <[email protected]>
Acked-by: David Miller <[email protected]> # for net

show more ...

Documentation/process: Add fallthrough pseudo-keyword

Describe the fallthrough pseudo-keyword.

Convert the coding-style.rst example to the keyword style.
Add description and links to deprecated.rst

Documentation/process: Add fallthrough pseudo-keyword

Describe the fallthrough pseudo-keyword.

Convert the coding-style.rst example to the keyword style.
Add description and links to deprecated.rst.

Miguel Ojeda comments on the eventual [[fallthrough]] syntax:
"Note that C17/C18 does not have [[fallthrough]].

C++17 introduced it, as it is mentioned above. I would keep the
__attribute__((fallthrough)) -> [[fallthrough]] change you did,
though, since that is indeed the standard syntax (given the paragraph
references C++17).

I was told by Aaron Ballman (who is proposing them for C) that it is
more or less likely that it becomes standardized in C2x. However, it
is still not added to the draft (other attributes are already,
though). See N2268 and N2269:

http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2268.pdf (fallthrough)
http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2269.pdf (attributes in general)"

Signed-off-by: Joe Perches <[email protected]>
Acked-by: Nick Desaulniers <[email protected]>
Signed-off-by: Linus Torvalds <[email protected]>

show more ...

docs: kbuild: convert docs to ReST and rename to *.rst

The kbuild documentation clearly shows that the documents
there are written at different times: some use markdown,
some use their own peculiar

docs: kbuild: convert docs to ReST and rename to *.rst

The kbuild documentation clearly shows that the documents
there are written at different times: some use markdown,
some use their own peculiar logic to split sections.

Convert everything to ReST without affecting too much
the author's style and avoiding adding uneeded markups.

The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

coding-style.rst: Generic alloc functions do not need OOM logging

Generic allocation functions already emit a dump_stack()
so additional error logging isn't useful.

Document it as such and add a re

coding-style.rst: Generic alloc functions do not need OOM logging

Generic allocation functions already emit a dump_stack()
so additional error logging isn't useful.

Document it as such and add a reference to the allocation
API.

Signed-off-by: Joe Perches <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

coding-style: Clarify the expectations around bool

There has been some confusion since checkpatch started warning about bool
use in structures, and people have been avoiding using it.

Many people f

coding-style: Clarify the expectations around bool

There has been some confusion since checkpatch started warning about bool
use in structures, and people have been avoiding using it.

Many people feel there is still a legitimate place for bool in structures,
so provide some guidance on bool usage derived from the entire thread that
spawned the checkpatch warning.

Link: https://lkml.kernel.org/r/CA+55aFwVZk1OfB9T2v014PTAKFhtVan_Zj2dOjnCy3x6E4UJfA@mail.gmail.com
Signed-off-by: Joe Perches <[email protected]>
Acked-by: Joe Perches <[email protected]>
Reviewed-by: Bart Van Assche <[email protected]>
Acked-by: Jani Nikula <[email protected]>
Reviewed-by: Joey Pabalinas <[email protected]>
Signed-off-by: Jason Gunthorpe <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation: fix coding-style.rst Sphinx warning

Fix Sphinx warning in coding-style.rst:

Documentation/process/coding-style.rst:446: WARNING: Inline interpreted text or phrase reference start-str

Documentation: fix coding-style.rst Sphinx warning

Fix Sphinx warning in coding-style.rst:

Documentation/process/coding-style.rst:446: WARNING: Inline interpreted text or phrase reference start-string without end-string.

Signed-off-by: Randy Dunlap <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...