The Linux Kernel Coding Style

Task No.4

Wonderful job in making it this far, I hope you have been having fun. Oh, you're getting bored, just booting and installing kernels? Well, time for some pedantic things to make you feel that those kernel builds are actually fun!

Part of the job of being a kernel developer is recognizing the proper Linux kernel coding style. The full description of this coding style can be found in the kernel itself, in the Documentation/CodingStyle file. I'd recommend going and reading that right now, it's pretty simple stuff, and something that you are going to need to know and understand. There is also a tool in the kernel source tree in the scripts/ directory called checkpatch.pl that can be used to test for adhering to the coding style rules, as kernel programmers are lazy and prefer to let scripts do their work for them...

And why a coding standard at all? That's because of your brain (yes, yours, not mine, remember, I'm just some dumb shell scripts). Once your brain learns the patterns, the information contained really starts to sink in better. So it's important that everyone follow the same standard so that the patterns become consistent. In other words, you want to make it really easy for other people to find the bugs in your code, and not be confused and distracted by the fact that you happen to prefer 5 spaces instead of tabs for indentation. Of course you would never prefer such a thing, I'd never accuse you of that, it was just an example, please forgive my impertinence!

Anyway, the tasks for this round all deal with the Linux kernel coding style. Attached to this message are two kernel modules that do not follow the proper Linux kernel coding style rules. Please fix both of them up, and send it back to me in such a way that does follow the rules.

What, you recognize one of these modules? Imagine that, perhaps I was right to accuse you of the using a "wrong" coding style :)

Yes, the logic in the second module is crazy, and probably wrong, but don't focus on that, just look at the patterns here, and fix up the coding style, do not remove lines of code.

Attachments:

1. hello_world.c - Note: This should be the module you submitted from the First Eudyptula Challenge. If you've been following along, this is the file we submitted.
2. coding_style.c

—Little Penguin

As the Little Penguin was saying, the Linux style guide is here not for your benefit, but to help other developers, maintainers, and reviewers understand and evaluate the code you write faster. The kernel works at a furious pace, receiving on average ~10 patches every hour, a pace that is only accelerating as more people and companies begin to depend on the project for the new device, radio, microwave or any other IoT gadget they're working on.

TLDR: The style guide helps everyone review your code which improves the chances of your patch being accepted.

Executive Summary of the Linux Kernel Coding Style

The style guide is a very straight forward document, the majority of it dealing with whitespace and naming things. (Something every project has to deal with regardless the number of developers it has) I'll list the "executive overview" here (for the SEO points 🙂) though you should really take a moment to skim the Linux coding style guide for the latest updates.

• tabs are 8 characters, one statement per line. Historically tab keys were used to help tabulate charts on typewriters. Now they help maintainers keep track of your control blocks.

• 80 characters per line. An old throwback to when screens only displayed 80 characters per line. "Now-O-Days", with modern 48" 8k monitors, the 80 character hard limit is a bit softer. Today we can get away with a few lines under 100 characters if it improves readability. One possible exception to this is printk() statements, allowing us to easily grep for them when debugging.

• brackets. Don't worry about brackets if you only need one line.

  if (err)
          return -ENOMEM;
  

  For multiple lines, place the bracket at the end of your if (switch, do, for, while, ...) statements.

  if (err) {
          pr_dbg("Failed to allocate memory");
          return -ENOMEM;
  }
  

  Though function have brackets on the next new line.

  int do_something_cool(void)
  {
          return something_cool == DONE;
  }
  

• spaces. Most of the time, spaces go after each keyword. Some notable exceptions to this are sizeof, typeof, alignof, and __attribute__ which are treaded somewhat like functions in the kernel.

• naming. Don't worry about descriptive variable names inside a function. tmp or err are perfectly acceptable. However global variables (to be used sparingly) should have descriptive names. Don't use MixedCase!

• typedefs. Just Don't. Typedefs only hurt readability. You can't immediately tell if it's a struct or an integer of some specific size, or a pointer (to a pointer, to a pointer... to...).

• commenting your code. If your explaining how the code works, you've written it wrong. Comments are for what your code does if the function's name didn't make this clear already.

These bullets take care of the majority of what a new kernel developer will deal with on a day-to-day basis, and if you're ever unsure about something you can always git grep <pattern> to see how others have coded similar things in the past.

scripts/checkpatch.pl

Fortunately, previous developers created a script to check for some of these style blunders and alleviate the burden put on maintainers to point out these minor coding style violations. This script is one of many helpful scripts inside the Linux source tree we downloaded in the second challenge. The one we're interested in and we will be using today is called scripts/checkpatch.pl.

At the root of the Linux source code, use the --help or --version options to see the usage instructions and get a complete list of all the options available.

$ ./scripts/checkpatch.pl --help

For this Eudyptula Challenge, we will remain focused on the --file or -f option to analyze the files the little penguin gave us (hello_world.c and coding_style.c) for style violations. I won't go into the specific changes we need to make (a task for you to complete). Instead I will go through how to use checkpatch.pl to find some of issues with the files the Little Penguin gave us.

We can check our file using the -f option followed by the file we want to check:

$ ./scripts/checkpatch.pl -f ~/eudyptupla/tasks/04/coding_style.c
...
total: 1 errors, 1 warnings, 1 checks, 35 lines checked

NOTE: For some of the reported defects, checkpatch may be able to
      mechanically convert to the typical style using --fix or --fix-inplace.

eudyptupla/tasks/04/coding_style.c has style problems, please review.

Then use you favorite editor to fix the issues checkpatch.pl printed out.

You can even use --strict or the --subjective option to enable more subjective tests and --codespell to check the file for misspelled words.

$ ./scripts/checkpatch.pl --strict --codespell -f ~/eudyptula ...

Once you've made your changes, and feel the code looks good (it's hard when you can remove any lines) use git format-patch HEAD~ and send in your changes.

Good Luck!

Wrapping Up

If you made it here, you may be surprised to see how little there was to this challenge. Essentially this "boils down" to reading the Linux style guide and practice using it. Though, so far in my software career, I have found that true for all coding standards.

PS: I made around 39 changes in all, though this may change depending on when you work on this. Hope that helps :)