Commit Graph

40 Commits

Author SHA1 Message Date
Linus Torvalds d6a24d0640 The documentation tree update for 4.1. Numerous fixes, the overdue removal
of the i2o docs, some new Chinese translations, and, hopefully, the README
 fix that will end the flow of identical patches to that file.
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1
 
 iQIcBAABAgAGBQJVMOeZAAoJEI3ONVYwIuV6/1YQAJwcVvd3ow6cMKuf8eRKMgjd
 crJUdRF9FTwyY21SRHBaonyiKOthnVedOUYnFQ5Z7jbII0EohJ//72nW0pQrHoGi
 0avkbM+ZAZzXfd/paOiZ5HtYkc8Bdc70mPU1fzfexnPm/JACOGznxQsob05r6/sT
 W1GyJcrLlp4uPrba9rhAdGtaa+mEFrt4SVCI+odXOnxQ/KOZSIu1n1F3bSSvL9zV
 YMBgRrCso+Cdtuhe4N3O1jsVy/hyOnvtqcUgwlD4VzElsshKvxdxHn47yeeWK1qI
 zZfGTv+q5QI/eZgIhBIrBpdCafgLipAmNZhX+M76xeNydhfhp60VizRgKfb6JiW1
 M+nLSnv2vxh4wgkJs7yWgW+8TJ0eCF/w2P/mBi6hDXuIul9gwgmNk+EZ7LONSh+2
 l3PV/dyswNs04qbYgFt2rygsxcg79RRbD54zi+S/3NU38/gh7nlidASKmNu1boG/
 KdZx3F0rmX/xQu4aQ5nIQl2N7sVLkEec+oN+ukQGyBTLVHkfAK06Z4EWUeYmmBKh
 M6gqRY5XJMtCm8D5bons/yZmwmpdZFZMxFGJ4enUwrfsJ8FQ8qy/KmFqF8SojGWQ
 HYs4ZUptz6SYa7K0Txe/q0pkrW+doy7t/Bz+JBNNdG7eLeHIpKhSqSlLIdB7MRKw
 NFA8a4PdgdMpf+Zr4bRy
 =LDbk
 -----END PGP SIGNATURE-----

Merge tag 'docs-for-linus' of git://git.lwn.net/linux-2.6

Pull documentation updates from Jonathan Corbet:
 "Numerous fixes, the overdue removal of the i2o docs, some new Chinese
  translations, and, hopefully, the README fix that will end the flow of
  identical patches to that file"

* tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (34 commits)
  Documentation/memcg: update memcg/kmem status
  Documentation: blackfin: Makefile: Typo building issue
  Documentation/vm/pagemap.txt: correct location of page-types tool
  Documentation/memory-barriers.txt: typo fix
  doc: Add guest_nice column to example output of `cat /proc/stat'
  Documentation/kernel-parameters: Move "eagerfpu" to its right place
  Documentation: gpio: Update ACPI part of the document to mention _DSD
  docs/completion.txt: Various tweaks and corrections
  doc: completion: context, scope and language fixes
  Documentation:Update Documentation/zh_CN/arm64/memory.txt
  Documentation:Update Documentation/zh_CN/arm64/booting.txt
  Documentation: Chinese translation of arm64/legacy_instructions.txt
  DocBook media: fix broken EIA hyperlink
  Documentation: tweak the maintainers entry
  README: Change gzip/bzip2 to xz compression format
  README: Update version number reference
  doc:pci: Fix typo in Documentation/PCI
  Documentation: drm: Use '->' when describing access through pointers.
  Documentation: Remove mentioning of block barriers
  Documentation/email-clients.txt: Fix one grammar mistake, add extra info about TB
  ...
2015-04-18 11:10:49 -04:00
Bartosz Golaszewski f2027543b9 documentation: update CodingStyle on local variables naming in macros
Describe proper naming convention for local variables in macros
resembling functions.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Cc: Guenter Roeck <linux@roeck-us.net>
Cc: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2015-04-17 09:03:54 -04:00
Pavel Kretov 09677e0ff8 Documentation/CodingStyle: improve text layout
Try to make coding style documentation look a bit more readable and
consistent with the following:

 - indent every code example in C to first tab-stop;
 - surround every code example with empty lines, both top and bottom;
 - remove empty lines where text looked way too spare;
 - do not indent examples in elisp and kconfig;
 - do not do any non-whitespace changes.

Signed-off-by: Pavel Kretov <firegurafiku@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-02-27 15:02:02 -07:00
Pavel Kretov 696156f03f Documentation/CodingStyle: fix tab-spaces mixture
Coding style description has a irregular mixture of tabs and spaces in two
places which is bad by any means and can possibly hurt somebody's sense
of beauty.

Signed-off-by: Pavel Kretov <firegurafiku@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-02-27 15:01:40 -07:00
Alison Chaiken 039d19a143 CodingStyle: enable emacs display of trailing whitespace
Suggest to developers who use emacs that they turn on the
instantaneous trailing-whitespace warning feature.

Signed-off-by: Alison Chaiken <alison_chaiken@mentor.com>
[jc: untabified to match its surroundings]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2015-01-28 12:05:46 -07:00
Dan Carpenter ea04036032 CodingStyle: add some more error handling guidelines
I added a paragraph on choosing label names, and updated the example
code to use a better label name.  I also cleaned up the example code to
more modern style by moving the allocation out of the initializer and
changing the NULL check.

Perhaps the most common type of error handling bug in the kernel is "one
err bugs".  CodingStyle already says that we should "avoid nesting" by
using error labels and one err style error handling tends to have
multiple indent levels, so this was already bad style.  But I've added a
new paragraph explaining how to avoid one err bugs by using multiple
error labels which is, hopefully, more clear.

Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>
Acked-by: Julia Lawall <julia.lawall@lip6.fr>
[jc: added GFP_KERNEL to kmalloc() call]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2014-12-02 08:55:32 -05:00
Josh Triplett 21228a1868 CodingStyle: Add a chapter on conditional compilation
Document several common practices and conventions regarding conditional
compilation, most notably the preference for ifdefs in headers rather
than .c files.

Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Acked-by: Geert Uytterhoeven <geert@linux-m68k.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2014-11-03 11:46:02 -05:00
Raymond L. Rivera 7c18fd786d CodingStyle: fix a minor typo
There was a minor typo in the CodingStyle document where the word 'section'
had been spelled as 'secton'.

Signed-off-by: Raymond L. Rivera <ray.l.rivera@gmail.com>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
2014-08-26 09:35:54 +02:00
Dan Streetman 6e099f557d Documentation: expand/clarify debug documentation
The pr_debug() and related debug print macros all differ from the normal
pr_XXX() macros, in that the normal ones print unconditionally, while
the debug macros are compiled out unless DEBUG is defined or
CONFIG_DYNAMIC_DEBUG is set.  This isn't obvious, and the only way to
find this out is either to review the actual printk.h code or to read
CodingStyle, and the message there doesn't highlight the fact.

Change Documentation/CodingStyle to clearly indicate that pr_debug() and
related debug printing macros behave differently than all other pr_XXX()
macros, and attempt to clarify when and where the different debug
printing methods might be used.

Add short comment to printk.h above the pr_XXX() macros indicating that
while these macros print unconditionally, pr_debug() does not.

Signed-off-by: Dan Streetman <ddstreet@ieee.org>
Cc: Joe Perches <joe@perches.com>
Cc: Fabian Frederick <fabf@skynet.be>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2014-06-04 16:54:17 -07:00
Dan Carpenter b57a0505e7 Documentation/CodingStyle: allow multiple return statements per function
A surprising number of newbies interpret this section to mean that only
one return statement is allowed per function.  Part of the problem is that
the "one return statement per function" rule is an actual style guideline
that people are used to from other projects.

Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>
Cc: Eduardo Valentin <eduardo.valentin@ti.com>
Cc: Rob Landley <rob@landley.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2013-07-03 16:08:01 -07:00
Kees Cook 0335cb469a Documentation: remove depends on CONFIG_EXPERIMENTAL
The CONFIG_EXPERIMENTAL config item has not carried much meaning for a
while now and is almost always enabled by default. As agreed during the
Linux kernel summit, remove it from any "depends on" lines in Kconfigs.

CC: Rob Landley <rob@landley.net>
CC: Jiri Kosina <jkosina@suse.cz>
CC: Masanari Iida <standby24x7@gmail.com>
CC: Jason Wessel <jason.wessel@windriver.com>
CC: Richard L Maliszewski <richard.l.maliszewski@intel.com>
CC: Gang Wei <gang.wei@intel.com>
CC: Shane Wang <shane.wang@intel.com>
CC: Harry Wei <harryxiyou@gmail.com>
Signed-off-by: Kees Cook <keescook@chromium.org>
Acked-by: Jason Wessel <jason.wessel@windriver.com>
2013-01-11 11:38:03 -08:00
Joe Perches c4ff1b5f8b CodingStyle: add networking specific block comment style
The block comment style in net/ and drivers/net is non-standard.
Document it.

Signed-off-by: Joe Perches <joe@perches.com>
Cc: "Allan, Bruce W" <bruce.w.allan@intel.com>
Cc: Andy Whitcroft <apw@canonical.com>
Cc: David Miller <davem@davemloft.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2012-10-06 03:04:59 +09:00
Xi Wang 15837294d4 CodingStyle: add kmalloc_array() to memory allocators
Add the new kmalloc_array() to the list of general-purpose memory
allocators in chapter 14.

Signed-off-by: Xi Wang <xi.wang@gmail.com>
Acked-by: Jesper Juhl <jj@chaosbits.net>
Acked-by: Pekka Enberg <penberg@kernel.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2012-05-31 17:49:26 -07:00
Josh Triplett 9a7c48b7c3 Documentation: CodingStyle: add inline assembly guidelines
Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2012-03-30 16:03:15 -07:00
Antonio Ospite b218ab0a5a Documentation: update CodingStyle use of braces
After commit 38829dc9d7 ("Documentation/CodingStyle: flesh out if-else
examples") highlight that if _only_one_ branch of a conditional
statement is a single statement, then braces are to be used on both
branches.

Signed-off-by: Antonio Ospite <ospite@studenti.unina.it>
Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2011-11-04 12:01:47 -07:00
Josh Triplett 6f76b6fcaa CodingStyle: Document the exception of not splitting user-visible strings, for grepping
Patch reviewers now recommend not splitting long user-visible strings,
such as printk messages, even if they exceed 80 columns.  This avoids
breaking grep.  However, that recommendation did not actually appear
anywhere in Documentation/CodingStyle.

See, for example, the thread at
  http://news.gmane.org/find-root.php?message_id=%3c1312215262.11635.15.camel%40Joe%2dLaptop%3e

Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2011-08-06 11:59:07 -07:00
Jesper Juhl 316b379988 Documentation: update CodingStyle memory allocators
The list of available general purpose memory allocators in
Documentation/CodingStyle chapter 14 is incomplete. This patch adds
the missing vzalloc() to the list.

Signed-off-by: Jesper Juhl <jj@chaosbits.net>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2011-07-06 13:17:51 -07:00
Harry Wei 38829dc9d7 Documentation/CodingStyle: flesh out if-else examples
There is a missing case for "Chapter 3: Placing Braces and Spaces".  We
often know we should not use braces where a single statement.  The first
case is:

	if (condition)
		action();

Another case is:

	if (condition)
		do_this();
	else
		do_that();

However, I can not find a description of the second case.

Signed-off-by: Harry Wei <harryxiyou@gmail.com>
Cc: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2011-03-22 17:44:16 -07:00
Roland Kammerer aa4862c38b Documentation: update header filename in CodingStyle
pr_info() and pr_debug() are in linux/printk.h, not linux/kernel.h.
Last updated is unnecessary, we have git for that.

Signed-off-by: Roland Kammerer <dev.rck@gmail.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Harry Wei <harryxiyou@gmail.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2011-03-16 10:47:03 -07:00
Martin Olsson 19af5cdb7c trivial: fix typo milisecond/millisecond for documentation and source comments.
Signed-off-by: Martin Olsson <martin@minimum.se>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
2009-06-12 18:01:46 +02:00
Dan Carpenter 70221395ba fix emacs indenting howto filename expansion
I don't think emacs understands tilde expansion, so use
"expand-file-name" to do that.

Signed-off-by: Dan Carpenter <error27@gmail.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-01-29 18:19:29 -08:00
Teemu Likonen 0acbc6c651 Documentation: update CodingStyle tips for Emacs users
With the previous Emacs tips example the kernel style was made available
for files in the kernel-tree only. This patch updates the tip to add a
separate cc-mode indent style ("linux-tabs-only"). This makes it easy to
switch between different indent styles and also makes the kernel style
easily available for any filetype mode (c++, awk, ...) that is managed
by the Emacs cc-mode.

Signed-off-by: Teemu Likonen <tlikonen@iki.fi>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2009-01-29 18:19:29 -08:00
Johannes Weiner a7f371e54f documentation: update CodingStyle tips for Emacs users
Describe a setup that integrates better with Emacs' cc-mode and also fixes
up the alignment of continuation lines to really only use tabs.

Signed-off-by: Johannes Weiner <hannes@saeurebad.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2008-07-25 10:53:29 -07:00
Alan Cox dff4982f5c CodingStyle: relax the 80-cole rule
I would suggest this change to make CodingStyle properly reflect the style
used by the kernel, rather than the current wording which is wishful
thinking and misleading, and comes from the same school of thought that
gets off on prescriptive grammar, latin and comp.std.c

Signed-off-by: Alan Cox <alan@redhat.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-10-17 08:42:55 -07:00
David Brownell 6b09448ab8 dev_vdbg() documentation
Update CodingStyle to talk about "-DDEBUG" message conventions and the
new "-DVERBOSE_DEBUG" convention.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
2007-07-18 15:49:50 -07:00
Josh Triplett 4e7bd66318 CodingStyle: add information about editor modelines
I recently received a patch including a file that had a vim modeline,
and I realized that nothing specifically proscribed that practice.

Signed-off-by: Josh Triplett <josh@freedesktop.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-07-16 09:05:50 -07:00
Josh Triplett a923fd6ae7 CodingStyle: add information about trailing whitespace
Signed-off-by: Josh Triplett <josh@kernel.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-07-16 09:05:50 -07:00
Robert P. J. Day 6754bb4de9 Documentation: fix the explanation of Kconfig files
Fix the obvious errors in the explanation of Kconfig files.

Signed-off-by: Robert P. J. Day <rpjday@mindspring.com>
Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-05-23 20:14:12 -07:00
Jesper Juhl 53ab97a1c1 Fix chapter reference in CodingStyle
commit 226a6b84aa renumbered Chapter 11 in
Documentation/CodingStyle to Chapter 12, but it didn't update the reference
to that chapter further down in the file.  This patch corrects the chapter
reference.

Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-05-08 11:15:13 -07:00
Oliver Neukum e659ba4a0d CodingStyle: start flamewar about use of braces
Signed-off-by: Oliver Neukum <oneukum@suse.de>
Cc: Tilman Schmidt <tilman@imap.cc>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
2007-05-08 11:15:12 -07:00
Robert P. J. Day 58637ec90b [PATCH] Add a new section to CodingStyle, promoting include/linux/kernel.h
Add a new section to the CodingStyle file, encouraging people not to
re-invent available kernel macros such as ARRAY_SIZE(), FIELD_SIZEOF(),
min() and max(), among others.

Signed-off-by: Robert P. J. Day <rpjday@mindspring.com>
Acked-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Jan Engelhardt <jengelh@gmx.de>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-12-22 08:55:49 -08:00
Randy Dunlap b3fc9941fb [PATCH] CodingStyle updates
Add some kernel coding style comments, mostly pulled from emails
by Andrew Morton, Jesper Juhl, and Randy Dunlap.

- add paragraph on switch/case indentation (with fixes)
- add paragraph on multiple-assignments
- add more on Braces
- add section on Spaces; add typeof, alignof, & __attribute__ with sizeof;
  add more on postfix/prefix increment/decrement operators
- add paragraph on function breaks in source files; add info on
  function prototype parameter names
- add paragraph on EXPORT_SYMBOL placement
- add section on /*-comment style, long-comment style, and data
  declarations and comments
- correct some chapter number references that were missed when
  chapters were renumbered

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Jesper Juhl <jesper.juhl@gmail.com>
Acked-by: Jan Engelhardt <jengelh@gmx.de>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-12-10 09:55:40 -08:00
Alan Stern c16a02d6f5 [PATCH] Add section on function return values to CodingStyle
This patch (as776) adds a new chapter to Documentation/CodingStyle,
explaining the circumstances under which a function should return 0 for
failure and non-zero for success as opposed to a negative error code for
failure and 0 for success.

Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-09-29 09:18:22 -07:00
Randy Dunlap 226a6b84aa [PATCH] CodingStyle: add typedefs chapter
Add a chapter on typedefs, copied from an email from Linus to lkml on Feb.
3, 2006.  (Subject: Re: [RFC][PATCH 1/5] Virtualization/containers:
startup)

Signed-off-by: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-06-23 07:43:08 -07:00
Jesper Juhl dc3d28d02e [PATCH] CodingStyle correction
Signed-off-by: Jesper Juhl <jesper.juhl@gmail.com>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-01-10 08:01:52 -08:00
Arjan van de Ven a771f2b82a [PATCH] Add a section about inlining to Documentation/CodingStyle
Adds a bit of text to Documentation/Codingstyle to state that inlining
everything "just because" is a bad idea

Signed-off-by: Arjan van de Ven <arjan@infradead.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-01-08 20:14:06 -08:00
Xose Vazquez Perez 5b0ed2c64d [PATCH] docs: updated some code docs
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2006-01-08 20:13:53 -08:00
Pekka J Enberg af4e5a218e [PATCH] CodingStyle: memory allocation
This patch adds a new chapter on memory allocation to
Documentation/CodingStyle.

Signed-off-by: Pekka Enberg <penberg@cs.helsinki.fi>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-09-17 11:50:02 -07:00
Pekka J Enberg e776eba0fe [PATCH] Add kerneldoc reference to CodingStyle
Signed-off-by: Pekka Enberg <penberg@cs.helsinki.fi>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>
2005-09-10 10:06:28 -07:00
Linus Torvalds 1da177e4c3 Linux-2.6.12-rc2
Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.

Let it rip!
2005-04-16 15:20:36 -07:00