[PATCH] Document board settting

[PATCH] Document board settting

[Yao Qi]

This patch is to describe all the existing board settings we are using
in GDB testsuite.  Some of them are obvious, but some are not.  I
referred CVS log and mail archives to get the description to each
of them.

I comment out gdb,noresults and use_cygmon, which I can't figure out
the purpose of using them.  I'll figure them out later.
Please pay attention to my explanation to "gdb,nofileio" and
"gdb,noinferiorio".  I am not satisfied with them, but unable
to tell the difference of them.

gdb/doc:

2012-04-24  Yao Qi  <yao@codesourcery.com>

	* gdbint.texinfo (Testsuite): New section `Board settings'.
---
 gdb/doc/gdbint.texinfo |   56 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 56 insertions(+), 0 deletions(-)

diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index fcc106c..80196b8 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -7873,6 +7873,62 @@ gdb_test "python print ttype.template_argument(2)" "&C::c"
 @end smallexample
 @end table
 
+@section Board settings
+In @value{GDBN} testsuite, the tests can be configured or customized in its board
+file by means of @dfn{Boarding Settings}.  Here are the board settings,
+
+@table @code
+
+@item gdb,cannot_call_functions
+Whether the board supports inferior call, that is, invoking inferior functions
+in @value{GDBN}.  If inferior call is required in test case, this variable
+should be checked.
+@item gdb,can_reverse
+Whether the board supports reverse execution.  If reverse execution is required
+in test case, this variable should be checked.
+@item gdb,no_hardware_watchpoints
+Whether the board supports hardware watchpoints.  If hardware watchpoints
+are required in test case, this variable should be checked.
+@item gdb,nofileio
+Whether the remote stub intercept target file operations and perform them on
+the host.
+@item gdb,noinferiorio
+Whether the inferior has I/O capability on the board.  If test case has to do
+some operations related to I/O, such as printing, this variable should be
+checked.
+@c @item gdb,noresults
+@c NEED DOCUMENT.
+@item gdb,nosignals
+Whether signals are supported on target board.  If test case uses signals,
+this variable should be checked.
+@item gdb,skip_huge_test
+Whether to skip time-consuming tests on the board with slow connection.  If
+test case is time-consuming, this variable should be checked.
+@item gdb,skip_float_tests
+Whether to skip tests related to float points on target board.  If the test
+cases use floating points, this variable should be checked.
+@item gdb,use_precord
+Whether support process record on target board.  If the test case use target
+record, this variable should be checked.
+@item gdb_server_prog
+The location of GDBserver.  If GDBserver somewhere other than its default
+location is used in test, specify the location of GDBserver in this variable.
+@item in_proc_agent
+The location of in-process agent.  If in-process agent other than its default
+location is used in test, specify the location of in-process agent in
+this variable.
+@item noargs
+Whether configuration of @value{GDBN} supports argument passing for inferior.
+If the test case needs argument passing, this variable should be checked.
+@item no_long_long
+Whether target board supports type @code{long long}.  If test case uses
+@code{long long}, this variable should be checked.
+@c @item use_cygmon
+@c NEED DOCUMENT.
+@item use_gdb_stub
+Whether the tests are running with gdb stub.
+@end table
+
 @node Hints
 
 @chapter Hints
-- 
1.7.0.4

Re: [PATCH] Document board settting

[Yao Qi]

On 04/24/2012 11:05 PM, Yao Qi wrote:
> This patch is to describe all the existing board settings we are using
> in GDB testsuite.  Some of them are obvious, but some are not.  I
> referred CVS log and mail archives to get the description to each
> of them.
> 
> I comment out gdb,noresults and use_cygmon, which I can't figure out
> the purpose of using them.  I'll figure them out later.
> Please pay attention to my explanation to "gdb,nofileio" and
> "gdb,noinferiorio".  I am not satisfied with them, but unable
> to tell the difference of them.
> 

I've sent another mail with s/settting/setting/ in $subject.

-- 
Yao (齐尧)

Re: [PATCH] Document board settting

[Eli Zaretskii]

> From: Yao Qi <yao@codesourcery.com>
> Date: Tue, 24 Apr 2012 23:05:56 +0800
> 
> This patch is to describe all the existing board settings we are using
> in GDB testsuite.  Some of them are obvious, but some are not.  I
> referred CVS log and mail archives to get the description to each
> of them.

Thank you!

> I comment out gdb,noresults and use_cygmon, which I can't figure out
> the purpose of using them.  I'll figure them out later.
> Please pay attention to my explanation to "gdb,nofileio" and
> "gdb,noinferiorio".  I am not satisfied with them, but unable
> to tell the difference of them.

> +@section Board settings
> +In @value{GDBN} testsuite, the tests can be configured or customized in its board file
                                                                        ^^^^^^^^^^^^^^^^^
"in the board file", I think.

> +file by means of @dfn{Boarding Settings}.
                         ^^^^^^^^^^^^^^^^^
I think you mean "Board Settings" here.

>                                           Here are the board settings,

I would rephrase

  Here are the supported board settings:

> +@item gdb,cannot_call_functions
> +Whether the board supports inferior call, that is, invoking inferior functions

Since it says "cannot", I think the meaning of this setting is that
inferior calls aren't supported.  So the "whether" part is not
appropriate.  Simply "the board does not support inferior calls" is
better.

> +in @value{GDBN}.  If inferior call is required in test case, this variable

  If inferior calls are required in a test case, ...

> +should be checked.
> +@item gdb,can_reverse
> +Whether the board supports reverse execution.

Again, it's better to say explicitly

  The board supports reverse execution.

>                                               If reverse execution is required
> +in test case, this variable should be checked.

Please fix this (and other similar places) as I suggested above.

Btw, I don't think it's a good idea to repeat the same sentence "If
FOO is required in a test case, this variable should be checked." for
every setting.  I think you should only state this once.

> +@item gdb_server_prog
> +The location of GDBserver.  If GDBserver somewhere other than its default
> +location is used in test, specify the location of GDBserver in this variable.

By "location" you mean the full file name, right?  If so, please say
so explicitly.  "Location" is ambiguous.

Re: [PATCH] Document board settting

[Yao Qi]

On 04/25/2012 02:20 PM, Eli Zaretskii wrote:
>> >                                               If reverse execution is required
>> > +in test case, this variable should be checked.
> Please fix this (and other similar places) as I suggested above.
> 

Fixed.

> Btw, I don't think it's a good idea to repeat the same sentence "If
> FOO is required in a test case, this variable should be checked." for
> every setting.  I think you should only state this once.
> 

I also felt odd when repeating this sentence time and time again in
doc.  In this version, they are removed, and I add a new sentence out
of the table.

"If the feature which is about the board setting variable is required
 in test cases, the corresponding board setting variable should be
 checked in test cases."

>> > +@item gdb_server_prog
>> > +The location of GDBserver.  If GDBserver somewhere other than its default
>> > +location is used in test, specify the location of GDBserver in this variable.
> By "location" you mean the full file name, right?  If so, please say
> so explicitly.  "Location" is ambiguous.

Either full file name or path relative to $build_dir/testsuite should
be OK.  I changed this part to explicitly point this out.

-- 
Yao (齐尧) 

gdb/doc:

2012-04-25  Yao Qi  <yao@codesourcery.com>

	* gdbint.texinfo (Testsuite): New section `Board settings'.
