[rfa] Clarify remote protocol RLE example

[rfa] Clarify remote protocol RLE example

[Daniel Jacobowitz]

Uwe pointed out that the example in the GDB manual for run-length
encoding is a bit confusing.  It suggests that "0* " should expand
to 000, but in fact it expands to 0000, because the initial zero
is counted separately.

Is this version clearer?  OK to commit?

-- 
Daniel Jacobowitz
CodeSourcery

2007-11-03  Daniel Jacobowitz  <dan@codesourcery.com>

	* gdb.texinfo (Overview): Clarify run-length encoding
	example.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.441
diff -u -p -U5 -r1.441 gdb.texinfo
--- gdb.texinfo	30 Oct 2007 19:35:35 -0000	1.441
+++ gdb.texinfo	3 Nov 2007 16:09:21 -0000
@@ -22937,22 +22937,24 @@ must also escape @code{0x2a} (@sc{ascii}
 is not interpreted as the start of a run-length encoded sequence
 (described next).
 
 Response @var{data} can be run-length encoded to save space.  A @samp{*}
 means that the next character is an @sc{ascii} encoding giving a repeat count
-which stands for that many repetitions of the character preceding the
+which stands for that many additional repetitions of the character preceding the
 @samp{*}.  The encoding is @code{n+29}, yielding a printable character
 where @code{n >=3} (which is where rle starts to win).  The printable
 characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
 value greater than 126 should not be used.
 
 So:
 @smallexample
 "@code{0* }"
 @end smallexample
 @noindent
-means the same as "0000".
+means the same as "0000".  The initial @code{0} contributes one zero,
+and the space (@sc{ascii} 32) contributes a repeat count of three
+additional zeros.
 
 The error response returned for some packets includes a two character
 error number.  That number is not well defined.
 
 @cindex empty response, for unsupported packets

Re: [rfa] Clarify remote protocol RLE example

[Eli Zaretskii]

> Date: Sat, 3 Nov 2007 12:19:56 -0400
> From: Daniel Jacobowitz <drow@false.org>
> Cc: Eli Zaretskii <eliz@gnu.org>, ukleinek@informatik.uni-freiburg.de
> 
> Uwe pointed out that the example in the GDB manual for run-length
> encoding is a bit confusing.  It suggests that "0* " should expand
> to 000, but in fact it expands to 0000, because the initial zero
> is counted separately.
> 
> Is this version clearer?  OK to commit?

Well, I still needed to read the text 2 or 3 times before I understood
what it tries to say.

How about this version instead:

 Response @var{data} can be run-length encoded to save space.
 Run-length encoding replaces runs of identical characters 

>  Response @var{data} can be run-length encoded to save space.  A @samp{*}
>  means that the next character is an @sc{ascii} encoding giving a repeat count
> -which stands for that many repetitions of the character preceding the
> +which stands for that many additional repetitions of the character preceding the
>  @samp{*}.  The encoding is @code{n+29}, yielding a printable character
>  where @code{n >=3} (which is where rle starts to win).  The printable
>  characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
>  value greater than 126 should not be used.
>  
>  So:
>  @smallexample
>  "@code{0* }"
>  @end smallexample
>  @noindent
> -means the same as "0000".
> +means the same as "0000".  The initial @code{0} contributes one zero,
> +and the space (@sc{ascii} 32) contributes a repeat count of three
> +additional zeros.
>  
>  The error response returned for some packets includes a two character
>  error number.  That number is not well defined.
>  
>  @cindex empty response, for unsupported packets
> 

Re: [rfa] Clarify remote protocol RLE example

[Eli Zaretskii]

> Date: Sat, 3 Nov 2007 12:19:56 -0400
> From: Daniel Jacobowitz <drow@false.org>
> Cc: Eli Zaretskii <eliz@gnu.org>, ukleinek@informatik.uni-freiburg.de

Sorry for the previous unfinished message: hit SEND by mistake.

> Uwe pointed out that the example in the GDB manual for run-length
> encoding is a bit confusing.  It suggests that "0* " should expand
> to 000, but in fact it expands to 0000, because the initial zero
> is counted separately.
> 
> Is this version clearer?  OK to commit?

Well, I still needed to read the text 2 or 3 times before I understood
what it tries to say.

How about this version instead:

 Response @var{data} can be run-length encoded to save space.
 Run-length encoding replaces runs of identical characters with the
 character @samp{*} followed by a repeat count.  The repeat count is
 itself sent encoded, to avoid binary characters in @var{data}: a
 value of @var{n} is sent as @code{@var{n}+29}.  For a repeat count
 greater or equal to 3, this produces a printable @sc{ascii}
 character, e.g.@: a space (@sc{ascii} code 32) for a repeat count of
 3.  (This is because run-length encoding starts to win for counts 3
 or more.)  Thus, for example, @samp{0* } is a run-length encoding of
 "0000": the space character after @samp{*} means repeat the leading
 @code{0} @w{@code{32 - 29 = 3}} more times.

>  The printable
>  characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
>  value greater than 126 should not be used.

This part I simply don't understand.  What does it mean ``should not
be used''? what should be done instead? break the string into several
smaller ones?

Re: [rfa] Clarify remote protocol RLE example

[Daniel Jacobowitz]

On Sat, Nov 03, 2007 at 09:01:21PM +0200, Eli Zaretskii wrote:
>  Response @var{data} can be run-length encoded to save space.
>  Run-length encoding replaces runs of identical characters with the
>  character @samp{*} followed by a repeat count.

How about "with an initial character, the character @samp{*}, and a
repeat count"?  With that, I quite like your version.

> >  The printable
> >  characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
> >  value greater than 126 should not be used.
> 
> This part I simply don't understand.  What does it mean ``should not
> be used''? what should be done instead? break the string into several
> smaller ones?

May not be used (they have special syntactical meaning in the
protocol).  So you need to stop the RLE string one character earlier,
e.g.:

  {0}		0
  {00}		00
  {000}		000
  {0* }		0000
  {0*!}		00000
  {0*"}		000000
  {0*"0}	0000000
  {0*"00}	00000000
  {0*%}		000000000

Rereading this, and looking at my notes in gdbserver, I don't think
there is any point to the restriction on + or -.  They're the protocol
ack and nack characters, but they can already appear elsewhere in
responses.  Jim, do you see any reason they should be forbidden?

-- 
Daniel Jacobowitz
CodeSourcery

Re: [rfa] Clarify remote protocol RLE example

[Eli Zaretskii]

> Date: Sat, 3 Nov 2007 15:18:22 -0400
> From: Daniel Jacobowitz <drow@false.org>
> Cc: gdb-patches@sourceware.org, ukleinek@informatik.uni-freiburg.de,
> 	Jim Blandy <jimb@codesourcery.com>
> 
> On Sat, Nov 03, 2007 at 09:01:21PM +0200, Eli Zaretskii wrote:
> >  Response @var{data} can be run-length encoded to save space.
> >  Run-length encoding replaces runs of identical characters with the
> >  character @samp{*} followed by a repeat count.
> 
> How about "with an initial character, the character @samp{*}, and a
> repeat count"?  With that, I quite like your version.

How about

 Run-length encoding replaces runs of identical characters with a
 @samp{*} followed by a repeat count.

?

> > This part I simply don't understand.  What does it mean ``should not
> > be used''? what should be done instead? break the string into several
> > smaller ones?
> 
> May not be used (they have special syntactical meaning in the
> protocol).  So you need to stop the RLE string one character earlier,

It strikes me that it would be easier and more clear to say that runs
of 7 and 8 characters should be sent as 6+1 and 6+2, respectively.

Re: [rfa] Clarify remote protocol RLE example

[Eli Zaretskii]

> Date: Sun, 04 Nov 2007 00:06:58 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> CC: gdb-patches@sourceware.org, ukleinek@informatik.uni-freiburg.de,         jimb@codesourcery.com
> 
> > Date: Sat, 3 Nov 2007 15:18:22 -0400
> > From: Daniel Jacobowitz <drow@false.org>
> > Cc: gdb-patches@sourceware.org, ukleinek@informatik.uni-freiburg.de,
> > 	Jim Blandy <jimb@codesourcery.com>
> > 
> > On Sat, Nov 03, 2007 at 09:01:21PM +0200, Eli Zaretskii wrote:
> > >  Response @var{data} can be run-length encoded to save space.
> > >  Run-length encoding replaces runs of identical characters with the
> > >  character @samp{*} followed by a repeat count.
> > 
> > How about "with an initial character, the character @samp{*}, and a
> > repeat count"?  With that, I quite like your version.
> 
> How about
> 
>  Run-length encoding replaces runs of identical characters with a
>  @samp{*} followed by a repeat count.
> 
> ?

Sorry, I now realize that I misunderstood the reason why you used the
"initial character".  You meant the repeated character itself, right?

Then how about this variant:

  Run-length encoding replaces runs of identical characters with one
  instance of the repeated character, followed by a @samp{*} and a
  repeat count.

Re: [rfa] Clarify remote protocol RLE example

[Daniel Jacobowitz]

On Sun, Nov 04, 2007 at 06:02:44AM +0200, Eli Zaretskii wrote:
> Sorry, I now realize that I misunderstood the reason why you used the
> "initial character".  You meant the repeated character itself, right?
> 
> Then how about this variant:
> 
>   Run-length encoding replaces runs of identical characters with one
>   instance of the repeated character, followed by a @samp{*} and a
>   repeat count.

When I put everything together, I came up with the attached patch.  Is
this clearer?

-- 
Daniel Jacobowitz
CodeSourcery

2007-12-16  Daniel Jacobowitz  <dan@codesourcery.com>

	* gdb.texinfo (Overview): Clarify run-length encoding
	example.  Remove the restriction on "+" and "-" characters.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.449
diff -u -p -r1.449 gdb.texinfo
--- gdb.texinfo	15 Dec 2007 13:13:12 -0000	1.449
+++ gdb.texinfo	16 Dec 2007 20:28:44 -0000
@@ -23158,20 +23158,24 @@ must also escape @code{0x2a} (@sc{ascii}
 is not interpreted as the start of a run-length encoded sequence
 (described next).
 
-Response @var{data} can be run-length encoded to save space.  A @samp{*}
-means that the next character is an @sc{ascii} encoding giving a repeat count
-which stands for that many repetitions of the character preceding the
-@samp{*}.  The encoding is @code{n+29}, yielding a printable character
-where @code{n >=3} (which is where rle starts to win).  The printable
-characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
-value greater than 126 should not be used.
-
-So:
-@smallexample
-"@code{0* }"
-@end smallexample
-@noindent
-means the same as "0000".
+Response @var{data} can be run-length encoded to save space.
+Run-length encoding replaces runs of identical characters with one
+instance of the repeated character, followed by a @samp{*} and a
+repeat count.  The repeat count is itself sent encoded, to avoid
+binary characters in @var{data}: a value of @var{n} is sent as
+@code{@var{n}+29}.  For a repeat count greater or equal to 3, this
+produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii}
+code 32) for a repeat count of 3.  (This is because run-length
+encoding starts to win for counts 3 or more.)  Thus, for example,
+@samp{0* } is a run-length encoding of ``0000'': the space character
+after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 =
+3}} more times.
+
+The printable characters @samp{#} and @samp{$} or with a numeric value
+greater than 126 must not be used.  Runs of six repeats (@samp{#}) or
+seven repeats (@samp{$}) can be expanded using a repeat count of only
+five (@samp{"}).  For example, @samp{00000000} can be encoded as
+@samp{0*"00}.
 
 The error response returned for some packets includes a two character
 error number.  That number is not well defined.

Re: [rfa] Clarify remote protocol RLE example

[Eli Zaretskii]

> Date: Sun, 16 Dec 2007 15:30:35 -0500
> From: Daniel Jacobowitz <drow@false.org>
> Cc: gdb-patches@sourceware.org, ukleinek@informatik.uni-freiburg.de,
> 	jimb@codesourcery.com
> 
> When I put everything together, I came up with the attached patch.  Is
> this clearer?

Yes, thanks.

Re: [rfa] Clarify remote protocol RLE example

[Daniel Jacobowitz]

On Mon, Dec 17, 2007 at 12:48:20AM +0200, Eli Zaretskii wrote:
> > When I put everything together, I came up with the attached patch.  Is
> > this clearer?
> 
> Yes, thanks.

Thanks again for your help!  I checked in this version.

-- 
Daniel Jacobowitz
CodeSourcery

Re: [rfa] Clarify remote protocol RLE example

[Jim Blandy]

Daniel Jacobowitz <drow at false.org> writes:
> On Sat, Nov 03, 2007 at 09:01:21PM +0200, Eli Zaretskii wrote:
>>  Response @var{data} can be run-length encoded to save space.
>>  Run-length encoding replaces runs of identical characters with the
>>  character @samp{*} followed by a repeat count.
>
> How about "with an initial character, the character @samp{*}, and a
> repeat count"?  With that, I quite like your version.
>
>> >  The printable
>> >  characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
>> >  value greater than 126 should not be used.
>> 
>> This part I simply don't understand.  What does it mean ``should not
>> be used''? what should be done instead? break the string into several
>> smaller ones?
>
> May not be used (they have special syntactical meaning in the
> protocol).  So you need to stop the RLE string one character earlier,
> e.g.:
>
>   {0}		0
>   {00}		00
>   {000}		000
>   {0* }		0000
>   {0*!}		00000
>   {0*"}		000000
>   {0*"0}	0000000
>   {0*"00}	00000000
>   {0*%}		000000000
>
> Rereading this, and looking at my notes in gdbserver, I don't think
> there is any point to the restriction on + or -.  They're the protocol
> ack and nack characters, but they can already appear elsewhere in
> responses.  Jim, do you see any reason they should be forbidden?

You're obviously right that the question is, "Should + and - be
permitted in packet bodies at all", not "are they permissible RLE
length characters".

If GDB sends a packet, and the stub sends an ACK and then a packet
that contains a +, but the ACK is garbled or dropped, GDB will skip
characters until it sees the + and then take that as the ACK.  Then
GDB will wait for the response which the stub has already sent, time
out, and retransmit the request.

However, if the packet doesn't contain a +, the consequence of the
missed ACK is a timeout anyway.

If GDB mistakes a packet body character for a NACK, it could
retransmit a request that the stub has carried out.  But we already
know that the protocol has no protection against retransmission, so
this is not a new bug.

So I don't think it makes any difference whether packets contain
ACK/NACK characters.

(I hereby express my resolution never to design a protocol that sends
acknowledgements outside checksummed frames.)

Re: [rfa] Clarify remote protocol RLE example

[Michael Snyder]

On Tue, 2007-11-06 at 10:30 -0800, Jim Blandy wrote:

> (I hereby express my resolution never to design a protocol that sends
> acknowledgements outside checksummed frames.)

/me wonders if there is a Dummies book for protocol design...