[PATCH] gdb/doc: extend the documentation of the jump command

[PATCH] gdb/doc: extend the documentation of the jump command

[Andrew Burgess]

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(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 940315b2713..781eaf727be 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -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

base-commit: 393946658fe67e95abe41d3de03b36d84563e873
-- 
2.25.4

Re: [PATCH] gdb/doc: extend the documentation of the jump command

[Eli Zaretskii]

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

Re: [PATCH] gdb/doc: extend the documentation of the jump command

[Andrew Burgess]

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