[Kernel-handbook-general] [PATCH 2/4] Convert all source files to DocBook format
Ben Hutchings
ben at decadent.org.uk
Thu Nov 5 22:49:58 UTC 2015
This was largely automatic using debiandoc2dbk, but I made the following
changes afterward:
- Rename files to match the old basenames
- Change <emphasis> inside <literal> (which is invalid) to <replaceable>
- Change <author> to <corpauthor> as the credited author is not a person
and the element contents were invalid
- Use entities defined in version.ent
- Set HTML output filenames to match debiandoc
- Add 'ch-' and 's-' prefixes to chapter and section IDs to match debiandoc
output
---
chapter-bugs.dbk | 474 +++++++++++++++++++++++++++++++++++++
chapter-bugs.sgml | 464 -------------------------------------
chapter-common-tasks.dbk | 578 ++++++++++++++++++++++++++++++++++++++++++++++
chapter-common-tasks.sgml | 504 ----------------------------------------
chapter-initramfs.dbk | 78 +++++++
chapter-initramfs.sgml | 74 ------
chapter-modules.dbk | 86 +++++++
chapter-modules.sgml | 88 -------
chapter-packaging.dbk | 223 ++++++++++++++++++
chapter-packaging.sgml | 213 -----------------
chapter-scope.dbk | 72 ++++++
chapter-scope.sgml | 58 -----
chapter-source.dbk | 71 ++++++
chapter-source.sgml | 81 -------
chapter-update-hooks.dbk | 156 +++++++++++++
chapter-update-hooks.sgml | 155 -------------
chapter-versions.dbk | 123 ++++++++++
chapter-versions.sgml | 125 ----------
debian/changelog | 1 +
kernel-handbook.dbk | 64 +++++
kernel-handbook.sgml | 68 ------
21 files changed, 1926 insertions(+), 1830 deletions(-)
create mode 100644 chapter-bugs.dbk
delete mode 100644 chapter-bugs.sgml
create mode 100644 chapter-common-tasks.dbk
delete mode 100644 chapter-common-tasks.sgml
create mode 100644 chapter-initramfs.dbk
delete mode 100644 chapter-initramfs.sgml
create mode 100644 chapter-modules.dbk
delete mode 100644 chapter-modules.sgml
create mode 100644 chapter-packaging.dbk
delete mode 100644 chapter-packaging.sgml
create mode 100644 chapter-scope.dbk
delete mode 100644 chapter-scope.sgml
create mode 100644 chapter-source.dbk
delete mode 100644 chapter-source.sgml
create mode 100644 chapter-update-hooks.dbk
delete mode 100644 chapter-update-hooks.sgml
create mode 100644 chapter-versions.dbk
delete mode 100644 chapter-versions.sgml
create mode 100644 kernel-handbook.dbk
delete mode 100644 kernel-handbook.sgml
diff --git a/chapter-bugs.dbk b/chapter-bugs.dbk
new file mode 100644
index 0000000..81df726
--- /dev/null
+++ b/chapter-bugs.dbk
@@ -0,0 +1,474 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<chapter id="ch-bugs">
+<?dbhtml filename="ch-bugs.html" ?>
+<title>Reporting and handling bugs</title>
+<section id="s9.1"><title>Bug handling policy for the kernel team</title>
+<section id="s9.1.1"><title>Required information</title>
+<para>
+Submitters are expected to run <command>reportbug</command> or other tool that
+runs our <systemitem role="package">bug</systemitem> script under the kernel
+version in question. The response to reports without this information should
+be a request to follow-up using <command>reportbug</command>. If we do not
+receive this information within a month of the request, the bug may be closed.
+</para>
+<para>
+Exceptions:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+If the kernel does not boot or is very unstable, instead of the usual system
+information we need the console messages via <ulink
+url="http://www.kernel.org/doc/Documentation/networking/netconsole.txt">netconsole</ulink>,
+<ulink url="http://www.kernel.org/doc/Documentation/serial-console.txt">serial
+console</ulink>, or a photograph.
+</para>
+</listitem>
+<listitem>
+<para>
+If the report is relaying information about a bug acknowledged upstream, we do
+not need system information but we do need specific references (<ulink
+url="http://bugzilla.kernel.org">bugzilla.kernel.org</ulink> or
+<command>git</command> commit id).
+</para>
+</listitem>
+<listitem>
+<para>
+If the bug is clearly not hardware-specific (e.g. packaging error), we do not
+need system information.
+</para>
+</listitem>
+<listitem>
+<para>
+If the bug is reported against a well-defined model, we may not need device
+listings.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s9.1.2"><title>Severities</title>
+<para>
+Many submitters report bugs with the wrong severity. We interpret the criteria
+as follows and will adjust severity as appropriate:
+</para>
+<variablelist>
+<varlistentry>
+<term>critical: makes unrelated software on the system (or the whole system) break...</term>
+<listitem>
+<para>
+The bug must make the kernel unbootable or unstable on common hardware or all
+systems that a specific flavour is supposed to support. There is no 'unrelated
+software' since everything depends on the kernel.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>grave: makes the package in question unusable or mostly so...</term>
+<listitem>
+<para>
+If the kernel is unusable, this already qualifies as critical.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>grave: ...or causes data loss...</term>
+<listitem>
+<para>
+We exclude loss of data in memory due to a crash. Only corruption of data in
+storage or communication, or silent failure to write data, qualifies.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>important</term>
+<listitem>
+<para>
+We include lack of support for new hardware that is generally available.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</section>
+
+<section id="s9.1.3"><title>Tagging</title>
+<para>
+We do not use user-tags. In order to aid bug triage we should make use of the
+standard tags and <literal>forwarded</literal> field defined by the BTS. In
+particular:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Add <literal>moreinfo</literal> whenever we are waiting for a response from the
+submitter and remove it when we are not
+</para>
+</listitem>
+<listitem>
+<para>
+Do not add <literal>unreproducible</literal> to bugs that may be
+hardware-dependent
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s9.1.4"><title>Analysis by maintainers</title>
+<para>
+Generally we should not expect to be able to reproduce bugs without having
+similar hardware. We should consider:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Searching <ulink url="http://bugzilla.kernel.org">bugzilla.kernel.org</ulink>
+(including closed bugs) or other relevant bug tracker
+</para>
+</listitem>
+<listitem>
+<para>
+Searching kernel mailing lists
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Of the many archives, <ulink url="http://news.gmane.org">news.gmane.org</ulink>
+seems to suck least
+</para>
+</listitem>
+<listitem>
+<para>
+Patches submitted to some lists are archived at <ulink
+url="http://patchwork.kernel.org">patchwork.kernel.org</ulink>
+</para>
+</listitem>
+</itemizedlist>
+</listitem>
+<listitem>
+<para>
+Viewing git commit logs for relevant source files
+</para>
+<itemizedlist>
+<listitem>
+<para>
+In case of a regression, from the known good to the bad version
+</para>
+</listitem>
+<listitem>
+<para>
+In other cases, from the bad version forwards, in case the bug has been fixed
+since
+</para>
+</listitem>
+</itemizedlist>
+</listitem>
+<listitem>
+<para>
+Searching kerneloops.org for similar oopses
+</para>
+</listitem>
+<listitem>
+<para>
+Matching the machine code and registers in an 'oops' against the source and
+deducing how the impossible happened (this doesn't work that often but when it
+does you look like a genius ;-)
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+<section id="s9.1.5"><title>Testing by submitter</title>
+<para>
+Depending on the technical sophistication of the submitter and the service
+requirements of the system in question (e.g. whether it's a production server)
+we can request one or more of the following:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Gathering more information passively (e.g. further logging, reporting contents
+of files in procfs or sysfs)
+</para>
+</listitem>
+<listitem>
+<para>
+Upgrading to the current stable/stable-proposed-updates/stable-security
+version, if it includes a fix for a similar bug
+</para>
+</listitem>
+<listitem>
+<para>
+Adding debug or fallback options to the kernel command line or module
+parameters
+</para>
+</listitem>
+<listitem>
+<para>
+Installing the unstable or backports version temporarily
+</para>
+</listitem>
+<listitem>
+<para>
+Rebuilding and installing the kernel with a specific patch added (the script
+<command>debian/bin/test-patches</command> should make this easy)
+</para>
+</listitem>
+<listitem>
+<para>
+Using <command>git bisect</command> to find a specific upstream change that
+introduced the bug
+</para>
+</listitem>
+</itemizedlist>
+<para>
+When a bug occurs in what upstream considers the current or previous stable
+release, and we cannot fix it, we ask the submitter to report it upstream at
+<ulink url="http://bugzilla.kernel.org">bugzilla.kernel.org</ulink> under a
+specific Product and Component, and to tell us the upstream bug number. We do
+not report bugs directly because follow-up questions from upstream need to go
+to the submitter, not to us. Given the upstream bug number, we mark the bug as
+forwarded. <command>bts-link</command> then updates its status.
+</para>
+</section>
+
+<section id="s9.1.6"><title>Keeping bugs separate</title>
+<para>
+Many submitters search for a characteristic error message and treat this as
+indicating a specific bug. This can lead to many 'me too' follow-ups where,
+for example, the message indicates a driver bug and the second submitter is
+using a different driver from the original submitter.
+</para>
+<para>
+In order to avoid the report turning into a mess of conflicting information
+about two or more different bugs:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+We should try to respond to such a follow-up quickly, requesting a separate bug
+report
+</para>
+</listitem>
+<listitem>
+<para>
+We can use the BTS <literal>summary</literal> command to improve the
+description of the bug
+</para>
+</listitem>
+<listitem>
+<para>
+As a last resort, it may be necessary to open new bugs with the relevant
+information, set their submitters accordingly, and close the original report
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Where the original report describes more than one bug ('...and other
+thing...'), we should clone it and deal with each separately.
+</para>
+</section>
+
+<section id="s9.1.7"><title>Applying patches</title>
+<para>
+Patches should normally be reviewed and accepted by the relevant upstream
+maintainer (aside from necessary adjustments for an older kernel version)
+before being applied.
+</para>
+</section>
+
+<section id="s9.1.8"><title>Talking to submitters</title>
+<para>
+We should always be polite to submitters. Not only is this implied by the
+<ulink url="http://www.debian.org/social_contract">Social Contract</ulink>, but
+it is likely to lead to a faster resolution of the bug. If a submitter
+overrated the severity, quietly downgrade it. If a submitter has done
+something stupid, request that they undo that and report back. 'Sorry' and
+'please' make a big difference in tone.
+</para>
+<para>
+We will maintain general advice to submitters at <ulink
+url="http://wiki.debian.org/DebianKernelReportingBugs">http://wiki.debian.org/DebianKernelReportingBugs</ulink>.
+</para>
+</section>
+
+</section>
+
+<section id="s9.2"><title>Filing a bug against a kernel package</title>
+<para>
+Debian kernel team keeps track of the kernel package bugs in the Debian Bug
+Tracking System (BTS). For information on how to use the system see <ulink
+url="http://bugs.debian.org">http://bugs.debian.org</ulink>. You can also
+submit the bugs by using the <literal>reportbug</literal> command from the
+package with the same name. Please note that kernel bugs found in
+distributions derived from Debian (such as Knoppix, Mepis, Progeny, Ubuntu,
+Xandros, etc.) should <emphasis>not</emphasis> be reported to the Debian BTS
+(unless they can be also reproduced on a Debian system using official Debian
+kernel packages). Derived distributions have their own policies and procedures
+regarding kernel packaging, so the bugs found in them should be reported
+directly to their bug tracking systems or mailing lists.
+</para>
+<para>
+Nothing in this chapter is intended to keep you from filing a bug against one
+of the Debian kernel packages. However, you should recognize that the
+resources of the Debian kernel team are limited, and efficient reaction to a
+bug is largely determined by the amount and quality of the information included
+in the bug report. Please help us to do a better job by using the following
+guidelines when preparing to file the bug against kernel packages:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<emphasis>Do the research.</emphasis> Before filing the bug search the web for
+the particular error message or symptom you are getting. As it is highly
+unlikely that you are the only person experiencing a particular problem, there
+is always a chance that it has been discussed elsewhere, and a possible
+solution, patch, or workaround has been proposed. If such information exists,
+always include the references to it in your report. Check the <ulink
+url="http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=linux&src=linux-2.6">current
+bug list</ulink> to see whether something similar has been reported already.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>Collect the information.</emphasis> Please provide enough information
+with your report. At a minimum, it should contain the exact version of the
+official Debian kernel package, where the bug is encountered, and steps to
+reproduce it. Depending on the nature of the bug you are reporting, you might
+also want to include the output of <literal>dmesg</literal> (or portions
+thereof), output of the <literal>lspci -vn</literal>.
+<command>reportbug</command> will do this automatically. If applicable,
+include the information about the latest known kernel version where the bug is
+not present, and output of the above commands for the working kernel as well.
+Use common sense and include other relevant information, if you think that it
+might help in solving the problem.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>Try to reproduce the problem with "vanilla" kernel.</emphasis> If you
+have a chance, try to reproduce the problem by building the binary kernel image
+from the "vanilla" kernel source, available from <ulink
+url="http://www.kernel.org">http://www.kernel.org</ulink> or its mirrors, using
+the same configuration as the Debian stock kernels. For more information on
+how to do this, look at <xref linkend="s-common-building"/>. If there is
+convincing evidence that the buggy behavior is caused by the Debian-specific
+changes to the kernel, the bug will usually be assigned higher priority by the
+kernel team. If the bug is not specific for Debian, check out the upstream
+<ulink url="http://bugzilla.kernel.org">kernel bug database</ulink> to see if
+it has been reported there. If you are sure that it is an upstream problem,
+you can also report your bug there (but submit it to Debian BTS anyway, so that
+we can track it properly).
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>Use the correct package to report the bug against.</emphasis> Please
+file bugs against the package containing the kernel version where the problem
+occurs (e.g. <systemitem
+role="package">linux-image-3.2.0-2-686-pae</systemitem>), not a metapackage
+(e.g. <systemitem role="package">linux-image-686-pae</systemitem>).
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>Bugs involving tainted kernels.</emphasis> If a kernel crashes, it
+normally prints out some debugging information, indicating, among other things,
+whether the running kernel has been tainted. The kernel is referred to as
+tainted if at the time of the crash it had some binary third-party modules
+loaded. As kernel developers do not have access to the source code for such
+modules, problems involving them are notoriously difficult to debug. It is
+therefore strongly recommended to try and reproduce the problem with an
+untainted kernel (by preventing the loading of binary modules, for example).
+If the problem is due to the presence of such modules, there is not much the
+kernel community can do about it and it should be reported directly to their
+authors.
+</para>
+</listitem>
+</itemizedlist>
+<section id="s9.2.1"><title>Bisecting (finding the upstream version that introduced a bug)</title>
+<para>
+When a bug is easy to reproduce locally but hard to get developers to reproduce
+(as is often true of workflow- or hardware-dependent bugs), it can be useful to
+compile and test a few versions to narrow down what changes introduced the
+regression.
+</para>
+<para>
+To start, recreate the problem with a vanilla kernel:
+</para>
+<screen>
+# apt-get install git build-essential
+$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+$ cd linux
+</screen>
+<para>
+The above commands acquire a vanilla kernel. Configure, build and test a
+binary package as explained in <xref linkend="s-common-building"/>:
+</para>
+<screen>
+$ make localmodconfig; # minimal configuration
+$ scripts/config --disable DEBUG_INFO; # to keep the build reasonably small
+$ make deb-pkg
+# dpkg -i ../linux-image-3.5.0_3.5.0-1_i386.deb; # substitute package name from the previous command
+# reboot
+</screen>
+<para>
+If the bug doesn't show up, try again with the official configuration file from
+/boot. (If it still doesn't show up after that, declare victory and
+celebrate.)
+</para>
+<para>
+Initialize the bisection process by declaring which versions worked and did not
+work:
+</para>
+<screen>
+$ cd linux
+$ git bisect start
+$ git bisect good v3.0; # or whichever was known to be good
+$ git bisect bad; # current version is bad
+</screen>
+<para>
+Now git checks out a version half-way in between to test. Build it, reusing
+the prepared configuration.
+</para>
+<screen>
+$ make silentoldconfig
+$ make deb-pkg
+</screen>
+<para>
+Install the package, reboot, and test.
+</para>
+<screen>
+$ git bisect good; # if this version doesn't exhibit the bug
+$ git bisect bad; # if it does
+$ git bisect skip; # if some other bug makes it hard to test
+</screen>
+<para>
+And on to the next iteration:
+</para>
+<screen>
+$ make silentoldconfig
+$ make deb-pkg
+</screen>
+<para>
+At the end of the process, the name of the "first bad commit" is printed, which
+is very useful for tracking down the bug. Narrowing down the regression range
+with a few rounds is useful even if you don't get that far; in that case, run
+<literal>git bisect log</literal> to produce a log. If you are the visual sort
+of person, <literal>git bisect visualize</literal> with the
+<literal>gitk</literal> package installed can show what is happening between
+steps.
+</para>
+<para>
+See Christian Couder's article "Fighting regressions with git bisect" from
+<ulink
+url="http://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html">kernel.org</ulink>
+or <ulink url="file:///usr/share/doc/git-doc/git-bisect-lk2009.html">the
+git-doc package</ulink> for details.
+</para>
+</section>
+
+</section>
+
+</chapter>
+
diff --git a/chapter-bugs.sgml b/chapter-bugs.sgml
deleted file mode 100644
index c892063..0000000
--- a/chapter-bugs.sgml
+++ /dev/null
@@ -1,464 +0,0 @@
- <chapt id="bugs">
- <heading>Reporting and handling bugs</heading>
-
- <sect>
- Bug handling policy for the kernel team
-
- <sect1>
- Required information
- <p>
- Submitters are expected to run <prgn>reportbug</prgn> or
- other tool that runs our <package>bug</package> script
- under the kernel version in question. The response to
- reports without this information should be a request to
- follow-up using <prgn>reportbug</prgn>. If we do not
- receive this information within a month of the request,
- the bug may be closed.
- </p>
- <p>
- Exceptions:
- <list>
- <item>
- If the kernel does not boot or is very unstable, instead
- of the usual system information we need the console
- messages via
- <url id="http://www.kernel.org/doc/Documentation/networking/netconsole.txt" name="netconsole">,
- <url id="http://www.kernel.org/doc/Documentation/serial-console.txt" name="serial console">,
- or a photograph.
- </item>
- <item>
- If the report is relaying information about a bug
- acknowledged upstream, we do not need system
- information but we do need specific references
- (<url id="http://bugzilla.kernel.org" name="bugzilla.kernel.org">
- or <prgn>git</prgn> commit id).
- </item>
- <item>
- If the bug is clearly not hardware-specific
- (e.g. packaging error), we do not need system
- information.
- </item>
- <item>
- If the bug is reported against a well-defined model, we
- may not need device listings.
- </item>
- </list>
- </p>
- </sect1>
-
- <sect1>
- Severities
- <p>
- Many submitters report bugs with the wrong severity. We
- interpret the criteria as follows and will adjust severity
- as appropriate:
- <taglist>
- <tag>
- critical: makes unrelated software on the system (or the
- whole system) break...
- </tag>
- <item>
- The bug must make the kernel unbootable or unstable on
- common hardware or all systems that a specific flavour
- is supposed to support. There is no 'unrelated
- software' since everything depends on the kernel.
- </item>
- <tag>
- grave: makes the package in question unusable or mostly
- so...
- </tag>
- <item>
- If the kernel is unusable, this already qualifies as
- critical.
- </item>
- <tag>
- grave: ...or causes data loss...
- </tag>
- <item>
- We exclude loss of data in memory due to a crash. Only
- corruption of data in storage or communication, or
- silent failure to write data, qualifies.
- </item>
- <tag>
- important
- </tag>
- <item>
- We include lack of support for new hardware that is
- generally available.
- </item>
- </taglist>
- </p>
- </sect1>
-
- <sect1>
- Tagging
- <p>
- We do not use user-tags. In order to aid bug triage we
- should make use of the standard tags
- and <tt>forwarded</tt> field defined by the BTS. In
- particular:
- <list>
- <item>
- Add <tt>moreinfo</tt> whenever we are waiting for a
- response from the submitter and remove it when we are
- not
- </item>
- <item>
- Do not add <tt>unreproducible</tt> to bugs that may be
- hardware-dependent
- </item>
- </list>
- </p>
- </sect1>
-
- <sect1>
- Analysis by maintainers
- <p>
- Generally we should not expect to be able to reproduce
- bugs without having similar hardware. We should consider:
- <list>
- <item>
- Searching <url id="http://bugzilla.kernel.org" name="bugzilla.kernel.org">
- (including closed bugs) or other relevant bug tracker
- </item>
- <item>
- Searching kernel mailing lists
- <list>
- <item>
- Of the many
- archives, <url id="http://news.gmane.org" name="news.gmane.org"> seems
- to suck least
- </item>
- <item>
- Patches submitted to some lists are archived at
- <url id="http://patchwork.kernel.org" name="patchwork.kernel.org">
- </item>
- </list>
- </item>
- <item>
- Viewing git commit logs for relevant source files
- <list>
- <item>
- In case of a regression, from the known good to the
- bad version
- </item>
- <item>
- In other cases, from the bad version forwards, in
- case the bug has been fixed since
- </item>
- </list>
- </item>
- <item>
- Searching kerneloops.org for similar oopses
- </item>
- <item>
- Matching the machine code and registers in an 'oops'
- against the source and deducing how the impossible
- happened (this doesn't work that often but when it does
- you look like a genius ;-)
- </item>
- </list>
- </p>
- </sect1>
-
- <sect1>
- Testing by submitter
- <p>
- Depending on the technical sophistication of the submitter
- and the service requirements of the system in question
- (e.g. whether it's a production server) we can request one
- or more of the following:
- <list>
- <item>
- Gathering more information passively (e.g. further
- logging, reporting contents of files in procfs or sysfs)
- </item>
- <item>
- Upgrading to the current
- stable/stable-proposed-updates/stable-security version,
- if it includes a fix for a similar bug
- </item>
- <item>
- Adding debug or fallback options to the kernel command
- line or module parameters
- </item>
- <item>
- Installing the unstable or backports version temporarily
- </item>
- <item>
- Rebuilding and installing the kernel with a specific
- patch added (the
- script <prgn>debian/bin/test-patches</prgn> should make
- this easy)
- </item>
- <item>
- Using <prgn>git bisect</prgn> to find a specific
- upstream change that introduced the bug
- </item>
- </list>
- </p>
- <p>
- When a bug occurs in what upstream considers the current
- or previous stable release, and we cannot fix it, we ask
- the submitter to report it upstream at
- <url id="http://bugzilla.kernel.org" name="bugzilla.kernel.org">
- under a specific Product and Component, and to tell us
- the upstream bug number. We do not report bugs directly
- because follow-up questions from upstream need to go to
- the submitter, not to us. Given the upstream bug number,
- we mark the bug as forwarded.
- <prgn>bts-link</prgn> then updates its status.
- </p>
- </sect1>
-
- <sect1>
- Keeping bugs separate
- <p>
- Many submitters search for a characteristic error message
- and treat this as indicating a specific bug. This can
- lead to many 'me too' follow-ups where, for example, the
- message indicates a driver bug and the second submitter is
- using a different driver from the original submitter.
- </p>
- <p>
- In order to avoid the report turning into a mess of
- conflicting information about two or more different bugs:
- <list>
- <item>
- We should try to respond to such a follow-up quickly,
- requesting a separate bug report
- </item>
- <item>
- We can use the BTS <tt>summary</tt> command to improve
- the description of the bug
- </item>
- <item>
- As a last resort, it may be necessary to open new bugs
- with the relevant information, set their submitters
- accordingly, and close the original report
- </item>
- </list>
- </p>
- <p>
- Where the original report describes more than one bug
- ('...and other thing...'), we should clone it and deal
- with each separately.
- </p>
- </sect1>
-
- <sect1>
- Applying patches
- <p>
- Patches should normally be reviewed and accepted by the
- relevant upstream maintainer (aside from necessary
- adjustments for an older kernel version) before being
- applied.
- </p>
- </sect1>
-
- <sect1>
- Talking to submitters
- <p>
- We should always be polite to submitters. Not only is
- this implied by the
- <url id="http://www.debian.org/social_contract"
- name="Social Contract">, but it is likely to lead to a
- faster resolution of the bug. If a submitter overrated
- the severity, quietly downgrade it. If a submitter has
- done something stupid, request that they undo that and
- report back. 'Sorry' and 'please' make a big difference
- in tone.
- </p>
- <p>
- We will maintain general advice to submitters at
- <url id="http://wiki.debian.org/DebianKernelReportingBugs"
- name="http://wiki.debian.org/DebianKernelReportingBugs">.
- </p>
- </sect1>
-
- </sect>
-
- <sect>
- Filing a bug against a kernel package
-
- <p>
- Debian kernel team keeps track of the kernel package bugs in
- the Debian Bug Tracking System (BTS). For information on how
- to use the system see <url id="http://bugs.debian.org"
- name="http://bugs.debian.org">. You can also submit the bugs
- by using the <tt>reportbug</tt> command from the package with
- the same name. Please note that kernel bugs found in
- distributions derived from Debian (such as Knoppix, Mepis,
- Progeny, Ubuntu, Xandros, etc.) should <em>not</em> be
- reported to the Debian BTS (unless they can be also reproduced
- on a Debian system using official Debian kernel
- packages). Derived distributions have their own policies and
- procedures regarding kernel packaging, so the bugs found in
- them should be reported directly to their bug tracking systems
- or mailing lists.
- </p>
- <p>
- Nothing in this chapter is intended to keep you from filing a
- bug against one of the Debian kernel packages. However, you should
- recognize that the resources of the Debian kernel team are
- limited, and efficient reaction to a bug is largely determined
- by the amount and quality of the information included in the
- bug report. Please help us to do a better job by using the
- following guidelines when preparing to file the bug against
- kernel packages:
- <list>
- <item>
- <em>Do the research.</em> Before filing the bug search the
- web for the particular error message or symptom you are
- getting. As it is highly unlikely that you are the only
- person experiencing a particular problem, there is always a
- chance that it has been discussed elsewhere, and a possible
- solution, patch, or workaround has been proposed. If such
- information exists, always include the references to it in
- your report. Check the <url id="http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=linux&src=linux-2.6" name="current bug list">
- to see whether something similar has been reported already.
- </item>
- <item>
- <em>Collect the information.</em> Please provide enough
- information with your report. At a minimum, it should
- contain the exact version of the official Debian kernel
- package, where the bug is encountered, and steps to
- reproduce it. Depending on the nature of the bug you are
- reporting, you might also want to include the output of
- <tt>dmesg</tt> (or portions thereof), output of the
- <tt>lspci -vn</tt>. <prgn>reportbug</prgn> will do this
- automatically. If applicable,
- include the information about the latest known kernel
- version where the bug is not present, and output of the
- above commands for the working kernel as well. Use
- common sense and include other relevant information,
- if you think that it might help in solving the problem.
- </item>
- <item>
- <em>Try to reproduce the problem with "vanilla" kernel.</em>
- If you have a chance, try to reproduce the problem by
- building the binary kernel image from the "vanilla" kernel
- source, available from <url id="http://www.kernel.org"
- name="http://www.kernel.org"> or its mirrors, using the same
- configuration as the Debian stock kernels. For more
- information on how to do this, look at <ref
- id="common-building">. If there is convincing evidence that
- the buggy behavior is caused by the Debian-specific changes
- to the kernel, the bug will usually be assigned higher
- priority by the kernel team. If the bug is not specific for
- Debian, check out the upstream <url
- id="http://bugzilla.kernel.org" name="kernel bug database">
- to see if it has been reported there. If you are sure that
- it is an upstream problem, you can also report your bug
- there (but submit it to Debian BTS anyway, so that we can
- track it properly).
- </item>
- <item>
- <em>Use the correct package to report the bug against.</em>
- Please file bugs against the package containing the kernel
- version where the problem occurs
- (e.g. <package>linux-image-3.2.0-2-686-pae</package>), not
- a metapackage (e.g. <package>linux-image-686-pae</package>).
- </item>
- <item>
- <em>Bugs involving tainted kernels.</em> If a kernel
- crashes, it normally prints out some debugging
- information, indicating, among other things, whether the
- running kernel has been tainted. The kernel is referred to
- as tainted if at the time of the crash it had some binary
- third-party modules loaded. As kernel developers do not
- have access to the source code for such modules, problems
- involving them are notoriously difficult to debug. It is
- therefore strongly recommended to try and reproduce the
- problem with an untainted kernel (by preventing the loading
- of binary modules, for example). If the problem is due to
- the presence of such modules, there is not much the kernel
- community can do about it and it should be reported directly
- to their authors.
- </item>
- </list>
- </p>
-
- <sect1>
- Bisecting (finding the upstream version that introduced a bug)
-
- <p>
- When a bug is easy to reproduce locally but hard to get developers
- to reproduce (as is often true of workflow- or hardware-dependent
- bugs), it can be useful to compile and test a few versions to narrow
- down what changes introduced the regression.
- </p>
-
- <p>
- To start, recreate the problem with a vanilla kernel:
- <example>
-# apt-get install git build-essential
-$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-$ cd linux
- </example>
- The above commands acquire a vanilla kernel.
- Configure, build and test a binary package as explained in
- <ref id="common-building">:
- <example>
-$ make localmodconfig; # minimal configuration
-$ scripts/config --disable DEBUG_INFO; # to keep the build reasonably small
-$ make deb-pkg
-# dpkg -i ../linux-image-3.5.0_3.5.0-1_i386.deb; # substitute package name from the previous command
-# reboot
- </example>
- If the bug doesn't show up, try again with the official
- configuration file from /boot. (If it still doesn't show up
- after that, declare victory and celebrate.)
- </p>
-
- <p>
- Initialize the bisection process by declaring which versions worked
- and did not work:
- <example>
-$ cd linux
-$ git bisect start
-$ git bisect good v3.0; # or whichever was known to be good
-$ git bisect bad; # current version is bad
- </example>
- Now git checks out a version half-way in between to test.
- Build it, reusing the prepared configuration.
- <example>
-$ make silentoldconfig
-$ make deb-pkg
- </example>
- </p>
-
- <p>
- Install the package, reboot, and test.
- <example>
-$ git bisect good; # if this version doesn't exhibit the bug
-$ git bisect bad; # if it does
-$ git bisect skip; # if some other bug makes it hard to test
- </example>
- And on to the next iteration:
- <example>
-$ make silentoldconfig
-$ make deb-pkg
- </example>
- </p>
-
- <p>
- At the end of the process, the name of the "first bad commit" is
- printed, which is very useful for tracking down the bug. Narrowing
- down the regression range with a few rounds is useful even if you
- don't get that far; in that case, run <tt>git bisect log</tt> to
- produce a log. If you are the visual sort of person, <tt>git bisect
- visualize</tt> with the <tt>gitk</tt> package installed can show
- what is happening between steps.
- </p>
-
- <p>
- See Christian Couder's article "Fighting regressions with git bisect"
- from <url id="http://www.kernel.org/pub/software/scm/git/docs/git-bisect-lk2009.html"
- name="kernel.org"> or <url id="file:///usr/share/doc/git-doc/git-bisect-lk2009.html"
- name="the git-doc package"> for details.
- </p>
- </sect1>
- </sect>
-</chapt>
-
diff --git a/chapter-common-tasks.dbk b/chapter-common-tasks.dbk
new file mode 100644
index 0000000..1486cf3
--- /dev/null
+++ b/chapter-common-tasks.dbk
@@ -0,0 +1,578 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<chapter id="ch-common-tasks">
+<?dbhtml filename="ch-common-tasks.html" ?>
+<title>Common kernel-related tasks</title>
+<section id="s-common-getting"><title>Obtaining the Debian kernel source</title>
+<para>
+To get the Debian kernel source at the current maximum patchlevel, it is
+sufficient to install the latest
+<literal>linux-source-<replaceable>version</replaceable></literal> package and unpack
+the source, for example:
+</para>
+<screen>
+# apt-get install linux-source-3.2
+$ tar jxf /usr/src/linux-source-3.2.tar.bz2
+</screen>
+<para>
+The unpacked source tree then will be available in
+<literal>linux-source-3.2</literal> directory.
+</para>
+</section>
+
+<section id="s-common-official"><title>Rebuilding official Debian kernel packages</title>
+<para>
+You can build all or selected kernel packages by following these instructions.
+You may be asked to do this in order to test a potential bug fix.
+</para>
+<section id="s4.2.1"><title>Preparation</title>
+<para>
+For Debian 6.0 (squeeze) and earlier versions, substitute the source package
+name <literal>linux-2.6</literal> for <literal>linux</literal>.
+</para>
+<para>
+Run the following commands:
+</para>
+<variablelist>
+<varlistentry>
+<term><literal># apt-get install build-essential fakeroot</literal></term>
+<term><literal># apt-get build-dep linux</literal></term>
+<listitem>
+<para>
+This will install the packages required by the kernel build process.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>$ apt-get source linux</literal></term>
+<listitem>
+<para>
+This will download and unpack the <literal>linux</literal> source package,
+making the tree available in the
+<literal>linux-<replaceable>version</replaceable></literal> directory. As always,
+the revision part of the version of this package (for example, 1 in 3.2.19-1)
+will determine its patchlevel with respect to the original upstream kernel
+source.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>$ cd linux-<replaceable>version</replaceable></literal></term>
+<listitem>
+<para>
+Enter the source directory.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<section id="s-common-size"><title>Disk space requirements</title>
+<para>
+Building binary packages for a single kernel flavour with debug info enabled
+(currently true for the <literal>686-pae</literal>, <literal>amd64</literal>,
+<literal>rt-686-pae</literal>, <literal>rt-amd64</literal> and
+<literal>s390x</literal> configurations) requires up to 10 GB space in the
+package directory and 300 MB in <literal>/tmp</literal> (or
+<literal>$TMPDIR</literal>).
+</para>
+<para>
+Building with debug info disabled requires about 2 GB and 25 MB respectively.
+You can disable debug info by changing the value of
+<literal>debug-info</literal> to <literal>false</literal> in
+<literal>debian/config/</literal><replaceable>arch</replaceable><literal>/defines</literal>.
+</para>
+<para>
+Building all binary packages for i386 or amd64 currently requires about 20 GB
+space in the package directory. Other architectures with no debug info or
+fewer drivers will require less space.
+</para>
+</section>
+
+</section>
+
+<section id="s4.2.2"><title>Simple patching and building</title>
+<para>
+The source package includes a script to simplify the process of building with
+extra patches. You can use this by running commands such as:
+</para>
+<screen>
+# apt-get install devscripts
+$ bash debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch
+</screen>
+<para>
+This script has options to control the flavour, featureset, etc. For a summary
+of the options, run:
+</para>
+<screen>
+$ bash debian/bin/test-patches
+</screen>
+<para>
+You may then need to build the linux-base package as well:
+</para>
+<screen>
+$ fakeroot make -f debian/rules.real install-linux-base
+</screen>
+<para>
+However, if you need to change the configuration or make other changes, you
+should not use this script and should follow the instructions below.
+</para>
+</section>
+
+<section id="s4.2.3"><title>Applying patches or configuration changes</title>
+<para>
+It is possible to apply extra patches to the source before starting the build.
+In the <literal>linux</literal> source package, the default (non-featureset)
+patches are automatically applied in the top level directory. If you are
+building the <literal>linux-2.6</literal> source package or building with a
+featureset, you should first apply the existing patches by running:
+</para>
+<screen>
+$ fakeroot debian/rules source
+</screen>
+<para>
+The patched source appears in the following directories.
+</para>
+<variablelist>
+<varlistentry>
+<term>linux default source:</term>
+<listitem>
+<para>
+top level
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>linux source with featureset:</term>
+<listitem>
+<para>
+<literal>debian/build/source_<replaceable>featureset</replaceable></literal>
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>linux-2.6</literal> default source:</term>
+<listitem>
+<para>
+<literal>debian/build/source_<replaceable>arch</replaceable>_none</literal>
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>linux-2.6</literal> source with featureset:</term>
+<listitem>
+<para>
+<literal>debian/build/source_<replaceable>arch</replaceable>_<replaceable>featureset</replaceable></literal>
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>
+You should apply the extra patches in the appropriate directory. In the
+<literal>linux</literal> source package you can use the
+<literal>quilt</literal> utility to do this.
+</para>
+<para>
+To change the configuration before building, for example for the 686-pae
+flavour on i386, run the commands:
+</para>
+<screen>
+$ fakeroot make -f debian/rules.gen setup_i386_none_686-pae
+$ make -C debian/build/build_i386_none_686-pae menuconfig
+</screen>
+<para>
+If the patches or configuration changes alter type definitions for the kernel,
+you may need to change the ABI name; see <xref linkend="s-abi-name"/>.
+</para>
+</section>
+
+<section id="s4.2.4"><title>Building many packages</title>
+<para>
+To build all possible packages for this architecture, run:
+</para>
+<screen>
+$ fakeroot debian/rules binary
+</screen>
+<para>
+To build all architecture-dependent packages, run:
+</para>
+<screen>
+$ fakeroot debian/rules binary-arch
+</screen>
+<para>
+To build all architecture-independent packages, run:
+</para>
+<screen>
+$ fakeroot debian/rules binary-indep
+</screen>
+</section>
+
+<section id="s4.2.5"><title>Building packages for one flavour</title>
+<para>
+For example, to build only the binary packages for 686-pae flavour on i386
+architecture, use the following commands:
+</para>
+<screen>
+$ fakeroot debian/rules source
+$ fakeroot make -f debian/rules.gen binary-arch_i386_none_686-pae
+</screen>
+<para>
+The target in this command has the general form of
+<literal><replaceable>target</replaceable>_<replaceable>arch</replaceable>_<replaceable>featureset</replaceable>_<replaceable>flavour</replaceable></literal>.
+Replace the <literal><replaceable>featureset</replaceable></literal> with
+<literal>none</literal> if you do not want any of the extra featuresets. This
+command will build the linux image and kernel headers packages. You may also
+need the <literal>linux-headers-<replaceable>version</replaceable>-common</literal>
+binary package, which can be built using the commands:
+</para>
+<screen>
+$ fakeroot debian/rules source
+$ fakeroot make -f debian/rules.gen binary-arch_i386_none_real
+</screen>
+<para>
+The target in this command has the general form of
+<literal><replaceable>target</replaceable>_<replaceable>arch</replaceable>_<replaceable>featureset</replaceable>_<replaceable>real</replaceable></literal>
+</para>
+</section>
+
+</section>
+
+<section id="s-common-official-vcs"><title>Building a development version of the Debian kernel package</title>
+<para>
+For Debian 6.0 (squeeze) and earlier versions, substitute the source package
+name <literal>linux-2.6</literal> for <literal>linux</literal>.
+</para>
+<para>
+To build a kernel image based on the kernel team's unreleased development
+version:
+</para>
+<variablelist>
+<varlistentry>
+<term><literal># apt-get install build-essential fakeroot rsync git</literal></term>
+<term><literal># apt-get build-dep linux</literal></term>
+<listitem>
+<para>
+The last two commands will install the build dependencies required by the
+kernel build process.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>$ git clone -b <replaceable>dist</replaceable> --single-branch https://anonscm.debian.org/git/kernel/linux.git</literal></term>
+<listitem>
+<para>
+This will check out the Debian packaging. <replaceable>dist</replaceable> is
+normally the distribution codename such as <literal>wheezy</literal> or
+<literal>sid</literal> (unstable). For the very latest version, usually based
+on an upstream release candidate, use <literal>master</literal>. Note that
+this will download several hundred megabytes of data.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>$ apt-get source -d linux</literal></term>
+<listitem>
+<para>
+This will download the <literal>linux</literal> upstream source (and the last
+released Debian patches). Depending on which version you are trying to build,
+you might need to override APT's version selection or download a tarball from
+<ulink url="http://people.debian.org">people.debian.org</ulink> instead.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>$ cd linux</literal></term>
+<term><literal>$ debian/rules orig</literal></term>
+<listitem>
+<para>
+This unpacks the upstream source and merges it with the Debian packaging.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>$ debian/rules debian/control</literal></term>
+<listitem>
+<para>
+This generates a Debian package control file based on the current definitions
+of the various kernel flavours which can be built.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>$ fakeroot debian/rules <replaceable>target</replaceable></literal></term>
+<listitem>
+<para>
+Finally, build binary packages as explained in <xref
+linkend="s-common-official"/>.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</section>
+
+<section id="s-gen-orig"><title>Generating orig tarball from newer upstream</title>
+<para>
+First you must add a changelog entry for the new upstream version. If the new
+version is a release candidate, change the string <literal>-rc</literal> to
+<literal>~rc</literal>. (In Debian package versions, a suffix beginning with
+<literal>~</literal> indicates a pre-release.)
+</para>
+<para>
+The 'orig' tarball is generated by the <literal>genorig.py</literal> script.
+It takes either a tarball and optional patch from kernel.org, or a git
+repository. First ensure you have the necessary tools installed:
+</para>
+<screen>
+# apt-get install unifdef
+</screen>
+<para>
+Then if you have a tarball, run a command such as:
+</para>
+<screen>
+$ debian/bin/genorig.py ../linux-3.4.tar.bz2 ../patch-3.5-rc1.bz2
+</screen>
+<para>
+Or if you have a git repository, pass the name of its directory:
+</para>
+<screen>
+$ debian/bin/genorig.py ~/src/linux
+</screen>
+<para>
+Either of these will generate a file such as
+<literal>../orig/linux_3.5~rc1.orig.tar.xz</literal>. You can then combine
+this tarball with the Debian packaging by running:
+</para>
+<screen>
+$ debian/rules orig
+</screen>
+</section>
+
+<section id="s-common-building"><title>Building a custom kernel from Debian kernel source</title>
+<para>
+This section describes the simplest possible procedure to build a custom kernel
+the "Debian way". It is assumed that user is somewhat familiar with kernel
+configuration and build process. If that's not the case, it is recommended to
+consult the kernel documentation and many excellent online resources dedicated
+to it.
+</para>
+<para>
+The easiest way to build a custom kernel (the kernel with the configuration
+different from the one used in the official packages) from the Debian kernel
+source is to use the <literal>linux-source</literal> package and the
+<literal>make deb-pkg</literal> target. First, prepare the kernel tree:
+</para>
+<screen>
+# apt-get install linux-source-3.2
+$ tar xjf /usr/src/linux-source-3.2.tar.bz2
+$ cd linux-source-3.2
+</screen>
+<para>
+The kernel now needs to be configured, that is you have to set the kernel
+options and select the drivers which are going to be included, either as
+built-in, or as external modules. The kernel build infrastructure offers a
+number of targets, which invoke different configuration frontends. For
+example, one can use console-based menu configuration by invoking the command
+</para>
+<screen>
+$ make menuconfig
+</screen>
+<para>
+Instead of <literal>menuconfig</literal> one can use <literal>config</literal>
+(text-based line-by-line configuration frontend) or <literal>xconfig</literal>
+(graphical configuration frontend). It is also possible to reuse your old
+configuration file by placing it as a <literal>.config</literal> file in the
+top-level directory and running one of the configuration targets (if you want
+to adjust something) or <literal>make oldconfig</literal> (to keep the same
+configuration). Note that different frontends may require different additional
+libraries and utilities to be installed to function properly. For example, the
+<literal>menuconfig</literal> frontend requires the <literal>ncurses</literal>
+library, which at time of writing is provided by the
+<literal>libncurses5-dev</literal> package.
+</para>
+<para>
+The build will use less disk space if the CONFIG_DEBUG_INFO option is disabled
+(see <xref linkend="s-common-size"/>). Debuginfo is only needed if you plan to
+use binary object tools like crash, kgdb, and SystemTap on the kernel.
+</para>
+<screen>
+$ scripts/config --disable DEBUG_INFO
+</screen>
+<para>
+After the configuration process is finished, the new or updated kernel
+configuration will be stored in <literal>.config</literal> file in the
+top-level directory. The build is started using the commands
+</para>
+<screen>
+$ make clean
+$ make deb-pkg
+</screen>
+<para>
+As a result of the build, a custom kernel package
+<literal>linux-image-3.2.19_3.2.19-1_i386.deb</literal> (name will reflect the
+version of the kernel and build number) will be created in the directory one
+level above the top of the tree. It may be installed using
+<literal>dpkg</literal> just as any other package:
+</para>
+<screen>
+
+# dpkg -i ../linux-image-3.2.19_3.2.19-1_i386.deb
+</screen>
+<para>
+This command will unpack the kernel, generate the initrd if necessary (see
+<xref linkend="ch-initramfs"/> for details), and configure the bootloader to make
+the newly installed kernel the default one. If this command completed without
+any problems, you can reboot using the
+</para>
+<screen>
+# shutdown -r now
+</screen>
+<para>
+command to boot the new kernel.
+</para>
+<para>
+For much more information about bootloaders and their configuration please
+check their documentation, which can be accessed using the commands
+<literal>man lilo</literal>, <literal>man lilo.conf</literal>, <literal>man
+grub</literal>, and so on. You can also look for documentation in the
+<literal>/usr/share/doc/<replaceable>package</replaceable></literal> directories,
+with <literal><replaceable>package</replaceable></literal> being the name of the
+package involved.
+</para>
+</section>
+
+<section id="s-kernel-org-package"><title>Building a custom kernel from the "pristine" kernel source</title>
+<para>
+Building a kernel from the "pristine" (also sometimes called "vanilla") kernel
+source, distributed from <ulink
+url="http://www.kernel.org">www.kernel.org</ulink> and its mirrors, may be
+occasionally useful for debugging or in the situations when a newer kernel
+version is desired. The procedure differs only in obtaining the kernel source:
+instead of unpacking the kernel source from Debian packages, the "pristine"
+source is downloaded using your favourite browser or using wget, as follows:
+</para>
+<screen>
+
+$ wget http://kernel.org/pub/linux/kernel/v3.x/linux-3.4.tar.bz2
+</screen>
+<para>
+The integrity of the downloaded archive may be verified by fetching the
+corresponding cryptographic signature
+</para>
+<screen>
+
+$ wget http://kernel.org/pub/linux/kernel/v3.x/linux-3.4.tar.sign
+</screen>
+<para>
+and running this command (<literal>gnupg</literal> package must be installed):
+</para>
+<screen>
+$ bunzip2 -c linux-3.4.tar.bz2 | gpg --verify linux-3.4.tar.sign -
+</screen>
+<para>
+Successful verification results in output similar to the one below:
+</para>
+<screen>
+gpg: Signature made Mon 21 May 2012 01:48:14 AM CEST using RSA key ID 00411886
+gpg: Good signature from "Linus Torvalds <torvalds at linux-foundation.org>"
+gpg: WARNING: This key is not certified with a trusted signature!
+gpg: There is no indication that the signature belongs to the owner.
+Primary key fingerprint: ABAF 11C6 5A29 70B1 30AB E3C4 79BE 3E43 0041 1886
+</screen>
+<para>
+After that the archive may be unpacked using
+</para>
+<screen>
+$ tar xjf linux-3.4.tar.bz2
+$ cd linux-3.4
+</screen>
+<para>
+The unpacked kernel tree (in <literal>linux-3.4</literal> now has to be
+configured. The existing configuration file may be used as a starting point
+</para>
+<screen>
+$ cp /boot/config-3.2.0-2-686-pae ./.config
+</screen>
+<para>
+After the configuration with one of the configuration frontends (invoked by
+<literal>make oldconfig</literal>, <literal>make config</literal>,
+<literal>make menuconfig</literal>, etc) is completed, the build may be started
+using <literal>make deb-pkg</literal> target as described above.
+</para>
+</section>
+
+<section id="s-common-out-of-tree"><title>Building out-of-tree kernel modules</title>
+<para>
+Some kernel modules are not included in the upstream or Debian kernel source,
+but are provided as third-party source packages. For some of the most popular
+out-of-tree modules, the binary Debian packages with modules built against the
+stock Debian kernels are provided. For example, if you are running stock
+Debian kernel <literal>3.2.0-2-686-pae</literal> (use the <literal>uname
+-r</literal> command to verify the version) from the
+<literal>linux-image-3.2.0-2-686-pae</literal> package, and would like to use
+the squash filesystem, all you need to do is install
+<literal>squashfs-modules-3.2.0-2-686-pae</literal> binary package, which
+provides the neccessary binary kernel modules.
+</para>
+<para>
+If you are not so lucky, and there are no binary module packages in the
+archive, there is a fair chance that the Debian archive contains the packaged
+<replaceable role="strong">source</replaceable> for the kernel modules. Names of
+such packages typically end in <literal>-source</literal>, for example
+<literal>squashfs-source</literal>, <literal>thinkpad-source</literal>,
+<literal>rt2x00-source</literal> and many others. These packages contain
+debianized source code of the kernel modules, suitable for building using the
+<literal>module-assistant</literal> (or <literal>m-a</literal>) script from the
+<literal>module-assistant</literal> package. Typical sequence to build a
+custom binary module package, matching a kernel
+<literal>3.2.0-2-686-pae</literal> (as returned by <literal>uname -r</literal>)
+from the debianized source consists of the following steps:
+</para>
+<para>
+Install a set of kernel headers, matching the kernel for which the modules are
+going to be built:
+</para>
+<screen>
+# apt-get install linux-headers-3.2.0-2-686-pae
+</screen>
+<para>
+Install the package containing the source:
+</para>
+<screen>
+# apt-get install squashfs-source
+</screen>
+<para>
+Invoke <literal>module-assistant</literal> (aka <literal>m-a</literal>) to do
+the heavy lifting:
+</para>
+<screen>
+# m-a build squashfs
+</screen>
+<para>
+As a result, a Debian package is going to be built and placed in
+<literal>/usr/src</literal>. It can be installed the usual way, using
+<literal>dpkg -i</literal>. Two last steps (building and installation) may be
+combined using the invocation
+</para>
+<screen>
+# m-a auto-install squashfs
+</screen>
+<para>
+Check out the <literal>module-assistant</literal> documentation (<literal>man
+module-assistant</literal>) for other options and much more information on how
+to use it.
+</para>
+<para>
+Finally, in some rare circumstances, you might need to build the kernel modules
+from the upstream source packages. In that case, follow the documentation
+included with the package to build the modules. If the build process will
+require you to specify the directory with the kernel headers, matching the
+currently running kernel, for stock Debian kernels this directory is
+<literal>/usr/src/linux-headers-<replaceable>uname</replaceable></literal>, provided
+by the <literal>linux-headers-<replaceable>uname</replaceable></literal> package.
+Here <literal><replaceable>uname</replaceable></literal> is the output of the
+<literal>uname -r</literal> command. If you are building and running your own
+custom kernels, it is a good idea to keep the original build tree around, as it
+also can be used for out-of-tree module building.
+</para>
+</section>
+
+</chapter>
+
diff --git a/chapter-common-tasks.sgml b/chapter-common-tasks.sgml
deleted file mode 100644
index 1420c05..0000000
--- a/chapter-common-tasks.sgml
+++ /dev/null
@@ -1,504 +0,0 @@
- <chapt id="common-tasks">
- <heading>Common kernel-related tasks</heading>
- <sect id="common-getting">
- <heading>Obtaining the Debian kernel source</heading>
- <p>
- To get the Debian kernel source at the current maximum patchlevel,
- it is sufficient to install the latest <tt>linux-source-<em>version</em></tt>
- package and unpack the source, for example:
- <example>
-# apt-get install linux-source-3.2
-$ tar jxf /usr/src/linux-source-3.2.tar.bz2
- </example>
- The unpacked source tree then will be available in <tt>linux-source-3.2</tt> directory.
- </p>
- </sect>
- <sect id="common-official">
- <heading>Rebuilding official Debian kernel packages</heading>
- <p>
- You can build all or selected kernel packages by following
- these instructions. You may be asked to do this in order to
- test a potential bug fix.
- </p>
- <sect1>
- <heading>Preparation</heading>
- <p>
- For Debian 6.0 (squeeze) and earlier versions, substitute
- the source package name <tt>linux-2.6</tt> for
- <tt>linux</tt>.
- </p>
- <p>
- Run the following commands:
- <taglist>
- <tag><tt># apt-get install build-essential fakeroot</tt></tag>
- <tag><tt># apt-get build-dep linux</tt></tag>
- <item>
- This will install the packages required by the kernel
- build process.
- </item>
- <tag><tt>$ apt-get source linux</tt></tag>
- <item>
- This will download and unpack the
- <tt>linux</tt> source package, making the
- tree available in the
- <tt>linux-<em>version</em></tt>
- directory. As always, the revision part of the version
- of this package (for example, 1 in 3.2.19-1) will
- determine its patchlevel with respect to the original
- upstream kernel source.
- </item>
- <tag><tt>$ cd linux-<em>version</em></tt></tag>
- <item>
- Enter the source directory.
- </item>
- </taglist>
- </p>
- <sect2 id="common-size">
- <heading>Disk space requirements</heading>
- <p>
- Building binary packages for a single kernel flavour
- with debug info enabled (currently true for
- the <tt>686-pae</tt>, <tt>amd64</tt>, <tt>rt-686-pae</tt>,
- <tt>rt-amd64</tt> and <tt>s390x</tt> configurations)
- requires up to 10 GB space in the package directory
- and 300 MB in <tt>/tmp</tt> (or <tt>$TMPDIR</tt>).
- </p>
- <p>
- Building with debug info disabled requires about
- 2 GB and 25 MB respectively. You can disable
- debug info by changing the value of <tt>debug-info</tt>
- to <tt>false</tt> in
- <tt>debian/config/</tt><var>arch</var><tt>/defines</tt>.
- </p>
- <p>
- Building all binary packages for i386 or amd64 currently
- requires about 20 GB space in the package
- directory. Other architectures with no debug info or
- fewer drivers will require less space.
- </p>
- </sect2>
- </sect1>
- <sect1>
- <heading>Simple patching and building</heading>
- <p>
- The source package includes a script to simplify the
- process of building with extra patches. You can use this
- by running commands such as:
- <example>
-# apt-get install devscripts
-$ bash debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch
- </example>
- This script has options to control the flavour, featureset,
- etc. For a summary of the options, run:
- <example>
-$ bash debian/bin/test-patches
- </example>
- </p>
- <p>
- You may then need to build the linux-base package as well:
- <example>
-$ fakeroot make -f debian/rules.real install-linux-base
- </example>
- </p>
- <p>
- However, if you need to change the configuration or make
- other changes, you should not use this script and should
- follow the instructions below.
- </p>
- </sect1>
- <sect1>
- <heading>Applying patches or configuration changes</heading>
- <p>
- It is possible to apply extra patches to the source before
- starting the build. In the <tt>linux</tt> source package,
- the default (non-featureset) patches are automatically
- applied in the top level directory. If you are building
- the <tt>linux-2.6</tt> source package or building with a
- featureset, you should first apply the existing patches by
- running:
- <example>
-$ fakeroot debian/rules source
- </example>
- The patched source appears in the following directories.
- <taglist>
- <tag>linux default source:</tag>
- <item>top level</item>
- <tag>linux source with featureset:</tag>
- <item><tt>debian/build/source_<em>featureset</em></tt></item>
- <tag><tt>linux-2.6</tt> default source:</tag>
- <item><tt>debian/build/source_<em>arch</em>_none</tt></item>
- <tag><tt>linux-2.6</tt> source with featureset:</tag>
- <item><tt>debian/build/source_<em>arch</em>_<em>featureset</em></tt></item>
- </taglist>
- You should apply the extra patches in the appropriate
- directory. In the <tt>linux</tt> source package you can
- use the <tt>quilt</tt> utility to do this.
- </p>
- <p>
- To change the configuration before building, for example
- for the 686-pae flavour on i386, run the commands:
- <example>
-$ fakeroot make -f debian/rules.gen setup_i386_none_686-pae
-$ make -C debian/build/build_i386_none_686-pae menuconfig
- </example>
- </p>
- <p>
- If the patches or configuration changes alter type
- definitions for the kernel, you may need to change the ABI
- name; see <ref id="abi-name">.
- </p>
- </sect1>
- <sect1>
- <heading>Building many packages</heading>
- <p>
- To build all possible packages for this architecture, run:
- <example>
-$ fakeroot debian/rules binary
- </example>
- To build all architecture-dependent packages, run:
- <example>
-$ fakeroot debian/rules binary-arch
- </example>
- To build all architecture-independent packages, run:
- <example>
-$ fakeroot debian/rules binary-indep
- </example>
- </p>
- </sect1>
- <sect1>
- <heading>Building packages for one flavour</heading>
- <p>
- For example, to build only the binary packages for 686-pae
- flavour on i386 architecture, use the following commands:
- <example>
-$ fakeroot debian/rules source
-$ fakeroot make -f debian/rules.gen binary-arch_i386_none_686-pae
- </example>
- The target in this command has the general form of
- <tt><em>target</em>_<em>arch</em>_<em>featureset</em>_<em>flavour</em></tt>.
- Replace the <tt><em>featureset</em></tt> with
- <tt>none</tt> if you do not want any of the extra
- featuresets. This command will build the linux image and
- kernel headers packages. You may also need
- the <tt>linux-headers-<em>version</em>-common</tt> binary
- package, which can be built using the commands:
- <example>
-$ fakeroot debian/rules source
-$ fakeroot make -f debian/rules.gen binary-arch_i386_none_real
- </example>
- The target in this command has the general form of
- <tt><em>target</em>_<em>arch</em>_<em>featureset</em>_<em>real</em></tt>
- </p>
- </sect1>
- </sect>
-
- <sect id="common-official-vcs">
- <heading>Building a development version of the Debian kernel package</heading>
- <p>
- For Debian 6.0 (squeeze) and earlier versions, substitute
- the source package name <tt>linux-2.6</tt> for
- <tt>linux</tt>.
- </p>
- <p>
- To build a kernel image based on the kernel team's
- unreleased development version:
- <taglist>
- <tag><tt># apt-get install build-essential fakeroot rsync git</tt></tag>
- <tag><tt># apt-get build-dep linux</tt></tag>
- <item>
- The last two commands will install the build
- dependencies required by the kernel build process.
- </item>
- <tag><tt>$ git clone -b <em>dist</em> --single-branch https://anonscm.debian.org/git/kernel/linux.git</tt></tag>
- <item>
- This will check out the Debian packaging. <em>dist</em>
- is normally the distribution codename such as
- <tt>wheezy</tt> or <tt>sid</tt> (unstable). For the very
- latest version, usually based on an upstream release
- candidate, use <tt>master</tt>. Note that this will
- download several hundred megabytes of data.
- </item>
- <tag><tt>$ apt-get source -d linux</tt></tag>
- <item>
- This will download the <tt>linux</tt> upstream
- source (and the last released Debian patches).
- Depending on which version you are trying to build,
- you might need to override APT's version selection
- or download a tarball from
- <url id="http://people.debian.org"
- name="people.debian.org"> instead.
- </item>
- <tag><tt>$ cd linux</tt></tag>
- <tag><tt>$ debian/rules orig</tt></tag>
- <item>
- This unpacks the upstream source and merges it with
- the Debian packaging.
- </item>
- <tag><tt>$ debian/rules debian/control</tt></tag>
- <item>
- This generates a Debian package control file based on
- the current definitions of the various kernel flavours
- which can be built.
- </item>
- <tag><tt>$ fakeroot debian/rules <em>target</em></tt></tag>
- <item>
- Finally, build binary packages as explained in
- <ref id="common-official">.
- </item>
- </taglist>
- </p>
- </sect>
-
- <sect id="gen-orig">
- <heading>Generating orig tarball from newer upstream</heading>
- <p>
- First you must add a changelog entry for the new upstream
- version. If the new version is a release candidate, change
- the string <tt>-rc</tt> to <tt>~rc</tt>. (In Debian package
- versions, a suffix beginning with <tt>~</tt> indicates a
- pre-release.)
- </p>
- <p>
- The 'orig' tarball is generated by the <tt>genorig.py</tt>
- script. It takes either a tarball and optional patch from
- kernel.org, or a git repository. First ensure you have the
- necessary tools installed:
- <example>
-# apt-get install unifdef
- </example>
- </p>
- <p>
- Then if you have a tarball, run a command such as:
- <example>
-$ debian/bin/genorig.py ../linux-3.4.tar.bz2 ../patch-3.5-rc1.bz2
- </example>
- </p>
- <p>
- Or if you have a git repository, pass the name of its
- directory:
- <example>
-$ debian/bin/genorig.py ~/src/linux
- </example>
- </p>
- <p>
- Either of these will generate a file such as
- <tt>../orig/linux_3.5~rc1.orig.tar.xz</tt>.
- You can then combine this tarball with the Debian packaging
- by running:
- <example>
-$ debian/rules orig
- </example>
- </p>
- </sect>
-
- <sect id="common-building">
- <heading>Building a custom kernel from Debian kernel source</heading>
- <p>
- This section describes the simplest possible procedure to
- build a custom kernel the "Debian way". It is assumed that
- user is somewhat familiar with kernel configuration and
- build process. If that's not the case, it is recommended to
- consult the kernel documentation and many excellent online
- resources dedicated to it.
- </p>
- <p>
- The easiest way to build a custom kernel (the kernel with
- the configuration different from the one used in the
- official packages) from the Debian kernel source is to use
- the <tt>linux-source</tt> package and the <tt>make deb-pkg</tt>
- target. First, prepare the kernel tree:
- <example>
-# apt-get install linux-source-3.2
-$ tar xjf /usr/src/linux-source-3.2.tar.bz2
-$ cd linux-source-3.2
- </example>
- The kernel now needs to be configured, that is you have to
- set the kernel options and select the drivers which are
- going to be included, either as built-in, or as external
- modules. The kernel build infrastructure offers a number of
- targets, which invoke different configuration frontends. For
- example, one can use console-based menu configuration by
- invoking the command
- <example>
-$ make menuconfig
- </example>
- Instead of <tt>menuconfig</tt> one can use <tt>config</tt>
- (text-based line-by-line configuration frontend) or
- <tt>xconfig</tt> (graphical configuration frontend). It is
- also possible to reuse your old configuration file by
- placing it as a <tt>.config</tt> file in the top-level
- directory and running one of the configuration targets (if
- you want to adjust something) or <tt>make oldconfig</tt>
- (to keep the same configuration).
- Note that different frontends may require different
- additional libraries and utilities to be installed to
- function properly. For example, the <tt>menuconfig</tt>
- frontend requires the <tt>ncurses</tt> library, which at
- time of writing is provided by the <tt>libncurses5-dev</tt>
- package.
- </p>
- <p>
- The build will use less disk space if the CONFIG_DEBUG_INFO
- option is disabled (see <ref id="common-size">).
- Debuginfo is only needed if you plan to use binary object
- tools like crash, kgdb, and SystemTap on the kernel.
- <example>
-$ scripts/config --disable DEBUG_INFO
- </example>
- </p>
- <p>
- After the configuration process is finished, the new or
- updated kernel configuration will be stored in
- <tt>.config</tt> file in the top-level directory. The build
- is started using the commands
- <example>
-$ make clean
-$ make deb-pkg
- </example>
- As a result of the build, a custom kernel package
- <tt>linux-image-3.2.19_3.2.19-1_i386.deb</tt> (name will
- reflect the version of the kernel and build number) will be
- created in the directory one level above the top of the
- tree. It may be installed using
- <tt>dpkg</tt> just as any other package:
- <example>
-# dpkg -i ../linux-image-3.2.19_3.2.19-1_i386.deb
- </example>
- This command will unpack the kernel, generate the initrd if
- necessary (see <ref id="initramfs"> for details), and configure
- the bootloader to make the newly installed kernel the
- default one. If this command completed without any problems,
- you can reboot using the
- <example>
-# shutdown -r now
- </example>
- command to boot the new kernel.
- </p>
- <p>
- For much more information about
- bootloaders and their configuration please check their
- documentation, which can be accessed using the commands
- <tt>man lilo</tt>, <tt>man
- lilo.conf</tt>, <tt>man grub</tt>, and so on. You can also
- look for documentation in the
- <tt>/usr/share/doc/<em>package</em></tt> directories, with
- <tt><em>package</em></tt> being the name of the package
- involved.
- </p>
- </sect>
-
- <sect id="kernel-org-package">
- <heading>Building a custom kernel from the "pristine" kernel source</heading>
- <p>Building a kernel from the "pristine" (also sometimes called "vanilla")
- kernel source, distributed from <url id="http://www.kernel.org" name="www.kernel.org">
- and its mirrors, may be occasionally useful for debugging or in the
- situations when a newer kernel version is desired. The procedure
- differs only in obtaining the kernel source: instead of unpacking
- the kernel source from Debian packages, the "pristine" source is
- downloaded using your favourite browser or using wget, as follows:
- <example>
-$ wget http://kernel.org/pub/linux/kernel/v3.x/linux-3.4.tar.bz2
- </example>
- The integrity of the downloaded archive may be verified by fetching
- the corresponding cryptographic signature
- <example>
-$ wget http://kernel.org/pub/linux/kernel/v3.x/linux-3.4.tar.sign
- </example>
- and running this command (<tt>gnupg</tt> package must be installed):
- <example>
-$ bunzip2 -c linux-3.4.tar.bz2 | gpg --verify linux-3.4.tar.sign -
- </example>
- Successful verification results in output similar to the one below:
- <example>
-gpg: Signature made Mon 21 May 2012 01:48:14 AM CEST using RSA key ID 00411886
-gpg: Good signature from "Linus Torvalds <torvalds at linux-foundation.org>"
-gpg: WARNING: This key is not certified with a trusted signature!
-gpg: There is no indication that the signature belongs to the owner.
-Primary key fingerprint: ABAF 11C6 5A29 70B1 30AB E3C4 79BE 3E43 0041 1886
- </example>
- After that the archive may be unpacked using
- <example>
-$ tar xjf linux-3.4.tar.bz2
-$ cd linux-3.4
- </example>
- The unpacked kernel tree (in <tt>linux-3.4</tt> now has to be configured.
- The existing configuration file may be used as a starting point
- <example>
-$ cp /boot/config-3.2.0-2-686-pae ./.config
- </example>
- After the configuration with one of the configuration frontends (invoked by <tt>make oldconfig</tt>,
- <tt>make config</tt>, <tt>make menuconfig</tt>, etc) is completed, the build
- may be started using <tt>make deb-pkg</tt> target as described above.
- </sect>
-
- <sect id="common-out-of-tree">
- <heading>Building out-of-tree kernel modules</heading>
- <p>
- Some kernel modules are not included in the upstream or
- Debian kernel source, but are provided as third-party source
- packages. For some of the most popular out-of-tree modules,
- the binary Debian packages with modules built against the
- stock Debian kernels are provided. For example, if you are
- running stock Debian kernel <tt>3.2.0-2-686-pae</tt> (use the
- <tt>uname -r</tt> command to verify the version) from the
- <tt>linux-image-3.2.0-2-686-pae</tt> package, and would like to
- use the squash filesystem, all you need to do is install
- <tt>squashfs-modules-3.2.0-2-686-pae</tt> binary package, which
- provides the neccessary binary kernel modules.
- </p>
-
- <p>
- If you are not so lucky, and there are no binary module
- packages in the archive, there is a fair chance that the
- Debian archive contains the packaged <strong>source</strong>
- for the kernel modules. Names of such packages typically end
- in <tt>-source</tt>, for example <tt>squashfs-source</tt>,
- <tt>thinkpad-source</tt>, <tt>rt2x00-source</tt> and many
- others. These packages contain debianized source code of the
- kernel modules, suitable for building using the
- <tt>module-assistant</tt> (or <tt>m-a</tt>) script from the
- <tt>module-assistant</tt> package. Typical sequence to
- build a custom binary module package, matching a kernel
- <tt>3.2.0-2-686-pae</tt> (as returned by <tt>uname -r</tt>)
- from the debianized source consists of the following steps:
- </p>
- <p>
- Install a set of kernel headers, matching the kernel for
- which the modules are going to be built:
- <example>
-# apt-get install linux-headers-3.2.0-2-686-pae
- </example>
- Install the package containing the source:
- <example>
-# apt-get install squashfs-source
- </example>
- Invoke <tt>module-assistant</tt> (aka <tt>m-a</tt>) to do
- the heavy lifting:
- <example>
-# m-a build squashfs
- </example>
- As a result, a Debian package is going to be built and placed
- in <tt>/usr/src</tt>. It can be installed the usual way, using
- <tt>dpkg -i</tt>. Two last steps (building and installation)
- may be combined using the invocation
- <example>
-# m-a auto-install squashfs
- </example>
- Check out the <tt>module-assistant</tt> documentation (<tt>man module-assistant</tt>)
- for other options and much more information on how to use it.
- </p>
-
- <p>
- Finally, in some rare circumstances, you might need to build the kernel modules
- from the upstream source packages. In that case, follow the documentation included
- with the package to build the modules. If the build process will
- require you to specify the directory with the kernel headers,
- matching the currently running kernel, for stock Debian kernels this directory is
- <tt>/usr/src/linux-headers-<em>uname</em></tt>, provided by the
- <tt>linux-headers-<em>uname</em></tt> package. Here <tt><em>uname</em></tt> is the
- output of the <tt>uname -r</tt> command. If you are building and running your own
- custom kernels, it is a good idea to keep the original build tree around, as it
- also can be used for out-of-tree module building.
- </p>
- </sect>
- </chapt>
diff --git a/chapter-initramfs.dbk b/chapter-initramfs.dbk
new file mode 100644
index 0000000..16adba7
--- /dev/null
+++ b/chapter-initramfs.dbk
@@ -0,0 +1,78 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<chapter id="ch-initramfs">
+<?dbhtml filename="ch-initramfs.html" ?>
+<title>Managing the initial ramfs (initramfs) archive</title>
+<para>
+The booting in Debian is a two-stage process, involving the initial RAM
+filesystem (initramfs for short, sometimes it is also referred to as initrd,
+which stands for initial RAM disk). First, the bootloader loads the kernel and
+initramfs into memory, and passes the execution control to the kernel. After
+basic initialization the kernel extracts the initramfs archive and mounts it as
+a temporary root filesystem. initramfs contains kernel modules and userspace
+programs required to initialize the physical or logical device(s) containing
+the real root filesystem. The <literal>init</literal> script on the initramfs
+loads modules and performs other neccessary initialization steps. At the end
+of this stage <literal>run-init</literal> deletes the initramfs from memory,
+mounts the real root filesystem and passes control to the
+<literal>/sbin/init</literal> program on it.
+</para>
+<para>
+Two major goals are achieved with such setup: the kernel size is kept under
+control by allowing most of the drivers to be compiled as modules (in a
+initramfs-less setup the drivers neccessary for the boot-time initialization of
+the root device must be compiled into it) and allow the setups which require
+initialization which cannot be done in-kernel, but is performed by userspace
+utilities.
+</para>
+<section id="s-initramfs-gen-tools"><title>Initramfs generation tools</title>
+<para>
+Since initramfs usually needs to be customized for the particular
+hardware/device configuration and kernel version, they are not included as a
+part of any package, but are generated on the fly at kernel installation time.
+Currently there are two tools in Debian capable of generating an initramfs:
+<literal>update-initramfs</literal> provided by
+<literal>initramfs-tools</literal> (default) and
+<literal>dracut-update-initramfs</literal> provided by the
+<literal>dracut</literal> package (experimental).
+</para>
+</section>
+
+<section id="s-initramfs-regen"><title>Regenerating the initramfs</title>
+<para>
+If changes are desired after the corresponding <literal>linux-image</literal>
+has been installed, the initramfs needs to be regenerated. This is achieved by
+the command
+</para>
+<screen>
+# dpkg-reconfigure linux-image-3.2.0-2-686-pae
+</screen>
+<para>
+where <literal>linux-image-3.2.0-2-686-pae</literal> is the name of the kernel
+package for which the initramfs regeneration is requested.
+</para>
+</section>
+
+<section id="s-initramfs-exam"><title>Examining the initramfs contents</title>
+<para>
+Occasionally it is useful to examine the contents of initramfs to diagnose a
+problem or for educational purposes. They are compressed
+<literal>cpio</literal> archives, which may be extracted using the command
+</para>
+<screen>
+$ zcat /boot/initrd.img-3.2.0-2-686-pae | cpio -i
+</screen>
+<para>
+It will unpack the contents of the initramfs into the current directory.
+</para>
+<para>
+It is also possible to list the contents of an initramfs using the
+<literal>cpio -t</literal> option or the command
+</para>
+<screen>
+$ lsinitramfs /boot/initrd.img-3.2.0-2-686-pae
+</screen>
+</section>
+
+</chapter>
+
diff --git a/chapter-initramfs.sgml b/chapter-initramfs.sgml
deleted file mode 100644
index 0310598..0000000
--- a/chapter-initramfs.sgml
+++ /dev/null
@@ -1,74 +0,0 @@
- <chapt id="initramfs">
- <heading>Managing the initial ramfs (initramfs) archive</heading>
- <p>
- The booting in Debian is a two-stage process, involving
- the initial RAM filesystem (initramfs for short, sometimes it
- is also referred to as initrd, which stands for initial RAM
- disk). First, the bootloader loads the kernel and initramfs
- into memory, and passes the execution control to the
- kernel. After basic initialization the kernel extracts the
- initramfs archive and mounts it as a temporary root
- filesystem. initramfs contains kernel modules and userspace
- programs required to initialize the physical or logical
- device(s) containing the real root filesystem. The
- <tt>init</tt> script on the initramfs loads modules and
- performs other neccessary initialization steps. At the end of
- this stage <tt>run-init</tt> deletes the initramfs from
- memory, mounts the real root filesystem and passes control to
- the <tt>/sbin/init</tt> program on it.
- </p>
- <p>
- Two major goals are achieved with such setup: the kernel size
- is kept under control by allowing most of the drivers to be
- compiled as modules (in a initramfs-less setup the drivers
- neccessary for the boot-time initialization of the root device
- must be compiled into it) and allow the setups which require
- initialization which cannot be done in-kernel, but is performed
- by userspace utilities.
- </p>
- <sect id="initramfs-gen-tools">
- <heading>Initramfs generation tools</heading>
- <p>
- Since initramfs usually needs to be customized for the particular
- hardware/device configuration and kernel version, they are not
- included as a part of any package, but are generated on the
- fly at kernel installation time. Currently there are two tools
- in Debian capable of generating an initramfs:
- <tt>update-initramfs</tt> provided by <tt>initramfs-tools</tt>
- (default) and <tt>dracut-update-initramfs</tt> provided by the
- <tt>dracut</tt> package (experimental).
- </p>
- </sect>
- <sect id="initramfs-regen">
- <heading>Regenerating the initramfs</heading>
- <p>
- If changes are desired after the corresponding
- <tt>linux-image</tt> has been installed, the initramfs needs to
- be regenerated. This is achieved by the command
- <example>
-# dpkg-reconfigure linux-image-3.2.0-2-686-pae
- </example>
- where <tt>linux-image-3.2.0-2-686-pae</tt> is the name of the
- kernel package for which the initramfs regeneration is requested.
- </sect>
- <sect id="initramfs-exam">
- <heading>Examining the initramfs contents</heading>
- <p>
- Occasionally it is useful to examine the contents of initramfs
- to diagnose a problem or for educational purposes. They are
- compressed <tt>cpio</tt> archives, which may be extracted
- using the command
- <example>
-$ zcat /boot/initrd.img-3.2.0-2-686-pae | cpio -i
- </example>
- It will unpack the contents of the initramfs into the current directory.
- </p>
- <p>
- It is also possible to list the contents of an initramfs
- using the <tt>cpio -t</tt> option or the command
- <example>
-$ lsinitramfs /boot/initrd.img-3.2.0-2-686-pae
- </example>
- </p>
- </sect>
- </chapt>
diff --git a/chapter-modules.dbk b/chapter-modules.dbk
new file mode 100644
index 0000000..77d159a
--- /dev/null
+++ b/chapter-modules.dbk
@@ -0,0 +1,86 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<chapter id="ch-modules">
+<?dbhtml filename="ch-modules.html" ?>
+<title>Managing the kernel modules</title>
+<para>
+Linux device drivers come in the form of kernel modules - object files which
+may be loaded into the running kernel to extend its functionality. The list of
+currently loaded kernel modules can be obtained using the
+<literal>lsmod</literal> command, modules may be loaded using
+<literal>modprobe</literal>, and removed using <literal>modprobe -r</literal>.
+The <literal>depmod</literal> command may be used to regenerate the list of
+available modules (after installation of the new modules, for example), even
+though it is pretty unlikely that you will ever need to invoke it by hand.
+</para>
+<para>
+Normally, the devices are detected and neccessary kernel modules are loaded by
+<literal>udev</literal> during boot time. Occasionally, one may need finer
+control over the loading of kernel modules, for example to pass the additional
+parameters to the module, force loading of some modules on startup, or prevent
+certain module(s) from being loaded.
+</para>
+<para>
+If some modules are not loaded automatically by <literal>udev</literal>, but
+you would like them to be loaded during boot, it is possible to force it by
+listing the names of the modules in <literal>/etc/modules</literal>. This will
+be scanned for the names of the modules (one name per line), which will then be
+loaded using <literal>modprobe</literal>. You can also specify the arguments
+for the modules. For example, a typical <literal>/etc/modules</literal> might
+look like that
+</para>
+<screen>
+loop max_int=32
+sbp2
+</screen>
+<para>
+To find out what parameters are accepted by a given module, you can use the
+<literal>modinfo</literal> command, for example:
+</para>
+<screen>
+# modinfo loop
+filename: /lib/modules/3.2.0-2-686-pae/kernel/drivers/block/loop.ko
+alias: devname:loop-control
+alias: char-major-10-237
+alias: block-major-7-*
+license: GPL
+depends:
+intree: Y
+vermagic: 3.2.0-2-686-pae SMP mod_unload modversions 686
+parm: max_loop:Maximum number of loop devices (int)
+parm: max_part:Maximum number of partitions per loop device (int)
+</screen>
+<para>
+To add custom arguments to the modules loaded by <literal>udev</literal> early
+in the boot process, you need to create a custom configuration file for
+<literal>modprobe</literal>, which <literal>udev</literal> uses to load the
+modules. For example, to pass an <literal>atapi_enabled=1</literal> argument
+to the <literal>libata</literal> kernel module, create
+<literal>/etc/modprobe.d/local</literal> file with a following line:
+</para>
+<screen>
+options libata atapi_enabled=1
+</screen>
+<para>
+You can choose arbitrary names for the configuration files in
+<literal>/etc/modprobe.d</literal> and put multiple <literal>options</literal>
+lines in the same file.
+</para>
+<para>
+Sometimes two different modules claim support for the same device, usually
+because two slightly different versions of the device exist, requiring
+different kernel modules to operate. In such situation <literal>udev</literal>
+loads both kernel modules, with unpredictable results. To avoid this problem,
+you can prevent any module (let's say, <literal>tulip</literal>) from loading
+by creating an arbitrarily named file, containing a line
+</para>
+<screen>
+blacklist tulip
+</screen>
+<para>
+in <literal>/etc/modprobe.d</literal> directory. See the
+<literal>modprobe</literal> manual page (<literal>man modprobe</literal>) for
+much more information on configuring and using modprobe.
+</para>
+</chapter>
+
diff --git a/chapter-modules.sgml b/chapter-modules.sgml
deleted file mode 100644
index e1d8403..0000000
--- a/chapter-modules.sgml
+++ /dev/null
@@ -1,88 +0,0 @@
-<chapt id="modules">
- <heading>Managing the kernel modules</heading>
- <p>
-
- Linux device drivers come in the form of kernel modules - object
- files which may be loaded into the running kernel to extend its
- functionality. The list of currently loaded kernel modules can be
- obtained using the <tt>lsmod</tt> command, modules may be loaded
- using <tt>modprobe</tt>, and removed using <tt>modprobe -r</tt>.
- The <tt>depmod</tt> command may be used to regenerate the list of
- available modules (after installation of the new modules, for
- example), even though it is pretty unlikely that you will ever
- need to invoke it by hand.
-
- </p>
- <p>
-
- Normally, the devices are detected and neccessary kernel modules
- are loaded by <tt>udev</tt> during boot time. Occasionally, one
- may need finer control over the loading of kernel modules, for
- example to pass the additional parameters to the module, force
- loading of some modules on startup, or prevent certain module(s)
- from being loaded.
-
- </p>
- <p>
-
- If some modules are not loaded automatically by <tt>udev</tt>, but
- you would like them to be loaded during boot, it is possible to force
- it by listing the names of the modules in <tt>/etc/modules</tt>.
- This will be scanned for the names of
- the modules (one name per line), which will then be loaded using
- <tt>modprobe</tt>. You can also specify the arguments for the modules.
- For example, a typical <tt>/etc/modules</tt> might look like that
- <example>
-loop max_int=32
-sbp2
- </example>
- To find out what parameters are accepted by a given module, you can
- use the <tt>modinfo</tt> command, for example:
- <example>
-# modinfo loop
-filename: /lib/modules/3.2.0-2-686-pae/kernel/drivers/block/loop.ko
-alias: devname:loop-control
-alias: char-major-10-237
-alias: block-major-7-*
-license: GPL
-depends:
-intree: Y
-vermagic: 3.2.0-2-686-pae SMP mod_unload modversions 686
-parm: max_loop:Maximum number of loop devices (int)
-parm: max_part:Maximum number of partitions per loop device (int)
- </example>
-
- </p>
- <p>
-
- To add custom arguments to the modules loaded by <tt>udev</tt>
- early in the boot process, you need to create a custom
- configuration file for <tt>modprobe</tt>, which <tt>udev</tt>
- uses to load the modules. For example, to pass an
- <tt>atapi_enabled=1</tt> argument to the <tt>libata</tt> kernel
- module, create <tt>/etc/modprobe.d/local</tt> file with a
- following line:
- <example>
-options libata atapi_enabled=1
- </example>
- You can choose arbitrary names for the configuration files in
- <tt>/etc/modprobe.d</tt> and put multiple <tt>options</tt> lines in
- the same file.
-
- </p>
- <p>
- Sometimes two different modules claim support for the same
- device, usually because two slightly different versions of the
- device exist, requiring different kernel modules to operate. In
- such situation <tt>udev</tt> loads both kernel modules, with
- unpredictable results. To avoid this problem, you can prevent
- any module (let's say, <tt>tulip</tt>) from loading by creating
- an arbitrarily named file, containing a line
- <example>
-blacklist tulip
- </example>
- in <tt>/etc/modprobe.d</tt> directory. See the <tt>modprobe</tt>
- manual page (<tt>man modprobe</tt>) for much more information on
- configuring and using modprobe.
- </p>
-</chapt>
diff --git a/chapter-packaging.dbk b/chapter-packaging.dbk
new file mode 100644
index 0000000..9d40386
--- /dev/null
+++ b/chapter-packaging.dbk
@@ -0,0 +1,223 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<chapter id="ch-packaging">
+<?dbhtml filename="ch-packaging.html" ?>
+<title>Debian kernel packages</title>
+<section id="s-source-pkg"><title>Source package</title>
+<para>
+To ensure that the latest kernel version, containing all the essential bug and
+security fixes is available on as many architectures as possible, starting with
+2.6.12 the kernel team introduced a new packaging scheme. In it most of the
+kernel-related binary packages are built from a single source package
+<literal>linux</literal> (previously <literal>linux-2.6</literal>). The
+<literal>linux</literal> source package supports building of kernel images and
+headers for all currently supported architectures. Subsequent sections of this
+chapter document the naming and contents of the binary packages built from the
+<literal>linux</literal> source package.
+</para>
+</section>
+
+<section id="s-arch-indep"><title>Architecture-independent packages</title>
+<variablelist>
+<varlistentry>
+<term><literal>linux-source-<replaceable>version</replaceable></literal></term>
+<listitem>
+<para>
+This package contains the Debian kernel source tarball. The patchlevel of the
+source is determined by the Debian revision of the package, for example the
+version 3.2.19-1 of the package <literal>linux-source-3.2</literal> contains
+the version 3.2.19 of the Debian kernel source patched to patchlevel 1. Once
+the package is installed, the source tarball is available at
+<literal>/usr/src/linux-source-<replaceable>version</replaceable>.tar.bz2</literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>linux-manual-<replaceable>version</replaceable></literal></term>
+<listitem>
+<para>
+This package contains the manual pages for the functions, constituting the
+kernel API. These pages are installed into
+<literal>/usr/share/man/man9/</literal>, and are accessible with the standard
+<literal>man</literal> command. Due to filename conflicts, only one
+<literal>linux-manual</literal> package may be installed at any given time.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>linux-doc-<replaceable>version</replaceable></literal></term>
+<listitem>
+<para>
+This package contains the rest of the kernel documentation in various formats.
+It is installed in
+<literal>/usr/share/doc/linux-doc-<replaceable>version</replaceable></literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>linux-support-<replaceable>version</replaceable>-<replaceable>abiname</replaceable></literal></term>
+<listitem>
+<para>
+This package contains the support files for building of out-of-tree modules for
+given version and abiname.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</section>
+
+<section id="s-arch-dep"><title>Architecture-dependent packages</title>
+<para>
+The kind of hardware the particular kernel package is designed for is uniquely
+identified by the <emphasis>architecture</emphasis>,
+<emphasis>featureset</emphasis>, and <emphasis>flavour</emphasis>. Kernels for
+all architectures are built from the same Debian kernel source tree, which is
+obtained using the procedure described in <xref linkend="ch-source"/>. Each
+architecture usually has multiple flavours of the binary kernel images.
+Different flavours correspond to different kernel configuration files, used to
+build the binary images from the <emphasis role="strong">same</emphasis> kernel
+tree.
+</para>
+<para>
+In order to build a working kernel with an extra featureset not provided by the
+upstream source, additional changes to the Debian kernel source are required.
+Again, multiple flavours of binary images may be built from the featureset
+tree. For example, the <literal>i386</literal> architecture has a number of
+different flavours, such as <literal>486</literal>, <literal>686-pae</literal>
+and <literal>amd64</literal>, built from the common Debian kernel source. It
+also contains the <literal>rt</literal> featureset. The source tree for
+building the kernels for each of these featuresets is obtained by applying
+additional patches to the Debian kernel source. It may be used to build the
+<literal>rt-686-pae</literal> binary image flavours. The names of the Debian
+binary packages incorporate the name of the flavour and, if necessary, the name
+of the featureset (there is no need to worry about the name of the
+architecture, since Debian tools will only allow installation of the packages
+with "correct" architecture). If the arch does not have any featuresets, the
+featureset part is omitted from the name, as indicated by the square brackets
+below.
+</para>
+<para>
+Package names also include the <emphasis>abiname</emphasis>, a small integer,
+which identifies the kernel's binary compatibility level. The kernels with
+different abinames are binary incompatible, so upgrading to a kernel with a
+different abiname will most likely require recompilation of third-party binary
+modules against the new kernel. The list of architecture-dependent packages
+together with a short description is given below.
+</para>
+<variablelist>
+<varlistentry>
+<term><literal>linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>-common[-<replaceable>featureset</replaceable>]</literal></term>
+<listitem>
+<para>
+This package contains a common set of kernel headers for a particular
+featureset (or arch, if featureset is empty). Together with the
+flavour-specific <literal>linux-headers</literal> package it provides a full
+set of kernel headers, suitable for building of out-of-tree modules. This
+package should not normally be installed directly, but only as a dependency of
+the flavour-specific headers package (see next description). It unpacks into
+the
+<literal>/usr/src/linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>-common[-<replaceable>featureset</replaceable>]</literal>
+directory.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<variablelist>
+<varlistentry>
+<term><literal>linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></literal></term>
+<listitem>
+<para>
+This package provides flavour-specific header files. It depends on the
+corresponding
+<literal>linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>-common[-<replaceable>featureset</replaceable>]</literal>
+package, and sets up symbolic links into its directory tree in such a way that
+the directory
+<literal>/usr/src/linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></literal>
+appears to contain a full set of headers, required for building of out-of-tree
+kernel modules. For more information on this check out <xref
+linkend="s-common-out-of-tree"/>. A complete set of kernel headers matching the
+currently running official kernel may be installed with a command
+</para>
+<screen>
+apt-get install linux-headers-$(uname -r)
+</screen>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>linux-image[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></literal></term>
+<term><literal>linux-headers[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></literal></term>
+<listitem>
+<para>
+These virtual packages provide (via dependencies) the latest binary image and
+matching set of header files (respectively) for a particular flavour. Example:
+<literal>linux-image-rt-686-pae</literal>
+</para>
+<para>
+In Debian 6.0 (squeeze) and earlier, the headers metapackages were named
+<literal>linux-headers-2.6[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>linux-image-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></literal></term>
+<listitem>
+<para>
+This package contains the binary kernel image and pre-built binary modules for
+a particular arch/featureset/flavour combination. Names of the files installed
+by this package are architecture-dependent. Typical locations of essential
+files for the <literal>i386</literal> architecture are:
+</para>
+<variablelist>
+<varlistentry>
+<term><literal>/boot/vmlinuz-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></literal></term>
+<listitem>
+<para>
+The binary (compressed) kernel image.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>/boot/initrd.img-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></literal></term>
+<listitem>
+<para>
+Initial RAM filesystem (initramfs) image. Note, that this file is
+automatically generated in the installation process and is <emphasis
+role="strong">not</emphasis> shipped as a part of the package. See <xref
+linkend="ch-initramfs"/> for more details.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>/boot/config-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></literal></term>
+<listitem>
+<para>
+The kernel configuration file used to build this particular kernel. May be
+used to rebuild the kernel from source, if necessary.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>/lib/modules/<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable>/</literal></term>
+<listitem>
+<para>
+Directory containing the pre-built binary kernel modules.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><literal>linux-libc-dev</literal></term>
+<listitem>
+<para>
+This package provides Linux kernel headers for use by userspace programs, such
+as GNU glibc and other system libraries.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</section>
+
+</chapter>
+
diff --git a/chapter-packaging.sgml b/chapter-packaging.sgml
deleted file mode 100644
index ed5ab3f..0000000
--- a/chapter-packaging.sgml
+++ /dev/null
@@ -1,213 +0,0 @@
-<chapt id="packaging">
- <heading>Debian kernel packages</heading>
- <sect id="source-pkg">
- <heading>Source package</heading>
- <p>
-
- To ensure that the latest kernel version, containing all the
- essential bug and security fixes is available on as many
- architectures as possible, starting with 2.6.12 the kernel team
- introduced a new packaging scheme. In it most of the
- kernel-related binary packages are built from a single source
- package <tt>linux</tt> (previously <tt>linux-2.6</tt>). The
- <tt>linux</tt> source package supports building of kernel
- images and headers for all currently supported
- architectures. Subsequent sections of this chapter document the
- naming and contents of the binary packages built from the
- <tt>linux</tt> source package.
-
- </p>
- <sect id="arch-indep">
- <heading>Architecture-independent packages</heading>
- <p>
- <taglist>
- <tag><tt>linux-source-<em>version</em></tt></tag>
- <item>
-
- This package contains the Debian kernel source
- tarball. The patchlevel of the source is determined by the
- Debian revision of the package, for example the version 3.2.19-1
- of the package <tt>linux-source-3.2</tt> contains the
- version 3.2.19 of the Debian kernel source patched to
- patchlevel 1. Once the package is installed, the source
- tarball is available at
- <tt>/usr/src/linux-source-<em>version</em>.tar.bz2</tt>.
- </item>
- <tag><tt>linux-manual-<em>version</em></tt></tag>
- <item>
-
- This package contains the manual pages for the functions,
- constituting the kernel API. These pages are installed
- into <tt>/usr/share/man/man9/</tt>, and are accessible
- with the standard <tt>man</tt> command. Due to filename
- conflicts, only one <tt>linux-manual</tt> package may be
- installed at any given time.
-
- </item>
- <tag><tt>linux-doc-<em>version</em></tt></tag>
- <item>
-
- This package contains the rest of the kernel documentation
- in various formats. It is installed in
- <tt>/usr/share/doc/linux-doc-<em>version</em></tt>.
-
- </item>
- <tag><tt>linux-support-<em>version</em>-<em>abiname</em></tt></tag>
- <item>
-
- This package contains the support files for building of
- out-of-tree modules for given version and abiname.
-
- </item>
- </taglist>
- </p>
- </sect>
- <sect id="arch-dep">
- <heading>Architecture-dependent packages</heading>
- <p>
-
- The kind of hardware the particular kernel package is
- designed for is uniquely identified by the
- <em>architecture</em>, <em>featureset</em>, and
- <em>flavour</em>. Kernels for all architectures are built
- from the same Debian kernel source tree, which is obtained
- using the procedure described in <ref id="source">. Each
- architecture usually has multiple flavours of the binary
- kernel images. Different flavours correspond to different
- kernel configuration files, used to build the binary images
- from the <strong>same</strong> kernel tree.
-
- </p>
-
- <p>
-
- In order to build a working kernel with an extra featureset
- not provided by the upstream source, additional changes to
- the Debian kernel source are required. Again, multiple
- flavours of binary images may be built from the featureset
- tree. For example, the <tt>i386</tt> architecture has a number of
- different flavours, such as <tt>486</tt>, <tt>686-pae</tt> and
- <tt>amd64</tt>, built from the common Debian kernel source. It
- also contains the <tt>rt</tt> featureset. The source tree for
- building the kernels for each of these featuresets is
- obtained by applying additional patches to the Debian kernel
- source. It may be used to build the <tt>rt-686-pae</tt>
- binary image flavours. The names of the
- Debian binary packages incorporate the name of the flavour
- and, if necessary, the name of the featureset (there is
- no need to worry about the name of the architecture, since
- Debian tools will only allow installation of the packages
- with "correct" architecture). If the arch does not have any
- featuresets, the featureset part is omitted from the name, as
- indicated by the square brackets below.
-
- </p>
- <p>
-
- Package names also include the <em>abiname</em>, a small
- integer, which identifies the kernel's binary compatibility
- level. The kernels with different abinames are binary
- incompatible, so upgrading to a kernel with a different
- abiname will most likely require recompilation of
- third-party binary modules against the new kernel. The list
- of architecture-dependent packages together with a short
- description is given below.
-
- </p>
- <p>
- <taglist>
- <tag><tt>linux-headers-<em>version</em>-<em>abiname</em>-common[-<em>featureset</em>]</tt></tag>
- <item>
-
- This package contains a common set of kernel headers for a
- particular featureset (or arch, if featureset is
- empty). Together with the flavour-specific
- <tt>linux-headers</tt> package it provides a full set of
- kernel headers, suitable for building of out-of-tree
- modules. This package should not normally be installed
- directly, but only as a dependency of the flavour-specific
- headers package (see next description). It unpacks into
- the
- <tt>/usr/src/linux-headers-<em>version</em>-<em>abiname</em>-common[-<em>featureset</em>]</tt>
- directory.
-
- </item>
- </taglist>
- <taglist>
- <tag><tt>linux-headers-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
- <item>
-
- This package provides flavour-specific header files. It
- depends on the corresponding
- <tt>linux-headers-<em>version</em>-<em>abiname</em>-common[-<em>featureset</em>]</tt>
- package, and sets up symbolic links into its directory
- tree in such a way that the directory
- <tt>/usr/src/linux-headers-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt>
- appears to contain a full set of headers, required for
- building of out-of-tree kernel modules. For more
- information on this check out <ref
- id="common-out-of-tree">. A complete set of kernel headers
- matching the currently running official kernel may be
- installed with a command
-
- <example>
-apt-get install linux-headers-$(uname -r)
- </example>
-
- </item>
- <tag><tt>linux-image[-<em>featureset</em>]-<em>flavour</em></tt></tag>
- <tag><tt>linux-headers[-<em>featureset</em>]-<em>flavour</em></tt></tag>
- <item>
- <p>
- These virtual packages provide (via dependencies) the latest
- binary image and matching set of header files (respectively)
- for a particular flavour. Example: <tt>linux-image-rt-686-pae</tt>
- </p>
- <p>
- In Debian 6.0 (squeeze) and earlier, the headers
- metapackages were
- named <tt>linux-headers-2.6[-<em>featureset</em>]-<em>flavour</em></tt>.
- </p>
- </item>
- <tag><tt>linux-image-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
- <item>
- <p>
- This package contains the binary kernel image and
- pre-built binary modules for a particular
- arch/featureset/flavour combination. Names of the files
- installed by this package are
- architecture-dependent. Typical locations of essential
- files for the <tt>i386</tt> architecture are:
- <taglist>
- <tag><tt>/boot/vmlinuz-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
- <item>
- The binary (compressed) kernel image.
- </item>
- <tag><tt>/boot/initrd.img-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
- <item>
- Initial RAM filesystem (initramfs) image. Note, that this file is automatically generated
- in the installation process and is <strong>not</strong> shipped as a part of the package.
- See <ref id="initramfs"> for more details.
- </item>
- <tag><tt>/boot/config-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
- <item>
- The kernel configuration file used to build this particular kernel. May be used
- to rebuild the kernel from source, if necessary.
- </item>
- <tag><tt>/lib/modules/<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em>/</tt></tag>
- <item>
- Directory containing the pre-built binary kernel modules.
- </item>
- </taglist>
- </item>
- <tag><tt>linux-libc-dev</tt></tag>
- <item>
- <p>
- This package provides Linux kernel headers for use by userspace programs,
- such as GNU glibc and other system libraries.
- </p>
- </item>
- </taglist>
- </p>
- </sect>
- </chapt>
diff --git a/chapter-scope.dbk b/chapter-scope.dbk
new file mode 100644
index 0000000..d9d4719
--- /dev/null
+++ b/chapter-scope.dbk
@@ -0,0 +1,72 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<chapter id="ch-scope">
+<?dbhtml filename="ch-scope.html" ?>
+<title>About this handbook</title>
+<section id="s1.1"><title>Scope</title>
+<para>
+The main goal of this handbook is to serve as a single access point to all
+kernel-related documentation. It contains the information about the Debian
+packaging of Linux kernel for Debian 7.0 (wheezy). The latest released version
+is always available from <ulink
+url="http://kernel-handbook.alioth.debian.org">http://kernel-handbook.alioth.debian.org</ulink>.
+Note that this is a work in progress, and some information is inaccurate.
+</para>
+<para>
+Some of the commands mentioned in the text must be executed with superuser
+priviliges, either by becoming the <literal>root</literal> user or by using
+<literal>sudo</literal>. To distinguish between commands which may be executed
+by an unprivileged user and those requiring superuser privileges, commands are
+prepended by <literal>$</literal> or <literal>#</literal> respectively. This
+symbol is not a part of the command.
+</para>
+</section>
+
+<section id="s-authors"><title>Authors and Contributors</title>
+<para>
+This handbook is maintained within the <ulink
+url="http://alioth.debian.org/projects/kernel-handbook">kernel-handbook</ulink>
+project on <ulink url="http://alioth.debian.org">Alioth</ulink>. The SGML
+source of the book may be checked out from the Debian <ulink
+url="http://anonscm.debian.org/gitweb/?p=kernel-handbook/kernel-handbook.git">git
+repository</ulink>. It is intended as a community project, thus all proposals
+for improvements and contributions are welcome. The preferred way to submit a
+contribution is to send it to the
+<literal>kernel-handbook-general at lists.alioth.debian.org</literal> mailing
+list. When submitting a contribution please clearly identify its copyright
+holder and include the licensing statement. Note that to be accepted the
+contribution must be licensed under the same license as the rest of the
+document, namely GPL version 2 or later. Below is the list of current
+contributors:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Jurij Smakov
+</para>
+</listitem>
+<listitem>
+<para>
+Sven Luther
+</para>
+</listitem>
+<listitem>
+<para>
+Andres Salomon
+</para>
+</listitem>
+<listitem>
+<para>
+Maximilian Attems
+</para>
+</listitem>
+<listitem>
+<para>
+Ben Hutchings
+</para>
+</listitem>
+</itemizedlist>
+</section>
+
+</chapter>
+
diff --git a/chapter-scope.sgml b/chapter-scope.sgml
deleted file mode 100644
index ed14ab2..0000000
--- a/chapter-scope.sgml
+++ /dev/null
@@ -1,58 +0,0 @@
-<chapt id="scope">
- <heading>About this handbook</heading>
- <sect>
- <heading>Scope</heading>
- <p>
-
- The main goal of this handbook is to serve as a single access
- point to all kernel-related documentation. It contains the
- information about the Debian packaging of Linux kernel for
- Debian 7.0 (wheezy). The latest released
- version is always available from <url
- id="http://kernel-handbook.alioth.debian.org"
- name="http://kernel-handbook.alioth.debian.org">. Note that this
- is a work in progress, and some information is inaccurate.
- </p>
- <p>
-
- Some of the commands mentioned in the text must be executed with
- superuser priviliges, either by becoming the <tt>root</tt> user
- or by using <tt>sudo</tt>. To distinguish between commands which
- may be executed by an unprivileged user and those requiring
- superuser privileges, commands are prepended by <tt>$</tt> or
- <tt>#</tt> respectively. This symbol is not a part of the
- command.
-
- </p>
- </sect>
- <sect id="authors">
- <heading>Authors and Contributors</heading>
- <p>
-
- This handbook is maintained within the <url
- id="http://alioth.debian.org/projects/kernel-handbook"
- name="kernel-handbook"> project on <url
- id="http://alioth.debian.org" name="Alioth">. The SGML source of
- the book may be checked out from the Debian
- <url id="http://anonscm.debian.org/gitweb/?p=kernel-handbook/kernel-handbook.git"
- name="git repository">. It is
- intended as a community project, thus all proposals for
- improvements and contributions are welcome. The preferred way to
- submit a contribution is to send it to the
- <tt>kernel-handbook-general at lists.alioth.debian.org</tt> mailing
- list. When submitting a contribution please clearly identify its
- copyright holder and include the licensing statement. Note that
- to be accepted the contribution must be licensed under the same
- license as the rest of the document, namely GPL version 2 or
- later. Below is the list of current contributors:
-
- <list>
- <item>Jurij Smakov</item>
- <item>Sven Luther</item>
- <item>Andres Salomon</item>
- <item>Maximilian Attems</item>
- <item>Ben Hutchings</item>
- </list>
- </p>
- </sect>
-</chapt>
diff --git a/chapter-source.dbk b/chapter-source.dbk
new file mode 100644
index 0000000..0b80549
--- /dev/null
+++ b/chapter-source.dbk
@@ -0,0 +1,71 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<chapter id="ch-source">
+<?dbhtml filename="ch-source.html" ?>
+<title>Debian kernel source</title>
+<section id="s-changes"><title>Changes to the pristine kernel source</title>
+<para>
+The kernels in Debian are distributed in binary form, built from the Debian
+kernel source. It is important to recognize that Debian kernel source may be
+(and in most cases is) different from the upstream (or "pristine") kernel
+source, distributed from <ulink
+url="http://www.kernel.org">www.kernel.org</ulink> and its mirrors. Due to
+licensing restrictions, unclear license information, or failure to comply with
+the Debian Free Software Guidelines (DFSG), parts of the kernel are removed in
+order to distribute the source in the <literal>main</literal> section of the
+Debian archive. Such removal produces
+<literal>linux_<replaceable>version</replaceable>.orig.tar.xz</literal> tarball,
+which serves as the original upstream source. <replaceable>version</replaceable> is
+the actual upstream version.
+</para>
+<para>
+The guidelines for firmware removal were set by the <ulink
+url="http://www.debian.org/vote/2006/vote_007">Handling source-less firmware in
+the Linux kernel</ulink> General Resolution and the <ulink
+url="http://lists.debian.org/debian-kernel/2006/10/msg00541.html">position
+statement</ulink> by the release managers. Even though these documents
+originally applied to the Etch release, there were no significant changes in
+the removal policy, so they were in effect for the Lenny release as well. As
+of version 2.6.31-1, all known sourceless firmware has been removed from the
+Debian package, but much of it is included in the <ulink
+url="http://packages.debian.org/source/firmware-nonfree">firmware-nonfree</ulink>
+package. Additional information about firmware licensing and removals may be
+found at the <ulink url="http://wiki.debian.org">Debian Wiki</ulink> page
+<ulink
+url="http://wiki.debian.org/KernelFirmwareLicensing">KernelFirmwareLicensing</ulink>.
+</para>
+</section>
+
+<section id="s-patches"><title>Debian kernel patches</title>
+<para>
+The source from which the Debian binary kernels are built is obtained by taking
+the source from
+<literal>linux_<replaceable>version</replaceable>.orig.tar.xz</literal> (that is,
+pristine kernel source with problematic parts removed) and applying a set of
+Debian patches. These patches typically implement essential fixes for serious
+bugs and security holes. The Debian version of the kernel packages has the
+form <replaceable>version</replaceable><literal>-</literal><replaceable>revision</replaceable> where
+<replaceable>version</replaceable> is the upstream version of the
+kernel (like 3.2.20) and <replaceable>revision</replaceable>
+determines the patchlevel. For example, the packages with version 3.2.20-1 are
+built from the <literal>linux_3.2.20.orig.tar.xz</literal> source, patched up
+to patchlevel 1. Certain packages include extra 'featuresets' not included in
+the upstream source, such as <literal>rt</literal>.
+</para>
+</section>
+
+<section id="s-acceptance"><title>Policy for patch acceptance</title>
+<para>
+The general policy of the Debian kernel team is that a patch must either fix a
+bug or add hardware support, and must be based on a change already accepted by
+the upstream kernel maintainers. The change does not need to have been
+included in an upstream release yet. This policy allows the team to drop most
+patches when moving to a new upstream version, rather than having to maintain
+an increasing series of Debian-specific patches. The recommended procedure for
+inclusion of patches introducing optional features is to submit to the upstream
+maintainer.
+</para>
+</section>
+
+</chapter>
+
diff --git a/chapter-source.sgml b/chapter-source.sgml
deleted file mode 100644
index fc91ef9..0000000
--- a/chapter-source.sgml
+++ /dev/null
@@ -1,81 +0,0 @@
-<chapt id="source">
- <heading>Debian kernel source</heading>
- <sect id="changes">
- <heading>Changes to the pristine kernel source</heading>
- <p>
-
- The kernels in Debian are distributed in binary form, built from
- the Debian kernel source. It is important to recognize that
- Debian kernel source may be (and in most cases is) different
- from the upstream (or "pristine") kernel source, distributed
- from <url id="http://www.kernel.org" name="www.kernel.org"> and
- its mirrors. Due to licensing restrictions, unclear license
- information, or failure to comply with the Debian Free Software
- Guidelines (DFSG), parts of the kernel are removed in order to
- distribute the source in the <tt>main</tt> section of the Debian
- archive. Such removal produces
- <tt>linux_<em>version</em>.orig.tar.xz</tt> tarball, which
- serves as the original upstream source. <em>version</em>
- is the actual upstream version.
-
- </p>
-
- <p>
- The guidelines for firmware removal were set by the <url
- id="http://www.debian.org/vote/2006/vote_007" name="Handling
- source-less firmware in the Linux kernel"> General Resolution
- and the <url
- id="http://lists.debian.org/debian-kernel/2006/10/msg00541.html"
- name="position statement"> by the release
- managers. Even though these documents originally applied to
- the Etch release, there were no significant changes in the
- removal policy, so they were in effect for the Lenny
- release as well. As of version 2.6.31-1, all known sourceless
- firmware has been removed from the Debian package, but much
- of it is included in the
- <url id="http://packages.debian.org/source/firmware-nonfree" name="firmware-nonfree"> package.
- Additional information about firmware licensing and removals
- may be found at the
- <url id="http://wiki.debian.org" name="Debian Wiki"> page <url
- id="http://wiki.debian.org/KernelFirmwareLicensing"
- name="KernelFirmwareLicensing">.
-
- </p>
- </sect>
- <sect id="patches">
- <heading>Debian kernel patches</heading>
- <p>
-
- The source from which the Debian binary kernels are built is
- obtained by taking the source from
- <tt>linux_<em>version</em>.orig.tar.xz</tt> (that
- is, pristine kernel source with problematic parts removed)
- and applying a set of Debian
- patches. These patches typically implement essential fixes for
- serious bugs and security holes. The Debian version of the
- kernel packages has the form <tt><em>version-revision</em></tt>
- where <tt><em>version</em></tt> is the upstream version of the
- kernel (like 3.2.20) and <tt><em>revision</em></tt> determines
- the patchlevel. For example, the packages with version 3.2.20-1
- are built from the <tt>linux_3.2.20.orig.tar.xz</tt> source,
- patched up to patchlevel 1. Certain packages include extra
- 'featuresets' not included in the upstream source, such as
- <tt>rt</tt>.
-
- </p>
- </sect>
- <sect id="acceptance">
- <heading>Policy for patch acceptance</heading>
- <p>
- The general policy of the Debian kernel team is that a patch
- must either fix a bug or add hardware support, and must be based
- on a change already accepted by the upstream kernel maintainers.
- The change does not need to have been included in an upstream
- release yet. This policy allows the team to drop most patches
- when moving to a new upstream version, rather than having to
- maintain an increasing series of Debian-specific patches. The
- recommended procedure for inclusion of patches introducing
- optional features is to submit to the upstream maintainer.
- </p>
- </sect>
-</chapt>
diff --git a/chapter-update-hooks.dbk b/chapter-update-hooks.dbk
new file mode 100644
index 0000000..e7e7357
--- /dev/null
+++ b/chapter-update-hooks.dbk
@@ -0,0 +1,156 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<chapter id="ch-update-hooks">
+<?dbhtml filename="ch-update-hooks.html" ?>
+<title>Package maintainer scripts and hooks</title>
+<para>
+Kernel packages for Debian have historically had complex maintainer scripts
+which can invoke the initramfs builder and/or a boot loader, based on a mixture
+of file tests, explicit configuration through the file
+<literal>/etc/kernel-img.conf</literal> and debconf questions. Starting with
+Debian 6.0, this has been greatly simplified.
+</para>
+<para>
+The following policy applies to Debian GNU/Linux 6.0 'squeeze' and later
+releases. Some parts may be applicable to kernels other than Linux, but this
+policy does not set any requirements for them.
+</para>
+<section id="s-kernel-hooks"><title>Kernel hooks</title>
+<para>
+The maintainer scripts in Linux kernel packages must use
+<literal>run-parts</literal> to invoke hook scripts in the corresponding
+subdirectory of <literal>/etc/kernel</literal>, e.g. the
+<literal>postinst</literal> script must invoke scripts in
+<literal>/etc/kernel/postinst.d</literal>.
+</para>
+<para>
+The arguments given to all kernel hook scripts are the kernel ABI version (the
+string that <literal>uname -r</literal> reports) and, optionally, the absolute
+path to the kernel image. If the second argument is missing then the path is
+either <literal>/boot/vmlinuz-<replaceable>version</replaceable></literal> or
+<literal>/boot/vmlinux-<replaceable>version</replaceable></literal>, according to
+architecture convention. The environment variable
+<literal>DEB_MAINT_PARAMS</literal> will contain the arguments given to the
+kernel maintainer script, possibly single-quoted. In a shell script, this
+variable can be parsed using:
+</para>
+<screen>
+eval set -- "$DEB_MAINT_PARAMS"
+</screen>
+<para>
+Kernel hook scripts may be run under debconf. In this case they must not use
+stdin and stdout, and should send all output to stderr (fd 2). A shell script
+can ensure that it does this using:
+</para>
+<screen>
+exec </dev/null >&2
+</screen>
+</section>
+
+<section id="s-kernel-hooks-loader"><title>Kernel hooks required for boot loaders</title>
+<para>
+Packages for boot loaders that need to be updated whenever the files they load
+are modified (i.e. those that store a block list) must install hook scripts in
+<literal>/etc/kernel/postinst.d</literal> and
+<literal>/etc/kernel/postrm.d</literal>.
+</para>
+<para>
+Since these boot loaders should be updated as the last step during
+installation/upgrade and removal, hook scripts for boot loaders must be named
+using the prefix <literal>zz-</literal> and no other packages may use this
+prefix or one that sorts later by the rules used by
+<literal>run-parts</literal>. A postrm hook script should warn but exit with
+code 0 if the boot loader configuration file still refers to the kernel image
+that has been removed.
+</para>
+<para>
+These boot loader packages must be installable on the filesystem in a disabled
+state where they will not write to the boot sector or other special storage.
+While a boot loader is disabled, any kernel hooks it includes must do nothing
+except (optionally) printing a warning that the boot loader is disabled, and
+must exit successfully.
+</para>
+<para>
+Packages for boot loaders that can provide a menu of kernel versions should
+install kernel hook scripts in order to update that menu.
+</para>
+</section>
+
+<section id="s-initramfs-hooks"><title>Initramfs hooks</title>
+<para>
+Packages for boot loaders that need to be updated whenever the files they load
+are modified must also install hook scripts in
+<literal>/etc/initramfs/post-update.d</literal>. Initramfs builders must call
+these scripts using <literal>run-parts</literal> after they create, update or
+delete an initramfs. The arguments given to these hook scripts are the kernel
+ABI version and the absolute path to the initramfs image.
+</para>
+<para>
+While a boot loader is disabled, any initramfs hook it includes must do nothing
+except (optionally) printing a warning that the boot loader is disabled, and
+must exit successfully.
+</para>
+</section>
+
+<section id="s-kernel-hooks-initramfs"><title>Kernel hooks required for initramfs builders</title>
+<para>
+Initramfs builders must install hook scripts in
+<literal>/etc/kernel/postinst.d</literal> and
+<literal>/etc/kernel/postrm.d</literal>, to create/update and delete the
+corresponding initramfs images. The postinst hook script must complete its
+work before returning.
+</para>
+</section>
+
+<section id="s-loader-optimisation"><title>Optimising boot loader updates</title>
+<para>
+During a kernel package installation, upgrade or removal, various boot loader
+hooks may be invoked (in this order):
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+A <literal>postinst_hook</literal> or <literal>postrm_hook</literal> command
+set by the user or the installer in <literal>/etc/kernel-img.conf</literal>
+</para>
+</listitem>
+<listitem>
+<para>
+A hook script in <literal>/etc/initramfs/post-update.d</literal>
+</para>
+</listitem>
+<listitem>
+<para>
+A hook script in <literal>/etc/kernel/postinst.d</literal> or
+...<literal>/postrm.d</literal>
+</para>
+</listitem>
+</orderedlist>
+<para>
+To avoid unnecessary updates, the hooks invoked at steps 1 and 2 may check
+whether <literal>$DPKG_MAINTSCRIPT_PACKAGE</literal> begins with
+<literal>linux-image-</literal> and do nothing in this case.
+</para>
+</section>
+
+<section id="s-deprecation"><title>Deprecated features</title>
+<para>
+Kernel packages must not invoke boot loaders except via hooks. If
+<literal>/etc/kernel-img.conf</literal> contains <literal>do_bootloader =
+yes</literal> or equivalent, maintainer scripts that previously acted on this
+must warn that they are ignoring it. <literal>linux-base</literal> must also
+warn on upgrade that the default has changed. In Debian 7.0 'wheezy', this
+prohibition extends to initramfs builder packages.
+</para>
+</section>
+
+<section id="s-init-config"><title>Initial configuration by the installer</title>
+<para>
+The installer must not define <literal>do_bootloader</literal>,
+<literal>postinst_hook</literal> or <literal>postrm_hook</literal> in
+<literal>/etc/kernel-img.conf</literal>.
+</para>
+</section>
+
+</chapter>
+
diff --git a/chapter-update-hooks.sgml b/chapter-update-hooks.sgml
deleted file mode 100644
index 5544f68..0000000
--- a/chapter-update-hooks.sgml
+++ /dev/null
@@ -1,155 +0,0 @@
-<chapt id="update-hooks">
- <heading>Package maintainer scripts and hooks</heading>
- <p>
- Kernel packages for Debian have historically had complex
- maintainer scripts which can invoke the initramfs builder and/or a
- boot loader, based on a mixture of file tests, explicit
- configuration through the file <tt>/etc/kernel-img.conf</tt> and
- debconf questions. Starting with Debian 6.0, this has been greatly
- simplified.
- </p>
- <p>
- The following policy applies to Debian GNU/Linux 6.0 'squeeze' and
- later releases. Some parts may be applicable to kernels other
- than Linux, but this policy does not set any requirements for
- them.
- </p>
- <sect id="kernel-hooks">
- <heading>Kernel hooks</heading>
- <p>
- The maintainer scripts in Linux kernel packages must use
- <tt>run-parts</tt> to invoke hook scripts in the corresponding
- subdirectory of <tt>/etc/kernel</tt>, e.g. the <tt>postinst</tt>
- script must invoke scripts in <tt>/etc/kernel/postinst.d</tt>.
- </p>
- <p>
- The arguments given to all kernel hook scripts are the kernel
- ABI version (the string that <tt>uname -r</tt> reports) and,
- optionally, the absolute path to the kernel image. If the
- second argument is missing then the path is
- either <tt>/boot/vmlinuz-<em>version</em></tt> or
- <tt>/boot/vmlinux-<em>version</em></tt>, according to
- architecture convention. The environment variable
- <tt>DEB_MAINT_PARAMS</tt> will contain the arguments given to
- the kernel maintainer script, possibly single-quoted. In a
- shell script, this variable can be parsed using:
- <example>
-eval set -- "$DEB_MAINT_PARAMS"
- </example>
- </p>
- <p>
- Kernel hook scripts may be run under debconf. In this case
- they must not use stdin and stdout, and should send all output
- to stderr (fd 2). A shell script can ensure that it does this
- using:
- <example>
-exec </dev/null >&2
- </example>
- </p>
- </sect>
- <sect id="kernel-hooks-loader">
- <heading>Kernel hooks required for boot loaders</heading>
- <p>
- Packages for boot loaders that need to be updated whenever the
- files they load are modified (i.e. those that store a block
- list) must install hook scripts in
- <tt>/etc/kernel/postinst.d</tt> and
- <tt>/etc/kernel/postrm.d</tt>.
- </p>
- <p>
- Since these boot loaders should be updated as the last step
- during installation/upgrade and removal, hook scripts for boot
- loaders must be named using the prefix <tt>zz-</tt> and no other
- packages may use this prefix or one that sorts later by the
- rules used by <tt>run-parts</tt>. A postrm hook script should
- warn but exit with code 0 if the boot loader configuration file
- still refers to the kernel image that has been removed.
- </p>
- <p>
- These boot loader packages must be installable on the filesystem
- in a disabled state where they will not write to the boot sector
- or other special storage. While a boot loader is disabled, any
- kernel hooks it includes must do nothing except (optionally)
- printing a warning that the boot loader is disabled, and must
- exit successfully.
- </p>
- <p>
- Packages for boot loaders that can provide a menu of kernel
- versions should install kernel hook scripts in order to update
- that menu.
- </p>
- </sect>
- <sect id="initramfs-hooks">
- <heading>Initramfs hooks</heading>
- <p>
- Packages for boot loaders that need to be updated whenever the
- files they load are modified must also install hook scripts in
- <tt>/etc/initramfs/post-update.d</tt>. Initramfs builders
- must call these scripts using <tt>run-parts</tt> after they
- create, update or delete an initramfs. The arguments given to
- these hook scripts are the kernel ABI version and the absolute
- path to the initramfs image.
- </p>
- <p>
- While a boot loader is disabled, any initramfs hook it includes
- must do nothing except (optionally) printing a warning that the
- boot loader is disabled, and must exit successfully.
- </p>
- </sect>
- <sect id="kernel-hooks-initramfs">
- <heading>Kernel hooks required for initramfs builders</heading>
- <p>
- Initramfs builders must install hook scripts in
- <tt>/etc/kernel/postinst.d</tt> and
- <tt>/etc/kernel/postrm.d</tt>, to create/update and delete the
- corresponding initramfs images. The postinst hook script must
- complete its work before returning.
- </p>
- </sect>
- <sect id="loader-optimisation">
- <heading>Optimising boot loader updates</heading>
- <p>
- During a kernel package installation, upgrade or removal, various
- boot loader hooks may be invoked (in this order):
- <enumlist>
- <item>
- A <tt>postinst_hook</tt> or <tt>postrm_hook</tt> command
- set by the user or the installer in
- <tt>/etc/kernel-img.conf</tt>
- </item>
- <item>
- A hook script in <tt>/etc/initramfs/post-update.d</tt>
- </item>
- <item>
- A hook script in <tt>/etc/kernel/postinst.d</tt> or
- ...<tt>/postrm.d</tt>
- </item>
- </enumlist>
- </p>
- <p>
- To avoid unnecessary updates, the hooks invoked at steps 1 and
- 2 may check whether <tt>$DPKG_MAINTSCRIPT_PACKAGE</tt> begins
- with <tt>linux-image-</tt> and do nothing in this case.
- </p>
- </sect>
- <sect id="deprecation">
- <heading>Deprecated features</heading>
- <p>
- Kernel packages must not invoke boot loaders except via hooks.
- If <tt>/etc/kernel-img.conf</tt> contains <tt>do_bootloader =
- yes</tt> or equivalent, maintainer scripts that previously
- acted on this must warn that they are ignoring
- it. <tt>linux-base</tt> must also warn on upgrade that the
- default has changed. In Debian 7.0 'wheezy', this prohibition
- extends to initramfs builder packages.
- </p>
- </sect>
- <sect id="init-config">
- <heading>Initial configuration by the installer</heading>
- <p>
- The installer must not define <tt>do_bootloader</tt>,
- <tt>postinst_hook</tt> or <tt>postrm_hook</tt> in
- <tt>/etc/kernel-img.conf</tt>.
- </p>
- </sect>
-</chapt>
diff --git a/chapter-versions.dbk b/chapter-versions.dbk
new file mode 100644
index 0000000..5e9b21f
--- /dev/null
+++ b/chapter-versions.dbk
@@ -0,0 +1,123 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<chapter id="ch-versions">
+<?dbhtml filename="ch-versions.html" ?>
+<title>Version numbers and ABIs</title>
+<section id="s-version-types"><title>The different types of version</title>
+<variablelist>
+<varlistentry>
+<term>Upstream version</term>
+<listitem>
+<para>
+The version that Linus or a stable series maintainer uses for a release.
+Currently Linus will use the version format:
+3.<replaceable>x</replaceable>[-rc<replaceable>y</replaceable>]. Stable series
+maintainers use the version format:
+3.<replaceable>x</replaceable>.<replaceable>y</replaceable>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Package version</term>
+<listitem>
+<para>
+The version used in a Debian package. Following Debian policy, it should
+follow the format
+<replaceable>upstreamversion</replaceable>-<replaceable>debianrevision</replaceable>.
+However, for an upstream release candidate, the string '-rc' must be replaced
+with '~rc' so that it will be recognised as an earlier version than the
+following release.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>Kernel version</term>
+<listitem>
+<para>
+This is the version that appears in kernel messages, filenames, package names
+and the output of 'uname -r'. In official kernel packages it follows the
+format
+<replaceable>upstreamversion</replaceable>[-<replaceable>abiname</replaceable>][-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable>.
+It is not changed for every new package version. The
+<replaceable>abiname</replaceable> is changed as explained below.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>
+Many programs parse the kernel version string reported by the
+<literal>uname</literal> system call or command and expect to find at least 3
+version components separated by dots. For compatibility, the official kernel
+packages currently add '.0' to the upstream version, but this will be dropped
+in wheezy+1.
+</para>
+</section>
+
+<section id="s-abi"><title>The kernel ABI</title>
+<para>
+An ABI (Application Binary Interface) is an interface between two software
+components, considered at the level of register allocation and memory layout.
+The ABI between the kernel and user-space is generally maintained carefully,
+and is not a concern here. However, the ABI between the kernel and its modules
+is not. In order to support out-of-tree modules, the kernel version should be
+changed when the ABI between the kernel and modules changes.
+</para>
+<section id="s-abi-name"><title>The ABI name</title>
+<para>
+In official kernel packages, we change the <replaceable>abiname</replaceable>
+part of the kernel version to mark ABI changes that aren't due to a new
+upstream version. This part comes from the <literal>abiname</literal> setting
+in <literal>debian/config/defines</literal>. We use either a number or 'trunk'
+(for experimental), but for a custom package it should be some other string.
+</para>
+</section>
+
+<section id="s-abi-maintenance"><title>Maintaining and updating the ABI</title>
+<para>
+In order to avoid the need for users to rebuild out-of-tree modules frequently,
+we try to avoid changing the kernel ABI during updates to a Debian stable or
+oldstable release. Most importantly, we avoid making such changes without
+changing the ABI name, except where it appears that out-of-tree modules do not
+depend on that part of the ABI.
+</para>
+<para>
+Bug fixes or configuration changes to the kernel may alter the ABI. If an
+exported function is conditional on
+<literal>CONFIG_</literal><replaceable>FOO</replaceable>, or it uses a type
+whose definition depends on
+<literal>CONFIG_</literal><replaceable>FOO</replaceable>, then turning
+<literal>CONFIG_</literal><replaceable>FOO</replaceable> on or off changes the
+ABI of that function, and thus of the kernel as a whole. Enabling or changing
+the configuration of a single driver usually doesn't change the ABI, because
+most drivers don't export anything.
+</para>
+<para>
+The kernel build process generates a 'symbol version' for each exported
+function or variable. This is a hash of the definitions that it depends on,
+and should change whenever the function's ABI changes. The kernel module
+loader detects incompatible modules by comparing symbol versions. The whole
+set of symbol versions represents the kernel ABI.
+</para>
+<para>
+We collect the symbol versions for previously uploaded packages under the
+directory <literal>debian/abi</literal> and then compare the new kernel with
+those. If the ABI name is unchanged but the ABI itself is changed - except for
+additions, or changes that we have marked as acceptable - then the build is
+aborted.
+</para>
+<para>
+If the kernel ABI has changed you must then change the ABI name in
+<literal>debian/config/defines</literal>. Then run the command
+</para>
+<screen>
+$ fakeroot debian/rules debian/control-real
+</screen>
+<para>
+to regenerate the package definitions for this ABI name.
+</para>
+</section>
+
+</section>
+
+</chapter>
+
diff --git a/chapter-versions.sgml b/chapter-versions.sgml
deleted file mode 100644
index 49e7210..0000000
--- a/chapter-versions.sgml
+++ /dev/null
@@ -1,125 +0,0 @@
- <chapt id="versions">
- <heading>Version numbers and ABIs</heading>
-
- <sect id="version-types">
- The different types of version
-
- <p>
- <taglist>
- <tag>Upstream version</tag>
- <item>
- The version that Linus or a stable series maintainer uses
- for a release. Currently Linus will use the version
- format: 3.<var>x</var>[-rc<var>y</var>]. Stable series
- maintainers use the version format:
- 3.<var>x</var>.<var>y</var>.
- </item>
- <tag>Package version</tag>
- <item>
- The version used in a Debian package. Following Debian
- policy, it should follow the format
- <var>upstreamversion</var>-<var>debianrevision</var>.
- However, for an upstream release candidate, the string
- '-rc' must be replaced with '~rc' so that it will be
- recognised as an earlier version than the following release.
- </item>
- <tag>Kernel version</tag>
- <item>
- This is the version that appears in kernel messages,
- filenames, package names and the output of 'uname -r'.
- In official kernel packages it follows the format
- <var>upstreamversion</var>[-<var>abiname</var>][-<var>featureset</var>]-<var>flavour</var>.
- It is not changed for every new package version.
- The <var>abiname</var> is changed as explained below.
- </item>
- </taglist>
- </p>
-
- <p>
- Many programs parse the kernel version string reported by
- the <tt>uname</tt> system call or command and expect to find
- at least 3 version components separated by dots. For
- compatibility, the official kernel packages currently add
- '.0' to the upstream version, but this will be dropped in
- wheezy+1.
- </p>
- </sect>
-
- <sect id="abi">
- The kernel ABI
-
- <p>
- An ABI (Application Binary Interface) is an interface
- between two software components, considered at the level of
- register allocation and memory layout. The ABI between the
- kernel and user-space is generally maintained carefully, and
- is not a concern here. However, the ABI between the kernel
- and its modules is not. In order to support out-of-tree
- modules, the kernel version should be changed when the ABI
- between the kernel and modules changes.
- </p>
-
- <sect1 id="abi-name">
- The ABI name
- <p>
- In official kernel packages, we change the
- <var>abiname</var> part of the kernel version to mark ABI
- changes that aren't due to a new upstream version. This
- part comes from the <tt>abiname</tt> setting in
- <tt>debian/config/defines</tt>. We use either a number or
- 'trunk' (for experimental), but for a custom package it
- should be some other string.
- </p>
- </sect1>
-
- <sect1 id="abi-maintenance">
- Maintaining and updating the ABI
- <p>
- In order to avoid the need for users to rebuild
- out-of-tree modules frequently, we try to avoid changing
- the kernel ABI during updates to a Debian stable or
- oldstable release. Most importantly, we avoid making such
- changes without changing the ABI name, except where it
- appears that out-of-tree modules do not depend on that
- part of the ABI.
- </p>
- <p>
- Bug fixes or configuration changes to the kernel may alter
- the ABI. If an exported function is conditional on
- <tt>CONFIG_</tt><var>FOO</var>, or it uses a type whose
- definition depends on <tt>CONFIG_</tt><var>FOO</var>, then
- turning <tt>CONFIG_</tt><var>FOO</var> on or off changes
- the ABI of that function, and thus of the kernel as a
- whole. Enabling or changing the configuration of a single
- driver usually doesn't change the ABI, because most
- drivers don't export anything.
- </p>
- <p>
- The kernel build process generates a 'symbol version' for
- each exported function or variable. This is a hash of the
- definitions that it depends on, and should change whenever
- the function's ABI changes. The kernel module loader
- detects incompatible modules by comparing symbol versions.
- The whole set of symbol versions represents the kernel
- ABI.
- </p>
- <p>
- We collect the symbol versions for previously uploaded
- packages under the directory <tt>debian/abi</tt> and then
- compare the new kernel with those. If the ABI name is
- unchanged but the ABI itself is changed - except for
- additions, or changes that we have marked as acceptable -
- then the build is aborted.
- </p>
- <p>
- If the kernel ABI has changed you must then change the ABI
- name in <tt>debian/config/defines</tt>. Then run the
- command
- <example>
-$ fakeroot debian/rules debian/control-real
- </example>
- to regenerate the package definitions for this ABI name.
- </p>
- </sect1>
- </sect>
- </chapt>
diff --git a/debian/changelog b/debian/changelog
index ff8742b..fce14eb 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -5,6 +5,7 @@ kernel-handbook (1.0.17) UNRELEASED; urgency=medium
* Remove 'python' from genorig.py command lines, as this is not needed
and is incorrect since it now needs Python 3
* Use changelog date as document date
+ * Convert all source files to DocBook format
-- Ben Hutchings <ben at decadent.org.uk> Sun, 30 Aug 2015 13:21:25 +0100
diff --git a/kernel-handbook.dbk b/kernel-handbook.dbk
new file mode 100644
index 0000000..0541b84
--- /dev/null
+++ b/kernel-handbook.dbk
@@ -0,0 +1,64 @@
+<?xml version='1.0' encoding='utf-8'?>
+<!-- -*- DocBook -*- -->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % versiondata SYSTEM "version.ent"> %versiondata;
+]>
+
+<book lang="en">
+<?dbhtml filename="index.html" ?>
+
+<title>Debian Linux Kernel Handbook</title>
+
+<bookinfo>
+
+<authorgroup>
+<corpauthor><link linkend="s-authors">The Debian Kernel Handbook Project</link></corpauthor>
+
+</authorgroup>
+<releaseinfo>version &version;</releaseinfo>
+
+<pubdate>&date;</pubdate>
+
+
+<copyright><year>2005-2012</year><holder>Debian Kernel Handbook Project</holder></copyright>
+<legalnotice>
+<para>
+This handbook is free software; you may redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2, or (at your option) any later version.
+</para>
+<para>
+This is distributed in the hope that it will be useful, but <emphasis>without
+any warranty</emphasis>; without even the implied warranty of merchantability
+or fitness for a particular purpose. See the GNU General Public License for
+more details.
+</para>
+<para>
+A copy of the GNU General Public License is available as
+<filename>/usr/share/common-licenses/GPL</filename> in the Debian GNU/Linux
+distribution or on the World Wide Web at <ulink
+url="http://www.gnu.org/copyleft/gpl.html">the GNU General Public
+Licence</ulink>. You can also obtain it by writing to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+</para>
+</legalnotice>
+
+</bookinfo>
+
+<!-- XInclude list start -->
+<xi:include href="chapter-scope.dbk" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="chapter-source.dbk" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="chapter-packaging.dbk" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="chapter-common-tasks.dbk" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="chapter-versions.dbk" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="chapter-modules.dbk" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="chapter-initramfs.dbk" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="chapter-update-hooks.dbk" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<xi:include href="chapter-bugs.dbk" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+<!-- XInclude list end -->
+
+
+
+</book>
+
diff --git a/kernel-handbook.sgml b/kernel-handbook.sgml
deleted file mode 100644
index 2eae126..0000000
--- a/kernel-handbook.sgml
+++ /dev/null
@@ -1,68 +0,0 @@
-<!doctype debiandoc system [
-<!-- include version information so we don't have to hard code it
- within the document -->
-<!entity % versiondata SYSTEM "version.ent"> %versiondata;
-<!entity chapter-scope SYSTEM "chapter-scope.sgml">
-<!entity chapter-source SYSTEM "chapter-source.sgml">
-<!entity chapter-packaging SYSTEM "chapter-packaging.sgml">
-<!entity chapter-common-tasks SYSTEM "chapter-common-tasks.sgml">
-<!entity chapter-versions SYSTEM "chapter-versions.sgml">
-<!entity chapter-modules SYSTEM "chapter-modules.sgml">
-<!entity chapter-initramfs SYSTEM "chapter-initramfs.sgml">
-<!entity chapter-update-hooks SYSTEM "chapter-update-hooks.sgml">
-<!entity chapter-bugs SYSTEM "chapter-bugs.sgml">
-]>
-<debiandoc>
-
- <book>
- <titlepag>
- <title>Debian Linux Kernel Handbook</title>
- <author><qref id="authors">The Debian Kernel Handbook Project</qref></author>
- <version>version &version;, &date;</version>
-
- <copyright>
- <copyrightsummary>
- Copyright © 2005-2012 Debian Kernel Handbook Project
- </copyrightsummary>
- <p>
- This handbook is free software; you may redistribute it and/or
- modify it under the terms of the GNU General Public License
- as published by the Free Software Foundation; either version
- 2, or (at your option) any later version.
- </p>
-
- <p>
- This is distributed in the hope that it will be useful, but
- <em>without any warranty</em>; without even the implied
- warranty of merchantability or fitness for a particular
- purpose. See the GNU General Public License for more
- details.
- </p>
-
- <p>
- A copy of the GNU General Public License is available as
- <file>/usr/share/common-licenses/GPL</file> in the Debian GNU/Linux
- distribution or on the World Wide Web at
- <url id="http://www.gnu.org/copyleft/gpl.html"
- name="the GNU General Public Licence">. You can also
- obtain it by writing to the Free Software Foundation, Inc.,
- 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
- </p>
- </copyright>
- </titlepag>
-
- <toc detail="sect1">
-
- &chapter-scope;
- &chapter-source;
- &chapter-packaging;
- &chapter-common-tasks;
- &chapter-versions;
- &chapter-modules;
- &chapter-initramfs;
- &chapter-update-hooks;
- &chapter-bugs;
-
- </book>
-</debiandoc>
-
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 811 bytes
Desc: Digital signature
URL: <http://lists.alioth.debian.org/pipermail/kernel-handbook-general/attachments/20151105/d4b71532/attachment-0001.sig>
More information about the Kernel-handbook-general
mailing list