[doc] Remote protocol: undocumented return value for 'p' and 'g'

[Pedro Alves <pedro at codesourcery dot com>]

Ref: <http://sourceware.org/ml/gdb/2010-12/msg00050.html>

The feature this documents was added back here:

Thu Oct 29 10:04:20 1998  Michael Snyder  <msnyder@cleaver.cygnus.com>

        [Support for trace debugging: registers that were not collected.]
        * remote.c (remote_fetch_registers): accept 'xxxx' in the register
        packet, with the meaning "register value is not available".
        Set register_valid to -1, which will connote "no value available".
        * findvar.c (read_relative_register_raw_bytes): return failure if
        register_valid == -1.  (value_of_register): return failure if 
        register_valid == -1.  (read_var_value): return error if 
        value_of_register fails for a register variable.
        (value_from_register): return failure if register_valid == -1.
        * eval.c (evaluate_subexp_standard): return error if 
        value_of_register fails for a register used in an expression.
        * infcmd.c (do_registers_info): display "value not available"
        for registers for which register_valid == -1.

        * tracepoint.c (set_raw_tracepoint): just save the filename as is
        from the symbol table, rather than trying to prepend the dir name.
        Also save the bfd section.  (tracepoints_info): use the section
        when looking up the function name.
        * tracepoint.h: add section field to tracepoint struct.

It's intended usage is in the context of inspecting tracepoints, to
report "the register exists, but I don't know its value, because I
haven't collected it."

(We actually have a local series of 60 or so (and counting)
trace debugging related patches that actually make use of
this mechanism).

Okay to apply?

-- 
Pedro Alves

2010-12-23  Pedro Alves  <pedro@codesourcery.com>

	gdb/doc/
	* gdb.texinfo (Packets) <read registers packet>: Document support
	for registers that were not collected.

---
 gdb/doc/gdb.texinfo |   15 +++++++++++++++
 1 file changed, 15 insertions(+)

Index: src/gdb/doc/gdb.texinfo
===================================================================
--- src.orig/gdb/doc/gdb.texinfo	2010-12-13 16:31:07.000000000 +0000
+++ src/gdb/doc/gdb.texinfo	2010-12-23 18:43:29.000000000 +0000
@@ -31796,6 +31796,21 @@ each register and their position within 
 determined by the @value{GDBN} internal gdbarch functions
 @code{DEPRECATED_REGISTER_RAW_SIZE} and @code{gdbarch_register_name}.  The
 specification of several standard @samp{g} packets is specified below.
+
+When reading registers from a trace frame (@pxref{Analyze Collected
+Data,,Using the Collected Data}), the stub may also return a string of
+literal @samp{x}'s in place of the register data digits, to indicate
+the corresponding register has not been collected, thus its value is
+unavailable.  For example, for an architecture with 4 registers of 4
+bytes each, the following reply indicates to @value{GDBN} that
+registers 0 and 2 have not been collected, while registers 1 and 3
+have been collected, and have value zero each:
+
+@smallexample
+-> @code{g}
+<- @code{xxxxxxxx00000000xxxxxxxx00000000}
+@end smallexample
+
 @item E @var{NN}
 for an error.
 @end table