document new shift operations

1 files changed, 15 insertions, 0 deletions

diff --git a/doc/il.txt b/doc/il.txt
index 9896672..964c864 100644
--- a/doc/il.txt
+++ b/doc/il.txt
@@ -491,6 +491,7 @@ return type used is long, the argument must be of type double.
   * `add`, `sub`, `div`, `mul` -- `T(T,T)`
   * `udiv`, `rem`, `urem` -- `I(I,I)`
   * `or`, `xor`, `and` -- `I(I,I)`
+  * `sar`, `shr`, `shl` -- `I(I,ww)`
 
 The base arithmetic instructions in the first bullet are
 available for all types, integers and floating points.
@@ -512,6 +513,20 @@ integer types.  Logical operations of typical programming
 languages can be implemented using <@ Comparisons > and
 <@ Jumps >.
 
+Shift instructions `sar`, `shr`, and `shl` shift right or
+left their first operand by the amount in the second
+operand.  The shifting amount is taken modulo the size of
+the result type.  Shifting right can either preserve the
+sign of the value (using `sar`), or fill the newly freed
+bits with zeroes (using `shr`).  Shifting left always
+fills the freed bits with zeroes.
+
+Remark that an arithmetic shift right (`sar`) is only
+equivalent to a division by a power of two for non-negative
+numbers.  This is because the shift right "truncates"
+towards minus infinity, while the division truncates
+towards zero.
+
 ~ Memory
 ~~~~~~~~