[binutils-gdb] Fix documentation about rot agent expression bytecode

[Simon Marchi <simark at sourceware dot org>]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=791fb3d7a58b86e5f30229625dfd33659f33fd6e

commit 791fb3d7a58b86e5f30229625dfd33659f33fd6e
Author: Simon Marchi <simon.marchi@ericsson.com>
Date:   Mon Jul 31 11:22:21 2017 +0200

    Fix documentation about rot agent expression bytecode
    
    The rot agent expression bytecode rotates the three items on the top of
    the stack.  It is not clear which way the rotation is.  However, the
    documentation currently shows this as the effect of the instructions:
    
       a b c => c b a
    
    which doesn't make sense, since the value b doesn't move.  The two
    valid possibilities I see are
    
      a b c => b c a
      a b c => c a b
    
    depending on which way you rotate.
    
    When looking at the gdbserver code, the top of the stack becomes the
    third item, and the next-to-top item becomes the top.  So the second
    form would be the right one, since in this notation the top of the stack
    is the rightmost element:
    
      a b c => c a b
    
    I adjusted the symbolic description and added a bit of text to make it
    more obvious.
    
    gdb/doc/ChangeLog:
    
    	* agentexpr.texi (rot): Fix symbolic description, improve
    	textual description.

Diff:
---
 gdb/doc/ChangeLog      | 5 +++++
 gdb/doc/agentexpr.texi | 6 ++++--
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index d43ae35..6a3d061 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2017-07-31  Simon Marchi  <simon.marchi@ericsson.com>
+
+	* agentexpr.texi (rot): Fix symbolic description, improve
+	textual description.
+
 2017-07-26  Yao Qi  <yao.qi@linaro.org>
 
 	* gdb.texinfo (Maintenance Commands): Document command
diff --git a/gdb/doc/agentexpr.texi b/gdb/doc/agentexpr.texi
index 5668e9c..081e5fa 100644
--- a/gdb/doc/agentexpr.texi
+++ b/gdb/doc/agentexpr.texi
@@ -396,8 +396,10 @@ is zero, this is the same as @code{dup}; if @var{n} is one, it copies
 the item under the top item, etc.  If @var{n} exceeds the number of
 items on the stack, terminate with an error.
 
-@item @code{rot} (0x33): @var{a} @var{b} @var{c} => @var{c} @var{b} @var{a}
-Rotate the top three items on the stack.
+@item @code{rot} (0x33): @var{a} @var{b} @var{c} => @var{c} @var{a} @var{b}
+Rotate the top three items on the stack.  The top item (c) becomes the third
+item, the next-to-top item (b) becomes the top item and the third item (a) from
+the top becomes the next-to-top item.
 
 @item @code{if_goto} (0x20) @var{offset}: @var{a} @result{}
 Pop an integer off the stack; if it is non-zero, branch to the given