1# Android Kernel Configs 2 3## How are kernel config settings typically stored? 4 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 10`arch/*/configs/`. 11 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. 22 23## How are Android's kernel configs stored? 24 25The kernel configs are stored in the [kernel/configs repo](https://android.googlesource.com/kernel/configs/). 26 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`. 31 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. 44 45In releases after Android P the architecture-specific base config fragments are 46removed, and conditional kernel config requirements are stored in 47`android-base-conditional.xml`. 48 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. 52 53Kernel configs vary by kernel version, so there are sets of kernel configs for 54each version of the kernel that Android supports. 55 56## How can I easily combine platform and required Android configs? 57 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: 61 62```sh 63ARCH=<arch> scripts/kconfig/merge_config.sh <...>/<platform>_defconfig <...>/android-base.config <...>/android-base-<arch>.config <...>/android-recommended.config 64``` 65 66This will generate a `.config` that can then be used to save a new defconfig or 67compile a new kernel with Android features enabled. 68 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: 74 75```sh 76make ARCH=<arch> <platform>_defconfig android-base.config android-base-<arch>.config android-recommended.config 77``` 78 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. 82 83## Are the config requirements tested? 84 85Starting with Android O the base kernel configs are not just advisory. They are 86tested as part of 87[VTS](https://android.googlesource.com/platform/test/vts-testcase/hal/+/master/treble/framework_vintf/AndroidTest.xml) 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. 92 93## Ensuring Device Upgradability 94 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. 103 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. 111 112Support for kernel configs from previous dessert releases is dropped from AOSP 113when the upgrade path from that dessert release is no longer supported. 114 115# Organization and Maintenance of the Kernel Config Repo 116 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. 124 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. 130 131## I want to add/modify/remove a kernel config requirement. What do I do? 132 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 135release directories. 136 137Because there is no tool to consistently generate these config fragments, 138please keep them alphabetically (not randomly) sorted. 139 140### `android-x.y/android-base.config` 141 142This file lists all common kernel configuration requirements on kernel version 143`x.y`. 144 145### `android-x.y/android-base-conditional.xml` 146 147Contains the following: 148 149* Minimum LTS required 150* Conditional requirements. 151 152### `android-x.y/Android.bp` 153 154Build rules from the aforementioned files to a 155[framework compatibility matrix](https://source.android.com/devices/architecture/vintf/comp-matrices) 156. See 157[this link](https://source.android.com/devices/architecture/vintf/match-rules#kernel) 158for details of the output format. 159 160## I want to freeze/release the current kernel requirements. What do I do? 161 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 165 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 169 master. 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. 179 180## I want to edit a released kernel requirement. What do I do? 181 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, 185 186### Allowed 187* Support a new kernel version by creating a new `<dessert>/android-x.y` 188 directory 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>` 196 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 208