debian: add extra package build routines

.gitignore

@@ -77,11 +77,6 @@ modules.order
 /kernel.spec
 /rpmbuild/
 
-#
-# Debian directory (make deb-pkg)
-#
-/debian/
-
 #
 # Snap directory (make snap-pkg)
 #

debian/README.Debian

@@ -0,0 +1,65 @@
+Linux kernel for Debian
+-----------------------
+
+Patches
+-------
+Debian applies small changes to the kernel source. These are split up into
+separated patches addressing individual problems. Each of the patch files
+contains a description and mentions the author. The patches can be found
+in the source package or at
+https://sources.debian.org/src/linux/<version>/debian/patches/
+(with the package version substituted).
+
+Config Files
+------------
+The .config files used to build the various linux-image files are dynamically
+generated during the linux package build.  See the source package for
+details.  Each linux-image-* package provides the complete .config file that
+was used to generate it.  This file is installed in /boot.
+
+Scope of security support
+-------------------------
+Security support is provided not only for the binary builds, but also
+for the full source package, allowing for locally customized kernels.
+However, kernel options that are not enabled in official Debian builds are
+given a lower priority for security support. Options marked as BROKEN
+or EXPERIMENTAL are of very low priority, and should not be enabled in
+customized builds for a security-sensitive environment.
+
+Building custom kernel binary packages
+--------------------------------------
+We recommend using the 'make deb-pkg' target provided by the upstream
+kernel source.
+
+Rebuilding official binary packages
+-----------------------------------
+You can build specific kernel binary packages using the targets in
+debian/rules.gen, which have names of the form:
+    binary-arch_<architecture>_<featureset>_<flavour>
+
+Example:
+    make -f debian/rules.gen binary-arch_i386_none_686
+
+Rebuilding Adaptec AIC7xxx/79xx firmware
+----------------------------------------
+You can rebuild the firmware for the Adaptec AIC7xxx/79xx SCSI Adapters. To
+do so you need to set AIC7XXX_BUILD_FIRMWARE/AIC79XX_BUILD_FIRMWARE config
+options.  Note that this requires to have the development packages for
+Berkeley Database (libdb-dev) installed.
+
+Non-free bits removed
+---------------------
+See the Files-Excluded field in debian/copyright.
+
+Changelog
+---------
+Older Debian changelog entries are no longer included in binary
+packages, but can be found in debian/changelog.old in the source
+package.
+
+Further information
+-------------------
+Debian Linux Kernel Handbook:
+             https://kernel-team.pages.debian.net/kernel-handbook/
+             or debian-kernel-handbook package
+Debian Wiki: https://wiki.debian.org/DebianKernel

debian/README.source

