[docs] tfind range/outside inclusive- exclusiveness

[Pedro Alves <pedro at codesourcery dot com>]

While implementing tracepoint support in our stubs, we found
it most useful if "tfind range" and "tfind outside" return
complementary and non-overlapping sets.  The documentation
sources wonder about this, and I suspect that whoever wrote
that considered that actual usage in the field would help
clarify the best behaviour.  We've had such experience now,
and we've actually had a customer complain about this.  :-)

So the patch documents (manual and online help) the
inclusive- exclusiveness of the ranges in the commands
and packets, and makes the QTFrame:range docu specify
inclusive.

Is this patch OK?  FWIW, the customer was happy.  :-)

There's confusion in the sources as well related to this.

trace_find_line_command does:

(...)
  /* Find within range of stated line.  */
  if (args && *args)
    tfind_1 (tfind_range, 0, start_pc, end_pc - 1, from_tty);
  else
    tfind_1 (tfind_outside, 0, start_pc, end_pc - 1, from_tty);
  do_cleanups (old_chain);
}

here, end_pc is the address of the start of the next line (from
find_line_pc_range), so it looks like it was already expected here
that tfind_range should be inclusive on both ends, and tfind_outsize
exclusive.  Had tfind_range been exclusive on the end range, it seems
like "tfind line LINENO" would miss a trace frame at the last
address of line LINENO.  So, it seems that this documentation patch
actually fixes a code bug.  :-)

-- 
Pedro Alves

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

	gdb/doc/
	* gdb.texinfo (Using the Collected Data): Specify that the address
	range of `tfind outsize' is exclusive, and that the address range
	of `tfind range' is inclusive.
	(Tracepoint Packets): Specify that the address range of `QTFrame:range' is
	inclusive, and that the address range of `QTFrame:outside' is exclusive

	gdb/
	* tracepoint.c (_initialize_tracepoint): Specify that the address
	range of `tfind outsize' is exclusive, and that the address range
	of `tfind range' is inclusive, in the commands' help strings.

---
 gdb/doc/gdb.texinfo |    8 ++++----
 gdb/tracepoint.c    |    4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

Index: src/gdb/doc/gdb.texinfo
===================================================================
--- src.orig/gdb/doc/gdb.texinfo	2010-02-12 15:02:33.000000000 +0000
+++ src/gdb/doc/gdb.texinfo	2010-02-12 15:02:36.000000000 +0000
@@ -9900,11 +9900,11 @@ snapshot with the same value of PC as th
 
 @item tfind outside @var{addr1}, @var{addr2}
 Find the next snapshot whose PC is outside the given range of
-addresses.
+addresses (exclusive).
 
 @item tfind range @var{addr1}, @var{addr2}
 Find the next snapshot whose PC is between @var{addr1} and
-@var{addr2}.  @c FIXME: Is the range inclusive or exclusive?
+@var{addr2} (inclusive).
 
 @item tfind line @r{[}@var{file}:@r{]}@var{n}
 Find the next snapshot associated with the source line @var{n}.  If
@@ -30546,12 +30546,12 @@ is a hexadecimal number.
 @item QTFrame:range:@var{start}:@var{end}
 Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the
 currently selected frame whose PC is between @var{start} (inclusive)
-and @var{end} (exclusive); @var{start} and @var{end} are hexadecimal
+and @var{end} (inclusive); @var{start} and @var{end} are hexadecimal
 numbers.
 
 @item QTFrame:outside:@var{start}:@var{end}
 Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first
-frame @emph{outside} the given range of addresses.
+frame @emph{outside} the given range of addresses (exclusive).
 
 @item QTStart
 Begin the tracepoint experiment.  Begin collecting data from tracepoint
Index: src/gdb/tracepoint.c
===================================================================
--- src.orig/gdb/tracepoint.c	2010-02-12 15:02:33.000000000 +0000
+++ src/gdb/tracepoint.c	2010-02-12 15:02:36.000000000 +0000
@@ -3610,12 +3610,12 @@ No argument means forward by one frame; 
 		  &tfindlist, "tfind ", 1, &cmdlist);
 
   add_cmd ("outside", class_trace, trace_find_outside_command, _("\
-Select a trace frame whose PC is outside the given range.\n\
+Select a trace frame whose PC is outside the given range (exclusive).\n\
 Usage: tfind outside addr1, addr2"),
 	   &tfindlist);
 
   add_cmd ("range", class_trace, trace_find_range_command, _("\
-Select a trace frame whose PC is in the given range.\n\
+Select a trace frame whose PC is in the given range (inclusive).\n\
 Usage: tfind range addr1,addr2"),
 	   &tfindlist);