K & R coding specification (Linux kernel coding Specification)

This is the Chinese version of documentation/codingstyle, and there seems to be no humor in lkd. Fuck Hungary naming method again.

"The question of containing function types in function names (the so-called Hungarian naming method) is that the compiler knows the types and
And can check those types.ProgramEmployee confused. It is no wonder that Microsoft always creates problematic programs ."

Linux KernelCodeStyle

This is a short document describing the preferred code style of the Linux kernel. The Code style varies from person to person, and I
I don't want to impose my opinion on anyone, but here I am talking about the style of the code that I must maintain,
I also hope that most other code can follow this style. Consider at least
Style.

First, I suggest you print a GNU code specification and do not read it. Burned it, which is a symbolic
Action.

Now let's start:

Chapter 1: Indent

The tab is 8 characters, so the indentation is also 8 characters. Some superstitious movements attempt to change indentation to 4 (or even 2) characters
Deep, which is almost equivalent to trying to define the value of the circumference rate as 3.

Reason: the full meaning of indentation lies in clearly defining the starting and ending points of a control block. Especially when you stare at your screen
After 20 hours in a row, you will find that a larger indentation will make it easier for you to distinguish indentation.

Now, some people complain that the 8-character indent will make the code move too far to the right, on the terminal screen with 80 characters
It is difficult to read such code. The answer to this question is, if you need more than three indentation, no matter how you use it
The Code already has a problem. You should correct your program.

In short, the 8-character indentation can make the code easier to read. Another benefit is that when your function is nested too deep
You can give a warning. Pay attention to this warning.

In a switch statement, the preferred way to eliminate multi-level Indentation is to align the "Switch" and its "case" labels with the same
One column instead of "Two indentations" and "case" labels. For example:

Switch (suffix ){
Case 'G ':
Case 'G ':
Mem y ){
...
} Else {
....
}

Reason: K & R.

Note that this way of placing braces can also minimize the number of empty (or almost empty) rows without losing
Read. Therefore, because the new lines on your screen are non-renewable resources (think about 25 rows of terminal screens), you will have more
Multiple empty rows to place comments.

When there is only one separate statement, no unnecessary braces are added.

If (condition)
Action ();

This is not applicable to a separate statement that is a branch of a condition statement. In this case, you need to use a large value in both branches.
Brackets.

If (condition ){
Do_this ();
Do_that ();
} Else {
Otherwise ();
}

3.1: Space

