--- gforth/doc/gforth.ds	2000/06/29 18:39:27	1.56
+++ gforth/doc/gforth.ds	2000/07/13 19:41:07	1.57
@@ -8680,6 +8680,23 @@ control structures}), with @code{if,}, @
 @code{cs-pick}, @code{else,}, @code{while,}, and @code{repeat,}.  The
 conditions are specified in a way specific to each assembler.
 
+Note that the register assignments of the Gforth engine can change
+between Gforth versions, or even between different compilations of the
+same Gforth version (e.g., if you use a different GCC version).  So if
+you want to refer to Gforth's registers (e.g., the stack pointer or
+TOS), I recommend defining your own words for refering to these
+registers, and using them later on; then you can easily adapt to a
+changed register assignment.  The stability of the register assignment
+is usually better if you build Gforth with @code{--enable-force-reg}.
+
+In particular, the resturn stack pointer and the instruction pointer are
+in memory in @code{gforth}, and usually in registers in
+@code{gforth-fast}.  The most common use of these registers is to
+dispatch to the next word (the @code{next} routine).  A portable way to
+do this is to jump to @code{' noop >code-address} (of course, this is
+less efficient than integrating the @code{next} code and scheduling it
+well).
+
 @node  Common Disassembler, 386 Assembler, Common Assembler, Assembler and Code Words
 @subsection Common Disassembler
 
@@ -8706,6 +8723,67 @@ to ensure that the end is recognized.
 The 386 assembler and disassembler included in Gforth was written by
 Andrew McKewan; it is in the public domain.
 
+The disassembler displays code in prefix Intel syntax.
+
+The assembler uses an Intel-inspired postfix syntax with reversed
+parameters.  As usual, a @code{,} is appended to the instruction names
+(including @code{rep,} etc.).
+
+The assembler is somewhat meager, missing a number of instructions
+(including FP) and absolute memory addressing modes.
+
+The registers have their usual names @code{eax} etc.  Immediate values
+are indicated by postfixing them with @code{#}, e.g., @code{3 #}.  Here
+are some examples of addressing modes:
+
+@example
+3 #
+eax
+100 [edi]
+4 [ebx] [ecx]
+0 [edi] [eax] *4 \ base register required!
+@end example
+
+Some example of instructions are:
+
+@example
+EAX EBX MOV,             \ move ebx,eax
+3 # EAX MOV,             \ mov eax,3
+100 [EDI] EAX MOV,       \ mov eax,100[edi]
+4 [EBX] [ECX] EAX MOV,   \ mov eax,4[ebx][ecx]
+16: EAX EBX MOV,         \ mov bx,ax
+@end example
+
+You cannot use the prefix @code{16:} with immediate operands.  The
+following forms are supported for binary instructions:
+
+@example
+<reg> <reg> <inst>
+<n> # <reg> <inst>
+<mem> <reg> <inst>
+<reg> <mem> <inst>
+@end example
+
+Immediate to memory is not supported.  The shift/rotate syntax is:
+
+@example
+<reg/mem> shl,
+<reg/mem> 4 shl,
+<reg/mem> cl shl,
+@end example
+
+Precede string instructions (@code{movs,} etc.) with @code{byte} to get
+the byte version.
+
+The control structure words @code{if,} @code{until,} etc. must be
+preceded by one of these conditions: @code{0= 0< u< u> < > ov ecx0<>}.
+You can invert the condition with @code{not} (Note that most of these
+words shadow some Forth words when @code{assembler} is before
+@code{forth} in the search path, e.g., in code words).  Currently the
+control structure words use one stack item, so you have to use
+@code{roll} instead of @code{cs-roll} to shuffle them (you can also use
+@code{swap} etc.).
+
 @node Alpha Assembler, MIPS assembler, 386 Assembler, Assembler and Code Words
 @subsection Alpha Assembler