mirror of
https://gitee.com/bianbu-linux/linux-6.6
synced 2025-04-24 14:07:52 -04:00
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 ...
This commit is contained in:
Linus Torvalds
commit
d6a24d0640
40 changed files with 490 additions and 778 deletions
|
|
@ -13,7 +13,7 @@ and NOT read it. Burn them, it's a great symbolic gesture.
|
|||
Anyway, here goes:
|
||||
|
||||
|
||||
Chapter 1: Indentation
|
||||
Chapter 1: Indentation
|
||||
|
||||
Tabs are 8 characters, and thus indentations are also 8 characters.
|
||||
There are heretic movements that try to make indentations 4 (or even 2!)
|
||||
|
|
@ -56,7 +56,6 @@ instead of "double-indenting" the "case" labels. E.g.:
|
|||
break;
|
||||
}
|
||||
|
||||
|
||||
Don't put multiple statements on a single line unless you have
|
||||
something to hide:
|
||||
|
||||
|
|
@ -156,25 +155,25 @@ comments on.
|
|||
|
||||
Do not unnecessarily use braces where a single statement will do.
|
||||
|
||||
if (condition)
|
||||
action();
|
||||
if (condition)
|
||||
action();
|
||||
|
||||
and
|
||||
|
||||
if (condition)
|
||||
do_this();
|
||||
else
|
||||
do_that();
|
||||
if (condition)
|
||||
do_this();
|
||||
else
|
||||
do_that();
|
||||
|
||||
This does not apply if only one branch of a conditional statement is a single
|
||||
statement; in the latter case use braces in both branches:
|
||||
|
||||
if (condition) {
|
||||
do_this();
|
||||
do_that();
|
||||
} else {
|
||||
otherwise();
|
||||
}
|
||||
if (condition) {
|
||||
do_this();
|
||||
do_that();
|
||||
} else {
|
||||
otherwise();
|
||||
}
|
||||
|
||||
3.1: Spaces
|
||||
|
||||
|
|
@ -186,8 +185,11 @@ although they are not required in the language, as in: "sizeof info" after
|
|||
"struct fileinfo info;" is declared).
|
||||
|
||||
So use a space after these keywords:
|
||||
|
||||
if, switch, case, for, do, while
|
||||
|
||||
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
|
||||
|
||||
s = sizeof(struct file);
|
||||
|
||||
Do not add spaces around (inside) parenthesized expressions. This example is
|
||||
|
|
@ -209,12 +211,15 @@ such as any of these:
|
|||
= + - < > * / % | & ^ <= >= == != ? :
|
||||
|
||||
but no space after unary operators:
|
||||
|
||||
& * + - ~ ! sizeof typeof alignof __attribute__ defined
|
||||
|
||||
no space before the postfix increment & decrement unary operators:
|
||||
|
||||
++ --
|
||||
|
||||
no space after the prefix increment & decrement unary operators:
|
||||
|
||||
++ --
|
||||
|
||||
and no space around the '.' and "->" structure member operators.
|
||||
|
|
@ -268,13 +273,11 @@ See chapter 6 (Functions).
|
|||
Chapter 5: Typedefs
|
||||
|
||||
Please don't use things like "vps_t".
|
||||
|
||||
It's a _mistake_ to use typedef for structures and pointers. When you see a
|
||||
|
||||
vps_t a;
|
||||
|
||||
in the source, what does it mean?
|
||||
|
||||
In contrast, if it says
|
||||
|
||||
struct virtual_container *a;
|
||||
|
|
@ -372,11 +375,11 @@ In source files, separate functions with one blank line. If the function is
|
|||
exported, the EXPORT* macro for it should follow immediately after the closing
|
||||
function brace line. E.g.:
|
||||
|
||||
int system_is_up(void)
|
||||
{
|
||||
return system_state == SYSTEM_RUNNING;
|
||||
}
|
||||
EXPORT_SYMBOL(system_is_up);
|
||||
int system_is_up(void)
|
||||
{
|
||||
return system_state == SYSTEM_RUNNING;
|
||||
}
|
||||
EXPORT_SYMBOL(system_is_up);
|
||||
|
||||
In function prototypes, include parameter names with their data types.
|
||||
Although this is not required by the C language, it is preferred in Linux
|
||||
|
|
@ -405,34 +408,34 @@ The rationale for using gotos is:
|
|||
modifications are prevented
|
||||
- saves the compiler work to optimize redundant code away ;)
|
||||
|
||||
int fun(int a)
|
||||
{
|
||||
int result = 0;
|
||||
char *buffer;
|
||||
int fun(int a)
|
||||
{
|
||||
int result = 0;
|
||||
char *buffer;
|
||||
|
||||
buffer = kmalloc(SIZE, GFP_KERNEL);
|
||||
if (!buffer)
|
||||
return -ENOMEM;
|
||||
buffer = kmalloc(SIZE, GFP_KERNEL);
|
||||
if (!buffer)
|
||||
return -ENOMEM;
|
||||
|
||||
if (condition1) {
|
||||
while (loop1) {
|
||||
...
|
||||
if (condition1) {
|
||||
while (loop1) {
|
||||
...
|
||||
}
|
||||
result = 1;
|
||||
goto out_buffer;
|
||||
}
|
||||
result = 1;
|
||||
goto out_buffer;
|
||||
...
|
||||
out_buffer:
|
||||
kfree(buffer);
|
||||
return result;
|
||||
}
|
||||
...
|
||||
out_buffer:
|
||||
kfree(buffer);
|
||||
return result;
|
||||
}
|
||||
|
||||
A common type of bug to be aware of it "one err bugs" which look like this:
|
||||
|
||||
err:
|
||||
kfree(foo->bar);
|
||||
kfree(foo);
|
||||
return ret;
|
||||
err:
|
||||
kfree(foo->bar);
|
||||
kfree(foo);
|
||||
return ret;
|
||||
|
||||
The bug in this code is that on some exit paths "foo" is NULL. Normally the
|
||||
fix for this is to split it up into two error labels "err_bar:" and "err_foo:".
|
||||
|
|
@ -503,9 +506,9 @@ values. To do the latter, you can stick the following in your .emacs file:
|
|||
(defun c-lineup-arglist-tabs-only (ignored)
|
||||
"Line up argument lists by tabs, not spaces"
|
||||
(let* ((anchor (c-langelem-pos c-syntactic-element))
|
||||
(column (c-langelem-2nd-pos c-syntactic-element))
|
||||
(offset (- (1+ column) anchor))
|
||||
(steps (floor offset c-basic-offset)))
|
||||
(column (c-langelem-2nd-pos c-syntactic-element))
|
||||
(offset (- (1+ column) anchor))
|
||||
(steps (floor offset c-basic-offset)))
|
||||
(* (max steps 1)
|
||||
c-basic-offset)))
|
||||
|
||||
|
|
@ -612,7 +615,7 @@ have a reference count on it, you almost certainly have a bug.
|
|||
|
||||
Names of macros defining constants and labels in enums are capitalized.
|
||||
|
||||
#define CONSTANT 0x12345
|
||||
#define CONSTANT 0x12345
|
||||
|
||||
Enums are preferred when defining several related constants.
|
||||
|
||||
|
|
@ -623,28 +626,28 @@ Generally, inline functions are preferable to macros resembling functions.
|
|||
|
||||
Macros with multiple statements should be enclosed in a do - while block:
|
||||
|
||||
#define macrofun(a, b, c) \
|
||||
do { \
|
||||
if (a == 5) \
|
||||
do_this(b, c); \
|
||||
} while (0)
|
||||
#define macrofun(a, b, c) \
|
||||
do { \
|
||||
if (a == 5) \
|
||||
do_this(b, c); \
|
||||
} while (0)
|
||||
|
||||
Things to avoid when using macros:
|
||||
|
||||
1) macros that affect control flow:
|
||||
|
||||
#define FOO(x) \
|
||||
do { \
|
||||
if (blah(x) < 0) \
|
||||
return -EBUGGERED; \
|
||||
} while(0)
|
||||
#define FOO(x) \
|
||||
do { \
|
||||
if (blah(x) < 0) \
|
||||
return -EBUGGERED; \
|
||||
} while(0)
|
||||
|
||||
is a _very_ bad idea. It looks like a function call but exits the "calling"
|
||||
function; don't break the internal parsers of those who will read the code.
|
||||
|
||||
2) macros that depend on having a local variable with a magic name:
|
||||
|
||||
#define FOO(val) bar(index, val)
|
||||
#define FOO(val) bar(index, val)
|
||||
|
||||
might look like a good thing, but it's confusing as hell when one reads the
|
||||
code and it's prone to breakage from seemingly innocent changes.
|
||||
|
|
@ -656,8 +659,8 @@ bite you if somebody e.g. turns FOO into an inline function.
|
|||
must enclose the expression in parentheses. Beware of similar issues with
|
||||
macros using parameters.
|
||||
|
||||
#define CONSTANT 0x4000
|
||||
#define CONSTEXP (CONSTANT | 3)
|
||||
#define CONSTANT 0x4000
|
||||
#define CONSTEXP (CONSTANT | 3)
|
||||
|
||||
5) namespace collisions when defining local variables in macros resembling
|
||||
functions:
|
||||
|
|
@ -809,11 +812,11 @@ you should use, rather than explicitly coding some variant of them yourself.
|
|||
For example, if you need to calculate the length of an array, take advantage
|
||||
of the macro
|
||||
|
||||
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
|
||||
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
|
||||
|
||||
Similarly, if you need to calculate the size of some structure member, use
|
||||
|
||||
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
|
||||
#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
|
||||
|
||||
There are also min() and max() macros that do strict type checking if you
|
||||
need them. Feel free to peruse that header file to see what else is already
|
||||
|
|
@ -826,19 +829,19 @@ Some editors can interpret configuration information embedded in source files,
|
|||
indicated with special markers. For example, emacs interprets lines marked
|
||||
like this:
|
||||
|
||||
-*- mode: c -*-
|
||||
-*- mode: c -*-
|
||||
|
||||
Or like this:
|
||||
|
||||
/*
|
||||
Local Variables:
|
||||
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
|
||||
End:
|
||||
*/
|
||||
/*
|
||||
Local Variables:
|
||||
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
|
||||
End:
|
||||
*/
|
||||
|
||||
Vim interprets markers that look like this:
|
||||
|
||||
/* vim:set sw=8 noet */
|
||||
/* vim:set sw=8 noet */
|
||||
|
||||
Do not include any of these in source files. People have their own personal
|
||||
editor configurations, and your source files should not override them. This
|
||||
|
|
@ -915,9 +918,9 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines),
|
|||
place a comment after the #endif on the same line, noting the conditional
|
||||
expression used. For instance:
|
||||
|
||||
#ifdef CONFIG_SOMETHING
|
||||
...
|
||||
#endif /* CONFIG_SOMETHING */
|
||||
#ifdef CONFIG_SOMETHING
|
||||
...
|
||||
#endif /* CONFIG_SOMETHING */
|
||||
|
||||
|
||||
Appendix I: References
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue