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

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

[Pedro Alves]

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

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

[Eli Zaretskii]

> From: Pedro Alves <pedro@codesourcery.com>
> Date: Thu, 23 Dec 2010 19:13:08 +0000
> 
> 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?

Yes, thanks.

> +literal @samp{x}'s in place of the register data digits, to indicate
> +the corresponding register has not been collected, thus its value is

"... to indicate that the corresponding register ..."

> +registers 0 and 2 have not been collected, while registers 1 and 3
> +have been collected, and have value zero each:
                        ^^^^^^^^^^^^^^^^^^^^^^^^
"and both have zero value"

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

[Pedro Alves]

On Thursday 23 December 2010 19:50:35, Eli Zaretskii wrote:
> > From: Pedro Alves <pedro@codesourcery.com>
> > Okay to apply?
> 
> Yes, thanks.
> 
> > +literal @samp{x}'s in place of the register data digits, to indicate
> > +the corresponding register has not been collected, thus its value is
> 
> "... to indicate that the corresponding register ..."
> 
> > +registers 0 and 2 have not been collected, while registers 1 and 3
> > +have been collected, and have value zero each:
>                         ^^^^^^^^^^^^^^^^^^^^^^^^
> "and both have zero value"
> 

Thanks!  Applied, as below.

-- 
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-23 20:22:59.000000000 +0000
+++ src/gdb/doc/gdb.texinfo	2010-12-23 20:26:07.000000000 +0000
@@ -31815,6 +31815,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
+that 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 both have zero value:
+
+@smallexample
+-> @code{g}
+<- @code{xxxxxxxx00000000xxxxxxxx00000000}
+@end smallexample
+
 @item E @var{NN}
 for an error.
 @end table