r3465 - trunk/docs/handbook

[Jurij Smakov]

Author: jurij-guest
Date: 2005-07-12 03:14:28 +0000 (Tue, 12 Jul 2005)
New Revision: 3465

Modified:
   trunk/docs/handbook/kernel-handbook.sgml
Log:
Update the chapter about arch-dependent packages.


Modified: trunk/docs/handbook/kernel-handbook.sgml
===================================================================
--- trunk/docs/handbook/kernel-handbook.sgml	2005-07-12 00:35:00 UTC (rev 3464)
+++ trunk/docs/handbook/kernel-handbook.sgml	2005-07-12 03:14:28 UTC (rev 3465)
@@ -266,9 +266,97 @@
       </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>subarchitecture</em>, and
+	  <em>flavour</em>. Kernels for most 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 for certain classes of
+	  hardware, additional changes to the Debian kernel source may
+	  be required. In that case, the patch set applied to produce
+	  a modified tree determines the subarchitecture.  Again,
+	  multiple flavours of binary images may be build from the
+	  subarchitecture tree. For example, the <tt>powerpc</tt>
+	  architecture may have <tt>power4</tt> and
+	  <tt>power4-smp</tt> flavours, built from the common Debian
+	  kernel source, as well as an <tt>apus</tt>
+	  subarchitecture. Tree for that subarchitecture is obtained
+	  by applying <tt>apus</tt>-specific patches to the Debian
+	  kernel source. This tree may be further used to build the
+	  <tt>apus-up</tt> and <tt>apus-smp</tt> binary image flavours
+	  <footnote> This example is for illustrative purposes only.
+	  Currently there are no supported subarchitectures in Debian.
+	  </footnote>. All the flavour identifiers across all
+	  architectures and subarchitectures are unique, so that the
+	  flavour name may be uniquely mapped to a (sub)architecture,
+	  if need arises.  The names of the Debian binary packages
+	  incorporate the name of the flavour and, if necessary, the
+	  name of the subarchitecture (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 subarches, the
+	  subarch part is omitted from the name.
+	</p>
+	<p>
+	  Package names also include the <em>abiname</em>, a small
+	  integer, which identifies the kernel's 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>subarch</em>-<em>version</em>-<em>abiname</em></tt></tag>
+	  <item>
+	    This package contains a common set of kernel headers for a particular
+	    subarch (or arch, if subarch 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>subarch</em>-<em>version</em>-<em>abiname</em></tt>
+	    directory.
+	  </item>
+	  </taglist>
+	  <taglist>
+	  <tag><tt>linux-headers-<em>subarch</em>-<em>version</em>-<em>abiname</em>-<em>flavour</em></tt></tag>
+	  <item>
+	    This package provides flavour-specific header files. It depends on the corresponding
+	    <tt>linux-headers-<em>subarch</em>-<em>version</em>-<em>abiname</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>subarch</em>-<em>version</em>-<em>abiname</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>subarch</em>-<em>version</em>-<em>abiname</em>-<em>flavour</em></tt></tag>
+	  <item>
+	  Bleh.
+	  </item>	  
+	  </taglist>
+	</p>
       </sect>
       <sect id="other-pkg">
         <heading>Other kernel-related packages</heading>
+	<p>
+	  To be contributed.
+	</p>
       </sect>
     </chapt>
     <chapt id="common-tasks">
@@ -416,12 +504,21 @@
       </sect>
       <sect id="common-out-of-tree">
         <heading>Building out-of-tree kernel modules</heading> 
+	<p>
+	  To be contributed.
+	</p>
       </sect>
       <sect id="common-debian-patches">
         <heading>Building kernels with packaged patches</heading>
+	<p>
+	  To be contributed.
+	</p>
       </sect>
       <sect id="common-ext-patches">
         <heading>Building kernels with third-party patches</heading>
+	<p>
+	  To be contributed.
+	</p>
       </sect>
     </chapt>
     <chapt id="initrd">