[PATCH 1/2] doc: Update our clang documentation to reflect current status

[Tom Rini]

First, since this document was written the biggest challenges at the
time are simply not applicable anymore. Second, we need to list the
challenges which are preventing more platforms from being able to be
built with Clang today.  Next, we update the general wording to be host
distribution agnostic. Finally, the section about xenguest_arm64 issues
is not present anymore.

Signed-off-by: Tom Rini <trini at konsulko.com>
---
Cc: Mark Kettenis <kettenis at openbsd.org>
This does leave the FreeBSD section unchanged and should likely be
looked at again by someone with a BSD build machine available.
---
 doc/build/clang.rst | 85 +++++++++++----------------------------------
 1 file changed, 21 insertions(+), 64 deletions(-)

diff --git a/doc/build/clang.rst b/doc/build/clang.rst
index 09bb988e9236..d8c554982567 100644
--- a/doc/build/clang.rst
+++ b/doc/build/clang.rst
@@ -1,34 +1,27 @@
 Building with Clang
 ===================
 
-The biggest problem when trying to compile U-Boot with Clang is that almost all
-archs rely on storing gd in a global register and the Clang 3.5 user manual
-states: "Clang does not support global register variables; this is unlikely to
-be implemented soon because it requires additional LLVM backend support."
-
-The ARM backend can be instructed not to use the r9 and x18 registers using
--ffixed-r9 or -ffixed-x18 respectively. As global registers themselves are not
-supported inline assembly is needed to get and set the r9 or x18 value. This
-leads to larger code then strictly necessary, but at least works.
-
-Debian based
-------------
-
-Required packages can be installed via apt, e.g.
-
-.. code-block:: bash
-
-    sudo apt-get install clang
-
-We make use of the CROSS_COMPILE variable to derive the build target which is
-passed as the --target parameter to clang.
-
-The CROSS_COMPILE variable further determines the paths to other build
-tools. As assembler we use the binary pointed to by '$(CROSS_COMPILE)as'
-instead of the LLVM integrated assembler (IAS).
-
-Here is an example demonstrating building U-Boot for the Raspberry Pi 2
-using clang:
+In general terms, U-Boot support building with Clang as the C compiler and
+building and booting our "sandbox" target is part of CI.
+
+There are however some specific issues that need to be addressed to fully
+support building with Clang on all targets.
+
+* Given the issue reported in https://github.com/llvm/llvm-project/issues/78778
+  currently one has to configure the build first with GCC.
+* Support for passing the correct flags along to `$(CPP)` needs to be
+  backported from the Linux Kernel.
+* Support for using Clang as the linker is required to support the LTO feature
+  which some platforms require in order to create an appropriately small
+  binary.
+
+In general, when building with Clang we make use of the CROSS_COMPILE variable
+to derive the build target which is passed as the --target parameter to clang.
+The CROSS_COMPILE variable further determines the paths to other build tools.
+As assembler we use the binary pointed to by '$(CROSS_COMPILE)as' instead of
+the LLVM integrated assembler (IAS).  After installing clang as per the
+instructions for your specific distribution, in order to build for example the
+Raspberry Pi 2 using clang:
 
 .. code-block:: bash
 
@@ -72,39 +65,3 @@ simplified with a simple wrapper script - saved as
 
     #!/bin/sh
     exec clang -target arm-freebsd-eabi --sysroot /usr/arm-freebsd "$@"
-
-
-Known Issues
-------------
-
-When build U-boot for `xenguest_arm64_defconfig` target, it reports linkage
-error:
-
-.. code-block:: bash
-
-    aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `do_hypervisor_callback':
-    /home/leoy/Dev2/u-boot/drivers/xen/hypervisor.c:188: undefined reference to `__aarch64_swp8_acq_rel'
-    aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `synch_test_and_set_bit':
-    /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:40: undefined reference to `__aarch64_ldset1_acq_rel'
-    aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `synch_test_and_clear_bit':
-    /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:28: undefined reference to `__aarch64_ldclr1_acq_rel'
-    aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `synch_test_and_set_bit':
-    /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:40: undefined reference to `__aarch64_ldset1_acq_rel'
-    aarch64-linux-gnu-ld.bfd: drivers/xen/hypervisor.o: in function `synch_test_and_clear_bit':
-    /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:28: undefined reference to `__aarch64_ldclr1_acq_rel'
-    aarch64-linux-gnu-ld.bfd: drivers/xen/events.o: in function `synch_test_and_clear_bit':
-    /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:28: undefined reference to `__aarch64_ldclr1_acq_rel'
-    aarch64-linux-gnu-ld.bfd: drivers/xen/events.o: in function `synch_test_and_set_bit':
-    /home/leoy/Dev2/u-boot/./arch/arm/include/asm/xen/system.h:40: undefined reference to `__aarch64_ldset1_acq_rel'
-    aarch64-linux-gnu-ld.bfd: drivers/xen/gnttab.o: in function `gnttab_end_access':
-    /home/leoy/Dev2/u-boot/drivers/xen/gnttab.c:109: undefined reference to `__aarch64_cas2_acq_rel'
-    Segmentation fault
-
-To fix the failure, we need to append option `-mno-outline-atomics` in Clang
-command to not generate local calls to out-of-line atomic operations:
-
-.. code-block:: bash
-
-    make HOSTCC=clang xenguest_arm64_defconfig
-    make HOSTCC=clang CROSS_COMPILE=aarch64-linux-gnu- \
-         CC="clang -target aarch64-linux-gnueabi -mno-outline-atomics" -j8
-- 
2.34.1