The space usage of Linux kernel depends on whether it is used for functions or keywords. (MOST) after the keyword
Add a space. The following are notable exceptions: sizeof, typeof, alignof, and _ attribute __.
To some extent it looks more like a function (they are often used with parentheses in Linux, even though in C
Parentheses are not required, just like the "sizeof Info" after "struct fileinfo Info" is declared ").

Therefore, place a space after these keywords:
If, switch, case, for, do, while
However, do not place spaces after the keywords sizeof, typeof, alignof, or _ attribute. For example,
S = sizeof (struct file );

Do not add spaces on both sides of the expression in parentheses. This is a counterexample:

S = sizeof (struct file );

When declaring a pointer type or returning a pointer type function, the preferred method of "*" is to bring it closer to the variable name or function.
Rather than the type name. Example:

Char * linux_banner;
Unsigned long memparse (char * PTR, char ** retptr );
Char * match_strdup (substring_t * s );

Use a space on both sides of most binary and ternary operators, for example, all of the following operators:

= +-*/% | & ^ =! =? :

But do not add spaces after The unary operator:
& * + -~ ! Sizeof typeof alignof _ attribute _ defined

No space is added before the suffix auto-increment and auto-increment unary operators:
++ --

The prefix auto-increment and auto-increment unary operators are not followed by spaces:
++ --

"." And "->" struct member operators are not preceded by spaces.

Do not leave blank spaces at the end of the row. Some editors that can be automatically indented will add a proper amount of white space at the beginning of the line in the new line, and then you
You can directly enter the code in that line. However, if you didn't enter code in that line at last, some editors won't
It will remove the added blank, just as you intentionally leave a blank row. This is how the blank lines at the end of a row are produced.
Born.

When git finds that the patch contains a blank line at the end of the line, it will warn you, and you can remove the blank line at the end of the line as required; however
If you are applying a series of patches, this will cause the subsequent patches to fail because you have changed the patch context.

Chapter 4: naming

C is a simple language, so should you name it. Different from Modula-2 and Pascal programmers, C programmers do not
Use a gorgeous name like thisvariableisatemporarycounter. C programmers will call that variable "TMP"
In this way, it will be easier to write, and at least it will not make it difficult to understand.

However, although case-insensitive names are not recommended, a descriptive name is required for global variables.
. Calling a global function "foo" is an unforgivable error.

Global variables (only when you really need them) need a descriptive name, just like a global function.
Number. If you have a function that can calculate the number of active users, you should call it "count_active_users ()" or
For a similar name, you should not call it "cntuser ()".

A problem occurs when the function name contains the function type (the so-called Hungarian naming method) -- the compiler knows the types
And can check those types, this can only confuse programmers. No wonder Microsoft always creates problematic programs.

The local variable name should be short and can express relevant meanings. If you have some random integer cyclic counters
It should be called "I ". Calling it "loop_counter" is not helpful, if it is not possible to be misunderstood. Similar
"Tmp" can be used to call any type of temporary variables.

If you are afraid of confusing your local variable name, you will encounter another problem, called function growth hormone imbalance syndrome.
. See chapter 6 (functions ).

Chapter 5: typedef

Do not use something like "vps_t.

Using typedef for struct and pointer is an error. When you see in the Code:

Vps_t;

What does this mean?

On the contrary

Struct virtual_container *;

You will know what "A" is.

Many people think that typedef can improve readability ". This is not the case. They are only useful in the following situations:

(A) completely opaque object (in this case, you must use typedef to hide what the object actually is ).

For example, for non-transparent objects such as "pte_t", you can only access them using suitable access functions.

Note! Opacity and "access function" are not good. The reason we use pte_t and other types is that it is
There is no shared accessible information.

(B) Clear Integer type. In this way, this abstraction can help eliminate confusion between "int" and "long.

U8/u32 is a Type Def with no problem at all, but they are more compatible with category (d) than here.

Pay attention again! To do so, there must be a reason. If a variable is "unsigned long", it is unnecessary.

Typedef unsigned long myflags_t;

However, if there is a clear reason, for example, it may be an "unsigned int" and
In other cases, it may be "unsigned long". Do not hesitate to use typedef.

(C) When you use sparse to create a new type literally for type check.

(D) the same type as the standard c99 type, with some exceptions.

Although it does not take a lot of time to adapt your eyes and brains to new standard types such as "uint32_t ",
People still refuse to use them.

Therefore, Linux is unique to the standard type of "u8/u32/u64" and their signed types are
Yes-although they are not mandatory in your new code.

When editing the existing code that has used a type set, you should follow the choices that have been made in the Code.

(E) types that can be used securely in the user space.

In some structures visible to the user space, the c99 type is not required and the "u32" mentioned above cannot be used"
Type. Therefore, we use _ u32 and similar types in all struct shared with the user space.

There may be other cases, but the basic rule is never to use typedef unless you can explicitly apply
Describe one of a rule.

In general, if elements in a pointer or struct can be reasonably directly accessed, they will not
It should be a typedef.

Chapter 6: Functions

The function should be short, beautiful, and complete only one thing. The function can be displayed on one or two screens (we all know
The size of the ISO/ANSI screen is 80x24). do only one thing and make it ready.

The maximum length of a function is inversely proportional to the complexity of the function and the indentation level. So, if you have a theory
It is very simple that there is only a very long (but simple) case statement function, and you need to do a lot of very
A small thing, such a function is very long, but it is also possible.

However, if you have a complex function and you suspect that a talented first-year high school student may even
If you cannot figure out the purpose of this function, you should strictly abide by the length limit mentioned above. Use helper functions, and
Get a descriptive name (if you think their performance is important, you can let the compiler inline them.
The effect is often better than writing a complex function .)

Another measure of the function is the number of local variables. This number should not exceed 5-10; otherwise, your function will have
Problem. Reconsider your function and split it into smaller functions. The human brain can be easily followed at the same time
Seven different things will be confused if they increase. Even if you are brilliant, you may not be able to remember you.
What I did a week ago.

In the source file, use blank lines to separate different functions. If the function needs to be exported, its export * macro should be close
Under its ending braces. For example:

Int system_is_up (void)
{
Return system_state = system_running;
}
Export_symbol (system_is_up );

The function prototype contains the function names and their data types. Although the C language does not have such requirements, in Linux
It is the practice advocated, because it can easily provide readers with more valuable information.

Chapter 7: centralized function exit Methods

Although some people claim that it is out of date, the GOTO statement equivalence is often used by the compiler. The specific form is
Unconditional jump command.

When a function exits from multiple locations and some general cleaning work is required, the benefits of goto are shown.
.

The reason is:

-Unconditional statements are easy to understand and track
-Reduced nesting degree
-Avoid errors caused by forgetting to update a single exit point during modification.
-Reduces the workload of the compiler and eliminates the need to delete redundant code ;)

