Re: Add fullname field in disassembly output

Andrew Burgess
2012-11-06T12:14:00Z

On 02/11/2012 3:32 PM, Pedro Alves wrote:
>
> But it looks strange to me that NEWS has more detail on the new output
> than the docs. IMO, it would be good if, e.g., something around the
> part that reads:
>
> The output for each instruction is composed of four fields:
>
> was updated to reflect the new field. The short examples alone
> don't explain what the field is.
>
> In any case, Eli will give you the final word on the docs bits.

So I agree that the documentation for -data-disassemble has been allowed to get out of date with all the new features available. As such, just adding the new field to the list you suggest would be more confusing I think.

So, new patch below, the code changes are the same, but I've attempted to improve the documentation for -data-disassemble, this now includes not only the new field I've added, but all the other fields that were not documented.

I've also filled in the cli 'disassemble' command as being the related cli command as it offers most (all?) of the features that -data-disassemble offers.

I tried to draw inspiration from surrounding documentation, but I suspect this will need a few changes to get right :) All feeback welcome.

Thanks,
Andrew

gdb/ChangeLog

2012-11-02 Andrew Burgess <aburgess@broadcom.com>

* source.c (print_source_lines_base): Add fullname field giving
full path to file in mi output.
* NEWS: Mention the new fullname field.

diff --git a/gdb/NEWS b/gdb/NEWS
index 069b84f..ccc9ba1 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -64,6 +64,9 @@ py [command]
async record "=record-started" and "=record-stopped".
** Memory changes are now notified using new async record
"=memory-changed".
+ ** The data-disassemble command response will include a "fullname" field
+ containing the absolute file name when gdb can determine it and source
+ has been requested.

*** Changes in GDB 7.5

diff --git a/gdb/source.c b/gdb/source.c
index bd11c63..465382e 100644
--- a/gdb/source.c
+++ b/gdb/source.c
@@ -1301,6 +1301,13 @@ print_source_lines_base (struct symtab *s, int line, int stopline, int noerror)
ui_out_field_int (uiout, "line", line);
ui_out_text (uiout, "\tin ");
ui_out_field_string (uiout, "file", s->filename);
+ if (ui_out_is_mi_like_p (uiout))
+ {
+ const char *fullname = symtab_to_fullname (s);
+
+ if (fullname != NULL)
+ ui_out_field_string (uiout, "fullname", fullname);
+ }
ui_out_text (uiout, "\n");
}

gdb/doc/ChangeLog

2012-11-02 Andrew Burgess <aburgess@broadcom.com>

* gdb.texinfo (GDB/MI Data Manipulation): Add fullname field to
the example -data-disassemble output. Extend the description of
the -data-disassemble results to document all fields. Document
the cli disassemble command as being related to -data-disassemble.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 21db475..ebec4e5 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -30717,21 +30717,65 @@ mixed source and disassembly with raw opcodes).

@subsubheading Result

-The output for each instruction is composed of four fields:
+The result of the -data-disassemble command will be a list named
+@samp{asm_insns}, the contents of this list depend on the @var{mode}
+used with the -data-disassemble command.

-@itemize @bullet
-@item Address
-@item Func-name
-@item Offset
-@item Instruction
-@end itemize
+For modes 0 and 2 the @samp{asm_insns} list contains tuples with the
+following fields:

-Note that whatever included in the instruction field, is not manipulated
-directly by @sc{gdb/mi}, i.e., it is not possible to adjust its format.
+@table @code
+@item address
+The address at which this instruction was disassembled.
+
+@item func-name
+The name of the function this instruction is within.
+
+@item offset
+The decimal offset in bytes from the start of @samp{func-name}.
+
+@item inst
+The text disassembly for this @samp{address}.
+
+@item opcodes
+This field is only present for mode 2. This contains the raw opcode
+bytes for the @samp{inst} field.
+
+@end table
+
+For modes 1 and 3 the @samp{asm_insns} list contains tuples names
+@samp{src_and_asm_line}, each of which has the following fields:
+
+@table @code
+@item line
+The line number within @samp{file}.
+
+@item file
+The file name from the compilation unit. This might be an absolute
+file name or a relative file name depending on the compile command
+used.
+
+@item fullname
+This field is optional. If it is present it will contain an absolute
+file name to @samp{file}. If this field is not present then gdb was
+unable to determine the absolute file name.
+
+@item line_asm_insn
+This is a list of tuples containing the disassembly for @samp{line} in
+@samp{file}. The fields of each tuple are the same as for
+-data-disassemble in @var{mode} 0 and 2, so @samp{address},
+@samp{func-name}, @samp{offset}, @samp{inst}, and optionally
+@samp{opcodes}.
+
+@end table
+
+Note that whatever included in the @samp{inst} field, is not
+manipulated directly by @sc{gdb/mi}, i.e., it is not possible to
+adjust its format.

