[binutils-gdb] Document the ARM_CC_FOR_TARGET testsuite variable

[binutils-gdb] Document the ARM_CC_FOR_TARGET testsuite variable

[Luis Machado]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=3abc1d8fe0e09a4ba806d5e2a1902ac45f825ee9

commit 3abc1d8fe0e09a4ba806d5e2a1902ac45f825ee9
Author: Luis Machado <luis.machado@arm.com>
Date:   Thu Jun 9 11:33:09 2022 +0100

    Document the ARM_CC_FOR_TARGET testsuite variable
    
    This variable is useful when exercising AArch64 multi-arch support (debugging
    32-bit AArch32 executables).
    
    Unfortunately it isn't well documented. This patch adds information about it
    and explains how to use it.

Diff:
---
 gdb/testsuite/README | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/gdb/testsuite/README b/gdb/testsuite/README
index 3a34dcdd154..330a385f349 100644
--- a/gdb/testsuite/README
+++ b/gdb/testsuite/README
@@ -328,6 +328,36 @@ For example, to turn on gdbserver debugging, you can do:
 
 	make check GDBSERVER_DEBUG="debug,replay"
 
+Architecture-specific Parameters
+******************************
+
+This section documents architecture-specific parameters that can be used with
+the GDB testsuite.
+
+- AArch64 (Linux)
+
+ARM_CC_FOR_TARGET
+
+The AArch64 ports of GDB and GDBserver support debugging AArch32
+32-bit programs running on 64-bit state.  There are some tests under
+gdb.multi/ that exercise this particular feature.
+
+By default, the testsuite tries to find a compiler capable of
+generating 32-bit executables.  If no compiler is found, or if the
+32-bit executable generated by the found compiler can't be executed
+correctly, the tests will be marked UNSUPPORTED.  The list of 32-bit
+Arm compiler names the testsuite will try can be found in
+gdb/testsuite/lib/gdb.exp:arm_cc_for_target.
+
+You can set ARM_CC_FOR_TARGET to override the search and explicitly
+specify the compiler to use.  This variable should contain the command
+line for the compiler, including the full path to it, if the compiler
+is not in $PATH.
+
+Example:
+
+	make check-gdb TESTS="gdb.multi/multi-arch.exp" RUNTESTFLAGS="ARM_CC_FOR_TARGET=arm-linux-gnueabihf-gcc"
+
 Race detection
 **************