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 --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d8f7413dc483ea81c9e56f19c51d5357fc721db7..263326d54e7c8e90f2ef7751b345ce8e1bcd26ab 100644 (file)
--- 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