@subsubheading @value{GDBN} Command

-There's no direct mapping from this command to the CLI.
+The corresponding @value{GDBN} command is @samp{disassemble}.

@subsubheading Example

@@ -30795,15 +30839,15 @@ Disassemble 3 instructions from the start of @code{main} in mixed mode:
-data-disassemble -f basics.c -l 32 -n 3 -- 1
^done,asm_insns=[
src_and_asm_line=@{line="31",
-file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
- testsuite/gdb.mi/basics.c",line_asm_insn=[
-@{address="0x000107bc",func-name="main",offset="0",
-inst="save %sp, -112, %sp"@}]@},
+file="../../../src/gdb/testsuite/gdb.mi/basics.c",
+fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
+line_asm_insn=[@{address="0x000107bc",
+func-name="main",offset="0",inst="save %sp, -112, %sp"@}]@},
src_and_asm_line=@{line="32",
-file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \
- testsuite/gdb.mi/basics.c",line_asm_insn=[
-@{address="0x000107c0",func-name="main",offset="4",
-inst="mov 2, %o0"@},
+file="../../../src/gdb/testsuite/gdb.mi/basics.c",
+fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c",
+line_asm_insn=[@{address="0x000107c0",
+func-name="main",offset="4",inst="mov 2, %o0"@},
@{address="0x000107c4",func-name="main",offset="8",
inst="sethi %hi(0x11800), %o2"@}]@}]
(gdb)

gdb/testsuite/ChangeLog

2012-11-02 Andrew Burgess <aburgess@broadcom.com>

* gdb.mi/mi-disassemble.exp: Expect fullname field in mi
disassembly output.