---
 gdb/doc/gdbint.texinfo |   51 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 51 insertions(+), 0 deletions(-)

diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index fcc106c..750321d 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -7873,6 +7873,57 @@ gdb_test "python print ttype.template_argument(2)" "&C::c"
 @end smallexample
 @end table
 
+@section Board settings
+In @value{GDBN} testsuite, the tests can be configured or customized in the board
+file by means of @dfn{Board Settings}.  Here are the supported board settings:
+
+If the feature which is about the board setting variable is required in test
+cases, the corresponding board setting variable should be checked in test cases.
+
+@table @code
+
+@item gdb,cannot_call_functions
+The board does not support inferior call, that is, invoking inferior functions
+in @value{GDBN}.
+@item gdb,can_reverse
+The board supports reverse execution.
+@item gdb,no_hardware_watchpoints
+The board does not support hardware watchpoints.
+@item gdb,nofileio
+@value{GDBN} is unable to intercept target file operations in remote and perform
+them on the host.
+@item gdb,noinferiorio
+The board is unable to provide I/O capability to the inferior.
+@c @item gdb,noresults
+@c NEED DOCUMENT.
+@item gdb,nosignals
+The board does not support signals.
+@item gdb,skip_huge_test
+Skip time-consuming tests on the board with slow connection.
+@item gdb,skip_float_tests
+Skip tests related to float points on target board.
+@item gdb,use_precord
+The board supports process record.
+@item gdb_server_prog
+The location of GDBserver.  If GDBserver somewhere other than its default
+location is used in test, specify the location of GDBserver in this variable.  The
+location can be either the full file name of GDBserver, or the path relative to
+testsuite directory in build dir.
+@item in_proc_agent
+The location of in-process agent.  If in-process agent other than its default
+location is used in test, specify the location of in-process agent in
+this variable.  The location can be either the full file name or the path relate
+to testsuite directory in build dir.
+@item noargs
+@value{GDBN} does not support argument passing for inferior.
+@item no_long_long
+The board does not support type @code{long long}.
+@c @item use_cygmon
+@c NEED DOCUMENT.
+@item use_gdb_stub
+The tests are running with gdb stub.
+@end table
+
 @node Hints
 
 @chapter Hints
-- 
1.7.0.4

Re: [PATCH] Document board settting

[Eli Zaretskii]

> Date: Wed, 25 Apr 2012 17:03:19 +0800
> From: Yao Qi <yao@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
> +@section Board settings
> +In @value{GDBN} testsuite, the tests can be configured or customized in the board
> +file by means of @dfn{Board Settings}.  Here are the supported board settings:
> +
> +If the feature which is about the board setting variable is required in test
> +cases, the corresponding board setting variable should be checked in test cases.

