Merge "Add binutils kernel deprecation schedule."
diff --git a/BINUTILS_KERNEL_DEPRECATION.md b/BINUTILS_KERNEL_DEPRECATION.md
new file mode 100644
index 0000000..343e91a
--- /dev/null
+++ b/BINUTILS_KERNEL_DEPRECATION.md
@@ -0,0 +1,58 @@
+In the effort to improve test coverage of the LLVM substitutes when building
+Linux kernels for Android distributions, as well as minimize build
+dependencies, we plan to phase kernel builds over to use the LLVM substitutes
+distributed through AOSP for Android S. This will remove the kernels from being
+dependent on binutils in Android. The NDK is currently the other largest
+dependency.
+
+Invoking a kernel build with all of the substitutes is tedious; see
+https://www.kernel.org/doc/html/latest/kbuild/llvm.html#llvm-utilities, so
+`make LLVM=1` was introduced in:
+commit a0d1c951ef08 ("kbuild: support LLVM=1 to switch the default tools to Clang/LLVM")
+which first landed in v5.7-rc1 and will need to be backported to at least 5.4.
+
+Support for using Clang's "integrated assembler" is a risk; we have gotten it
+working upstream, but then small changes to assembly quickly uncover missing
+support. Thus `LLVM_IAS=1` is a separate flag from `LLVM=1`.
+
+The plan for S is:
+
+1. Ensure a0d1c951ef08 is backported to all supported kernel version branches
+   for S.
+2. Wire up support in Android common kernel's build/build.sh to forward
+   `LLVM=1` to `make` from a supplied config. `LLVM=1` needs to be specified
+   for all invocations of `make`.
+3. Update kernel configs to use `LLVM=1` and remove the individual flags like
+   `CC=clang`, `NM=llvm-nm`, and such.
+4. Create a branch of
+   https://android.googlesource.com/platform/prebuilts/gcc/linux-x86/aarch64/aarch64-linux-android-4.9/
+   that only contains the GNU as (assembler) binary.
+5. Update repo manifests for kernels to use the branch from 4, and ensure
+   kernels build cleanly.
+
+5 is potentially a lot of work, depending on whether we have a lot of fixes to
+backport or certain configs are broken that haven't been tested upstream.
+
+A stretch goal, assuming we get LLVM_IAS=1 in shape:
+6. Wire up support in Android common kernel's build/build.sh to forward
+   `LLVM_IAS=1` to `make` from a supplied config. `LLVM_IAS=1` needs to be
+   specified for all invocations of `make`. Alternatively, we can just modify
+   the top level Makefile to do what LLVM_IAS=1 would do anyways, though having
+   flexibility of turning it off quickly should it regress in mainline is
+   probably a safer bet.
+7. Update kernel configs to use `LLVM_IAS=1`, unless we simply modified the top
+   level Makefile in 6.
+8. Remove GNU binutils from Android kernel manifests.
+
+I think we can get all 8 done for S, but 6,7,8 are a risk, and aren't critical
+to solve for S. Luckily, our comrades over at CrOS LLVM are helping whip
+Clang's integrated assembler into shape. In fact, they may end up beating us to
+the punch.
+
+See this public hotlist for some of the outstanding issues to be resolved.
+https://github.com/ClangBuiltLinux/linux/issues?q=is%3Aissue+is%3Aopen+label%3A%22%5BTOOL%5D+integrated-as%22
+(Not all of those are blockers).
+
+The version of GNU binutils distributed by AOSP is version 2.27.0.20170315 (ToT
+GNU binutils is 2.35) plus cherry picks. The 5.9-rc1 linux kernel currently
+requires binutils 2.23 or newer.