diff --git a/gdb/testsuite/gdb.mi/mi-disassemble.exp b/gdb/testsuite/gdb.mi/mi-disassemble.exp
index 377ffde..695521a 100644
--- a/gdb/testsuite/gdb.mi/mi-disassemble.exp
+++ b/gdb/testsuite/gdb.mi/mi-disassemble.exp
@@ -115,6 +115,7 @@ proc test_disassembly_mixed {} {
global mi_gdb_prompt
global hex
global decimal
+ global fullname_syntax

set line_callee2_head [gdb_get_line_number "callee2 ("]
set line_callee2_open_brace [expr $line_callee2_head + 1]
@@ -125,7 +126,7 @@ proc test_disassembly_mixed {} {
# -data-disassembly -s $pc -e "$pc+8" -- 1

mi_gdb_test "002-data-disassemble -f basics.c -l $line_callee2_open_brace -- 1" \
- "002\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$line_callee2_open_brace\",file=\".*basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"callee2\",offset=\"0\",inst=\".*\"\}.*\\\]\}.*,src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",line_asm_insn=\\\[.*\{address=\"$hex\",func-name=\"callee2\",offset=\"$decimal\",inst=\".*\"\}\\\]\}\\\]" \
+ "002\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$line_callee2_open_brace\",file=\".*basics.c\",fullname=\"${fullname_syntax}basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"callee2\",offset=\"0\",inst=\".*\"\}.*\\\]\}.*,src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",fullname=\"${fullname_syntax}basics.c\",line_asm_insn=\\\[.*\{address=\"$hex\",func-name=\"callee2\",offset=\"$decimal\",inst=\".*\"\}\\\]\}\\\]" \
"data-disassemble file, line assembly mixed"

#
@@ -134,7 +135,7 @@ proc test_disassembly_mixed {} {
# which we are now, even if we have specified that the range is only 2 insns.
#
mi_gdb_test "003-data-disassemble -s \$pc -e \"\$pc+4\" -- 1" \
- "003\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",inst=\".*\"\}.*\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",inst=\".*\"\}\\\]\}\\\]" \
+ "003\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",fullname=\"${fullname_syntax}basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",inst=\".*\"\}.*\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",inst=\".*\"\}\\\]\}\\\]" \
"data-disassemble range assembly mixed"
}

@@ -142,6 +143,7 @@ proc test_disassembly_mixed_with_opcodes {} {
global mi_gdb_prompt
global hex
global decimal
+ global fullname_syntax

set line_callee2_head [gdb_get_line_number "callee2 ("]
set line_callee2_open_brace [expr $line_callee2_head + 1]
@@ -152,7 +154,7 @@ proc test_disassembly_mixed_with_opcodes {} {
# -data-disassembly -s $pc -e "$pc+8" -- 3

mi_gdb_test "002-data-disassemble -f basics.c -l $line_callee2_open_brace -- 3" \
- "002\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$line_callee2_open_brace\",file=\".*basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"callee2\",offset=\"0\",opcodes=\".*\",inst=\".*\"\}.*\\\]\}.*,src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",line_asm_insn=\\\[.*\{address=\"$hex\",func-name=\"callee2\",offset=\"$decimal\",opcodes=\".*\",inst=\".*\"\}\\\]\}\\\]" \
+ "002\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$line_callee2_open_brace\",file=\".*basics.c\",fullname=\"${fullname_syntax}basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"callee2\",offset=\"0\",opcodes=\".*\",inst=\".*\"\}.*\\\]\}.*,src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",fullname=\"${fullname_syntax}basics.c\",line_asm_insn=\\\[.*\{address=\"$hex\",func-name=\"callee2\",offset=\"$decimal\",opcodes=\".*\",inst=\".*\"\}\\\]\}\\\]" \
"data-disassemble file, line assembly mixed with opcodes"

#
@@ -161,7 +163,7 @@ proc test_disassembly_mixed_with_opcodes {} {
# which we are now, even if we have specified that the range is only 2 insns.
#
mi_gdb_test "003-data-disassemble -s \$pc -e \"\$pc+4\" -- 3" \
- "003\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",opcodes=\".*\",inst=\".*\"\}.*\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",opcodes=\".*\",inst=\".*\"\}\\\]\}\\\]" \
+ "003\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",fullname=\"${fullname_syntax}basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",opcodes=\".*\",inst=\".*\"\}.*\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",opcodes=\".*\",inst=\".*\"\}\\\]\}\\\]" \
"data-disassemble range assembly mixed with opcodes"
}

@@ -169,6 +171,7 @@ proc test_disassembly_mixed_lines_limit {} {
global mi_gdb_prompt
global hex
global decimal
+ global fullname_syntax

set line_main_head [gdb_get_line_number "main ("]
set line_main_open_brace [expr $line_main_head + 1]
@@ -182,15 +185,15 @@ proc test_disassembly_mixed_lines_limit {} {

mi_gdb_test "print/x \$pc" "" ""
mi_gdb_test "222-data-disassemble -f basics.c -l $line_main_body -n 20 -- 1" \
- "222\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"main\",offset=\"0\",inst=\".*\"\},.*,\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",inst=\".*\"\}\\\]\}\]" \
+ "222\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",fullname=\"${fullname_syntax}basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"main\",offset=\"0\",inst=\".*\"\},.*,\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",inst=\".*\"\}\\\]\}\]" \
"data-disassemble file, line, number assembly mixed"

mi_gdb_test "222-data-disassemble -f basics.c -l $line_main_body -n 0 -- 1" \
- "222\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$line_main_open_brace\",file=\".*basics.c\",line_asm_insn=\\\[\\\]\}\\\]" \
+ "222\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$line_main_open_brace\",file=\".*basics.c\",fullname=\"${fullname_syntax}basics.c\",line_asm_insn=\\\[\\\]\}\\\]" \
"data-disassemble file, line, number (zero lines) assembly mixed"

mi_gdb_test "222-data-disassemble -f basics.c -l $line_main_body -n 50 -- 1" \
- "222\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"main\",offset=\"0\",inst=\".*\"\}.*,\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",inst=\".*\"\}\\\]\}\]" \
+ "222\\^done,asm_insns=\\\[src_and_asm_line=\{line=\"$decimal\",file=\".*basics.c\",fullname=\"${fullname_syntax}basics.c\",line_asm_insn=\\\[\{address=\"$hex\",func-name=\"main\",offset=\"0\",inst=\".*\"\}.*,\{address=\"$hex\",func-name=\"main\",offset=\"$decimal\",inst=\".*\"\}\\\]\}\]" \
"data-disassemble file, line, number (more than main lines) assembly mixed"
}