This should be before the sentence saying "Here are the supported
board settings".  Like this:

  In @value{GDBN} testsuite, the tests can be configured or customized
  in the board file by means of @dfn{Board Settings}.  Each setting
  should be consulted by test cases that depend on the corresponding
  feature.

  Here are the supported board settings:

    The
> +location can be either the full file name of GDBserver, or the path relative to
> +testsuite directory in build dir.

 Suggest a slight rewording:

  The location is a file name of GDBserver that can be either absolute or
  relative to the testsuite subdirectory of the build directory.

> +@item in_proc_agent
> +The location of in-process agent.  If in-process agent other than its default
> +location is used in test, specify the location of in-process agent in
> +this variable.  The location can be either the full file name or the path relate
> +to testsuite directory in build dir.

Same here.

OK with those changes.

Thanks.

[committed] : [PATCH] Document board settting

[Yao Qi]

On 04/25/2012 06:05 PM, Eli Zaretskii wrote:
>> Date: Wed, 25 Apr 2012 17:03:19 +0800
>> From: Yao Qi <yao@codesourcery.com>
>> CC: <gdb-patches@sourceware.org>
>>
>> +@section Board settings
>> +In @value{GDBN} testsuite, the tests can be configured or customized in the board
>> +file by means of @dfn{Board Settings}.  Here are the supported board settings:
>> +
>> +If the feature which is about the board setting variable is required in test
>> +cases, the corresponding board setting variable should be checked in test cases.
> 
> This should be before the sentence saying "Here are the supported
> board settings".  Like this:
> 
>   In @value{GDBN} testsuite, the tests can be configured or customized
>   in the board file by means of @dfn{Board Settings}.  Each setting
>   should be consulted by test cases that depend on the corresponding
>   feature.
> 
>   Here are the supported board settings:
> 
>     The
>> +location can be either the full file name of GDBserver, or the path relative to
>> +testsuite directory in build dir.
> 
>  Suggest a slight rewording:
> 
>   The location is a file name of GDBserver that can be either absolute or
>   relative to the testsuite subdirectory of the build directory.
> 
>> +@item in_proc_agent
>> +The location of in-process agent.  If in-process agent other than its default
>> +location is used in test, specify the location of in-process agent in
>> +this variable.  The location can be either the full file name or the path relate
>> +to testsuite directory in build dir.
> 
> Same here.
> 
> OK with those changes.
> 

This is what I committed.
http://sourceware.org/ml/gdb-cvs/2012-04/msg00201.html

-- 
Yao (齐尧) 

gdb/doc:

2012-04-25  Yao Qi  <yao@codesourcery.com>

	* gdbint.texinfo (Testsuite): New section `Board settings'.
---
 gdb/doc/gdbint.texinfo |   51 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 51 insertions(+), 0 deletions(-)

diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index fcc106c..267a6eb 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -7873,6 +7873,57 @@ gdb_test "python print ttype.template_argument(2)" "&C::c"
 @end smallexample
 @end table
 
+@section Board settings
+In @value{GDBN} testsuite, the tests can be configured or customized in the board
+file by means of @dfn{Board Settings}.  Each setting should be consulted by
+test cases that depend on the corresponding feature.
+
+Here are the supported board settings:
+
+@table @code
+
+@item gdb,cannot_call_functions
+The board does not support inferior call, that is, invoking inferior functions
+in @value{GDBN}.
+@item gdb,can_reverse
+The board supports reverse execution.
+@item gdb,no_hardware_watchpoints
+The board does not support hardware watchpoints.
+@item gdb,nofileio
+@value{GDBN} is unable to intercept target file operations in remote and perform
+them on the host.
+@item gdb,noinferiorio
+The board is unable to provide I/O capability to the inferior.
+@c @item gdb,noresults
+@c NEED DOCUMENT.
+@item gdb,nosignals
+The board does not support signals.
+@item gdb,skip_huge_test
+Skip time-consuming tests on the board with slow connection.
+@item gdb,skip_float_tests
+Skip tests related to float points on target board.
+@item gdb,use_precord
+The board supports process record.
+@item gdb_server_prog
+The location of GDBserver.  If GDBserver somewhere other than its default
+location is used in test, specify the location of GDBserver in this variable.
+The location is a file name of GDBserver that can be either absolute or
+relative to testsuite subdirectory in build directory.
+@item in_proc_agent
+The location of in-process agent.  If in-process agent other than its default
+location is used in test, specify the location of in-process agent in
+this variable.  The location is a file name of in-process agent that can be
+either  absolute or relative to testsuite subdirectory in build directory.
+@item noargs
+@value{GDBN} does not support argument passing for inferior.
+@item no_long_long
+The board does not support type @code{long long}.
+@c @item use_cygmon
+@c NEED DOCUMENT.
+@item use_gdb_stub
+The tests are running with gdb stub.
+@end table
+
 @node Hints
 
 @chapter Hints
-- 
1.7.0.4