<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  <!ENTITY DhtoolRefentry SYSTEM "dh_installkpatches.refentry-contents.sgml">
<!--  <!ENTITY DhtoolRefentry SYSTEM "dh_installkpatches.refentry.sgml" SUBDOC> -->
]>

<article>
  <articleinfo>
    <title>Packaging Linux kernel patches for Debian</title>
    <author>
      <firstname>Yann</firstname>
      <surname>Dirson</surname>
      <affiliation>
	<orgname>Debian</orgname>
	<address><email>dirson@debian.org</email></address>
      </affiliation>
    </author>
    <releaseinfo>$Revision: 1.14 $</releaseinfo>

    <abstract>
      <para>This document describes a debhelper add-on mechanism that
      allows consistent packaging of various kinds of Linux kernel
      patches.</para>
    </abstract>

    <revhistory>
      <revision>
	<revnumber>1.1</revnumber>
	<date>2000-06-10</date>
	<revremark>Initial plain-text revision</revremark>
      </revision>
      <revision>
	<revnumber>1.4</revnumber>
	<date>2001-05-14</date>
	<revremark>New "Depends" field</revremark>
      </revision>
      <revision>
	<revnumber>1.8</revnumber>
	<date>2002-02-08</date>
	<revremark>New syntax "Kernel-version: all"</revremark>
      </revision>
      <revision>
	<revnumber></revnumber>
	<date>2002-02-10</date>
	<revremark>Moved to DocBook, made it more of a real
	manual</revremark>
      </revision>
      <revision>
	<revnumber>1.9</revnumber>
	<date>2002-02-14</date>
	<revremark>Kernel-version ranges</revremark>
      </revision>
      <revision>
	<revnumber>1.10</revnumber>
	<date>2002-02-18</date>
	<revremark>First description of "revision 1" format</revremark>
      </revision>
      <revision>
	<revnumber>1.12</revnumber>
	<date>2002-07-16</date>

	<revremark>Integrated feedback from maintainers of
	kpatch-packages.  Default fields.  Renamed operations.
	Miscellaneous updates and additions.</revremark>
      </revision>
      <revision>
	<revnumber>1.13</revnumber>
	<date>2003-04-04</date>
	<revremark>New field "Debian-patch-file"</revremark>
      </revision>
    </revhistory>
  </articleinfo>

  <section>
    <title>Features</title>

    <itemizedlist>
      <title>Current features</title>
      <listitem>
	<para>robustness of patch application</para>
      </listitem>
      <listitem>
	<para>support for variable parameters on
	<citerefentry><refentrytitle>patch</><manvolnum>1</></>
	command line (eg. <option>-p</>)</para>
      </listitem>
      <listitem>
	<para>allows to apply a version of a patch that was originally
	targetted at another version</para>
      </listitem>
      <listitem>
	<para>handles (un-)application of patch dependencies</para>
      </listitem>
      <listitem>
	<para>records in kernel packages build with this patch applied
	the name and version of the package which shipped the
	patch.</para>
      </listitem>
    </itemizedlist>

    <itemizedlist>
      <title>Features to come with version 1.0</title>
      <listitem>
	<para>application of multi-part patches</para>
      </listitem>
      <listitem>
	<para>support for file copying and archive unpacking as patch
	operation, in addition to diff application</para>
      </listitem>
      <listitem>
	<para>support for patch variants for different flavours of a
	kernel, both to support heavy patches, and to help dealing
	with otherwise overlaping patches</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>The <command>dh_installkpatches</> debhelper add-on</title>

    <refentry>
    &DhtoolRefentry;
    </refentry>
  </section>

  <section>
    <title>Description of the <filename>kpatches</> file format</title>

    <para>The syntax of <filename>kpatches</> files is inspired by the
    syntax of Debian control-files.  A <filename>kpatches</> file
    contains sections, which are separated by one or more empty lines.
    Each section is made of <literal>Key: value</> lines.</para>

    <section>
      <title>Revision 0 kpatches files</title>

      <para>This is the currently supported format for kpatches files.
	It is to be superceded shortly with a new revision, more
	general, described later in this document.</para>

      <para>The file starts with a section for generic patch
	information, and then has one for each patchfile, allowing
	versions of the patch for many kernel versions to be specified
	in one file.</para>

      <section>
	<title>The generic part</title>

	<section>
	  <title>Mandatory fields</title>

	  <glosslist>
	    <glossentry>
	      <glossterm>Patch-name</glossterm>
	      <glossdef>
		<para>a short descriptive name for the patch
		  <note>
		    <para>Patch-name's cannot contain "pipe" (|) and
		      "double quote" (") characters, for purely
		      implementation reasons.  Patch-name's that contain
		      "slash" (/) characters would not be allowed before
		      dh-kpatches 0.99.3.</para>
		  </note>
		</para>
		<example>
		  <title>Examples</title>
		  <programlisting>
		    Patch-name: Kernel debugger
		    Patch-name: Tracing toolkit
		    Patch-name: Kernel crash dump</programlisting>
		</example>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Patch-id</glossterm>
	      <glossdef>
		<para>a short identifier for the patch</para>
		<example>
		  <title>Examples</title>
		  <programlisting>
		    Patch-id: kdb
		    Patch-id: ltt
		    Patch-id: lkcd</programlisting>
		</example>
	      </glossdef>
	    </glossentry>
	  </glosslist>
	</section>

	<section>
	  <title>Optional fields</title>

	  <glosslist>
	    <glossentry>
	      <glossterm>Path-strip-level</glossterm>
	      <glossdef>
		<para>default value for the per-patchfile field of the
		  same name (see below).</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Architecture</glossterm>
	      <glossdef>
		<para>default value for the per-patchfile field of the
		  same name (see below).</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Depends</glossterm>
	      <glossdef>
		<para>default value for the per-patchfile field of the
		  same name (see below).</para>
	      </glossdef>
	    </glossentry>
	  </glosslist>
	</section>
      </section>

      <section>
	<title>The patchfile-specific parts</title>
	<section>
	  <title>Mandatory fields</title>

	  <glosslist>
	    <glossentry>
	      <glossterm>Patch-file</glossterm>
	      <glossdef>
		<para>The name of the patch file.  It may optionally be
		  compressed with gzip.  This should be the first field of
		  each patchfile-specific section.</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Kernel-version</glossterm>
	      <glossdef>
		<para>The version (or range of versions) of the kernel
		  this patch is designed for.  Other optional fields may
		  be introduced in the future to document other versions
		  which are known to work, and versions known not to
		  work.</para>

		<para>Version ranges are specified as <literal
		><replaceable >ver1</> - <replaceable >ver2</></>,
		where both versions must belong to the same "kernel
		branch" (eg. 2.2, or 2.4), and must be mentionned in
		increasing order.<note>
		    
		    <para>Kernel versions used in ranges should show
		    an empty EXTRAVERSION field.  This is because no
		    special comparision scheme has been implemented to
		    handle the special meaning associated with
		    EXTRAVERSION values like <literal>pre2</> or
		    <literal>test5</>.</para> </note></para>

		<para>As a special case, the value "all" is allowed, for
		  patches that don't depend on a specific version (eg. if
		  they just add a set of files).</para>
	      </glossdef>
	    </glossentry>
	  </glosslist>
	</section>

	<section>
	  <title>Optional fields</title>

	  <para>The optional fields, when not provided, all take
	    hopefully reasonable default values</para>

	  <glosslist>
	    <glossentry>
	      <glossterm>Architecture</glossterm>
	      <glossdef>
		<para>a comma-separated list of the debian identifiers
		  for archs supported by this patch.</para>
		<para>Default is "all".</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Path-strip-level</glossterm>
	      <glossdef>
		<para>the value to pass as argument to the
		  <citerefentry><refentrytitle>patch</><manvolnum>1</></>
		  <option>-p</> option (aka <option>--strip</>).</para>
		<para>Default is 1.</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Depends</glossterm>
	      <glossdef>
		<para>a comma-separated list of Patch-Id's of patches
		  this one depends on.</para>
		<para>Default is no dependency.</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Debian-patch-file</glossterm>
	      <glossdef>
		<para>A special version of Patch-file, specifying that
		a version of the patch file that only applies to a
		Debian-patched kernel from a
		<literal>kernel-source-<replaceable>version</></>
		package, in case the vanilla patch does not
		fit.</para>
	      </glossdef>
	    </glossentry>
	  </glosslist>
	</section>
      </section>

      <section>
	<title>Examples of revision 0 <filename>kpatches</> files</title>

	<section>
	  <title>kdb</title>

	  <para>These are the 2 <filename>kpatches</> files for the
	  kernel-debugger patch.  This patch was monolithic for 2.2
	  kernels, and has been split for recent 2.4 kernels into an
	  architecture-independant part and one architecture-dependant
	  part per supported architecture.</para>

	  <example>
	    <title>The architecture-independant kdb patch</title>
	    <programlisting><inlinemediaobject>
		<imageobject>
		  <imagedata fileref="../examples/kernel-patch-kdb.kpatches.common" format="linespecific">
		</imageobject>
	      </inlinemediaobject></programlisting>
	  </example>
	  
	  <example>
	    <title>The architecture-dependant kdb patches</title>
	    <programlisting><inlinemediaobject>
		<imageobject>
		  <imagedata fileref="../examples/kernel-patch-kdb.kpatches.arch" format="linespecific">
		</imageobject>
	      </inlinemediaobject></programlisting>
	  </example>
	</section>
      </section>
    </section>

    <section>
      <title>Revision 1 kpatches files</title>

      <para>This will be the next supported format for kpatches files.
      It has not been implemented yet.  It is described here for
      public review.</para>

      <para>There are 3 levels of information in this file.  A
      kernel-patch (1st level) is a set of patch alternatives (2nd
      level), each of which is made of a sequence of patch operations
      (3rd level).</para>

      <para>The file starts with a section for generic patch
      information, and then, for each alternative, has an
      alternative-specific section followed by one section for each
      patch operation.</para>

      <para>An alternative section is syntactically distinguished from
      an operation section by their mandatory constituent fields.</para>

      <section>
	<title>The generic part</title>

	<section>
	  <title>Mandatory fields.</title>

	  <glosslist>
	    <glossentry>
	      <glossterm>Kpatch-format-version</glossterm>
	      <glossdef>
		<para>the version of the kpatches spec this files
		complies with.  For this version, it should be 1.</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Patch-name</glossterm>
	      <glossdef>
		<para>a short descriptive name for the patch
		<note>
		    <para>Patch-name's cannot contain "pipe" (|) and
		    "double quote" (") characters, for purely
		    implementation reasons.  Patch-name's that contain
		    "slash" (/) characters would not be allowed before
		    dh-kpatches 0.99.3.</para>
		  </note>
	      </para>
		<example>
		  <title>Examples</title>
		  <programlisting>
		  Patch-name: Kernel debugger
		  Patch-name: Tracing toolkit
		  Patch-name: Kernel crash dump</programlisting>
		</example>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>OS-kernel</glossterm>
	      <glossdef>
		<para>The identifier of the kernel the patch is meant
	      for.  Current possible values include <literal>linux</>,
	      <literal>hurd</>, <literal>netbsd</>, and there is a
	      default value of <literal>linux</>.</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Patch-id</glossterm>
	      <glossdef>
		<para>a short identifier for the patch</para>
		<example>
		  <title>Examples</title>
		  <programlisting>
		  Patch-id: kdb
		  Patch-id: ltt
		  Patch-id: lkcd</programlisting>
		</example>
	      </glossdef>
	    </glossentry>
	  </glosslist>
	</section>

	<section>
	  <title>Optional fields</title>

	  <para>For various fields in the alternative-specific and
	  operation-specific parts it can be useful to provide default
	  values.  These are defined using fields named by prepending
	  <literal>Default-</> to those fields names.</para>

	  <para>Examples include <literal>Default-Path-strip-level</>
	  and <literal>Default-Architecture</>.</para>
	</section>
      </section>


      <section>
	<title>The alternative-specific parts</title>

	<para>A number of alternative-specific fields are used as
	<emphasis>conditions</> for this alternative to be considered.
	This allows not only to specify in the same file versions of
	the patch for many kernel versions, but also to specify
	versions of the patch for different <emphasis>kernel
	flavours</>.  For example, the LTT patch comes for 2 kernel
	flavours: plain kernel, and RTAI-patched kernel.</para>
      
	<para>The order of alternative sections is significant: the
	1st alternative for which all conditions are fullfilled is
	selected, and all further alternatives are ignored.</para>

	<section>
	  <title>Mandatory fields</title>

	  <glosslist>
	    <glossentry>
	      <glossterm>Kernel-version</glossterm>
	      <glossdef>
		<para>This field is a condition.</para>

		<para>The version (or range of versions) of the kernel
		  this patch is designed for.  Other optional fields may
		  be introduced in the future to document other versions
		  which are known to work, and versions known not to
		  work.</para>

		<para>Version ranges are specified as <literal
		><replaceable >ver1</> - <replaceable >ver2</></>,
		where both versions must belong to the same "kernel
		branch" (eg. 2.2, or 2.4), and must be mentionned in
		increasing order.</para>

		<para>As a special case, the value "all" is allowed, for
		  patches that don't depend on a specific version (eg. if
		  they just add a set of files).</para>
	      </glossdef>
	    </glossentry>
	  </glosslist>
	</section>

	<section>
	  <title>Optional fields</title>

	  <para>The optional fields, when not provided, all take
	    hopefully reasonable default values</para>

	  <glosslist>
	    <glossentry>
	      <glossterm>Kernel-flavour</glossterm>
	      <glossdef>
		<para>This field is a condition for this alternative
		to be considered - a test to check whether a patch is
		applied.  It is not to be confused with
		<literal>Depends</>, which will pull others patches
		first if they are not applied yet.</para>

		<para>a comma-separated list of Patch-Id's of patches
		that need to be applied for this one to be considered
		for application.<note> <para>It may be necessary to
		add support for flavour versionning (if a patch is
		disruptive enough to warrant being qualified as a
		flavour, it is likely that some of its evolution will
		be disruptive as well).</para> </note> <note> <para>It
		may be useful to add flavour negations, this has to be
		investigated at some point.</para> </note> </para>

		<para>Default is "" (plain/vanilla kernel).</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Architecture</glossterm>
	      <glossdef>
		<para>This field is a condition.</para>

		<para>a comma-separated list of the debian identifiers
		  for archs supported by this patch.</para>
		<para>Default is "all".</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>Depends</glossterm>
	      <glossdef>
		<para>This field is NOT a condition.</para>

		<para>a comma-separated list of Patch-Id's of patches
		this one depends on.  Patches in this list, as opposed
		to those in the Kernel-flavour list, are such that
		this patch cannot be applied without them.</para>

		<para>Default is "" (no dependency).</para>
	      </glossdef>
	    </glossentry>
	  </glosslist>
	</section>
      </section>

      <section>
	<title>The operation-specific parts</title>
	<section>
	  <title>Mandatory fields</title>

	  <note>
	    <para>I have not firmly decided yet how to formalise these
	    parts, and I'm looking for opinions here.</para>

	    <para>I had originally elected to put the emphasis on
	    <emphasis>operations</>; this is fine with "copy" and
	    "unpack", but "diff" usually refer to the inverse
	    operation (building the data), and "patch", despite being
	    used for this purpose for quite some time now, is already
	    being used here with a broader meaning.  Another problem
	    with "unpack" is that it is broad enough so that the data
	    (ie. archive) may potentially be provided in several
	    formats (eg. tar.gz, tar.bz2, zip, etc.) - that will
	    require some (unnecessary) intelligence within the tool,
	    and will impair modularity (ie. adding support for more
	    archive formats using plugin modules).</para>

	    <para>Another alternative would be to put the emphasis on
	    the <emphasis>data</>.  That would mean replacing
	    <literal>Operation</> fields with something like
	    <literal>Format</> fields, which would have values like
	    "tree", "file", "diff", "tar.gz", "tar", etc.  A careful
	    object-oriented implementation would take care of the
	    similarities between those.</para>

	    <para>Another one was suggested by Baruch Even - see below
	    for an example and some discussion.</para>
	  </note>

	  <glosslist>
	    <glossentry>
	      <glossterm>Operation</glossterm>
	      <glossdef>
		<para>The identifier for a type of patch operation.
		Valid operations may include "diff", "copy", "unpack",
		possibly depending on installed plugins.  Other fields
		in the section will depend on the value of this
		field.</para>
	      </glossdef>
	    </glossentry>
	  </glosslist>
	</section>

	<section>
	  <title>Types of operation</title>

	  <glosslist>
	    <glossentry>
	      <glossterm>diff</glossterm>
	      <glossdef>
		<para>The application of a diff file (aka. patch file)
		to the kernel tree.</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>copy</glossterm>
	      <glossdef>
		<para>The copy of a file, or of a directory tree into
		the kernel tree.</para>
	      </glossdef>
	    </glossentry>
	    <glossentry>
	      <glossterm>unpack</glossterm>
	      <glossdef>
		<para>The unpacking of a tarball (or other archive ?)
		into the kernel tree.</para>
	      </glossdef>
	    </glossentry>
	  </glosslist>
	</section>

	<section>
	  <title>Per-operation-type fields</title>

	  <section>
	    <title>Fields for the <emphasis>diff</> operation</title>

	    <section>
	      <title>Mandatory fields</title>
	      <glosslist>
		<glossentry>
		  <glossterm>File</glossterm>
		  <glossdef>
		    <para>The name of the diff file.</para>
		  </glossdef>
		</glossentry>
	      </glosslist>
	    </section>

	    <section>
	      <title>Optional fields</title>

	      <glosslist>
		<glossentry>
		  <glossterm>Path-strip-level</glossterm>
		  <glossdef>
		    <para>the value to pass as argument to the
		      <citerefentry><refentrytitle>patch</><manvolnum>1</></>
		      <option>-p</> option (aka <option>--strip</>).</para>
		    <para>Default is 1.</para>
		  </glossdef>
		</glossentry>
	      </glosslist>
	    </section>
	  </section>

	  <section>
	    <title>Fields for the <emphasis>unpack</> operation</title>
	    <section>
	      <title>Mandatory fields</title>
	      <glosslist>
		<glossentry>
		  <glossterm>File</glossterm>
		  <glossdef>
		    <para>The name of the archive file.</para>
		  </glossdef>
		</glossentry>
	      </glosslist>
	    </section>

	    <section>
	      <title>Optional fields</title>
	      <glosslist>
		<glossentry>
		  <glossterm>Path-strip-level</glossterm>
		  <glossdef>
		    <para>Similar to the option of the same name for
		    the <literal>diff</> operation: strips the
		    <replaceable>N</> first path components of each
		    member the archive.</para>
		    <para>Default is 0.</para>
		    
		    <para>For tarballs, this option will probably
		    require <citerefentry> <refentrytitle>pax</>
		    <manvolnum>1</> </citerefentry> to be
		    applicable.</para>
		  </glossdef>
		</glossentry>
	      </glosslist>
	    </section>
	  </section>

	  <section>
	    <title>Fields for the <emphasis>copy</> operation</title>
	    <section>
	      <title>Mandatory fields</title>
	      <glosslist>
		<glossentry>
		  <glossterm>From</glossterm>
		  <glossdef>
		    <para>The path of the file or directory to copy.</para>
		  </glossdef>
		</glossentry>
		<glossentry>
		  <glossterm>To</glossterm>
		  <glossdef>
		    <para>The directory in which to copy it.</para>
		  </glossdef>
		</glossentry>
	      </glosslist>
	    </section>
	  </section>
	</section>

      </section>

      <section>
	<title>Examples of revision 1 <filename>kpatches</> files</title>

	<section>
	  <title>ltt</title>

	  <para>The <application>Linux trace toolkit</> provides
	  kernel patches both for vanilla kernels and for RTAI
	  kernels.  Although there's not yet a packaged version of the
	  RTAI patch, here is what it would look like.</para>

	  <example>
	    <title>The LTT patch</title>
	    <programlisting><inlinemediaobject>
		<imageobject>
		  <imagedata fileref="../examples-v1/kernel-patch-ltt.kpatches" format="linespecific">
		</imageobject>
	      </inlinemediaobject></programlisting>
	  </example>
	  
	</section>

	<section>
	  <title>lkcd</title>

	  <para>The <application>kernel crash dump</> patch requires
	  that a script be copied into the <filename>debian</> part of
	  the kernel tree.  Currently this is done by a creating a new
	  patch (named <literal>kerntypes</>) with hand-written
	  <literal>apply</> script, not taking advantage of the
	  dh-kpatches mechanism.  Here is how it would look like in
	  revision 1:</para>

	  <example>
	    <title>The LKCD patch</title>
	    <programlisting><inlinemediaobject>
		<imageobject>
		  <imagedata fileref="../examples-v1/kernel-patch-lkcd.kpatches" format="linespecific">
		</imageobject>
	      </inlinemediaobject></programlisting>
	  </example>
	  
	  <para>Baruch Even <email>baruch@debian.org</> suggested a
	  syntax that may be simpler.  Here is the same example
	  rewritten to use such a syntax, with some interpolations
	  from myself.</para>

	  <example>
	    <title>The LKCD patch (alternate version)</title>
	    <programlisting><inlinemediaobject>
		<imageobject>
		  <imagedata fileref="../examples-v1/kernel-patch-lkcd-alt.kpatches" format="linespecific">
		</imageobject>
	      </inlinemediaobject></programlisting>
	  </example>

	  <para>The description is more concise, but I fear it would
	  be too losely structured (much more of the information gets
	  stored in left-hand parts of statement), possibly leading to
	  strange-looking stanzas, and possibly impairing
	  extensibility.  Here is what the expanded version of the
	  last sample (without default fields) would look like:</para>

	  <example>
	    <title>The LKCD patch (second alternate version)</title>
	    <programlisting><inlinemediaobject>
		<imageobject>
		  <imagedata fileref="../examples-v1/kernel-patch-lkcd-alt-expanded.kpatches" format="linespecific">
		</imageobject>
	      </inlinemediaobject></programlisting>
	  </example>


	  <para>In the same spirit, but datatype-driven instead of
	  operation-driven.  This one lies somewhere in between
	  Baruch's proposal and my original one.</para>

	  <example>
	    <title>The LKCD patch (third alternate version)</title>
	    <programlisting><inlinemediaobject>
		<imageobject>
		  <imagedata fileref="../examples-v1/kernel-patch-lkcd-alt3.kpatches" format="linespecific">
		</imageobject>
	      </inlinemediaobject></programlisting>
	  </example>

	</section>
      </section>
    </section>
  </section>

</article>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-shorttag:t
End:
-->
