1# Android Kernel Configs
3## How are kernel config settings typically stored?
5When building the Linux kernel for a particular platform one usually begins by
6basing the kernel configuration off of a particular defconfig. The platform’s
7defconfig contains all of the Linux kconfig settings required to properly
8configure the kernel build (features, default system parameters, etc) for that
9platform. Defconfig files are typically stored in the kernel tree at
12It may be desirable to modify the kernel configuration beyond what the hardware
13platform requires in order to support a particular hardware or software
14feature. Storing these kernel configuration changes is often done using
15fragments. These are files which have the same format as a defconfig but are
16typically much smaller, as they only contain the kernel configuration settings
17needed to support the hardware or software feature/behavior in question.
18Maintainers of hardware extensions or software features can use fragments to
19compactly express their kernel requirements. The fragments can be combined
20with a platform defconfig using the kernel's make rules or using the
21`scripts/kconfig/merge_config.sh` script in the kernel tree.
23## How are Android's kernel configs stored?
25The kernel configs are stored in the [kernel/configs repo](https://android.googlesource.com/kernel/configs/).
27Kernel configuration settings that must be present for Android to function are
28located in the base config fragment, `android-base.config`. Configuration settings
29that enhance Android’s functionality in some way but are not required for it to
30run are located in the recommended config fragment, `android-recommended.config`.
32Some kernel config requirements only apply on certain architectures. Other
33requirements only apply if some other kernel config option has a particular
34value. The platform owner may also have a choice between several config
35options. These types of constraints cannot be expressed with a simple kernel
36config fragment. In releases up to and including Android P, kernel config
37requirements that are specific to a particular architecture are contained in
38architecture-specific base config fragments, such as
39`android-base-arm64.config`. If an architecture-specific base config fragment
40does not exist for a particular architecture in Android P or an earlier
41release, it means there are no required kernel config options for Android
42specific to that architecture. Note that the architecture-agnostic kernel
43config requirements from `android-base.config` still apply in that case.
45In releases after Android P the architecture-specific base config fragments are
46removed, and conditional kernel config requirements are stored in
49In Android R or above, additional config fragments are added conditionally
50on build variants. In particular, `non_debuggable.config` contains additional
51requirements for user builds.
53Kernel configs vary by kernel version, so there are sets of kernel configs for
54each version of the kernel that Android supports.
56## How can I easily combine platform and required Android configs?
58Assuming you already have a minimalist defconfig for your platform, a possible
59way to enable these options would be to use the aforementioned
60`merge_config.sh` script in the kernel tree. From the root of the kernel tree:
63ARCH=<arch> scripts/kconfig/merge_config.sh <...>/<platform>_defconfig <...>/android-base.config <...>/android-base-<arch>.config <...>/android-recommended.config
66This will generate a `.config` that can then be used to save a new defconfig or
67compile a new kernel with Android features enabled.
69The kernel build system also supports merging in config fragments directly. The
70fragments must be located in the `kernel/configs` directory of the kernel tree
71and they must have filenames that end with the extension ".config". The
72platform defconfig must also be located in `arch/<arch>/configs/`. Once these
73requirements are satisfied, the full defconfig can be prepared with:
76make ARCH=<arch> <platform>_defconfig android-base.config android-base-<arch>.config android-recommended.config
79If there is an `android-base-conditional.xml` file for your release/kernel
80version combination, it is necessary to review it and manually edit your
81defconfig to satisfy any applicable requirements.
83## Are the config requirements tested?
85Starting with Android O the base kernel configs are not just advisory. They are
86tested as part of
88(specifically the SystemVendorTest.KernelCompatibility subtest of
89CtsOnGsiTrebleFrameworkVintfTest), and also during device boot when the vendor
90interface (which includes the kernel configuration) and framework compatibility
91matrix are compared.
93## Ensuring Device Upgradability
95Devices launched with prior releases of Android must be able to upgrade to
96later releases of Android. This means that AOSP must function not only with
97device kernels that adhere to the Android kernel configs of the current
98release, but also with those device kernels that adhere to the configs of past
99releases. To facilitate that in the VtsKernelConfig test and in the framework
100compatibility matrix, past versions of the Android kernel config requirements
101are stored in the kernel/configs repo. During tests the appropriate versions
102of the configs are accessed depending on the launch level of the device.
104If you are adding a new feature to AOSP which depends on a particular kernel
105configuration value, either that kernel configuration value must already be
106present in the base android config fragments of past releases still on the
107supported upgrade path, or the feature must be designed in a way to degrade
108gracefully when the required kernel configuration is not present (and not be
109essential to AOSP’s overall functionality). All configs on the supported
110upgrade path are in the kernel/configs repo.
112Support for kernel configs from previous dessert releases is dropped from AOSP
113when the upgrade path from that dessert release is no longer supported.
115# Organization and Maintenance of the Kernel Config Repo
117The top level of the kernel configs repo contains directories for each
118supported kernel version. These contain the kernel config requirements (and
119recommendations) for the next release. There are also directories at
120the top level for previous releases. These directories contain the
121final kernel config requirements (for all supported kernel versions) for those
122releases and must not be changed once those releases have been
123published. AOSP must support all kernel configurations in this repo.
125For release branches the structure is similar, except there are no configs at
126the top level. When a release is branched from master the top-level configs are
127copied into a new directory for the release (this change is propagated to
128master) and the top-level configs are removed (this change is not propagated to
129master) since no development beyond that release is done in that branch.
131## I want to add/modify/remove a kernel config requirement. What do I do?
133Modify the top level kernel configs in AOSP. Make sure to modify the configs
134for all applicable kernel versions. Do not modify the config fragments in
137Because there is no tool to consistently generate these config fragments,
138please keep them alphabetically (not randomly) sorted.
142This file lists all common kernel configuration requirements on kernel version
147Contains the following:
149* Minimum LTS required
150* Conditional requirements.
154Build rules from the aforementioned files to a
155[framework compatibility matrix](https://source.android.com/devices/architecture/vintf/comp-matrices)
158for details of the output format.
160## I want to freeze/release the current kernel requirements. What do I do?
162Prior to a [FCM Version release](https://source.android.com/devices/architecture/vintf/fcm#new-fcm-versions)
163(often accompanied with a dessert release as well), the kernel requirements must
164be frozen. Follow the following steps
166* Copy the top-level `android-*` directories to a release directory, preferably
167 with the dessert name (for example, `q`).
168 * Remove top-level `android-*` directories. This change is not propagated to
170* Edit the new `<dessert>/android-*/Android.bp` files and rename the modules.
171 For example, change `kernel_config_current_4.9` in `q/android-4.9/Android.bp`
172 to `kernel_config_q_4.9`
173* Under `hardware/interfaces/compatibility_matrices/Android.bp`, edit
174 `kernel_config` field for the `framework_compatibility_matrix.current.xml`
175 to use the new modules.
176 * `framework_compatibility_matrix.current.xml` will be renamed to
177 `framework_compatibility_matrix.<level>.xml` as part of the FCM Version
178 release, which is a separate process.
180## I want to edit a released kernel requirement. What do I do?
182Don't edit a released kernel requirement unless necessary. If you have to make
183such a change, after discussing the change with maintainers, keep in mind that
184you **CANNOT** make a requirement more restrictive. Specifically,
187* Support a new kernel version by creating a new `<dessert>/android-x.y`
189* Remove a line from `<dessert>/android-*/android-base.config`
190* Remove a line from `<dessert>/android-*/android-base-*.config`
191* In `<dessert>/android-*/android-base-conditional.xml`
192 * Lower minimum LTS requirement from `x.y.u` to `x.y.v` (where `v < u`)
193 * Remove a `<group>`
194 * Add a condition `<group><conditions><config>`
195 * Remove a conditional requirement `<group><config>`
197### Not allowed
198* Add or change a line from `<dessert>/android-*/android-base.config`
199* Add or change a line from `<dessert>/android-*/android-base-*.config`
200* Add new conditional requirements `<dessert>/android-*/android-base-*.config`
201* Rename existing conditional requirements `<dessert>/android-*/android-base-*.config`
202* In `<dessert>/android-*/android-base-conditional.xml`
203 * Raise minimum LTS requirement from `x.y.u` to `x.y.v` (where `v < u`)
204 * Add a new `<group>`
205 * Remove or change a condition `<conditions><config>`
206 * Add or change a conditional requirement `<group><config>`
207* Other changes that are not in the [Allowed](#allowed) list