Merge "Add binutils kernel deprecation schedule."
diff --git a/BINUTILS_KERNEL_DEPRECATION.md b/BINUTILS_KERNEL_DEPRECATION.md
new file mode 100644
@@ -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
+Invoking a kernel build with all of the substitutes is tedious; see
+`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
+ 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
+See this public hotlist for some of the outstanding issues to be resolved.
+(Not all of those are blockers).
+The version of GNU binutils distributed by AOSP is version 22.214.171.12470315 (ToT
+GNU binutils is 2.35) plus cherry picks. The 5.9-rc1 linux kernel currently
+requires binutils 2.23 or newer.