Commit Graph

20 Commits

Author SHA1 Message Date
Dan Williams a5f526ecb0 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 <rdunlap@infradead.org>
Acked-by: Dave Airlie <airlied@redhat.com>
Acked-by: SeongJae Park <sjpark@amazon.de>
Acked-by: Christian Brauner <christian.brauner@ubuntu.com>
Acked-by: James Bottomley <James.Bottomley@HansenPartnership.com>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Acked-by: Andy Lutomirski <luto@kernel.org>
Acked-by: Laura Abbott <laura@labbott.name>
Acked-by: Gustavo A. R. Silva <gustavoars@kernel.org>
Reviewed-by: Matthias Brugger <matthias.bgg@gmail.com>
Reviewed-by: Mark Brown <broonie@kernel.org>
Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Olof Johansson <olof@lixom.net>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Chris Mason <clm@fb.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Dan Williams <dan.j.williams@intel.com>
2020-07-03 23:54:35 -07:00
Geert Uytterhoeven 77d22a4388 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: bdc48fa11e ("checkpatch/coding-style: deprecate 80-column warning")
Signed-off-by: Geert Uytterhoeven <geert@linux-m68k.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2020-06-10 10:38:21 -07:00
Joe Perches bdc48fa11e 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 <joe@perches.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2020-05-31 11:00:42 -07:00
Tony Fischetti fb0e0ffe7f 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 <tony.fischetti@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-02-19 04:03:54 -07:00
Pankaj Bharadiya c593642c8b 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 <pankaj.laxminarayan.bharadiya@intel.com>
Link: https://lore.kernel.org/r/20190924105839.110713-3-pankaj.laxminarayan.bharadiya@intel.com
Co-developed-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Kees Cook <keescook@chromium.org>
Acked-by: David Miller <davem@davemloft.net> # for net
2019-12-09 10:36:44 -08:00
Joe Perches b9918bdcac 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 <joe@perches.com>
Acked-by: Nick Desaulniers <ndesaulniers@google.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2019-10-11 09:26:05 -07:00
Mauro Carvalho Chehab cd238effef 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 <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-14 14:21:21 -06:00
Joe Perches bba757d857 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 <joe@perches.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-04-01 14:58:46 -06:00
Jason Gunthorpe 7967656ffb 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 <joe@perches.com>
Acked-by: Joe Perches <joe@perches.com>
Reviewed-by: Bart Van Assche <bvanassche@acm.org>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Reviewed-by: Joey Pabalinas <joeypabalinas@gmail.com>
Signed-off-by: Jason Gunthorpe <jgg@mellanox.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-01-20 19:07:39 -07:00
Randy Dunlap 7fbc258fea 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 <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-01-14 08:31:57 -07:00
Bart Van Assche 2fec7b3309 Documentation/CodingStyle: Use directory-local variables for emacs settings
In emacs 23.1 support for directory-local variables was added (see also
https://lists.gnu.org/archive/html/info-gnu-emacs/2009-07/msg00000.html).
Simplify the settings in coding-style.rst by using that feature.
Additionally, do not inherit any settings from emacs' linux coding style
to minimize dependencies on the version of emacs that is being used.

I have verified with several large and nontrivial kernel source files
that the new settings format code according to what checkpatch expects.

Signed-off-by: Bart Van Assche <bvanassche@acm.org>
Cc: Matthew Wilcox <willy@infradead.org>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Alison Chaiken <alison@she-devel.com>
Cc: Joe Perches <joe@perches.com>
Cc: Federico Vaga <federico.vaga@vaga.pv.it>
Cc: Geyslan G. Bem <geyslan@gmail.com>
Cc: Tiago Natel de Moura <tiago4orion@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-01-07 15:32:49 -07:00
Alexey Dobriyan 3fe5dbfef4 Documentation/process/coding-style.rst: don't use "extern" with function prototypes
`extern' with function prototypes makes lines longer and creates more
characters on the screen.

Do not bug people with checkpatch.pl warnings for now as fallout can be
devastating.

Link: http://lkml.kernel.org/r/20181101134153.GA29267@avx2
Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
Reviewed-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2019-01-04 13:13:45 -08:00
Federico Vaga f77af637f2 doc:process: add links where missing
Some documents are refering to others without links. With this
patch I add those missing links.

This patch affects only documents under process/ and labels where
necessary.

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-12-06 10:21:19 -07:00
Miguel Ojeda d4ef8d3ff0 clang-format: add configuration file
clang-format is a tool to format C/C++/...  code according to a set of
rules and heuristics.  Like most tools, it is not perfect nor covers
every single case, but it is good enough to be helpful.

In particular, it is useful for quickly re-formatting blocks of code
automatically, for reviewing full files in order to spot coding style
mistakes, typos and possible improvements.  It is also handy for sorting
``#includes``, for aligning variables and macros, for reflowing text and
other similar tasks.  It also serves as a teaching tool/guide for
newcomers.

The tool itself has been already included in the repositories of popular
Linux distributions for a long time.  The rules in this file are
intended for clang-format >= 4, which is easily available in most
distributions.

This commit adds the configuration file that contains the rules that the
tool uses to know how to format the code according to the kernel coding
style.  This gives us several advantages:

  * clang-format works out of the box with reasonable defaults;
    avoiding that everyone has to re-do the configuration.

  * Everyone agrees (eventually) on what is the most useful default
    configuration for most of the kernel.

  * If it becomes commonplace among kernel developers, clang-format
    may feel compelled to support us better. They already recognize
    the Linux kernel and its style in their documentation and in one
    of the style sub-options.

Some of clang-format's features relevant for the kernel are:

  * Uses clang's tooling support behind the scenes to parse and rewrite
    the code. It is not based on ad-hoc regexps.

  * Supports reasonably well the Linux kernel coding style.

  * Fast enough to be used at the press of a key.

  * There are already integrations (either built-in or third-party)
    for many common editors used by kernel developers (e.g. vim,
    emacs, Sublime, Atom...) that allow you to format an entire file
    or, more usefully, just your selection.

  * Able to parse unified diffs -- you can, for instance, reformat
    only the lines changed by a git commit.

  * Able to reflow text comments as well.

  * Widely supported and used by hundreds of developers in highly
    complex projects and organizations (e.g. the LLVM project itself,
    Chromium, WebKit, Google, Mozilla...). Therefore, it will be
    supported for a long time.

See more information about the tool at:

    https://clang.llvm.org/docs/ClangFormat.html
    https://clang.llvm.org/docs/ClangFormatStyleOptions.html

Link: http://lkml.kernel.org/r/20180318171632.qfkemw3mwbcukth6@gmail.com
Signed-off-by: Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Andy Whitcroft <apw@canonical.com>
Cc: Joe Perches <joe@perches.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2018-04-11 10:28:35 -07:00
Gary R Hook 1dbba2cf30 Documentation/CodingStyle: Add an example for braces
Add another example of required braces when using a compound statement in
a loop.

Signed-off-by: Gary R Hook <gary.hook@amd.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-03-21 09:17:09 -06:00
Ayan Shafqat 68f04b571d Doc: fix a markup error in coding-style.rst
The "\n\t" sequence needs to be quoted or it will not render properly.

[jc: no signoff from the author, but it's trivial]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-06-05 16:12:08 -06:00
Mauro Carvalho Chehab 1dc4bbf0b2 docs-rst: doc-guide: split the kernel-documentation.rst contents
Having the kernel-documentation at the topmost level doesn't
allow generating a separate PDF file for it. Also, makes harder
to add extra contents. So, place it on a sub-dir.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:22:04 -07:00
Masahiro Yamada beab6cb20c coding-style: fix mismatch of jump label name
Commit 865a1caa4b ("CodingStyle: Clarify and complete chapter 7")
renamed the label "out_buffer" to "out_free_buffer", but missed to
change this line.

Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-07 19:05:03 -07:00
Mauro Carvalho Chehab 8c27ceff36 docs: fix locations of several documents that got moved
The previous patch renamed several files that are cross-referenced
along the Kernel documentation. Adjust the links to point to
the right places.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-10-24 08:12:35 -02:00
Mauro Carvalho Chehab 186128f753 docs-rst: add documents to development-process
Add several documents to the development-process ReST book.

As we don't want renames, use symlinks instead, keeping those
documents on their original place.

Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-10-24 08:12:35 -02:00