Signed-off-by: Roland Hieber <r...@pengutronix.de>
---
doc/dev_kconfig_diffs.rst | 79 +++++++++++++++++++++++++++++++++++
doc/dev_layers_in_ptxdist.rst | 3 +-
doc/dev_manual.rst | 1 +
3 files changed, 82 insertions(+), 1 deletion(-)
create mode 100644 doc/dev_kconfig_diffs.rst
diff --git a/doc/dev_kconfig_diffs.rst b/doc/dev_kconfig_diffs.rst
new file mode 100644
index 000000000000..5673bd2d2dd6
--- /dev/null
+++ b/doc/dev_kconfig_diffs.rst
@@ -0,0 +1,79 @@
+.. _kconfig-diffs:
+
+Kconfig Diffs
+-------------
+
+For packages using Kconfig as their configuration system, PTXdist can generate
+their config file from another *reference config file* and a *Kconfig diff* on
+the fly.
+This mechanism can be used to build configuration variants of a kernel or
+barebox package.
+For example, a "debug" kernel package can refer to the config file of the
+"production" kernel as its reference config file, and its Kconfig diff then
+only contains the Kconfig symbols that were changed in the "debug" variant:
+
++-----------------------------------+-------------------------------------+-----------------------------------+
+| release config symbol | debug kconfig diff |
resulting debug config symbol |
++===================================+=====================================+===================================+
+| CONFIG_LOCALVERSION="release" | CONFIG_LOCALVERSION="debug" |
CONFIG_LOCALVERSION="debug" |
++-----------------------------------+-------------------------------------+-----------------------------------+
+| # CONFIG_ARCH_MULTI_V6 is not set | | #
CONFIG_ARCH_MULTI_V6 is not set |
++-----------------------------------+-------------------------------------+-----------------------------------+
+| CONFIG_ARCH_MULTI_V7=y | |
CONFIG_ARCH_MULTI_V7=y |
++-----------------------------------+-------------------------------------+-----------------------------------+
+| # CONFIG_CGROUP_DEBUG is not set | CONFIG_CGROUP_DEBUG=y |
CONFIG_CGROUP_DEBUG=y |
++-----------------------------------+-------------------------------------+-----------------------------------+
+| # CONFIG_DEBUG_PREEMPT is not set | CONFIG_DEBUG_PREEMPT=y |
CONFIG_DEBUG_PREEMPT=y |
++-----------------------------------+-------------------------------------+-----------------------------------+
+| CONFIG_WATCHDOG=y | # CONFIG_WATCHDOG is not set | #
CONFIG_WATCHDOG is not set |
++-----------------------------------+-------------------------------------+-----------------------------------+
+| CONFIG_WATCHDOG_CORE=y | # CONFIG_WATCHDOG_CORE is undefined |
|
++-----------------------------------+-------------------------------------+-----------------------------------+
+| CONFIG_BCM2835_WDT=y | # CONFIG_BCM2835_WDT is undefined |
|
++-----------------------------------+-------------------------------------+-----------------------------------+
+
+Kconfig does not write symbols to the config file that have unfulfilled
dependencies (e.g., in the
+above example ``CONFIG_WATCHDOG_CORE`` and ``CONFIG_BCM2835_WDT`` depend on
``CONFIG_WATCHDOG``).
+Those symbols that are not present in the resulting debug config file are
represented as ``… is
+undefined`` in the diff.
+
+The first line of the Kconfig diff file contains the MD5 sum of the reference
config file.
+PTXdist uses this checksum to detect when the reference config has changed,
+in which case the diff needs to be regenerated from the package's config file,
+and to make sure that the diff is applicable to the reference config.
+
+Using Kconfig diffs
+~~~~~~~~~~~~~~~~~~~
+
+The main part is setting the ``<PKG>_REF_CONFIG`` variable of a package to the
reference config
+file, for example::
+
+ # rules/kernel.make:
+ KERNEL_CONFIG := $(call ptx/in-platformconfigdir,
kernelconfig-release)
+
+::
+
+ # rules/kernel-debug.make:
+ KERNEL_DEBUG_CONFIG := $(call ptx/in-platformconfigdir,
kernelconfig-debug)
+ KERNEL_DEBUG_REF_CONFIG := $(call ptx/in-platformconfigdir,
kernelconfig-release)
+
+PTXdist will now automatically generate ``kernelconfig-debug`` from
``kernelconfig-release`` and
+``kernelconfig-debug.diff`` whenever doing and *oldconfig* or *menuconfig* on
the *kernel-debug*
+package.
+If any symbols were changed by that operation, both the
``kernelconfig-debug.diff`` and the
+``kernelconfig-debug`` are updated afterwards.
+
+Kconfig diffs and layers
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+PTXdist uses the same diff mechanism whenever the config file of a
Kconfig-style package is changed
+in an inherited layer (see :ref:`layers-in-ptxdist`).
+In that case, the diff is calculated between the package's config file in the
base layer and the
+package's (adapted) config file in the current layer.
+
+.. note::
+ When using both ``<PKG>_REF_CONFIG`` and inter-layer Kconfig diffs, the
inter-layer diff takes
+ precedence, and the reference config file in the inherited layer is ignored.
+ In the following example, arrows represent the config diff relation:
+
+ .. image:: dev_kconfig_diffs_layer_precedence.svg
diff --git a/doc/dev_layers_in_ptxdist.rst b/doc/dev_layers_in_ptxdist.rst
index ec92c8c8a86c..a1066396ca28 100644
--- a/doc/dev_layers_in_ptxdist.rst
+++ b/doc/dev_layers_in_ptxdist.rst
@@ -98,7 +98,8 @@ Packages with kconfig Based Config Files
For packages such as the Linux kernel that have kconfig based config files,
a lot of the infrastructure to handle config files and deltas across
-multiple layers can be reused. Consistency validation is done implicitly
+multiple layers can be reused (see :ref:`kconfig-diffs`).
+Consistency validation is done implicitly
and ``menuconfig`` and other kconfig commands will use config files and
deltas as expected.
diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index 03a05a661a97..c232cc91428a 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -14,4 +14,5 @@ This chapter shows all (or most) of the details of how
PTXdist works.
dev_add_bin_only_files
dev_create_new_pkg_templates
dev_layers_in_ptxdist
+ dev_kconfig_diffs
dev_code_signing
--
2.29.2
_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de
To unsubscribe, send a mail with subject "unsubscribe" to
ptxdist-requ...@pengutronix.de
