Working with the Ubuntu kernel config
=====================================

The Ubuntu kernel source tree produces several kernel binaries, one for each valid
combination of architecture (amd64, arm64, ppc64el, etc) and flavour (generic,
lowlatency, 64k-pages, etc), and each of this combination requires a
corresponding .config file.

Once a new patch is applied, or after a rebase on a new upstream release, all
.config files need to be refreshed (config options could have been added/removed
or renamed, their dependencies could have changed, etcetc) and we must assure
that some critical config options are always match a specific value in order to
have a sound kernel.

The Ubuntu approach is to store all config information (config name,
per-arch/per-flavour value and other useful metadata) into a single text file
(``debian.master/config/annotations``) and generate the required .config file at
build time.

To know more about annotations inner working, refer to this `document`_.

Annotations format is self-explanatory:


.. code-block:: shell

       # ARCH: amd64 arm64 armhf ppc64el riscv64 s390x
       # FLAVOUR: amd64-generic arm64-generic arm64-generic-64k armhf-generic armhf-generic-lpae ppc64el-generic riscv64-generic s390x-generic

       CONFIG_104_QUAD_8         policy<{'amd64': 'm'}>
       CONFIG_60XX_WDT           policy<{'amd64': 'm'}>
       CONFIG_64BIT              policy<{'amd64': 'y', 'arm64': 'y', 'ppc64el': 'y', 'riscv64': 'y', 's390x': 'y'}>
       CONFIG_6LOWPAN_DEBUGFS    policy<{'amd64': 'n', 'arm64': 'n', 'armhf': 'n', 'ppc64el': 'n', 'riscv64': 'n', 's390x': '-'}>
       ...

nonetheless, a helper script (``debian/scripts/misc/annotations``) is provided to ease querying and modifying the configutation.

For example, to find the value of a specific option:

.. code-block:: shell

       $ ./debian/scripts/misc/annotations --query --config CONFIG_DEBUG_FS
       {
               "CONFIG_DEBUG_FS": {
               "policy": {
                     "amd64": "y",
                     "arm64": "y",
                     "armhf": "y",
                     "ppc64el": "y",
                     "riscv64": "y",
                     "s390x": "y"
               },
               "note": "'required debug option'"
               }
       }

Or to change the its value:

.. code-block:: shell

       $ ./debian/scripts/misc/annotations --config CONFIG_DEBUG_FS --arch arm64 --flavour generic --write n
       {
               "CONFIG_DEBUG_FS": {
               "policy": {
                     "amd64": "y",
                     "arm64": "y",
                     "arm64-generic": "n",
                     "armhf": "y",
                     "ppc64el": "y",
                     "riscv64": "y",
                     "s390x": "y"
               },
               "note": "'required debug option'"
               }
       }  

And once you are done with your changes, commit them:

.. code-block:: shell

       $ git add debian.master/config/annotations
       $ git commit -s -m "UBUNTU: [Config] arm64/generic: disable DEBUG_FS"

pay particular attention to:
 - always add a ``Signed-off-by`` line (``git commit -s`` switch)
 - config changes should always use a ``UBUNTU: [Config] $arch/$flavour: …`` subject format (if arch or flavour is omitted, it means all architectures/flavours are affected).


.. _document: https://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/unstable/tree/debian.master/config/README.rst