KernelTrap - documentation

Quote: Maze of Twisty Little Documentation Patches

Jeremy — Fri, 01 Feb 2008 02:06:20 +0000

"You are trapped in a maze of twisty little documentation patches, all pedantic."

Quote: Things Don't Work How They Are Documented

Jeremy — Wed, 31 Oct 2007 18:44:22 +0000

"Rule #1 in kernel programming: don't *ever* think that things actually work the way they are documented to work. The documentation is a starting point, nothing else."

Formatting Bug Fix Emails

Jeremy — Wed, 24 Oct 2007 07:31:50 +0000

"I'll just take this opportunity to ask people that when they send bug-fixes, please try to make the subject line and message make sense for a *reader*, not for yourself (or even to me, although if it's readable to some generic person, it's hopefully readable to me too!)," Linus Torvalds explained in response to a recent bugfix. He went on to provide some general rules:

"1)if it's not fairly generic, specify the area (architecture, subsystem, driver) that the fix is for in the subject line. [...] 2) don't use commit names in the subject line - and while it's great to use them in the body of the explanation, even there you don't want to assume that people read it from within git. [...] 3) write the commit message for an outsider, and use whitespace. The third-most common fixup I end up doing (after the above two) is to split things up into shorter paragraphs, after somebody wrote a good changelog entry, but made it one large unreadable blob of text."

Linus added, "I end up editing just about half of all the commit messages of stuff I get in email (except for Andrew's stuff, since Andrew largely does the same kinds of cleanups anyway, so I only need to edit up a small percentage of the patches he forwards). I'd like it to be *much* less than that, so I thought I should speak up since I had an example of this."

SysRq Help

Jeremy — Tue, 23 Oct 2007 06:47:22 +0000

"For SysRq, we can get [a] hot key list from Documentation/sysrq.txt, but in most of cases, the user can't access it [when] using SysRq to debug, so it is better for SysRq to provide online help for the users," Yi Yang noted, explaining the need for his patch to improve SysReq's built in help. He continued, "in addition, that function has a big loop with another big loop embedded which is very inefficient".

The general reaction was that the changes were unnecessary. Valdis Kletnieks pointed out, "you're optimizing code that hopefully never gets executed, and even if it does, you have the optimization *backwards*. If you're worried about the efficiency, trim it down to output 3 lines - do you realize how many instructions it takes in the VGA and fb drivers to actually *output* all these lines?" He added that people using SysRq for debugging usually fall into two classes and don't require lengthy online help, "1) he has been told 'recreate the problem, hit alt-sysreq-cokebottle, and send me the results', or 2) he's already read the file in Documentation/ and just needs a reminder."

Exact Kernel Names

Jeremy — Sun, 21 Oct 2007 10:33:08 +0000

When asked how to best refer to kernels between official releases and release candidates, Linus Torvalds pointed to his automated git snapshots. "I still call them 'nightly snapshots', but they do in fact happen twice a day if there have been changes, so that's not technically correct," he noted. The latest snapshot is 2.6.23-git15, "this is an exact name, because you can go to kernel.org and look up the exact commit ID that was used to generate it (there's an 'ID' file associated with each snapshot there)." For git users, he suggested using the "git describe" command to get the git name, with the current head being named v2.6.23-6562-g8add244. He went on to explain that the name "tells you three things: (a) it's based on 2.6.23 (b) there's been 6562 commits since 2.6.23 and (c) the top-of-tree abbreviated commit is '8add244'."

When asked about the previously discussed usage of "-rc0" and other similar proposed naming conventions, Linus replied:

"Please don't use those names. They don't actually tell anything about where in the cycle it is, and as you can see above, there's been 6500+ commits since 2.6.23, so saying '2.6.23-rc0' or similar really isn't very helpful if anybody actually cares about just where in the release cycle you are."

Tracking Down Merge Errors With git

Jeremy — Wed, 17 Oct 2007 00:14:57 +0000

In a short discussion following a patch titled "fix abdhid mismerge", Al Viro noted troubles in tracking down the changeset that caused the problem, "what's the right way to trace the things like that? Linus?" Linus Torvalds, as the original author of git, replied, "in general, I'm afraid that merge errors are simply not very easy to find." He then offered some general tips for tracking down mis-merges, noting, "if anybody can come up with a better way to find these kinds of mis-merges, I'd love to hear about it." In regards to this particular case, he explained:

"'-c' is for regular combined merges: any file that was modified in both parents will show up as a combination of the diffs of both sides, while a file that was taken in its *entirety* is ignored.

"In this case that's exactly what you wanted. It's just too noisy to necessarily be the default, and you can still have a silent mis-merge if the merger picked *only* one side.

But in general, I suspect that '-c' is often a good thing to try if you cannot find the cause of some change in a regular commit, and suspect a merge error."

Student Kernel Projects

Jeremy — Mon, 15 Oct 2007 06:54:40 +0000

"The kernel newbies community often gets inquiries from CS students who need a project for their studies and would like to do something with the Linux kernel, but would also like their code to be useful to the community afterwards," explained Rik van Riel in a posting titled "WANTED: kernel projects for CS students". He offered a link to a Kernel Newbies wiki page titled "KernelProjects" adding, "if you have ideas on what projects would be useful, please add them to this page (or email me)". Rik explained that he was assembling a list of projects on that page that meet the following criteria:

"Are self contained enough that the students can implement the project by themselves, since that is often a university requirement; are self contained enough that Linux could merge the code (maybe with additional changes) after the student has been working on it for a few months; are large enough to qualify as a student project, luckily there is flexibility here since we get inquiries for anything from 6 week projects to 6 month projects."

Defining the Reviewed-by Tag

Jeremy — Tue, 09 Oct 2007 03:07:22 +0000

"Last month, at the kernel summit, there was discussion of putting a Reviewed-by: tag onto patches to document the oversight they had received on their way into the mainline," began Jonathan Corbet in an effort to define the meaning of the recently introduced reviewed-by tag. He continued, "that tag has made an occasional appearance since then, but there has not yet been a discussion of what it really means. So it has not yet brought a whole lot of value to the process."

In the continued discussion, it was requested that all commit tags be defined, prompting Jonathan to update his documentation to include Signed-off-by, Acked-by, Cc, and Tested-by along with his documentation for Reviewed-by. He offered the following definition for the new Reviewed-by tag:

"The patch has been reviewed and found acceptible according to the Reviewer's Statement as found at the bottom of this file. A Reviewed-by tag is a statement of opinion that the patch is an appropriate modification of the kernel without any remaining serious technical issues. Any interested reviewer (who has done the work) can offer a Reviewed-by tag for a patch."