Update the -fno-integrated-as docs a bit.

In particular, link to our migration advice.

This commit is based on 3e47e46, with
the Changelog-r24.md part removed so it can be cherry-picked to
aosp/ndk-release-r23.

Bug: http://b/200995199
Bug: android/ndk#1569
Test: N/A
Change-Id: I61c3107bd389c2da1a5641babdef6f56ca487b1f
(cherry picked from commit 3236d6773fe6ed59f4b44c58c0a5a2fd0e28f86a)

docs/BuildSystemMaintainers.md

@@ -244,15 +244,19 @@ are not limited to:
 
 Note that `llvm-as` is **not** an equivalent of GNU `as`, but rather a tool for
 assembling LLVM IR. If you are currently using `as` directly, you will need to
-migrate to using `clang` as a driver for building assembly.
+migrate to using `clang` as a driver for building assembly.  See [Clang
+Migration Notes] for advice on fixing assembly to be LLVM compatible.
 
-GNU Binutils remains available for now but is deprecated and will be removed in
-an upcoming release of the NDK. Those tools are installed to
+GNU Binutils remains available up to and including r23, but has been
+removed in r24. In r23 or earlier, GNU binutils tools are installed to
 `<NDK>/toolchains/llvm/prebuilt/<host-tag>/bin/<triple>-<tool>` and
 `<NDK>/toolchains/llvm/prebuilt/<host-tag>/<triple>/bin/<tool>`.
 
-Note that binutils `as` is used by Clang if the `-fno-integrated-as` argument is
-used.
+Note that by default `/usr/bin/as` is used by Clang if the
+`-fno-integrated-as` argument is used, which is almost certainly not
+what you want!
+
+[Clang Migration Notes]: ClangMigration.md
 
 ## Sysroot
 
@@ -286,8 +290,6 @@ by their .so file extension and their presence in `<NDK>/meta/system_libs.json`.
 The entries in this file are a key/value pair that maps library names to the
 first API level the library is introduced.
 
-[Issue 801]: https://github.com/android-ndk/ndk/issues/801
-
 ## STL
 
 ### libc++
@@ -384,12 +386,6 @@ Android requires [Position-independent executables] beginning with API 21. Clang
 builds PIE executables by default. If invoking the linker directly or not using
 Clang, use `-pie` when linking.
 
-Clang does not properly set the ARMv7 architecture for the non-integrated
-assembler. If using `-fno-integrated-as`, you must explicitly pass
-`-march=armv7-a` when compiling for 32-bit ARM. Note that by default Clang will
-use the integrated assembler, and this flag is not needed in that case. See
-[Issue 906].
-
 Android Studio's LLDB debugger uses a binary's build ID to locate debug
 information. To ensure that LLDB works with a binary, pass an option like
 `-Wl,--build-id=sha1` to Clang when linking. Other `--build-id=` modes are OK,

docs/changelogs/Changelog-r23.md

@@ -11,9 +11,10 @@ For Android Studio issues, follow the docs on the [Android Studio site].
 
 * GNU binutils, excluding the GNU Assembler (GAS), has been removed. GAS will be
   removed in the next release. If you are building with `-fno-integrated-as`,
-  file bugs if anything is preventing you from removing that flag.
+  file bugs if anything is preventing you from removing that flag. See
+  [Clang Migration Notes] for advice about making assembly compatible with LLVM.
 
-* Support for GDB has ended. GDB will be removed from the next release. Use LLDB
+* Support for GDB has ended. GDB will be removed in the next release. Use LLDB
   instead. Note that `ndk-gdb` uses LLDB by default.
 
 * NDK r23 is the last release that will support non-Neon. Beginning with NDK
@@ -25,6 +26,8 @@ For Android Studio issues, follow the docs on the [Android Studio site].
   release. The minimum OS supported by the NDK for r24 will be KitKat (API level
   19).
 
+[Clang Migration Notes]: ClangMigration.md
+
 ## Changes
 
 * Includes Android 12 APIs.