[PATCH] [aarch64, testsuite] Document the ARM_CC_FOR_TARGET testsuite variable

[PATCH] [aarch64, testsuite] Document the ARM_CC_FOR_TARGET testsuite variable

[Luis Machado]

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.
---
 gdb/testsuite/README | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/gdb/testsuite/README b/gdb/testsuite/README
index 3a34dcdd154..5b3fde75ece 100644
--- a/gdb/testsuite/README
+++ b/gdb/testsuite/README
@@ -736,3 +736,31 @@ Use [is_remote target] to check whether the DejaGnu target board is
 remote.  When what you really want to know is whether GDB is using the
 remote protocol, because feature X is only available when GDB debugs
 natively, check gdb_protocol instead.
+
+Architecture-specific settings
+******************************
+
+This section documents architecture-specific settings and flags that can be
+used with the GDB testsuite.
+
+- AArch64 (Linux)
+
+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.
+
+The tests will attempt to find a compiler capable of generating 32-bit
+executables through the ARM_CC_FOR_TARGET variable.  This variable should
+contain the command line for the compiler, including the full path to it, if
+the compiler is not in $PATH.
+
+If ARM_CC_FOR_TARGET is not set, the testsuite will guess some compiler
+commands.  If none is found, or if the 32-bit executable generated by
+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.
+
+Example invocation:
+
+make check-gdb TESTS="gdb.multi/multi-arch.exp" RUNTESTFLAGS="ARM_CC_FOR_TARGET=arm-linux-gnueabihf-gcc"
-- 
2.25.1

Re: [PATCH] [aarch64, testsuite] Document the ARM_CC_FOR_TARGET testsuite variable

[Pedro Alves]

On 2022-06-09 14:06, Luis Machado wrote:
> 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.
> ---
>  gdb/testsuite/README | 28 ++++++++++++++++++++++++++++
>  1 file changed, 28 insertions(+)
> 
> diff --git a/gdb/testsuite/README b/gdb/testsuite/README
> index 3a34dcdd154..5b3fde75ece 100644
> --- a/gdb/testsuite/README
> +++ b/gdb/testsuite/README
> @@ -736,3 +736,31 @@ Use [is_remote target] to check whether the DejaGnu target board is
>  remote.  When what you really want to know is whether GDB is using the
>  remote protocol, because feature X is only available when GDB debugs
>  natively, check gdb_protocol instead.
> +
> +Architecture-specific settings
> +******************************

The non-architecture-specific settings are actually called "parameters", as in:

 Testsuite Parameters
 ********************

I think your new section should come right after that one, and be called 

"Architecture-specific Parameters"

> +
> +This section documents architecture-specific settings and flags that can be

s/settings and flags/parameters/

> +used with the GDB testsuite.
> +
> +- AArch64 (Linux)
> +

There should be a line with the parameter name before describing it, like in
the generic section.  Just:

ARM_CC_FOR_TARGET

followed by an empty line.

> +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.
> +

...

> +The tests will attempt to find a compiler capable of generating 32-bit

"attempt to find" here sound a bit odd here, since with the variable set, the
testsuite doesn't try to find anything, it assumes what we specify works.
See below.

> +executables through the ARM_CC_FOR_TARGET variable.  This variable should
> +contain the command line for the compiler, including the full path to it, if
> +the compiler is not in $PATH.
> +
> +If ARM_CC_FOR_TARGET is not set, the testsuite will guess some compiler
> +commands.  If none is found, or if the 32-bit executable generated by
> +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.
> +

I suggest swapping around the description to first say what happens by
default, and then talk about overriding the default.  Like this:

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 invocation:
> +
> +make check-gdb TESTS="gdb.multi/multi-arch.exp" RUNTESTFLAGS="ARM_CC_FOR_TARGET=arm-linux-gnueabihf-gcc"

The command line should be indended, like all the other example invocations in the file.

Otherwise LGTM.

And ... I notice I actually broke setting ARM_CC_FOR_TARGET...  I'll fix it in a second.

Re: [PATCH] [aarch64, testsuite] Document the ARM_CC_FOR_TARGET testsuite variable

[Luis Machado]

On 6/9/22 15:30, Pedro Alves wrote:
> 
> On 2022-06-09 14:06, Luis Machado wrote:
>> 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.
>> ---
>>   gdb/testsuite/README | 28 ++++++++++++++++++++++++++++
>>   1 file changed, 28 insertions(+)
>>
>> diff --git a/gdb/testsuite/README b/gdb/testsuite/README
>> index 3a34dcdd154..5b3fde75ece 100644
>> --- a/gdb/testsuite/README
>> +++ b/gdb/testsuite/README
>> @@ -736,3 +736,31 @@ Use [is_remote target] to check whether the DejaGnu target board is
>>   remote.  When what you really want to know is whether GDB is using the
>>   remote protocol, because feature X is only available when GDB debugs
>>   natively, check gdb_protocol instead.
>> +
>> +Architecture-specific settings
>> +******************************
> 
> The non-architecture-specific settings are actually called "parameters", as in:
> 
>   Testsuite Parameters
>   ********************
> 
> I think your new section should come right after that one, and be called
> 
> "Architecture-specific Parameters"
> 
>> +
>> +This section documents architecture-specific settings and flags that can be
> 
> s/settings and flags/parameters/
> 
>> +used with the GDB testsuite.
>> +
>> +- AArch64 (Linux)
>> +
> 
> There should be a line with the parameter name before describing it, like in
> the generic section.  Just:
> 
> ARM_CC_FOR_TARGET
> 
> followed by an empty line.
> 
>> +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.
>> +
> 
> ...
> 
>> +The tests will attempt to find a compiler capable of generating 32-bit
> 
> "attempt to find" here sound a bit odd here, since with the variable set, the
> testsuite doesn't try to find anything, it assumes what we specify works.
> See below.
> 
>> +executables through the ARM_CC_FOR_TARGET variable.  This variable should
>> +contain the command line for the compiler, including the full path to it, if
>> +the compiler is not in $PATH.
>> +
>> +If ARM_CC_FOR_TARGET is not set, the testsuite will guess some compiler
>> +commands.  If none is found, or if the 32-bit executable generated by
>> +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.
>> +
> 
> I suggest swapping around the description to first say what happens by
> default, and then talk about overriding the default.  Like this:
> 
> 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 invocation:
>> +
>> +make check-gdb TESTS="gdb.multi/multi-arch.exp" RUNTESTFLAGS="ARM_CC_FOR_TARGET=arm-linux-gnueabihf-gcc"
> 
> The command line should be indended, like all the other example invocations in the file.
> 
> Otherwise LGTM.

Thanks. I've made those changes locally and pushed it as 3abc1d8fe0e09a4ba806d5e2a1902ac45f825ee9.