linux内核编程风格.pdf
Linux kernel coding styleThis is a short document describing the preferred coding style for thelinux kernel.Coding style is very personal,and I wont _force_ myviews on anybody,but this is what goes for anything that I have to beable to maintain,and Id prefer it for most other things too.Pleaseat least consider the points made here.First off,Id suggest printing out a copy of the GNU coding standards,and NOT read it.Burn them,its a great symbolic gesture.Anyway,here goes:Chapter 1:IndentationTabs are 8 characters,and thus indentations are also 8 characters.There are heretic movements that try to make indentations 4(or even 2!)characters deep,and that is akin to trying to define the value of PI tobe 3.Rationale:The whole idea behind indentation is to clearly define wherea block of control starts and ends.Especially when youve been lookingat your screen for 20 straight hours,youll find it a lot easier to seehow the indentation works if you have large indentations.Now,some people will claim that having 8-character indentations makesthe code move too far to the right,and makes it hard to read on a80-character terminal screen.The answer to that is that if you needmore than 3 levels of indentation,youre screwed anyway,and should fixyour program.In short,8-char indents make things easier to read,and have the addedbenefit of warning you when youre nesting your functions too deep.Heed that warning.The preferred way to ease multiple indentation levels in a switch statement isto align the switch and its subordinate case labels in the same columninstead of double-indenting the case labels.E.g.:switch(suffix)case G:case g:mem=30;break;case M:case m:mem=20;break;case K:case k:mem y).else.Rationale:K&R.Also,note that this brace-placement also minimizes the number of empty(or almost empty)lines,without any loss of readability.Thus,as thesupply of new-lines on your screen is not a renewable resource(think25-line terminal screens here),you have more empty lines to putcomments on.Do not unnecessarily use braces where a single statement will do.if(condition)action();andif(condition)do_this();elsedo_that();This does not apply if only one branch of a conditional statement is a singlestatement;in the latter case use braces in both branches:if(condition)do_this();do_that();else otherwise();3.1:SpacesLinux kernel style for use of spaces depends(mostly)onfunction-versus-keyword usage.Use a space after(most)keywords.Thenotable exceptions are sizeof,typeof,alignof,and _attribute_,which looksomewhat like functions(and are usually used with parentheses in Linux,although they are not required in the language,as in:sizeof info afterstruct fileinfo info;is declared).So use a space after these keywords:if,switch,case,for,do,whilebut not with sizeof,typeof,alignof,or _attribute_.E.g.,s=sizeof(struct file);Do not add spaces around(inside)parenthesized expressions.This example is*bad*:s=sizeof(struct file);When declaring pointer data or a function that returns a pointer type,thepreferred use of*is adjacent to the data name or function name and notadjacent to the type name.Examples:char*linux_banner;unsigned long long memparse(char*ptr,char*retptr);char*match_strdup(substring_t*s);Use one space around(on each side of)most binary and ternary operators,such as any of these:=+-*/%|&=!=?:but no space after unary operators:&*+-!sizeof typeof alignof _attribute_ definedno 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.Do not leave trailing whitespace at the ends of lines.Some editors withsmart indentation will insert whitespace at the beginning of new lines asappropriate,so you can start typing the next line of code right away.However,some such editors do not remove the whitespace if you end up notputting a line of code there,such as if you leave a blank line.As a result,you end up with lines containing trailing whitespace.Git will warn you about patches that introduce trailing whitespace,and canoptionally strip the trailing whitespace for you;however,if applying a seriesof patches,this may make later patches in the series fail by changing theircontext lines.Chapter 4:NamingC is a Spartan language,and so should your naming be.Unlike Modula-2and Pascal programmers,C programmers do not use cute names likeThisVariableIsATemporaryCounter.A C programmer would call thatvariable tmp,which is much easier to write,and not the least moredifficult to understand.HOWEVER,while mixed-case names are frowned upon,descriptive names forglobal variables are a must.To call a global function foo is ashooting offense.GLOBAL variables(to be used only if you _really_ need them)need tohave descriptive names,as do global functions.If you have a functionthat counts the number of active users,you should call thatcount_active_users()or similar,you should _not_ call it cntusr().Encoding the type of a function into the name(so-called Hungariannotation)is brain damaged-the compiler knows the types anyway and cancheck those,and it only confuses the programmer.No wonder MicroSoftmakes buggy programs.LOCAL variable names should be short,and to the point.If you havesome random integer loop counter,it should probably be called i.Calling it loop_counter is non-productive,if there is no chance of itbeing mis-understood.Similarly,tmp can be just about any type ofvariable that is used to hold a temporary value.If you are afraid to mix up your local variable names,you have anotherproblem,which is called the function-growth-hormone-imbalance syndrome.See chapter 6(Functions).Chapter 5:TypedefsPlease dont use things like vps_t.Its a _mistake_ to use typedef for structures and pointers.When you see avps_t a;in the source,what does it mean?In contrast,if it saysstruct virtual_container*a;you can actually tell what a is.Lots of people think that typedefs help readability.Not so.They areuseful only for:(a)totally opaque objects(where the typedef is actively used to _hide_ what the object is).Example:pte_t etc.opaque objects that you can only access using the proper accessor functions.NOTE!Opaqueness and accessor functions are not good in themselves.The reason we have them for things like pte_t etc.is that there really is absolutely _zero_ portably accessible information there.(b)Clear integer types,where the abstraction _helps_ avoid confusion whether it is int or long.u8/u16/u32 are perfectly fine typedefs,although they fit into category(d)better than here.NOTE!Again-there needs to be a _reason_ for this.If something is unsigned long,then theres no reason to dotypedef unsigned long myflags_t;but if there is a clear reason for why it under certain circumstances might be an unsigned int and under other configurations might be unsigned long,then by all means go ahead and use a typedef.(c)when you use sparse to literally create a _new_ type for type-checking.(d)New types which are identical to standard C99 types,in certain exceptional circumstances.Although it would only take a short amount of time for the eyes and brain to become accustomed to the standard types like uint32_t,some people object to their use anyway.Therefore,the Linux-specific u8/u16/u32/u64 types and their signed equivalents which are identical to standard types are permitted-although they are not mandatory in new code of your own.When editing existing code which already uses one or the other set of types,you should conform to the existing choices in that code.(e)Types safe for use in userspace.In certain structures which are visible to userspace,we cannot require C99 types and cannot use the u32 form above.Thus,we use _u32 and similar types in all structures which are shared with userspace.Maybe there are other cases too,but the rule should basically be to NEVEREVER use a typedef unless you can clearly match one of those rules.In general,a pointer,or a struct that has elements that can reasonablybe directly accessed should _never_ be a typedef.Chapter 6:FunctionsFunctions should be short and sweet,and do just one thing.They shouldfit on one or two screenfuls of text(the ISO/ANSI screen size is 80 x24,as we all know),and do one thing and do that well.The maximum length of a function is inversely proportional to thecomplexity and indentation level of that function.So,if you have aconceptually simple function that is just one long(but simple)case-statement,where you have to do lots of small things for a lot ofdifferent cases,its OK to have a longer function.However,if you have a complex function,and you suspect that aless-than-gifted first-year high-school student might not evenunderstand what the function is all about,you should adhere to themaximum limits all the more closely.Use helper functions withdescriptive names(you can ask the compiler to in-line them if you thinkits performance-critical,and it will probably do a better job of itthan you would have done).Another measure of the function is the number of local variables.Theyshouldnt exceed 5-10,or youre doing something wrong.Re-think thefunction,and split it into smaller pieces.A human brain cangenerally easily keep track of about 7 different things,anything moreand it gets confused.You know youre brilliant,but maybe youd liketo understand what you did 2 weeks from now.In source files,separate functions with one blank line.If the function isexported,the EXPORT*macro for it should follow immediately after the closingfunction brace line.E.g.: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 Linuxbecause it is a simple way to add valuable information for the reader.Chapter 7:Centralized exiting of functionsAlbeit deprecated by some people,the equivalent of the goto statement isused frequently by compilers in form of the unconditional jump instruction.The goto statement comes in handy when a function exits from multiplelocations and some common work such as cleanup has to be done.The rationale is:-unconditional statements are easier to understand and follow-nesting is reduced-errors by not updating individual exit points when making modifications are prevented-saves the compiler work to optimize redundant code away;)int fun(int a)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:CommentingComments are good,but there is also a danger of over-commenting.NEVERtry to explain HOW your code works in a comment:its much better towrite the code so that the _working_ is obvious,and its a waste oftime to explain badly written code.Generally,you want your comments to tell WHAT your code does,not HOW.Also,try to avoid putting comments inside a function body:if thefunction is so complex that you need to separately comment parts of it,you should probably go back to chapter 6 for a while.You can makesmall comments to note or warn about something particularly clever(orugly),but try to avoid excess.Instead,put the comments at the headof the function,telling people what it does,and possibly WHY it doesit.When commenting the kernel API functions,please use the kernel-doc format.See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-docfor details.Linux style for comments is the C89/*.*/style.Dont use C99-style/.comments.The preferred style for long(multi-line)comments 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.*/Its also important to comment data,whether they are basic types or derivedtypes.To this end,use just one data declaration per line(no commas formultiple data declarations).This leaves you room for a small comment on eachitem,explaining its use.Chapter 9:Youve made a mess of itThats OK,we all do.Youve probably been told by your long-time Unixuser helper that GNU emacs automatically formats the C sources foryou,and youve noticed that yes,it does do that,but the defaults ituses are less than desirable(in fact,they are worse than randomtyping-an infinite number of monkeys typing into GNU emacs would nevermake a good program).So,you can either get rid of GNU emacs,or change it to use sanervalues.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)(*(max steps 1)c-basic-offset)(add-hook c-mode-common-hook (lambda();Add kernel style (c-add-style linux-tabs-only (linux(c-offsets-alist (arglist-cont-nonempty c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)(add-hook c-mode-hook (lambda()(let(filename(buffer-file-name);Enable kernel mode for the appropriate files (when(and filename (string-match(expand-file-name/src/linux-trees)filename)(setq indent-tabs-mode t)(c-set-style linux-tabs-only)This will make emacs go better with the kernel coding style for Cfiles below/src/linux-trees.But even if you fail in getting emacs to do sane formatting,noteverything is lost:use indent.Now,again,GNU indent has the same brain-dead settings that GNU emacshas,which is why you need to give it a few command line options.However,thats not too bad,because even the makers of GNU indentrecognize the authority of K&R(the GNU people arent evil,they arejust severely misguided in this matter),so you just give indent theoptions-kr-i8(stands for K&R,8 character indents),or usescripts/Lindent,which indents in the latest style.indent has a lot of options,and especially when it comes to commentre-formatting you may want to take a look at the man page.Butremember:indent is not a fix for bad programming.Chapter 10:Kconfig configuration filesFor all of the Kconfig*configuration files throughout the source tree,the indentation is somewhat different.Lines under a config definitionare indented with one tab,while help text is indented an additional twospaces.Example:config AUDITbool Auditing supportdepends on NEThelp Enable auditing infrastructure that can be used with another kernel subsystem,such as SELinux(which requires this for logging of avc messages output).Does not do system-call auditing without CONFIG_AUDITSYSCALL.Features that might still be considered unstable should be defined asdependent on EXPERIMENTAL:config SLUBdepends on EXPERIMENTAL&!ARCH_USES_SLAB_PAGE_STRUCTbool SLUB(Unqueued Allocator).while seriously dangerous features(such as write support for certainfilesystems)should advertise this prominently in their prompt string:config ADFS_FS_RWbool ADFS write support(DANGEROUS)depends on ADFS_FS.For full documentation on the configuration files,see the fileDocumentation/kbuild/kconfig-language.t