@@ -0,0 +1,305 @@
+Checklist for uploaders
+=======================
+
+There is a checklist in the kernel-team.git repository; see
+<https://salsa.debian.org/kernel-team/kernel-team/-/blob/master/docs/kernel-upload-checklist.md>.
+
+Updating the upstream source
+============================
+
+In addition to the build-dependencies, you will need the rsync package
+installed.
+
+1) Run: ./debian/bin/genorig.py <repository>
+
+   where <repository> is a local or remote git repository with the
+   upstream release tag in it.
+
+   If you do not have a local repository, use the appropriate one of:
+
+   * https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+   * https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
+   * git://kernel.ubuntu.com/ubuntu/linux.git
+
+   This will produce ../orig/linux_<version>.orig.tar.xz
+   (e.g. linux_3.5~rc1.orig.tar.xz).
+
+   It involves deleting files for DFSG compliance, as listed in the
+   Files-Excluded field in debian/copyright.
+
+2) Run: make -f debian/rules orig
+
+   This will apply the main quilt series to the upstream source, which
+   will usually fail due to conflicts with upstream changes.  You need
+   to resolve those by dropping or refreshing patches.
+
+Recording updates in the changelog
+----------------------------------
+
+Upstream commits that we already cherry-picked and included in a
+previous package upload should not be mentioned, since they don't make
+any difference to the package.  Any other commits that fix a Debian
+bug report and/or a security issue with a CVE ID should always be
+listed, along with the (Closes: #nnnnnn) and/or (CVE-yyyy-nnnn)
+reference.
+
+Aside from those general rules:
+
+* For an upstream release candidate, don't attempt to list the changes
+
+* For a stable release by Linus, refer to the summary at
+  kernelnewbies.org, e.g. https://kernelnewbies.org/Linux_4.5
+
+* For a stable update, refer to the changelog on kernel.org, e.g.
+  https://www.kernel.org/pub/linux/kernel/v4.x/ChangeLog-4.5.1, and
+  list all changes that are relevant to our package and that fix bugs
+  that we would consider 'important' or higher severity
+
+  - The script debian/bin/stable-update updates the changelog
+    version and inserts the list of changes.  It doesn't attempt to
+    filter out irrelevant or unimportant changes.
+
+  - If you have time, please delete irrelevant changes such as:
+    + Fixes for architectures not supported by the package
+    + Fixes for drivers that aren't enabled in any of our configurations
+    + Build fixes for configurations that we don't use
+    + Fixes for lockdep false positives
+
+If you have time, please add bracketted prefixes to the upstream
+change list as described below under "Changelog conventions".
+
+Applying patches to the Debian kernel tree
+==========================================
+
+The Debian kernel packaging uses the quilt patch system, but with
+multiple series to allow for featuresets.
+
+Patches are stored below debian/patches, loosely sorted in bugfix/,
+features/ and debian/. Patches are in the standard kernel patch
+format (unified diff to be applied with patch -p1) and generally have
+DEP-3 headers.
+
+For each optional featureset there is an additional patch directory
+debian/patches-<featureset>.
+
+If you want to generate a source tree with all patches applied, run
+make -f debian/rules source
+
+The resulting source can be found below debian/build.
+
+Changelog conventions
+=====================
+
+If a change only affects some architectures, flavours or featuresets,
+this should be noted with a bracketted prefix on the changelog line:
+
+* [<fset>] Change to featureset <fset>
+* [<arch>] Change that affects Debian architecture <arch>
+* [<arch1>,<arch2>...] Change that affects Debian architectures
+  <arch1>, <arch2>, ...
+* [<arch>/<flavour>] Change that affects kernel flavour <flavour>
+  on Debian architecture <arch>
+* [<arch>/{<flavour1>,<flavour2>...}] Change that affects kernel
+  flavours <flavour1>, <flavour2>, ... on Debian architecture <arch>
+
+You can use wildcards to cover multiple values, e.g. 'arm*' for armel,
+armhf and arm64 architectures.  Also 'x86' is used to cover the Debian
+architectures amd64, i386 and x32.
+
+Kernel config files
+===================
+
+Each kernel configuration file is constructed dynamically from a
+number of files under debian/config and (if it exists)
+debian/config.local.  They are read in the following order, such that
+files later on the list can override settings from earlier files.
+Files in debian/config.local can also override settings from the
+corresponding file in debian/config.
+
+1. Common:
+   - Default filename: config
+   - Filename list: [build.config]
+2. Per kernel architecture:
+   - Default filename: kernelarch-<karch>/config
+   - Filename list: [kernelarch.build.config]
+3. Per Debian architecture:
+   - Default filename: <arch>/config
+   - Filename list: [kernelarch.debianarch.build.config]
+4. Per Debian architecture and flavour:
+   - Default filename: <arch>/config.<flavour>
+   - Filename list: [kernelarch.debianarch.flavour.build.config]
+5. Per featureset:
+   - Default filename: featureset-<fset>/config
+   - Filename list: [featureset.build.config]
+6. Per Debian architecture and featureset:
+   - Default filename: <arch>/<fset>/config
+   - Filename list: [kernelarch.debianarch.featureset.build.config]
+7. Per Debian architecture, featureset, and flavour:
+   - Default filename: <arch>/<fset>/config.<flavour>
+   - Filename list:
+     [kernelarch.debianarch.featureset.flavour.build.config]
+
+You can check the final list of configuration files by reading
+debian/rules.gen.  Each binary-arch_<arch>_<fset>_<flavour>_image
+rule passes the list to debian/rules.real as the KCONFIG variable.
+
+These files should be kept in order using the kconfigeditor2
+utility from <https://salsa.debian.org/kernel-team/kernel-team>.
+With this source package as your working directory, run:
+
+    debian/rules source
+    .../kernel-team/utils/kconfigeditor2/process.py .
+
+This will also warn about any symbols that no longer exist, or
+cannot be explicitly configured.
+
+Control file
+============
+The master control file debian/control must be generated before the package is
+uploaded. debian/rules contains various targets to facilitate this task:
+
+debian/control  Generates the control file by invoking the
+                debian/bin/gencontrol.py script, which combines the templates
+                from the templates directory and architecture-specific
+                defines.toml file to produce the debian/control file. Note that
+                this target is intentionally made to fail with a non-zero exit
+                code to make sure that it is never run during an automatic
+                build.
+
+orig            Populate the current directory with all files from the unpacked
+                upstream tarball in ../orig/linux_${ver} and apply the Debian
+                quilt patch stack.
+
+clean-generated Clean up all auto-generated files inside the ./debian directory
+
+maintainerclean What clean-generated does and additionally also cleans up all
+                files other than the ./debian and ./.git directories.
+
+The following variables are substituted into the templates:
+
+@version@      Upstream kernel version, for example 2.6.11.
+@arch@         The Debian arch name, such as powerpc or i386.
+@flavour@      The build flavour, such as 686 or k7-smp.
+@class@        The CPU/architecture class; displayed in synopsis.  It should
+               be fairly short, as the synopsis is supposed to be <80 chars.
+               It should be in the form "foo class", and will show up in the
+	       description as "foo class machines".
+@longclass@    The CPU/architecture class; displayed in the extended
+               description.  The same rules apply as in @class@.  If
+	       this is unset, it will default to @class@.
+@desc@         (Potentially) multi-line verbiage that's appended to
+               -image descriptions.
+
+Normally, the arch-specific contents should be controlled by
+adjusting the corresponding defines.toml file.
+
+Build-dependencies that relate to specific binary packages can be
+specified in a Build-Depends field in the template for that binary
+package.  gencontrol.py will append the value to the source package's
+Build-Depends-Arch or Build-Depends-Indep field, as appropriate.  It
+will also use the binary package's Architecture and Build-Profile as
+the architecture-qualification and/or restriction for each build-
+dependency that doesn't already have them.
+
+TODO:
+- Patches applied to the upstream source
+- How to define a flavour
+- More detail on generation of debian/control and configs
+
+Running tests
+=============
+
+linux supports autopkgtest and should be able to run most of the
+kernel's self-tests on any architecture where kexec is supported,
+but it has higher resource requirements than most packages:
+
+- A VM with plenty of disk space (10GB is enough), RAM (1GB is
+  probably enough) and at least 2 CPUs
+- The temporary directory for adt-virt-qemu (-o option) will need
+  several GB of space, so a tmpfs may not be suitable
+
+Note that if you tell adt-run to use an 'unbuilt tree' (i.e. an
+unpacked source package) it does not exclude VCS directories such as
+.git.  Either use a packed source package or copy the working tree
+elsewhere excluding .git.
+
+Example invocation:
+
+    adt-run -B ../linux-image-4.2.0-rc6-amd64_4.2~rc6-1~exp2_amd64.deb \
+        ../linux_4.2~rc6-1~exp2.dsc \
+	--timeout-test=1200 \
+        --- adt-virt-qemu /var/cache/autopkgtest/adt-sid.img -o /var/tmp -c 2
+
+Build profiles
+==============
+
+Several build profiles are understood and supported:
+
+- nodoc: Exclude most documentation
+- noudeb: Exclude installer udeb packages
+- pkg.linux.notools: Exclude userland tool packages (linux-kbuild-<version>,
+  linux-perf, etc.)
+- pkg.linux.mintools: Build minimal set of userland tool packages
+  (linux-kbuild-<version>)
+- pkg.linux.nokernel: Exclude kernel image and header packages
+- pkg.linux.nokerneldbg: Exclude kernel debug packages
+- pkg.linux.nokerneldbginfo: Build kernel without debug symbols (also disables
+  BTF)
+- pkg.linux.nosource: Exclude source binary package (linux-source-<version>)
+- cross: Needed when cross-building.
+- nopython: Disable Python bindings.  This currently disables building the
+  linux-perf-<version> package, as the perf program embeds Python.
+- pkg.linux.nometa: Exclude most meta-packages.  The linux-headers-*-all*
+  packages can still be built.
+- pkg.linux.quick: Perform a limited build that should provide good
+  coverage yet be quick enough for use in CI.
+
+Build rules
+===========
+
+The Debian build rules are split across multiple makefiles:
+
+- debian/rules: Standard top-level makefile for Debian package build.
+- debian/rules.gen: Intermediate makefile between debian/rules and
+  debian/rules.real.  This is generated by gencontrol.py based on
+  the configuration under debian/config.
+- debian/rules.real: Makefile for building a single kernel flavour
+  or other group of binary packages.
+- debian/rules.d: Makefiles for building userland code from specific
+  source directories.  The directory structure mirrors the kernel
+  source directories.  debian/rules.real uses the "make-tools" to
+  invoke these makefiles.
+
+All builds *must* be done out-of-tree in a subdirectory of
+debian/build, so that the output files do not end up in the
+linux-source-<version> binary package.  Currently kernel builds use
+debian/build/build_<arch>_<featureset>_<flavour>, userland code uses
+debian/build/build-tools/<source-dir> and documentation uses
+debian/build/build-doc.
+
+Code signing
+============
+
+The kernel image and modules may be signed after building, to support
+a Secure Boot or Trusted Boot policy.  In Debian, this is performed by
+a "code signing service" that is separate from the normal package
+build process.
+
+The initial package build generates binary packages named
+linux-image-<arch>-signed-template, that contain a source package
+template and metadata about the files to be signed.  The code signing
+service will download this and the linux-image packages to be signed.
+It will add detached signatures to the source package, then upload it
+(without ever running debian/rules).
+
+The source package template is generated by
+debian/bin/gencontrol_signed.py and debian/rules.real with files from
+debian/signing_templates and debian/templates.  To test changes to
+these:
+
+1. Build the linux source package.
+2. Generate the signed source package by running the script
+   "debian-test-sign" from the kernel-team.git repository.  It is
+   also possible to set up a development configuration of the
+   official code signing service, but this is more complicated.
+3. Build the signed source package.