sarnoldwelcome everyone to the third day of UMeet :)
sarnoldour first speaker today is gregkh, a long-time kernel hacker
sarnoldhe has been maintaining the kernel's USB stack for .. 1.5 years? and has worked at IBM's linux
technology center for a little longer. If I recall correctly.
gregkhlong time?  heh, I'm not _that_ old :)
sarnoldgreg's talk is going to be about the coding style in the kernel, as it appears most people trying to
get drivers merged into the kernel screw it up somehow :)
sarnoldgregkh: you've got a kid. :) I think that makes you old. :)
sarnoldanyway, please welcome gregkh. :)
gregkhheh, good point :)
gregkhI'm here to talk about proper Linux kernel coding style.
gregkhI'm going to go through a few reasons why we have a style guideline,
gregkhthen go over the currently documented style rules, and then cover
gregkhsome "undocumented" rules that everyone should also follow.
gregkhfeel free to ask questions whenever you want on #qc
gregkhFirst off, why should we have a kernel coding style at all?
gregkhAfter all, code formatting doesn't effect memory use, execution speed,
gregkhor anything else a user of the kernel would notice.
gregkh
gregkhThe main reason is that if a large body of code is written in a common
gregkhstyle, it directly effects how easy it is to quickly understand the code,
gregkhreview it, and revise it.  And since the Linux kernel source is meant for
gregkhothers to modify, we want this code to be as easy to change as possible.
gregkh
gregkhThere have been a lot of research about this topic, and people can ask me
gregkhoffline if they want any citations.
gregkh
gregkhI'm kind of glossing over the reasons why we need rules, so are there any questions about this?
gregkhgood, no excuses for why anyone here isn't following them :)
gregkh
gregkhSo what are the Linux kernel coding rules?
gregkhFirst off, read the Documentation/CodingStyle file in the kernel tree.
gregkhIt lists a number of rules that should _always_ be followed.
gregkh< zanshin> Are the rules because Linus wants them that way or are they based on something else?
gregkhthey are based on both because Linus wants them that way, and because of history.
gregkha combination of both.
gregkhI'll summarize the CodingStyle rules here:
gregkh - all tabs must be 8 characters, and the [TAB] character must be used instead of spaces.
gregkhIf your code is shifting off the side of the screen too much because
gregkhof this, it's a good hint that you need to clean up the logic of your code.
gregkhBe careful that your editor settings do not change tabs to spaces, I've seen that happen a lot.
gregkh
gregkh - braces must have the opening brace last on the line, and the closing brace first on the line.
gregkhFor example:
gregkh        if (x is true) {
gregkh                we do y
gregkh        }
gregkhThe only exception to this rule is functions, which have the opening
gregkhbrace at the beginning of the line like:
gregkh        int function(int x)
gregkh        {
gregkh                body of function
gregkh        }
gregkh
gregkh< jmgv> and class if you use c++ i suppose
gregkhjmgv: there is no c++ in the kernel :)
gregkh
gregkhIf you want to convert a file to this proper style, look at the
gregkhscripts/Lindent script in the kernel tree.  It is a good start at
gregkhfiguring out the indent(1) command line arguments to get the proper kernel style.
gregkh
gregkhany questions about indenting and tabs?
gregkhthere are lots of bad examples of this in the kernel, but I'm not going to go into those here.
gregkh< gcc> the proper way to break a too long line
gregkhThere really isn't a "proper" way, just make it look sane.  indent(1) can cause some horrible things to
happen with regards to that, so make sure you clean up after it by hand.
gregkh< jmgv> how mandatory are these rules.
gregkhvery mandatory, your patch will be rejected.
gregkhok, moving on...
gregkh
gregkh- Your variables and functions should be declared descriptively and yet concisely.
gregkhYou should not use long flowery names like, CommandAllocationGroupSize or DAC960_V1_EnableMemoryMailboxI
nterface(),
gregkh but instead, name them cmd_group_size, or enable_mem_mailbox().
gregkhMixed case names are frowned upon and encoding the type of the
gregkhvariable or function in the name (like "Hungarian notation") is forbidden.
gregkh< mulix> how about patches to clean up the coding style of old drivers?
gregkhthat's accepted by some people.
gregkhbut some maintainers are very stuborn about not changing their style.  ignore them :)
gregkh
gregkhnext item,
gregkh  - Functions should do only one thing, and do it well.
gregkhThey should be short, and hopefully contain only one or two screens of text.
gregkhnow this one is broken _all_ the time, but please, try to follow it.  it will make
gregkhmaintaining your code easier over time.
gregkh
gregkh  - Comments are very good to have, but they have to be good comments.
gregkhBad comments explain how the code works, who wrote a specific function on a
gregkhspecific date, or other such useless things.  Good comments explain what
gregkhthe file or function does, and why it does it.
gregkhIf you are going to comment functions, use the kerneldoc format.
gregkhThis is explained in the Documentation/kernel-doc-nano-HOWTO.txt and
gregkhscripts/kernel-doc files in the kernel tree.
gregkhThis allows documentation to be automatically generated from your code.
gregkh
gregkhand the final written rule,
gregkh  - reference count your data structures.
gregkhThis isn't so much a style guideline, as a proper coding guideline.
gregkhIf another thread can find your data structure, and you do not have a
gregkhreference count on it, you almost certainly have a bug.
gregkhNow the kernel has a kobject structure that can easily be used if you
gregkhneed to have a reference count within your structure.
gregkh
gregkhany questions on the documented rules?
gregkh< snide> what about the unicity of the different function names all over the code ?
gregkhwhat does "unicity" mean?
gregkhdo you mean "global namespace"?
gregkhyes, pick your function names well, and don't make them global unless they have to be.
gregkh
gregkhOk, moving on to the unwritten rules.
gregkh- Use code that is already written.
gregkhUse the list structures, the string functions, the kobject structure,
gregkhthe endian functions, and other, already written and debugged functions within your kernel
gregkhcode.
gregkhDo NOT duplicate already written work just because you want to
gregkhuse the library functions, they are there for a reason.
gregkh
gregkhMoving on to my favorite rule:
gregkh- typedef is EVIL!
gregkhEVIL EVIL EVIL EVIL EVIL!
gregkhNEVER USE typedef IN YOUR CODE!!!
gregkhgot it?  :)
gregkheven if you're ingo, he's slowly changing too :)
gregkhOnly in _very_ rare cases should you create a typedef.
gregkhA function pointer is one of those instances.
gregkh< gcc> why it so evil
gregkhIt hides information from the programmer, and enables them to do stupid things.
gregkhlike pass a whole structure on the stack as a paramater, and other such nonsense.
gregkhagain, typedefs for function pointers is ok.
gregkhbut that's it.
gregkhIf you only remember one "unwritten" rule, please remember that one.
gregkhI'm going to pause for a few minutes to let the translators catch up, sorry for typing so fast
gregkh< zanshin> what is bad about passing structures as parameters?
gregkhpass a pointer to a structure, not the whole structure, or that will take up too much room on the
stack, and be very slow.
gregkhok, moving on,
gregkh - do not place "magic numbers" within your code.
gregkhIf you are going to use a numeric value, document it, and make it a
gregkh#define for others to understand what you are trying to do.
gregkhIf it's a number that a user might possibly want to be able to change, make it either a sysctl value, a
command line option, or a module paramater option.
gregkh
gregkh - do not put #ifdef within a .c file.
gregkhThey are allowd only within .h files.
gregkhUse the preprocessor to compile away code that is not configured in, do not use
gregkh#ifdef within the body of code to do this.
gregkh
gregkhany questions about this?
gregkh< snide> but what about #ifdef CONFIG_SMP inside mm/slab.c for exemple
gregkhyes, in some places it can't be helped, but for the majority of code, do not use it.
gregkh
gregkhAlso remember all of these rules are just guidelines, you will find places that break everyone of them,
but try to follow them for 99% of your code.
gregkhOne last unwritten rule, use labeled identifiers for structures that you initialize at compile time.
gregkhand by that I mean the following:
gregkhstruct foo bar = {
gregkh.a = 24,
gregkh.b = 42,
gregkh};
gregkhuse the C99 style initializers, and not the gnu style, as people are going through the whole kernel
gregkhand converting them.
gregkh
gregkhSo in conclusion:
gregkh - read Documenatation/CodingStyle
gregkh - follow it.
gregkh - use scripts/Lindent.
gregkh - Do not use typedef
gregkh
gregkhany further questions?
gregkh< snide> how to avoid using #ifdef CONFIG_MYOPTION in a practical way then [ any exemple ? ]
gregkhas an example, look at include/linux/hiddev.h and drivers/usb/input/hid_core.c for some functions
gregkhthat get compiled away if #ifdef CONFIG_USB_HIDDEV is not enabled.
gregkhI also have a longer paper that was presented at ols2002 about this topic at:
http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_paper/codingstyle.ps
gregkhand some slides at: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
gregkh< snide> so better split up the .c files ?
gregkhNo, split up the functions, and use static inline functions that do nothing if the config option is not
enabled,
gregkhthen in the .c file, always call them.  gcc will compile them away to nothing if that option is not enabled.
gregkhalso look at include/security.h in the 2.5.51 kernel, it has lots of examples of this if CONFIG_SECURITY is not enabled.
gregkh< snide> so using a function that the content will be wiped out with an #ifdef ?
gregkhIn a way, see the above examples for how it works.
gregkhSo that's it, any other questions?  If anyone has any later, feel free to email me.
sarnoldgregkh: thanks :)
sarnoldthanks also to EMPEROR, who has been providing on-the-fly translation to spanish in #redes :)
fernand0plas plas plas plas plas plas plas plas pals plas plas
fernand0plas plas plas plas plas plas plas plas pals plas plas
fsckednice talk, grek
fsckedgreg
fernand0plas plas plas plas plas plas plas plas pals plas plas
fernand0plas plas plas plas plas plas plas plas pals plas plas
BorZunggood talk gregkh thanks you :)
Rawsockwhile(1){ clap() ; }
gccgregkh: nice talk... thanks..
tiriclap clap clap clap
mulixclap clap clap clap clap clap clap clap
mulixclap clap clap clap clap clap clap clap
Rawsockow' somebody preempt me please :)
fsckedkillall Rawsock
fsckedthere
gregkhthank you to everyone, and to the orginizers of this conference, I appreciate you letting me talk.
Rawsockthx
VicMedinaclap clap
VicMedina=)
JoelRse vaaa se vaaa
EMPERORthanxs by your conference gregkh
JoelRal loco, al loco al loco le queda poco
fernand0thank you very much to you
davejoops, wrong window.. 8)
davejthanks sarnold
MJ-usaclap clap clap clap clap clap clap clap clap clap
MJ-usaclap clap clap clap clap clap clap clap clap clap
MJ-usaclap clap clap clap clap clap clap clap clap clap
MJ-usaslow clap for avoid  flooding
EMPERORthanxs by your conference gregkh
EMPERORvery good :)
EMPERORgreetings for you.
tiriit was very good :)
MJesus_the soanish traslator are VicMedina Emperor,  and tiri, and also have made an excelent work !
MJesus_soanish /spanish
VicMedina=)
JoelRai gŁant tu transleit tu
riel_well done gregkh
tiriI'm going to study. Good bye!
twinhola a todos
Apclap clap clap
MJesus_Ap, in #qc still  there are discussion

Generated by irclog2html.pl by Jeff Waugh - find it at freshmeat.net!