Finish updating vm.texi

* doc/ref/compiler.texi (Bytecode): Update macro-assembler instructions,
  and move most of them to the instruction set reference.
* doc/ref/vm.texi (A Virtual Machine for Guile, VM Programs): Minor
  fixes.
(Instruction Set): Update for Guile 3 instruction set.
* libguile/vm-engine.c (vm_engine): Update a few instruction
  docstrings.

doc/ref/compiler.texi

@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  2008-2016
+@c Copyright (C)  2008-2016, 2018
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -1175,15 +1175,15 @@ compile-time from a machine-readable description of the VM.  With a few
 exceptions for certain operand types, each operand of an emit procedure
 corresponds to an operand of the corresponding instruction.
 
-Consider @code{vector-length}, from @pxref{Miscellaneous Instructions}.
+Consider @code{allocate-words}, from @pxref{Memory Access Instructions}.
 It is documented as:
 
-@deftypefn Instruction {} vector-length u12:@var{dst} u12:@var{src}
+@deftypefn Instruction {} allocate-words s12:@var{dst} s12:@var{nwords}
 @end deftypefn
 
 Therefore the emit procedure has the form:
 
-@deffn {Scheme Procedure} emit-vector-length asm dst src
+@deffn {Scheme Procedure} emit-allocate-words asm dst nwords
 @end deffn
 
 All emit procedure take the assembler as their first argument, and
@@ -1191,9 +1191,9 @@ return no useful values.
 
 The argument types depend on the operand types.  @xref{Instruction Set}.
 Most are integers within a restricted range, though labels are generally
-expressed as opaque symbols.
-
-There are a few macro-instructions as well.
+expressed as opaque symbols.  Besides the emitters that correspond to
+instructions, there are a few additional helpers defined in the
+assembler module.
 
 @deffn {Scheme Procedure} emit-label asm label
 Define a label at the current program point.
@@ -1203,15 +1203,11 @@ Define a label at the current program point.
 Associate @var{source} with the current program point.
 @end deffn
 
-@deffn {Scheme Procedure} emit-cache-current-module! asm module scope
-@deffnx {Scheme Procedure} emit-cached-toplevel-box asm dst scope sym bound?
-@deffnx {Scheme Procedure} emit-cached-module-box asm dst module-name sym public? bound?
-Macro-instructions to implement caching of top-level variables.  The
-first takes the current module, in the slot @var{module}, and associates
-it with a cache location identified by @var{scope}.  The second takes a
-@var{scope}, and resolves the variable.  @xref{Top-Level Environment
-Instructions}.  The last does not need a cached module, rather taking
-the module name directly.
+@deffn {Scheme Procedure} emit-cache-ref asm dst key
+@deffnx {Scheme Procedure} emit-cache-set! asm key val
+Macro-instructions to implement compilation-unit caches.  A single cache
+cell corresponding to @var{key} will be allocated for the compilation
+unit.
 @end deffn
 
 @deffn {Scheme Procedure} emit-load-constant asm dst constant
@@ -1237,17 +1233,6 @@ variables -- procedures that are not closures.
 Delimit a clause of a procedure.
 @end deffn
 
-@deffn {Scheme Procedure} emit-br-if-symbol asm slot invert? label
-@deffnx {Scheme Procedure} emit-br-if-variable asm slot invert? label
-@deffnx {Scheme Procedure} emit-br-if-vector asm slot invert? label
-@deffnx {Scheme Procedure} emit-br-if-string asm slot invert? label
-@deffnx {Scheme Procedure} emit-br-if-bytevector asm slot invert? label
-@deffnx {Scheme Procedure} emit-br-if-bitvector asm slot invert? label
-TC7-specific test-and-branch instructions.  The TC7 is a 7-bit code that
-is part of a heap object's type.  @xref{The SCM Type in Guile}.  Also,
-@xref{Branch Instructions}.
-@end deffn
-
 The linker is a complicated beast.  Hackers interested in how it works
 would do well do read Ian Lance Taylor's series of articles on linkers.
 Searching the internet should find them easily.  From the user's

libguile/vm-engine.c

@@ -1382,7 +1382,7 @@ VM_NAME (scm_thread *thread)
       NEXT (2);
     }
 
-  /* call-thread dst:24 IDX:32
+  /* call-scm<-thread dst:24 IDX:32
    *
    * Call the SCM-returning instrinsic with index IDX, passing the
    * current scm_thread* as argument.  Place the SCM result in DST.
@@ -1895,8 +1895,8 @@ VM_NAME (scm_thread *thread)
 
   /* scm-ref/tag dst:8 obj:8 tag:8
    *
-   * Reference the first word of OBJ, subtract the immediate TAG, and
-   * store the resulting SCM to DST.
+   * Load the first word of OBJ, subtract the immediate TAG, and store
+   * the resulting SCM to DST.
    */
   VM_DEFINE_OP (69, scm_ref_tag, "scm-ref/tag", DOP1 (X8_S8_S8_C8))
     {
@@ -1909,10 +1909,10 @@ VM_NAME (scm_thread *thread)
       NEXT (1);
     }
 
-  /* scm-ref/tag dst:8 obj:8 tag:8
+  /* scm-set!/tag obj:8 tag:8 val:8
    *
-   * Reference the first word of OBJ, subtract the immediate TAG, and
-   * store the resulting SCM to DST.
+   * Set the first word of OBJ to the SCM value VAL plus the immediate
+   * value TAG.
    */
   VM_DEFINE_OP (70, scm_set_tag, "scm-set!/tag", OP1 (X8_S8_C8_S8))
     {
@@ -2068,7 +2068,7 @@ VM_NAME (scm_thread *thread)
       NEXT (1);
     }
 
-  /* scm-ref/immediate dst:8 obj:8 idx:8
+  /* atomic-scm-ref/immediate dst:8 obj:8 idx:8
    *
    * Atomically reference the SCM object at word offset IDX from local
    * OBJ, and store it to DST, using the sequential consistency memory
@@ -2805,7 +2805,7 @@ VM_NAME (scm_thread *thread)
       NEXT (1);
     }
 
-  /* =? a:12 b:12
+  /* heap-numbers-equal? a:12 b:12
    *
    * Set the comparison result to EQUAL if the SCM values A and B are
    * numerically equal, in the sense of "=".  Set to NONE otherwise.  It