[Guile-commits] 352/437: Update documentation

[Andy Wingo]

wingo pushed a commit to branch lightning
in repository guile.

commit 3695a2e99cf8490d47f601fd146164a29d913015
Author: pcpa <address@hidden>
Date:   Sat Jan 17 13:09:08 2015 -0200

    Update documentation
    
        * doc/body.texi: Correct wrong/outdated information for
        hton*, pusharg* and ret*, and add missing documentation
        for rsb*, qmul*, qdvi* and putarg*.
---
 ChangeLog     |  6 ++++++
 doc/body.texi | 55 +++++++++++++++++++++++++++++++++++++++++++++----------
 2 files changed, 51 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f78f581..ddcd2d6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2015-01-17 Paulo Andrade <address@hidden>
+
+       * doc/body.texi: Correct wrong/outdated information for
+       hton*, pusharg* and ret*, and add missing documentation
+       for rsb*, qmul*, qdvi* and putarg*.
+
 2015-01-15 Paulo Andrade <address@hidden>
 
        * configure.ac, lib/jit_disasm.c: Rewrite workaround
diff --git a/doc/body.texi b/doc/body.texi
index 28b9424..5a1c4a3 100644
--- a/doc/body.texi
+++ b/doc/body.texi
@@ -224,6 +224,8 @@ subxr                O1 = O2 - (O3 + carry)
 subxi                O1 = O2 - (O3 + carry)
 subcr                O1 = O2 - O3, set carry
 subci                O1 = O2 - O3, set carry
+rsbr         _f  _d  O1 = O3 - O1
+rsbi         _f  _d  O1 = O3 - O1
 mulr         _f  _d  O1 = O2 * O3
 muli         _f  _d  O1 = O2 * O3
 divr     _u  _f  _d  O1 = O2 / O3
@@ -242,6 +244,27 @@ rshr     _u          O1 = O2 >> address@hidden sign bit is 
propagated unless us
 rshi     _u          O1 = O2 >> address@hidden sign bit is propagated unless 
using the @code{_u} modifier.}
 @end example
 
address@hidden Four operand binary ALU operations
+These accept two result registers, and two operands; the last one can
+be an immediate. The first two arguments cannot be the same register.
+
address@hidden stores the low word of the result in @code{O1} and the
+high word in @code{O2}. For unsigned multiplication, @code{O2} zero
+means there was no overflow. For signed multiplication, no overflow
+check is based on sign, and can be detected if @code{O2} is zero or
+minus one.
+
address@hidden stores the quotient in @code{O1} and the remainder in
address@hidden It can be used as quick way to check if a division is
+exact, in which case the remainder is zero.
+
address@hidden
+qmulr    _u       O1 O2 = O3 * O4
+qmuli    _u       O1 O2 = O3 * O4
+qdivr    _u       O1 O2 = O3 / O4
+qdivi    _u       O1 O2 = O3 / O4
address@hidden example
+
 @item Unary ALU operations
 These accept two operands, both of which must be registers.
 @example
@@ -249,7 +272,7 @@ negr         _f  _d  O1 = -O2
 comr                 O1 = ~O2
 @end example
 
-There unary ALU operations are only defined for float operands.
+These unary ALU operations are only defined for float operands.
 @example
 absr         _f  _d  O1 = fabs(O2)
 sqrtr                O1 = sqrt(O2)
@@ -335,9 +358,10 @@ two instructions actually perform the same task, yet they 
are
 assigned to two mnemonics for the sake of convenience and
 completeness.  As usual, the first operand is the destination and
 the second is the source.
+The @code{_ul} variant is only available in 64-bit architectures.
 @example
-htonr    @r{Host-to-network (big endian) order}
-ntohr    @r{Network-to-host order }
+htonr    _us _ui _ul @r{Host-to-network (big endian) order}
+ntohr    _us _ui _ul @r{Network-to-host order }
 @end example
 
 @item Load operations
@@ -375,13 +399,15 @@ that uses the appropriate wordsize call.
 These are:
 @example
 prepare     (not specified)
-pushargr    _c  _uc  _s  _us  _i  _ui  _l  _f  _d
-pushargi    _c  _uc  _s  _us  _i  _ui  _l  _f  _d
+pushargr                                   _f  _d
+pushargi                                   _f  _d
 arg         _c  _uc  _s  _us  _i  _ui  _l  _f  _d
 getarg      _c  _uc  _s  _us  _i  _ui  _l  _f  _d
+putargr                                    _f  _d
+putargi                                    _f  _d
 ret         (not specified)
-retr        _c  _uc  _s  _us  _i  _ui  _l  _f  _d
-reti        _c  _uc  _s  _us  _i  _ui  _l  _f  _d
+retr                                       _f  _d
+reti                                       _f  _d
 retval      _c  _uc  _s  _us  _i  _ui  _l  _f  _d
 epilog      (not specified)
 @end example
@@ -398,11 +424,11 @@ the @code{pushargr} or @code{pushargi} to push the 
arguments @strong{in
 left to right order}; and use @code{finish} or @code{call} (explained below)
 to perform the actual call.
 
address@hidden and @code{getarg} are used by the callee.
address@hidden, @code{getarg} and @code{putarg} are used by the callee.
 @code{arg} is different from other instruction in that it does not
 actually generate any code: instead, it is a function which returns
-a value to be passed to @address@hidden a
-value'' means that @lightning{} code that compile these
+a value to be passed to @code{getarg} or @code{putarg}. @footnote{``Return
+a value'' means that @lightning{} code that compile these
 instructions return a value when expanded.} You should call
 @code{arg} as soon as possible, before any function call or, more
 easily, right after the @code{prolog} instructions
@@ -417,6 +443,15 @@ that generates other code, so they will be treated more
 specifically in @ref{GNU lightning examples, , Generating code at
 run-time}.
 
address@hidden is a mix of @code{getarg} and @code{pusharg} in that
+it accepts as first argument a register or immediate, and as
+second argument a value returned by @code{arg}. It allows changing,
+or restoring an argument to the current function, and is a
+construct required to implement tail call optimization. Note that
+arguments in registers are very cheap, but will be overwritten
+at any moment, including on some operations, for example division,
+that on several ports is implemented as a function call.
+
 Finally, the @code{retval} instruction fetches the return value of a
 called function in a register.  The @code{retval} instruction takes a
 register argument and copies the return value of the previously called