Re: [PATCH 3/3] gdb/mi: Add new commands -symbol-info-{functions,variables,types}

Eli Zaretskii
2019-09-27T05:43:26Z

> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Cc: Andrew Burgess <andrew.burgess@embecosm.com>
> Date: Fri, 27 Sep 2019 00:09:37 +0100
>
> diff --git a/gdb/NEWS b/gdb/NEWS
> index 779fd91d3a6..9c1d08a24c4 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -302,6 +302,10 @@ focus, winheight, +, -, >, <
> These can be used to catch C++ exceptions in a similar fashion to
> the CLI commands 'catch throw', 'catch rethrow', and 'catch catch'.
>
> +-symbol-info-functions, -symbol-info-types, and -symbol-info-variables
> + These commands are the MI equivalent of the CLI commands 'info
> + functions', 'info types', and 'info variables' respectively.
> +
> * Other MI changes

This part is OK.

> +@noindent
> +Returns a list containing the names and types for all global functions
^^^^^^^
"Return", to be consistent with our style in describing the other MI
commands.

> +taken from the debug information. The functions are grouped by source
> +file, and the line number on which each function is defined is given.

It is best to avoid passive tense if possible and practical. In this
case, I suggest to reword the last sentence as

The functions are grouped by source file, and shown with the line
number on which each function is defined.

> +When @code{--include-nondebug} is passed then the output also includes
> +code symbols from the symbol table.

Again, this reqording:

The @code{--include-nondebug} option causes the output to include
code symbols from the symbol table.

avoids passive tense and makes the text more clear.

> +@subsubheading Example
> +@smallexample
> +(gdb)
> +-symbol-info-functions
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{line="36",definition="void f4(int *);"@},
> + @{line="42",definition="int main();"@},
> + @{line="30",definition="static my_int_t f1(int, int);"@}]@},
> + @{filename="gdb.mi/mi-sym-info-2.c",
> + fullname="/project/gdb.mi/mi-sym-info-2.c",
> + definitions=[@{line="33",definition="float f2(another_float_t);"@},
> + @{line="39",definition="int f3(another_int_t);"@},
> + @{line="27",definition="static another_float_t f1(int);"@}]@}]@}
> +(gdb)
> +-symbol-info-functions --name f1
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{line="30",definition="static my_int_t f1(int, int);"@}]@},
> + @{filename="gdb.mi/mi-sym-info-2.c",
> + fullname="/project/gdb.mi/mi-sym-info-2.c",
> + definitions=[@{line="27",definition="static another_float_t f1(int);"@}]@}]@}
> +(gdb)
> +-symbol-info-functions --type void
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{line="36",definition="void f4(int *);"@}]@}]@}
> +(gdb)
> +-symbol-info-functions --include-nondebug
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{line="36",definition="void f4(int *);"@},
> + @{line="42",definition="int main();"@},
> + @{line="30",definition="static my_int_t f1(int, int);"@}]@},
> + @{filename="gdb.mi/mi-sym-info-2.c",
> + fullname="/project/gdb.mi/mi-sym-info-2.c",
> + definitions=[@{line="33",definition="float f2(another_float_t);"@},
> + @{line="39",definition="int f3(another_int_t);"@},
> + @{line="27",definition="static another_float_t f1(int);"@}]@}],
> + nondebug=
> + [@{address="0x0000000000400398",name="_init"@},
> + @{address="0x00000000004003b0",name="_start"@},
> + ...
> + ]@}
> +@end smallexample

This long series of examples should have @group..@end group to make
sure TeX doesn't break any example between pages.

> +@noindent
> +Returns a list of all defined types. The types are grouped by source
^^^^^^^
"Return".

> +file, and the line number on which each user defined type is defined.

See previous comments.

> +Some base types are not defined in the source code but are added to
> +the debug information by the compiler, for example @code{int},
> +@code{float}, etc, these types do not have an associated line number.

This slight modification

@code{float}, etc.; these types do not have an associated line number.

is more grammatically correct, and also reads easier.

> +The options @code{--name} allows the list of types returned to be
^^^^^^^
"option", in singular

> +@smallexample
> +(gdb)
> +-symbol-info-types
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{definition="float"@},
> + @{definition="int"@},
> + @{line="27",definition="typedef int my_int_t;"@}]@},
> + @{filename="gdb.mi/mi-sym-info-2.c",
> + fullname="/project/gdb.mi/mi-sym-info-2.c",
> + definitions=[@{line="24",definition="typedef float another_float_t;"@},
> + @{line="23",definition="typedef int another_int_t;"@},
> + @{definition="float"@},
> + @{definition="int"@}]@}]@}
> +(gdb)
> +-symbol-info-types --name _int_
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{line="27",definition="typedef int my_int_t;"@}]@},
> + @{filename="gdb.mi/mi-sym-info-2.c",
> + fullname="/project/gdb.mi/mi-sym-info-2.c",
> + definitions=[@{line="23",definition="typedef int another_int_t;"@}]@}]@}
> +@end smallexample

See previous comments about the long example.

> +@noindent
> +Returns a list containing the names and types for all global variables
> +taken from the debug information. The variables are grouped by source
> +file, and the line number on which each variable is definedd given.
> +
> +When @code{--include-nondebug} is passed then the output also includes
> +data symbols from the symbol table.

See previous comments about similar text.

> +@subsubheading Example
> +@smallexample
> +(gdb)
> +-symbol-info-variables
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{line="25",definition="static float global_f1;"@},
> + @{line="24",definition="static int global_i1;"@}]@},
> + @{filename="gdb.mi/mi-sym-info-2.c",
> + fullname="/project/gdb.mi/mi-sym-info-2.c",
> + definitions=[@{line="21",definition="int global_f2;"@},
> + @{line="20",definition="int global_i2;"@},
> + @{line="19",definition="static float global_f1;"@},
> + @{line="18",definition="static int global_i1;"@}]@}]@}
> +(gdb)
> +-symbol-info-variables --name f1
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{line="25",definition="static float global_f1;"@}]@},
> + @{filename="gdb.mi/mi-sym-info-2.c",
> + fullname="/project/gdb.mi/mi-sym-info-2.c",
> + definitions=[@{line="19",definition="static float global_f1;"@}]@}]@}
> +(gdb)
> +-symbol-info-variables --type float
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{line="25",definition="static float global_f1;"@}]@},
> + @{filename="gdb.mi/mi-sym-info-2.c",
> + fullname="/project/gdb.mi/mi-sym-info-2.c",
> + definitions=[@{line="19",definition="static float global_f1;"@}]@}]@}
> +(gdb)
> +-symbol-info-variables --include-nondebug
> +^done,symbols=
> + @{debug=
> + [@{filename="gdb.mi/mi-sym-info-1.c",
> + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c",
> + definitions=[@{line="25",definition="static float global_f1;"@},
> + @{line="24",definition="static int global_i1;"@}]@},
> + @{filename="gdb.mi/mi-sym-info-2.c",
> + fullname="/project/gdb.mi/mi-sym-info-2.c",
> + definitions=[@{line="21",definition="int global_f2;"@},
> + @{line="20",definition="int global_i2;"@},
> + @{line="19",definition="static float global_f1;"@},
> + @{line="18",definition="static int global_i1;"@}]@}],
> + nondebug=
> + [@{address="0x00000000004005d0",name="_IO_stdin_used"@},
> + @{address="0x00000000004005d8",name="__dso_handle"@}
> + ...
> + ]@}
> +@end smallexample

See previous comments about long examples.

Thanks.