Print registers not saved in the frame as "<not saved>" instead of "<optimized out>".

[deliverable/binutils-gdb.git] / gdb / doc / gdb.texinfo

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 07d5068797d49067f1a30a4c1f2efdcd512cd8a4..cf6f7d30a88b3acabf0562aa78b21d3390d9b79c 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -10031,10 +10031,33 @@ were exited and their saved registers restored.  In order to see the
 true contents of hardware registers, you must select the innermost
 frame (with @samp{frame 0}).
 
-However, @value{GDBN} must deduce where registers are saved, from the machine
-code generated by your compiler.  If some registers are not saved, or if
-@value{GDBN} is unable to locate the saved registers, the selected stack
-frame makes no difference.
+@cindex caller-saved registers
+@cindex call-clobbered registers
+@cindex volatile registers
+@cindex <not saved> values
+Usually ABIs reserve some registers as not needed to be saved by the
+callee (a.k.a.: ``caller-saved'', ``call-clobbered'' or ``volatile''
+registers).  It may therefore not be possible for @value{GDBN} to know
+the value a register had before the call (in other words, in the outer
+frame), if the register value has since been changed by the callee.
+@value{GDBN} tries to deduce where the inner frame saved
+(``callee-saved'') registers, from the debug info, unwind info, or the
+machine code generated by your compiler.  If some register is not
+saved, and @value{GDBN} knows the register is ``caller-saved'' (via
+its own knowledge of the ABI, or because the debug/unwind info
+explicitly says the register's value is undefined), @value{GDBN}
+displays @w{@samp{<not saved>}} as the register's value.  With targets
+that @value{GDBN} has no knowledge of the register saving convention,
+if a register was not saved by the callee, then its value and location
+in the outer frame are assumed to be the same of the inner frame.
+This is usually harmless, because if the register is call-clobbered,
+the caller either does not care what is in the register after the
+call, or has code to restore the value that it does care about.  Note,
+however, that if you change such a register in the outer frame, you
+may also be affecting the inner frame.  Also, the more ``outer'' the
+frame is you're looking at, the more likely a call-clobbered
+register's value is to be wrong, in the sense that it doesn't actually
+represent the value the register had just before the call.
 
 @node Floating Point Hardware
 @section Floating Point Hardware