Migrating to the common kernel-image package
--------------------------------------------
Files for architecture <arch> should be placed into arch/<arch>.
Minimally, this directory should contain a control.in, config.default
and at least one flavour configuration file config.<flavour>. It can
optionally contain config.common, Makefile.inc and multiple flavour
configuration files. For arches with subarches the subdirectory
arch/<arch>/<subarch> with the same file structure must be created
for each subarch.

Support for arch/subarch-specific patches
-----------------------------------------
Patches specific to a particular architecture or subarchitecture and
not included into the debian patch set should be placed in the
'patches' subdirectory of arch/<arch> or arch/<arch>/<subarch>. This
directory is expected to contain the patch files and a file 'list'
with list of patches to apply.

Config files
------------
Configuration files are constructed dynamically by concatenating a number
of config files as described below. Any of the files, except the .default
and lowest-level .<flavour> files, may be missing.

For architecture without subarches:

  Configuration file for kernel-image:

  arch/config.common
  arch/<arch>/config.common 
  arch/<arch>/config.<flavour>
  
  Configuration file for kernel-headers:

  arch/<arch>/config.default

For architecture with subarches:

  arch/config.common
  arch/<arch>/config.common
  arch/<arch>/<subarch>/config.common
  arch/<arch>/<subarch>/config.<flavour>

  Configuration file for kernel-headers:

  arch/<arch>/<subarch>/config.default

It is possible to avoid the inclusion of the arch-independent
config file (handy for the transitional period) by setting the
include_common_config variable to 'no' in Makefile.inc.

Debian and arch/subarch specific patches
-----------------------------
This is not really settled yet. Ideally we would like to integrate all
this stuff into the kernel-source package. So for now it is probably
reasonable to assume that common-arch debian patches are going to be
in debian/patches directory. As I understand, we will not need the
kernel-tree stuff, as the source with patches is going to accompany each
upload. So we might just place them there along with the list, which will
determine the order of application. For unmerged arch/subarch specific
patches we can do the same in the arch/subarch directory: patches/
subdir will contain patches and a list. Currently the kernel is patched
using the kernel-source package only.

Control file
------------
The master control file debian/control must be generated before
the package is uploaded. debian/rules contains the debian/control 
target, which generates the control file by concatenating the 
common debian/control.in and all the control.in files found in
and in subdirectories of arch/<arch>, and performing the variable
substitution. Currently the following variables are going to be
substituted:

@karch@     Replaced by the architecture string, identical to
            DEB_HOST_ARCH, as returned by dpkg-architecture.
@version@   Upstream kernel version, for example 2.6.11.
@ktver@     Minor version of kernel-tree to build-depend on. 
@abiname@   Abiname value for this set of packages.
@kbpkg@     Current name and version of the kernel-build
            package to build-depend on. Typical value may 
            be 'kernel-build-2.6-3', for example.

After variable substitution the resulting file is formatted to
ensure that the only blank lines are the ones separating the
entries (i.e. before the next Package: line).

Makefile.inc
------------
Each architecture subdirectory in arch may contain a Makefile.inc
file, which is included by debian/rules after definining all the
variables. It may be used to override the standard variables on
per-architecture basis and other evil things. So far the valid uses of
this file include the setting of the following variables:

include_common_config	

  Setting it to 'no' (without quotes) will prevent the common kernel
  config from being included for this particular architecture.
  Typical usage:

  include_common_config := no

headers_dirs		

  This variable is substituted into the headers-install script,
  controlling which asm-* directories are included into the
  kernel-headers package. By default it is set to karch (see
  above). See header-install.in file for detail. Typical usage:
  
  headers_dirs := sparc | sparc64

headers_extra

  This variable is substituted into the headers-install script,'
  and may be used to specify extra files, which a particular
  architecture would like to include in the kernel-headers package.
  Files should be specified with a full path relative to the
  top-level kernel directory, unquoted and separated by spaces.
  Typical usage:

  headers_extra := arch/i386/kernel/asm-offsets.s

headers_subarch

  The subarch to pass to the --subarch option for the make-kpkg
  call to build the kernel-headers. Typical usage:

  headers_subarch := sparc64

added_patches

  Setting this variable to non-empty value will cause an option
  --added_patches to be added to the make-kpkg 'build' and
  'kernel-image' calls. The value of the variable will be
  given as an argument for the --added-patchs option. The value
  of this variable may contain a special string @uver@ which
  is going to be expanded into the upstream kernel's version
  with dots replaced by underscores (for example, 2_6_11 for the
  kernel version 2.6.11). Typical usage:

  added_patches := debian,hppa-@uver@

build_subarch

  Setting this variable to non-empty value will cause an option
  --subarch to be added to 'build' and 'kernel-image' make-kpkg
  calls, followed by the flavour for which the kernel is built.
  In general, if you wish to add subarch support for your 
  architecture, you should contact kernel-package maintainer
  to ensure that the flavour name correctly maps onto a kernel
  subarch name. Currently only mips and sparc are using this
  facility, and both of them should be fine. Typical usage:

  build_subarch := yes

  Note that the value of this variable is ignored.

build_makeflags

  This variable may contain the make flags settings for the
  make-kpkg invocation in the 'build' target. Currently it is
  only used by amd64, where it should be set to something like

  build_makeflags := 'CC=amd64-linux-gcc V=1'

  The value of the variable must be properly quoted. 
 
initrd_modules

  This variable may contain a space-separated list of modules
  which should be hard-linked into the /lib/modules/<version>/initrd
  directory, so that they will be included by mkinitrd. Full
  pathname relative to the /lib/modules/<version> directory should
  be give, no quoting is necessary. Typical usage:

  initrd_modules := kernel/drivers/video/vesafb.ko kernel/security/capability.ko

image_postproc [NOT IMPLEMENTED YET]

  A command to be run on the kernel image after it's built. Location of
  the image will be appended to this command as the last argument. One
  usage is stripping the image on sparc, otherwise it is too big to be
  booted:

  image_postproc := strip -R .comment -R .note -K sun4u_init -K _end -K _start
 
  Note that for cross-compiling a proper strip command should be used
  (such as sparc-linux-strip, or something like this).

image_prefix [NOT IMPLEMENTED YET]

  This variable may contain an expression, which will be used as a wrapper
  for the make-kpkg when its target is kernel_image. This option is a kludge,
  needed for sparc, which has to prepend this call with either 'sparc32' or
  'sparc64', depending on the flavour being built (otherwise depmod breaks
  when building sparc32 kernels on sparc64). For this obscure case it may
  be used like that (very evil):

  image_prefix := $${i%-smp}

  The shell variable ${i} will contain the current flavour in the rules file.