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

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

[Andrew Burgess]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=0d42948f0c822ed3782a45771c8fbc21aa2d6553

commit 0d42948f0c822ed3782a45771c8fbc21aa2d6553
Author: Andrew Burgess <aburgess@redhat.com>
Date:   Mon Apr 24 15:27:27 2023 +0100

    gdb/doc: extend the documentation of the jump command
    
    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
    
    Approved-By: Eli Zaretskii <eliz@gnu.org>

Diff:
---
 gdb/doc/gdb.texinfo | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d8f7413dc48..263326d54e7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -20618,6 +20618,14 @@ makes the next @code{continue} command or stepping command execute at
 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