gdb/doc: extend the documentation of the jump command
Commit Message
This commit addresses PR gdb/7946. While checking for bugs relating
to the jump command I noticed a long standing bug that points out a
deficiency with GDB's documentation of the jump command.
The bug points out that 'jump 0x...' is not always the same as 'set
$pc = 0x...' and then 'continue'. Writing directly to the $pc
register does not update any auxiliary state, e.g. $npc on SPARC,
while using 'jump' does.
It felt like this would be an easy issue to address by adding a
paragraph to the docs, so I took a stab at writing something suitable.
Bug: https://sourceware.org/bugzilla/show_bug.cgi?id=7946
---
gdb/doc/gdb.texinfo | 8 ++++++++
1 file changed, 8 insertions(+)
base-commit: 393946658fe67e95abe41d3de03b36d84563e873
Comments
> Cc: Andrew Burgess <aburgess@redhat.com>
> Date: Mon, 24 Apr 2023 17:15:38 +0100
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>
> This commit addresses PR gdb/7946. While checking for bugs relating
> to the jump command I noticed a long standing bug that points out a
> deficiency with GDB's documentation of the jump command.
>
> The bug points out that 'jump 0x...' is not always the same as 'set
> $pc = 0x...' and then 'continue'. Writing directly to the $pc
> register does not update any auxiliary state, e.g. $npc on SPARC,
> while using 'jump' does.
>
> It felt like this would be an easy issue to address by adding a
> paragraph to the docs, so I took a stab at writing something suitable.
Thanks, this is fine.
Approved-By: Eli Zaretskii <eliz@gnu.org>
Eli Zaretskii <eliz@gnu.org> writes:
>> Cc: Andrew Burgess <aburgess@redhat.com>
>> Date: Mon, 24 Apr 2023 17:15:38 +0100
>> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>>
>> This commit addresses PR gdb/7946. While checking for bugs relating
>> to the jump command I noticed a long standing bug that points out a
>> deficiency with GDB's documentation of the jump command.
>>
>> The bug points out that 'jump 0x...' is not always the same as 'set
>> $pc = 0x...' and then 'continue'. Writing directly to the $pc
>> register does not update any auxiliary state, e.g. $npc on SPARC,
>> while using 'jump' does.
>>
>> It felt like this would be an easy issue to address by adding a
>> paragraph to the docs, so I took a stab at writing something suitable.
>
> Thanks, this is fine.
>
> Approved-By: Eli Zaretskii <eliz@gnu.org>
Pushed.
Thanks,
Andrew
@@ -20617,6 +20617,14 @@
address @code{0x485}, rather than at the address where your program stopped.
@xref{Continuing and Stepping, ,Continuing and Stepping}.
+However, writing directly to @code{$pc} will only change the value of
+the program-counter register, while using @code{jump} will ensure that
+any additional auxiliary state is also updated. For example, on
+SPARC, @code{jump} will update both @code{$pc} and @code{$npc}
+registers prior to resuming execution. When using the approach of
+writing directly to @code{$pc} it is your job to also update the
+@code{$npc} register.
+
The most common occasion to use the @code{jump} command is to back
up---perhaps with more breakpoints set---over a portion of a program
that has already executed, in order to examine its execution in more