README.md: docs for conditional.xml and freezing
Test: none
Change-Id: Ib376c4c265719b9c7bb78b05eb6204d007e23eac
diff --git a/README.md b/README.md
index 541b9bc..e0c7bc3 100644
--- a/README.md
+++ b/README.md
@@ -29,14 +29,22 @@
that enhance Android’s functionality in some way but are not required for it to
run are located in the recommended config fragment, `android-recommended.config`.
-There may be required kernel config settings that do not apply to all
-architectures - some may be specific to ARM64 for example. As a result, there
-are architecture-specific base config fragments, such as
-`android-base-arm64.config`. If an architecture-specific base config fragment does
-not exist for a particular architecture, it means there are no required kernel
-config options for Android specific to that architecture. Note that the
-architecture-agnostic kernel config requirements from `android-base.config` still
-apply in that case.
+Some kernel config requirements only apply on certain architectures. Other
+requirements only apply if some other kernel config option has a particular
+value. The platform owner may also have a choice between several config
+options. These types of constraints cannot be expressed with a simple kernel
+config fragment. In releases up to and including Android P, kernel config
+requirements that are specific to a particular architecture are contained in
+architecture-specific base config fragments, such as
+`android-base-arm64.config`. If an architecture-specific base config fragment
+does not exist for a particular architecture in Android P or an earlier
+release, it means there are no required kernel config options for Android
+specific to that architecture. Note that the architecture-agnostic kernel
+config requirements from `android-base.config` still apply in that case.
+
+In releases after Android P the architecture-specific base config fragments are
+removed, and conditional kernel config requirements are stored in
+`android-base-conditional.xml`.
Kernel configs vary by kernel version, so there are sets of kernel configs for
each version of the kernel that Android supports.
@@ -64,6 +72,10 @@
make ARCH=<arch> <platform>_defconfig android-base.config android-base-<arch>.config android-recommended.config
```
+If there is an `android-base-conditional.xml` file for your release/kernel
+version combination, it is necessary to review it and manually edit your
+defconfig to satisfy any applicable requirements.
+
## Are the config requirements tested?
Starting with Android O the base kernel configs are not just advisory. They
@@ -118,3 +130,72 @@
Because there is no tool to consistently generate these config fragments,
please keep them alphabetically (not randomly) sorted.
+
+### `android-x.y/android-base.config`
+
+This file lists all common kernel configuration requirements on kernel version
+`x.y`.
+
+### `android-x.y/android-base-conditional.xml`
+
+Contains the following:
+
+* Minimum LTS required
+* Conditional requirements.
+
+### `android-x.y/Android.bp`
+
+Build rules from the aforementioned files to a
+[framework compatibility matrix](https://source.android.com/devices/architecture/vintf/comp-matrices)
+. See
+[this link](https://source.android.com/devices/architecture/vintf/match-rules#kernel)
+for details of the output format.
+
+## I want to freeze/release the current kernel requirements. What do I do?
+
+Prior to a [FCM Version release](https://source.android.com/devices/architecture/vintf/fcm#new-fcm-versions)
+(often accompanied with a dessert release as well), the kernel requirements must
+be frozen. Follow the following steps
+
+* Copy the top-level `android-*` directories to a release directory, preferably
+ with the dessert name (for example, `q`).
+ * Remove top-level `android-*` directories. This change is not propagated to
+ master.
+* Edit the new `<dessert>/android-*/Android.bp` files and rename the modules.
+ For example, change `kernel_config_current_4.9` in `q/android-4.9/Android.bp`
+ to `kernel_config_q_4.9`
+* Under `hardware/interfaces/compatibility_matrices/Android.bp`, edit
+ `kernel_config` field for the `framework_compatibility_matrix.current.xml`
+ to use the new modules.
+ * `framework_compatibility_matrix.current.xml` will be renamed to
+ `framework_compatibility_matrix.<level>.xml` as part of the FCM Version
+ release, which is a separate process.
+
+## I want to edit a released kernel requirement. What do I do?
+
+Don't edit a released kernel requirement unless necessary. If you have to make
+such a change, after discussing the change with maintainers, keep in mind that
+you **CANNOT** make a requirement more restrictive. Specifically,
+
+### Allowed
+* Support a new kernel version by creating a new `<dessert>/android-x.y`
+ directory
+* Remove a line from `<dessert>/android-*/android-base.config`
+* Remove a line from `<dessert>/android-*/android-base-*.config`
+* In `<dessert>/android-*/android-base-conditional.xml`
+ * Lower minimum LTS requirement from `x.y.u` to `x.y.v` (where `v < u`)
+ * Remove a `<group>`
+ * Add a condition `<group><conditions><config>`
+ * Remove a conditional requirement `<group><config>`
+
+### Not allowed
+* Add or change a line from `<dessert>/android-*/android-base.config`
+* Add or change a line from `<dessert>/android-*/android-base-*.config`
+* Add new conditional requirements `<dessert>/android-*/android-base-*.config`
+* Rename existing conditional requirements `<dessert>/android-*/android-base-*.config`
+* In `<dessert>/android-*/android-base-conditional.xml`
+ * Raise minimum LTS requirement from `x.y.u` to `x.y.v` (where `v < u`)
+ * Add a new `<group>`
+ * Remove or change a condition `<conditions><config>`
+ * Add or change a conditional requirement `<group><config>`
+* Other changes that are not in the [Allowed](#allowed) list
