--- /dev/null
+
+ Theory of operation for Kconfig
+=================================
+
+This document explains briefly how how the Kconfig system works in the
+backported code. It's obviously based on the original drivers' Kconfig
+but is "hacked up" by the backporting process.
+
+
+ Operation in the backport output tree
+---------------------------------------
+
+Let's start with the output, i.e. with the build-time Kconfig operation.
+At build time, it is necessary to know what symbols are available in the
+backported code, and in many cases also which are available in the kernel
+it's being compiled against, e.g. to only allow selecting any PCI drivers
+if PCI is enabled in the kernel.
+
+As usual, the Kconfig tree starts with the file "Kconfig" at the root of
+the output directory. This file ships in this repository in the backport
+directory (but as all other Kconfig files will have been modified at the
+backport output generation time.)
+
+This "root" Kconfig file includes all the other Kconfig files that are
+used to configure everything. This includes the compat/Kconfig file that
+also ships in this repository and contains the backport symbols as well
+as the generated ones -- Kconfig.kernel and Kconfig.versions.
+
+These files (Kconfig.kernel and Kconfig.versions) are generated at build
+time and depend on the kernel that they the backport is compiled against.
+The former (Kconfig.kernel) is generated from the kernel's .config file
+and contains all the Kconfig symbols (options) as hidden and unchangeable
+options that the kernel has enabled. This addresses the dependency issue,
+it will for example contain
+
+config PCI
+ bool
+ default y
+
+if the kernel has PCI enabled. For a modular option, here's an example:
+
+config CORDIC
+ tristate
+ default m
+
+(though if CORDIC was built into the kernel, it'd be "bool", but that's
+immaterial for the usage here since it can't be changed anyway)
+
+If the kernel doesn't have it then this will be missing, and any driver
+that "depends on PCI" will not be selectable in the configuration.
+
+The second file (Kconfig.versions) is generated from just the version of
+the kernel and also contains invisible and unselectable boolean options
+like
+
+config BACKPORT_KERNEL_X
+ def_bool y
+
+to indicate that APIs introduced in kernel version X (e.g. 3_3 for 3.3
+or 2_6_24 for 2.6.24) must be backported. Essentially, the presence of
+a symbol BACKPORT_KERNEL_X indicates that the kernel that the code is
+being compiled against is older than X.
+
+All together, this allows the correct options to be selected by the user.
+
+There's one more caveat: At backport configuration time, the CONFIG_
+environment variable is set to CPTCFG_ ("compat config", but also chosen
+because it has the same length as CONFIG_). This shows up in the .config
+file and other places, and in fact in all makefiles and in the code. The
+reason for this is that it must be possible to distinguish between kernel
+and backport options (even though we sort of port over kernel options).
+This allows code to, for example, have "#ifdef CONFIG_PM" which can only
+be set or cleared in the kernel, not in the backport configuration. Since
+this is needed, a transformation step is done at backport creation time.
+
+
+
+ Backport creation for Kconfig
+-------------------------------
+
+In order to achieve correct operation with all the above, multiple steps
+are necessary during the backport creation process.
+
+These are the problems and their solutions:
+ 1) As just mentioned, all symbols are now named CPTCFG_* instead of the
+ original CONFIG_*. This requires that all code files (and makefiles)
+ are updated to use CPTCFG_* and CPTCFG_*_MODULE instead of the CONFIG_
+ versions of the same. However, not *all* CONFIG_* usage may be changed
+ since some options must come from the kernel still.
+ To achieve this, all Kconfig files are walked during the backporting
+ process, starting at the root "Kconfig", and any symbols defined in
+ them collected. Later then, only those options are renamed. They are
+ also recorded for the build process in the output file .local-symbols.
+
+ 2) Kconfig files may reference files that don't exist when they're copied
+ but not all the drivers, e.g. drivers/net/wireless/Kconfig is copied
+ but only a single driver, e.g. iwlwifi, so references to other drivers
+ will not exist.
+ To address this, the backport process records which files it can find
+ while walking the Kconfig tree. Later, any reference to files that
+ don't exist in the backport output is commented out. Note that in this
+ process, the files 'Kconfig.kernel' and 'Kconfig.versions' need to be
+ ignored since they will be generated at build time.
+
+ 3) Kconfig files may include configuration options that cannot be built,
+ for example when the drivers/net/wireless/Makefile is copied it will
+ have options for old drivers like AIRO etc. which aren't copied into
+ the output.
+ To address this, the generation process also walks the Makefile tree
+ (see also the 'makefile-operation' file) and collects all options
+ referencing files or directories that don't exist. These options are
+ then modified in the Kconfig file to "depend on n", making them not
+ selectable (I considered removing them entirely but that seemed too
+ brittle.)
+
+ 4) Some code simply cannot be built on very old kernels, e.g. Bluetooth
+ requires at least 2.6.29 due to the shash crypto code. This cannot be
+ determined easily automatically, so the 'dependencies' file is read
+ and options that are listed there are rewritten to include
+ depends on !BACKPORT_KERNEL_X_Y
+ (where X_Y is the listed kernel version), which makes them available
+ only on kernels >= X.Y.
+
+ 5) It's impossible to select options to be built-in, so all tristate
+ config options are changed to "depends on m" to force them modular.
--- /dev/null
+
+ Theory of operation for output Makefiles
+==========================================
+
+This document explains briefly how how the Makefile system works in the
+backported code. It's obviously based on the kernel's Makefile system
+but must be modified by the backporting process to work.
+
+
+ Operation in the backport output tree
+---------------------------------------
+
+Again, let's start with how it works in the result and not with how the
+modifications are made. There are a few different Makefiles that are used
+to achieve this result -- you can look into the details there.
+
+At build time, the very first thing the make system has to do is ensure
+the Kconfig.kernel and Kconfig.versions files exist and are up-to-date,
+this is done by reading the kernel's .config file and storing its md5sum
+to make sure it can react to changes.
+
+Once these are in place, the configuration process can start with any of
+the tools -- menuconfig, defconfig-*, ...
+
+When the configuration is complete and exists in .config, the autoconf
+header (include/linux/compat_autoconf.h) must be generated. This step is
+also done in the make system (by a small embedded shell script) and needs
+the .local-symbols so it only includes the symbols from the backport.
+
+After this exists, all that's left to do is source the .config file and
+export everything in there into the environment for calling the kernel's
+build system.
+
+
+ Backport creation for Makefiles
+---------------------------------
+
+Similar to Kconfig (see the "kconfig-operation" file) there are issues
+with just taking the kernel's makefiles and attempting to use them out
+of tree. The "wrapper" make system is described above, but some other
+transformations are needed.
+
+First though, one "root" Makefile is shipped with the backport tree, the
+file Makefile.kernel. This is the file that the kernel sees and it has
+references to all the makefiles that the backport is supposed to include.
+Some of these may also be invalid/stale, like in any Makefile copied from
+the kernel.
+
+The main thing here is that some symbols may refer to another directory
+or C file that doesn't exist. For example, this:
+
+obj-$(CONFIG_FOO) += foo/
+
+If the foo/ directory wasn't copied into the backport, then the symbol
+FOO will be disabled in the Kconfig, and not treated as a local one.
+Therefore, if CONFIG_FOO is set in the base kernel, the make system may
+attempt to recurse into the foo/ directory and fail the build. Thus, any
+such references that cannot be satisfied due to missing code are changed
+to
+obj-$(IMPOSSIBLE_FOO) += foo/
+
+This preserves the original intent and makefile syntax while disabling
+the recursion that would fail.
+
+NOTE: The makefile parser in the generation script is very very basic and
+ really only works for this particular syntax that the kernel uses.
+
+ Right now, the parser doesn't even understand line continuations,
+ though this would be fairly to fix.
+
+ Also, the parser doesn't understand temporary variables and then
+ sometimes disables things it shouldn't, this is the reason for the
+ brcm80211 patches (at the time of writing -- those patches might be
+ acceptable upstream.)
+
+ Finally, the parser thinks that .o files can only be built from .c
+ files, so any other files won't be handled correctly.
projects / openwrt / staging / blogic.git / commitdiff