|
|
|
|
- Why do you use " GNU/Linux " sometimes and just " Linux " in other parts of the FAQ?
- (ADB) In this FAQ, we have tried to use the word "Linux" or the expression "Linux kernel" to designate the kernel, and GNU/Linux to designate the entire body of GNU/GPL'ed OS software, as found in the various distributions. We prefer to call a cat, a cat, and a GNU, a GNU. ;-)
The purpose of the FAQ is to provide information on the Linux kernel and avoid debates on e.g. semantics issues. Further discussion of the relationship between GNU software and Linux can be found at http://www.gnu.org/gnu/linux-and-gnu.html .
BTW, it seems many people forget that the linux kernel mailing list is a forum for discussion of kernel -related matters, not GNU/Linux in general; please do not bring up this subject on the list.
- What is an experimental kernel version?
- (ADB) Linux kernel versions are divided in two series: experimental (odd series e.g. 1.3.xx or 2.1.x) and production (even series e.g. 1.2.xx, 2.0.xx, 2.2.x, 2.4.x and so on). The experimental series are fast moving versions which are used to test new features, algorithms, device drivers, etc. By their own nature the experimental kernels may behave in unpredictable ways, so one may experience data losses, random machine lockups, etc.
- What is a production kernel?
- (ADB) Production or stable kernels have a well defined feature set, a low number of known bugs, and tried and proven drivers. They are released less frequently than the experimental kernels, but even so some "vintages" are considered better than others. GNU/Linux distributions are usually based on chosen stable kernel versions, not necessarily the latest production version.
- What is a feature freeze?
- (ADB) A feature freeze is when Linus announces on the linux-kernel list that he will not consider any more features until the release of a new stable kernel version. Usually the net effect of such an announcement is that on the following days people on the list propose a flurry of new features before Linus really enforces the feature freeze. ;-)
- What is a code freeze?
- (ADB) A code freeze is more restrictive than a feature freeze; it means only severe bug fixes are accepted. This is a short phase that usually precedes the creation of a new stable kernel tree.
- What is a f.g.hh pre i kernel?
- (ADB) These are intermediate pre-release versions of version f.g.hh . Note that usually i < 5, but e.g. 2.0.34 pre i was available with i = 1 to 16. Sometimes " pre " is replaced by the initials of the developer putting together the kernel revision, e.g. 2.1.105 ac 4 means the 4th intermediate release of kernel version 2.1.105 by Alan Cox.
- Where do I get the latest kernel source?
- (ADB) The primary site for the Linux kernel (experimental and production) sources is hosted by Transmeta (the company Linus Torvalds used to work for) on a dedicated Web server at http://www.kernel.org/ . This site is mirrored across the world, and has pointers to mirrors for each country. You can go directly to a mirror for your country by going to http://www.CODE.kernel.org/ where "CODE" is the appropriate country code. For example, "au" is the country code for Australia, so the principle mirror site for Australia is http://www.au.kernel.org/
- (REG) You may also access tarballs and patches directly via ftp from ftp://ftp.CODE.kernel.org/pub/linux/kernel/ which is where Linus distributes his kernels from. Other notable kernel hackers have directories under the people directory, which is where they keep their kernel patches. The testing directory is where Linus puts pre-release patches. The pre-release patches are mainly intended for other developers, so they can stay in sync with changes in Linus' source tree. These are often highly experimental and may crash or cause filesystem corruption. Use at your own risk.
Note that Linus and Marcelo are using GIT to manage their kernel source trees, and it is more convenient for them to make snapshots of their latest trees available via GIT, rather than make patches. If you want access to these snapshots (which are merely a work in progress, and may be buggy), there are several access methods available:
-
CVS: :pserver:anonymous@cvs.kernel.org:/home/cvs/linux-2.[45]
-
Subversion: svn://svn.kernel.org/linux-2.[46]/trunk
- (JBG) Linux is no longer maintained with the BitKeeper source code management system, but with GIT , a tool Linus wrote after BitKeeper was no longer available to all developers. You can browse Linus's latest kernel source as well as all other people's projects hosted on kernel.org . There's also a nice Overview of GIT and some helper tools as well as a complete Tutorial to get you into using GIT.
- Where do I get extra kernel patches?
- (REG) There are many places which provide various extra patches to the kernel for new features. One fairly good archive is available at: http://www.linuxhq.com/ .
- What is a patch?
- (RRR) A patch file (as it refers to the Linux kernel) is an ASCII text file that contains the differences between the original code and the new code, plus some additional information such as filenames and line numbers. The patch program (man patch) can then apply the patch to an existing kernel source tree.
- How do I make a patch suitable for the linux kernel list?
- (REG) Here are some basic guidelines for posting patches. For information on how to generate patches, see the entry by RRR below.
- Ensure the patch does not have trailing control-M characters on each line. A number of broken tools used to encode patches add control-M for "DOS compatibility". This breaks many versions of patch , so be sure to configure your tools properly, or use unbroken tools, otherwise your patch will be silently deleted.
- Include the patch inline in your email, in plain text. Do not post it as a base64 MIME attachment. Many people will not be able to read your patch, and thus your patch will be deleted without comment.
- This FAQ previously advised posting a URL to a patch if the patch is large. This is no longer recommended. The preferred way to submit a large patch is to break it up into logical chunks, with a descriptive comment for each, and post each piece with a subject line like
" [PATCH] cleanup of foo driver [1/5] ".
Do not start a new thread for each chunk - rather, post each chunk as a followup to the previous chunk. You may want to begin with an explanatory post, and label it something like
" [PATCH] cleanup of foo driver [0/5] ".
See Documentation/SubmittingPatches for more information.
- If you want Linus or one of the primary maintainers (i.e. Marcelo, David) to apply your patch, you must Cc: them explicitly, otherwise your patch will be ignored.
- When sending patches to Linus or one of the primary maintainers, you must include the patch inline, in plain text, no matter how large the patch.
- If you want to send a patch to the list for comment, and also send it to Linus/primary maintainer for inclusion, and the patch is large, you may wonder how to reconcile the conflicting requirements. The solution is obvious: post the URL to the mailing list, wait for comments, and later send the patch, inline, to Linus/primary maintainer. Yes, this is more work for you. No, we don't care.
- If you have a mailer that eats whitespace or causes similar corruption, then FIX YOUR MAILER , don't expect to be able to take the easy solution and MIME encode your patch.
Finally, I've seen one person question the veracity of these guidelines, stating that the rules are rather more relaxed, and this FAQ is being over zealous. Fortunately, the King Penguin himself responded to this, so I include his words on this, so that there can be no doubt: If I get a patch in an attachment (other than a "Text/PLAIN" type attachment with no mangling and that pretty much all mail readers and all tools will see as a normal body), I simply WILL NOT apply it unless I have strong reason to. I usually wont even bother looking at it, unless I expected something special from the sender. Really. Don't send patches as attachments. Linus
- A caveat applies for people using a Mozilla Mail client. Andrew Morton noted that Mozilla mangles spaces in column zero when patches are included in the message body. Fortunately, Mozilla Mail sends patch attachments as type text/plain or text/x-patch (depending on the presence of a file extension), so it's safe to send patches as attachments instead.
- (RRR) To make a patch you use the diff program (read the info file for diff). The easiest way to do this is to set up two source trees under /usr/src, set a symlink "/usr/src/linux" to point to the modified tree, and diff one tree against the other. The file /usr/src/Documentation/CodingStyle has more specific information, read it . Things to remember:
- Always specify unified (-u) diff format.
- Avoid making formatting changes to the source that make the diff needlessly larger. Watch out for editors that convert tabs to spaces or vice versa.
- Unless you have specific reasons, diff against the latest official source tree. Otherwise, your patch is likely to be ignored. Either way, specify in your post against what you've diff'ed.
- Make sure your diff includes only the intended changes in your patch, not every other patch you have made to your source tree. Usually patches are limited to a few files, or directories. It is best to only diff the relevant files i.e. if I only made changes to the file driver_xyz.c under drivers/net, then I would use the following commands (assuming you have the original source tree named "linux-2.1.105", and the modified tree pointed at by the symlink "linux"): cd /usr/src diff -u linux-2.1.105/drivers/net/driver_xyz.c \ linux/drivers/net/driver_xyz.c > my_patch
- The following two should go without saying: the arguments to diff are first source (the original, unmodified file(s)) , and then destination (your modified version of the file(s)) , otherwise you get a reversed patch (and lots of people wondering what you're smoking). Also, make sure your patch applies and compiles cleanly.
- Of course you need to set up two identical source directories to be able to diff the tree later. A nice trick -- requiring a little bit of consideration, though -- is to create the modified source tree from hard links to the original source tree: tar xzvf linux-2.1.anything.tar.gz mv linux linux-2.1.anything.orig cp -al linux-2.1.anything.orig linux-2.1.anything
This will hardlink every source file from the original tree to a new location; it is very fast, since it does not need to create some 80+ megabytes of files. You can now apply patches to the linux-2.1.anything source tree, since patch does not change the original files but move them to filename .orig , so the contents of the hard-linked file will not be changed.
Assuming that your editor does the same thing, too (moving original files to backup files before writing out changed ones) you can also freely edit within the hardlinked tree. If your editor does not handle files this way, you need to make a copy of each file before editing it, like this: cp driver_xyz.c temporary; mv temporary driver_xyz.c
You can use file permissions to remind you to do this. Just remove write permissions from all the files in the directory you are working in: chmod -w *.c
The changed tree can be diffed at high speed, since most files don't just have indentical contents, they are identical files in both trees. Naturally removing that tree is quite fast, too. Thanks to Janos Farkas < chexum@shadow.banki.hu > for this trick.
- Finally, review the patch file (the format is not that complicated) before posting, and include all relevant information as to the nature of the patch. In particular, specify: why is this patch needed/useful, and what exactly does it fix/improve.
- How do I apply a patch?
- (TAC) (From /usr/src/linux/README ) You can upgrade between releases by patching. Patches are distributed in the traditional gzip and the new bzip2 format. To install by patching, get all the newer patch files, enter the top-level directory of the unpacked kernel source tree and execute:
gzip -cd patchXX.gz | patch -p1 or:
bzip2 -dc patchXX.bz2 | patch -p1
(repeat xx for all versions bigger than the version of your current source tree, in order ) and you should be ok. You may want to remove the backup files (xxx~ or xxx.orig), and make sure that there are no failed patches (xxx# or xxx.rej). If there are, either you or me has made a mistake.
Alternatively, the script patch-kernel can be used to automate this process. It determines the current kernel version and applies any patches found. Use it thus:
scripts/patch-kernel .
The first argument in the command is the location of the kernel source. Patches are applied from the current directory, but an alternative directory can be specified as the second argument.
- (RRR) To apply kernel patches please take a look at the kernel README file (/usr/src/linux/README) under "Installing the kernel". There is also a good explanation on the Linux HQ Project site.
- What's vger?
- (REG) "vger" is the name of the machine which hosts the LKML server. This server also hosts a number of other linux-related mailing lists. More information about the server is available at http://vger.kernel.org/
- What is a CVS tree? Where can I find more information about CVS?
- (REG) "CVS" is short for Concurrent Versions System, a Source Code Management system.
- Is there a CVS tutorial somewhere?
- (ADB) Here is a CVS tutorial which you can find online:
- An interactive CVS tutorial.
Getting a general idea of how CVS works takes about 15 minutes (highly recommended). Note that there are various graphical front ends to CVS, so you don't have to learn the usual assortment of cryptic commands.
- How do I get my patch into the kernel?
- (RRR) Depending on your patch there are several ways to get it into the kernel. The first thing is to determine under which maintainer does your code fall into (look in the MAINTAINERS file). If your patch is only a small bugfix and you're sure that it is 'obviously correct', then by all means send it to the appropriate maintainer and post it to the list. If there is urgency to the bugfix (i.e. a major security hole) you can also send it to Linus directly, but remember he's likely to ignore random patches unless they are "obviously correct" to him, have the maintainer's approval, or have been well tested and meet the first condition. In case you're wondering what constitutes well tested, here's another important bit: one purpose of the list is to get patches peer-reviewed and well-tested. Now, if your patch is relatively big, i.e. a rewrite of a large code section or a new device driver, then to conserve bandwidth and disk-space just post an announcement to the list with a link to the patch. Lastly, if you're not too sure about your patch yet, want some feedback from the maintainer, or wish to avoid open-season flaming on work-in-progress, then use private email.
- (REG) If there is no specific maintainer for the part of the kernel you want to patch, then you have three main options:
- send it to linux-kernel@vger.kernel.org and hope someone picks it up and feeds it to Linus, or maybe Linus himself will pick it up (don't count on it)
- send it to linux-kernel and Cc: Linus Torvalds <torvalds@osdl.org> and hope Linus will apply it. Note that Linus operates like a black box. Do not expect a response from him. You will need to check patches he releases to see if he applied your patch. If he doesn't apply your patch, you will need to resend it (often many times). If after weeks or months and many patch releases he still hasn't applied it, maybe you should give up. He probably doesn't like it
- send it to linux-kernel and Cc: Alan Cox <alan@redhat.com> . Alan is better at responding to email, and will queue your patch and resend it to Linus periodically, so you can forget about it. He also serves as a good taste tester. If Alan accepts your patch, it's more likely that Linus will too. If he doesn't like your patch, you will probably get an email saying so. Expect it to be terse.
- Why does the kernel tarball contain a directory called linux/ instead of linux-x.y.z/ ?
- (DW) Because that's the way Linus wants it. It makes applying many consecutive patches simpler, because the directory doesn't need to be renamed each time, and it also makes life easier for Linus.
- What's the difference between the official kernels and Alan Cox's -ac series of patches?
- (REG, contributed by Erik Mouw) Alan's kernel can be seen as a test bed for Linus' kernels. While Linus is very conservative and only applies obvious and well tested patches to the 2.4 kernel, Alan maintains a set of kernel patches that contains new concepts, more and/or newer drivers, and more intrusive patches. If the patches prove themselves stable, Alan submits them to Linus to include them into the official kernel.
- What does it mean for a module to be tainted?
- (REG, contributed by John Levon) Some vendors distribute binary modules (i.e. modules without available source code under a free software license). As the source is not freely available, any bugs uncovered whilst such modules are loaded cannot be investigated by the kernel hackers. All problems discovered whilst such a module is loaded must be reported to the vendor of that module, not the Linux kernel hackers and the linux-kernel mailing list. The tainting scheme is used to identify bug reports from kernels with binary modules loaded: such kernels are marked as "tainted" by means of the MODULE_LICENSE tag. If a module is loaded that does not specify an approved license, the kernel is marked as tainted. The canonical list of approved license strings is in linux/include/linux/module.h .
"oops" reports marked as tainted are of no use to the kernel developers and will be ignored. A warning is output when such a module is loaded. Note that you may come across module source that is under a compatible license, but does not have a suitable MODULE_LICENSE tag. If you see a warning from modprobe or insmod for a module under a compatible license, please report this bug to the maintainers of the module, so that they can add the necessary tag.
- (KO) If a symbol has been exported with EXPORT_SYMBOL_GPL then it appears as unresolved for modules that do not have a GPL compatible MODULE_LICENSE string, and prints a warning. A module can also taint the kernel if you do a forced load. This bypasses the kernel/module verification checks and the result is undefined, when it breaks you get to keep the pieces.
- (KO) According to Alan Cox, a license of "BSD without advertisement clause" is not a suitable free software license. This license type allows binary only modules without source code. Any modules in the kernel tarball with this license should really be "Dual BSD/GPL" .
- What is this about GPLONLY symbols?
- (REG) By default, symbols are exported using EXPORT_SYMBOL , so they can be used by loadable modules. During the 2.4 series, a new export directive EXPORT_SYMBOL_GPL was added. This is almost the same thing, except that the symbol can only be accessed by modules which have a GPL compatible licence (note that this includes dual-licenced BSD/GPL code). This new directive was added for these reasons:
- To clarify the ambiguous legal ground on which non-GPL (particularly proprietary) modules lie. A strict reading of the GPL prohibits loading proprietary modules into the kernel. While Linus has consistently stated that proprietary modules are allowed (i.e. he has granted an explicit exemption), it is not clear that he is able to speak for all developers who have contributed to the Linux kernel. While many think Linus' edict means that all contributed code falls under this exemption granted by Linus, not everyone agrees that this is a legally sound argument. The new EXPORT_SYMBOL_GPL directive makes the licence conditions explicit, and thus removes the legal ambiguity.
- To allow choice for developers who wish, for their own reasons, to contribute code which cannot be used by proprietary modules. Just as a developer has the right to distribute code under a proprietary licence, so too may a developer distribute code under an anti-proprietary licence (i.e. strict GPL).
Note that Linus has stated that existing symbols will not be switched to GPL-only. Developers of proprietary modules for Linux need not fear. Furthermore, it is quite unlikely that Linus will look favourably upon the introduction of new core driver APIs which are restricted to GPL-only modules. This would not be in the best interests of Linux. Linus has forwarded me a message he sent to someone else to clarify his views. Note that since that time, several developers have eroded the number of non-GPL only symbols by writing new (usually better) infrastructure and interfaces and deprecating the older interfaces. The newer interfaces are often tagged as GPL-only. In addition, there are some "kernel janitors" who aggressively submit patches to remove all symbols (whether GPL-only or not) which are not used by code shipped with the kernel source tree.
- Do I have to use GIT to send patches?
- (REG) Absolutely not. Some kernel developers, including Linus and Marcelo, have chosen to use GIT to manage their kernel source trees, but this does not mean you need to use GIT yourself to maintain your trees or submit patches. Many notable kernel developers continue to maintain their source trees using other tools and techniques, and continue to send conventional patches.
- Who maintains the kernel?
- (REG) Originally, Linus Torvalds maintained the kernel. As the kernel has matured, he has delegated maintenance for older stable versions to others, while he continues development of the latest "bleeding edge" release. As of 27-MAY-2002, the following kernel versions are maintained by these people:
- 2.0 David Weinehall <tao@acc.umu.se>
- 2.2 Alan Cox <alan@lxorguk.ukuu.org.uk>
- 2.4 Marcelo Tosatti <mtosatti@redhat.com>
- 2.6 Linus Torvalds <torvalds@osdl.org>
- The kernel doesn't compile cleanly. What shall I do?
- (REG) First make sure you have the latest version of that kernel series. Perhaps a pre-patch already has a fix. If not, search the list archives for a fix. Don't contribute to noise on the list by asking a question that may already have been answered.
If the problem has not yet been fixed, try digging into the code yourself and post a fix to the mailing list. You'll be famous! Beware that making broken code compile just for the sake of a clean 'make bzImage modules' doesn't count as a fix, and your fix will be discarded, ignored or flamed.
|
|
|