Int fun (int)
{
Int result = 0;
Char * buffer = kmalloc (size );

If (buffer = NULL)
Return-enomem;

If (condition1 ){
While (loop1 ){
...
}
Result = 1;
Goto out;
}
...
Out:
Kfree (buffer );
Return result;
}

Chapter 8: Notes

Annotations are good, but there is a risk of excessive annotations. Never explain in comments how your code works: Better
The practice is to let others see your code, and it is a waste of time to explain the code that is poorly written.

Generally, you want your comments to tell others what your code has done, rather than how it is done. Please do not comment
Put it inside a function body: if the function is complicated and requires independent comments, you may need to return
Chapter 6. You can make some small comments to indicate or warn some clever (or slot) practices, but do not
Add too much. What you should do is place the annotation in the function header to tell people what it has done. You can also add it to do this.
Reasons for these issues.

When commenting on Kernel API functions, use the kernel-DOC format. See
Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-Doc for details.

The annotation style of Linux is c89. Do not use c99 style "//..." annotations.

The preferred comment style for long (multi-line) is:

/*
* This is the preferred style for multi-line
* Comments in the Linux kernel source code.
* Please use it consistently.
*
* Description: a column of asterisks on the left side,
* With beginning and ending almost-blank lines.
*/

Data annotation is also very important, whether it is basic type or derivative type. To facilitate this, each line should only
Declare one data (do not use commas to declare multiple data at a time ). In this way, you have space to write a segment for each data
Small comments are used to explain their usage.

Chapter 9: You have screwed up things

This is nothing. We are all like this. Maybe you have been using UNIX for a long time and have told you that "GNU Emacs" can
Automatically help you format CSource codeAnd you have noticed that this is indeed the case, but the default value and
They wanted a far cry (in fact, even worse than random calls-countless monkeys typing in GNU Emacs never
Will create a good program) (for more information, see infinite monkey theorem)

So you either give up GNU Emacs or change it to make it use more reasonable settings. You can
To paste the following section into your. emacs file.

(Defun Linux-C-mode ()
"C mode with adjusted defaults for use with the Linux kernel ."
(Interactive)
(C-mode)
(C-set-style "K & R ")
(Setq tab-width 8)
(Setq indent-Tabs-mode t)
(Setq C-Basic-offset 8 ))

In this way, the M-x Linux-C-mode command is defined. When you hack a module
-*-Linux-C-*-placed at a location in the first two rows. This mode will be automatically called. If you want to modify
If files in/usr/src/Linux are automatically opened by magic in Linux-C-mode, you may need to add

(Setq auto-mode-alist (Cons' ("/usr/src/Linux. */. * //. [CH] $". Linux-C-mode)
Auto-mode-alist ))

