Linux Kernel Architecture

Mauerer runbapp06.tex V1 - 09/04/2008 6:14pm Page 1277

Appendix F: The Kernel Development Process

*

* The name of this device has nothing to do with the name of the device in

* /dev. It only helps to keep track of the different owners of devices. If

* your module name has only one type of devices it’s ok to use, for example, the name

* of the module here.

*

* This function registers a range of 256 minor numbers. The first minor number

*is0.

*/

int register_chrdev(unsigned int major, const char *name,

const struct file_operations *fops)

...

Notice that the comment line starts withtwoasterisks. This identifies the comment as akerneldoccom-

ment. Functions prefixed by such comments will be included in the API reference, which can be created

withmake htmldocsand similar commands. Variable names must be prefixed with the@sign and will be

formatted accordingly in the generated output.The comment should include the following:

❑ A description of the parameters that specifieswhatthe function does (as opposed tohowthe func-

tion does this).

❑ The possible return codes and their meanings.

❑ Any limitations of the function, the range of valid parameters, and/or any special considerations

that must be taken into account.

F.3.2 Submission and Review

This section describes two important social components of kernel development: Submitting patches to

mailing lists, and the subsequent review process.

Preparing Patchesfora Mailing List

Most patches are submitted to the mailing list of the respective subsystem before they are considered

for inclusion into any kernel tree — unless you are a top-notch kernel contributor who submits patches

directly to Linus or Andrew (in which case, you would probably not be reading this anyway...). Again,

there are some conventions that should be obeyed as described here:

❑ Subject lines start with[PATCH], and the rest of the subject should give a concise description of

what the patch is all about. A good subject is very important because it is not only used on the

mailing list, but in the case of an acceptance, it will appear in the git change logs.

❑ If a patch is not supposed to be applied directly, or if it requires more discussion, it can be

marked with an additional identifier such as[RFC].

❑ Larger changes should be split up into multiple patches with one logical change per patch.

Likewise, you should send only one patch per e-mail. Each should be numbered as[PATCH

m/N],wheremis a counter andNis the total number of patches .[PATCH 0/N]should contain an

overview about the follow-up patches.

❑ A more detailed description of each patch should be contained in the e-mail body. Again, this

text will not get lost after the patch is integrated, but will find its way into the git repository

where it serves to document the changes.