To your. emacs file.

However, even if you try to make Emacs correct to format the code, it does not mean that you have lost everything: You can also use"
Indent ".

However, GNU indent has the same problematic settings as GNU Emacs, so you need to give it some command options. No
This is not too bad, because even the authors of GNU indent agree with the authority of K & R (GNU people are not bad
People, they are seriously misled on this issue), so you just need to specify the option "-Kr-i8" for indent"
("K & R, 8 characters indented"), or use "scripts/lindent", which can be the most fashionable way
Indent source code.

"Indent" has many options, especially when re-formatting comments, you may need to take a look at its manual page. However
Remember: "indent" cannot correct bad programming habits.

Chapter 10: kconfig configuration file

For all kconfig * configuration files distributed throughout the source code tree, their indentation method is different from that of C code. Next
In the "Config" definition, the line below is Indented by a tab, and the help information is Indented by two spaces. For example:

Config Audit
Bool "auditing support"
Depends on Net
Help
Enable auditing infrastructure that can be used with another
Kernel subsystem, such as SELinux (which requires this
Logging of AVC messages output). Does not do system-call
Auditing without config_auditsyscall.

Features that are still considered unstable should be defined as dependent on "experimental ":

Config slub
Depends on Experimental &&! Arch_uses_slab_page_struct
Bool "slub (unqueued Allocator )"
...

And those dangerous functions (such as writing support for some file systems) should be explicitly declared in their prompt strings.
One point:

Config adfs_fs_rw
Bool "ADFs write support (dangerous )"
Depends on adfs_fs
...

To view the complete documentation of the configuration file, see documentation/kbuild/kconfig-language.txt.

Chapter 2: Data Structure

If a data structure is visible outside the single-line execution environment where it is created and destroyed, it must have a reference
Digit. There is no garbage collection in the kernel (and garbage collection outside the kernel is slow and inefficient), which means you absolutely need
Record your usage of this data structure.

Reference counting means you can avoid locking and allow multiple users to access this data structure in parallel-without worrying about
This data structure disappears only because it is not used for the moment. Those users may have been sleeping for a while or
Other things.

Note that locking cannot replace reference counting. Locking is to maintain data structure consistency, and the reference count is a memory Tube
Skills. We usually need both of them. Do not confuse them.

Many data structures actually have two levels of reference count, which usually have different "classes" users. Subclass counter statistics subclass
The number of users. Each time the sub-class counter is reduced to zero, the Global Counter is reduced by one.

This "multi-level reference count" example can be managed in memory ("struct mm_struct": mm_users and mm_count)
And in the file system ("struct super_block": s_count and s_active.

Remember: if another execution clue can find your data structure, but this data structure does not reference counters, this
Is almost certainly a bug.

Chapter 2: macros, enumerations, and RTL

The macro name used to define constants and the tags in the enumeration must be capitalized.

# Define constant 0x12345

It is best to use enumeration when defining several related constants.

The macro name must be in upper case, but the macro name in the form of a function can be in lower case.

Generally, if you can write an inline function, do not write the macro of the imaging function.

Macros containing multiple statements should be included in a do-while code block:

# 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 the control process:

# Define Foo (X )/
Do {/
If (blah (x) F ))

There are also min () and max () macros that can perform strict type checks. You can use them if needed. You can check it by yourself
The header file also defines what you can use. If there is a definition, you should not be in your code.
Customize it by yourself.

Chapter 4: Editor mode line and other things that require coarse

Some editors can explain the configuration information embedded in the source file marked by some special tags. For example, emacs
It can be interpreted as a line like this:

-*-Mode: C -*-

Or:

/*
Local variables:
Compile-command: "gcc-dmagic_debug_flag Foo. c"
End:
*/

Vim can explain the following mark:

/* VIM: Set Sw = 8 NOET */

Do not include any such content in the source code. Everyone has their own editor configuration, and your source file should not
This overwrites others' configurations. This includes the indentation and pattern settings. People can use their own models
Or use other clever methods that can generate correct indentation.