fxn suggestions

2 files changed, 103 insertions, 76 deletions

diff --git a/doc/mdk_gstart.texi b/doc/mdk_gstart.texi
index 97c180b..c9b936b 100644
--- a/doc/mdk_gstart.texi
+++ b/doc/mdk_gstart.texi
@@ -4,7 +4,7 @@
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_gstart.texi,v 1.11 2001/09/26 23:15:55 jao Exp $
+@c $Id: mdk_gstart.texi,v 1.12 2002/03/19 22:38:13 jao Exp $
 
 @node Getting started, mixvm.el, MIX and MIXAL tutorial, Top
 @chapter Getting started
@@ -409,7 +409,8 @@ MIX > run
 Running ...
 ... done
 Elapsed time: 10 /Total program time: 11 (Total uptime: 22)
-MIX > @end example
+MIX >
+@end example
 @noindent
 (As an aside, the above sample also shows how the virtual machine
 handles cummulative time statistics and automatic program restart).
diff --git a/doc/mdk_tut.texi b/doc/mdk_tut.texi
index b7c171b..461fcf6 100644
--- a/doc/mdk_tut.texi
+++ b/doc/mdk_tut.texi
@@ -1,10 +1,10 @@
 @c -*-texinfo-*-
 @c This is part of the GNU MDK Reference Manual.
-@c Copyright (C) 2000, 2001
+@c Copyright (C) 2000, 2001, 2002
 @c   Free Software Foundation, Inc.
 @c See the file mdk.texi for copying conditions.
 
-@c $Id: mdk_tut.texi,v 1.5 2001/09/26 23:15:55 jao Exp $
+@c $Id: mdk_tut.texi,v 1.6 2002/03/19 22:38:13 jao Exp $
 
 @node MIX and MIXAL tutorial, Getting started, Installing MDK, Top
 @comment  node-name,  next,  previous,  up
@@ -83,10 +83,10 @@ Sample MIX words are @samp{- 12 00 11 01 63} and @samp{+ 12 11 34 43
 00}.
 
 You can refer to subfields within a word using a @dfn{field
-specification} or @dfn{fspec} of the form ``(@var{l}:@var{r})'', where
-@var{l} denotes the first byte, and @var{r} the last byte of the
+specification} or @dfn{fspec} of the form ``(@var{L}:@var{R})'', where
+@var{L} denotes the first byte, and @var{R} the last byte of the
 subfield.
-When @var{l} is zero, the subfield includes the word's
+When @var{L} is zero, the subfield includes the word's
 sign. An fspec can also be represented as a single value @code{F}, given
 by @code{F = 8*L + R} (thus the fspec @samp{(1:3)}, denoting the first
 three bytes of a word, is represented by the integer 11).
@@ -115,7 +115,7 @@ J (jump) register. This register stores positive two-byte values,
 usually representing a jump address.
 @item @code{rI1}, @code{rI2}, @code{rI3}, @code{rI4}, @code{rI5}, @code{rI6}
 Index registers. These six registers can store a signed two-byte
-value. Their contents is used as indexing values for the computation of
+value. Their contents are used as indexing values for the computation of
 effective memory addresses.
 @end table
 
@@ -284,9 +284,14 @@ M = ADDRESS + [rI2] = -32 + 63 = 31
 V = [M](MOD) = (- 10 11 00 11 22)(1:3) = + 00 00 10 11 00
 @end example
 
-In the following subsections, we will assing to each MIX instruction a
-mnemonic, or symbolic name. For instance, the mnemonic of @samp{OPCODE}
-10 is @samp{LD2}. Thus we can rewrite the above instruction as
+Note that, when computing @samp{V} using a word and an fspec, we apply
+a left padding to the bytes selected by @samp{MOD} to obtain a
+complete word as the result. 
+
+In the following subsections, we will
+assing to each MIX instruction a mnemonic, or symbolic name. For
+instance, the mnemonic of @samp{OPCODE} 10 is @samp{LD2}. Thus we can
+rewrite the above instruction as
 
 @example
 LD2  -32,2(1:3)
@@ -323,13 +328,13 @@ OPCODE = 15, MOD = fspec. @code{rX <- V}.
 Put in rIi the contents of cell no. M.
 OPCODE = 8 + i, MOD = fspec. @code{rIi <- V}.
 @item LDAN
-Put in rA the negative contents of cell no. M.
+Put in rA the contents of cell no. M, with opposite sign.
 OPCODE = 16, MOD = fspec. @code{rA <- -V}.
 @item LDXN
-Put in rX the negative contents of cell no. M.
+Put in rX the contents of cell no. M, with opposite sign.
 OPCODE = 23, MOD = fspec. @code{rX <- -V}.
 @item LDiN
-Put in rIi the negative contents of cell no. M.
+Put in rIi the contents of cell no. M, with opposite sign.
 OPCODE = 16 + i, MOD = fspec. @code{rIi <- -V}.
 @end ftable
 
@@ -342,7 +347,7 @@ word @w{@samp{+ 00 13 01 27 11}} represents the instruction
 LD3    13,1(3:3)
  ^      ^ ^  ^
  |      | |  |
- |      | |   --- MOD = 27 = 3*8 + 7
+ |      | |   --- MOD = 27 = 3*8 + 3
  |      |  --- INDEX = 1
  |       --- ADDRESS = 00 13
   --- OPCODE = 11
@@ -359,7 +364,8 @@ the MIX computer is the following:
 As, in this case, @w{@samp{M = 13 + [rI1] = 12}}, we have
 
 @example
-V = [M](3:3) = (- 01 02 03 04 05)(3:3) = + 00 00 00 00 03
+V = [M](3:3) = (- 01 02 03 04 05)(3:3)
+  = + 00 00 00 00 03
 @end example
 @noindent
 (note that the specified subfield is left-padded with null bytes to
@@ -412,7 +418,7 @@ By way of example, consider the instruction @samp{STA 1200(2:3)}. It
 causes the MIX to fetch bytes no. 4 and 5 of register A and copy them to
 bytes 2 and 3 of memory cell no. 1200 (remember that, for these
 instructions, MOD specifies a subfield of @emph{the memory
-address}). The others bytes of the memory cell retain their
+address}). The other bytes of the memory cell retain their
 values. Thus, if prior to the instruction execution we have
 
 @example
@@ -475,33 +481,34 @@ the overflow toggle is set to TRUE.
 
 In these instructions, @samp{M} (the address of the instruction after
 indexing) is used as a number instead of as the address of a memory
-cell.
+cell. Consequently, @samp{M} can have any valid word value (i.e., it's
+not limited to the 0-3999 range of a memory address).
 
 @ftable @code
 @item ENTA
-Enter [rA]. OPCODE = 48, MOD = 2. @code{rA <- M}.
+Enter @samp{M} in [rA]. OPCODE = 48, MOD = 2. @code{rA <- M}.
 @item ENTX
-Enter [rX]. OPCODE = 55, MOD = 2. @code{rX <- M}.
+Enter @samp{M} in [rX]. OPCODE = 55, MOD = 2. @code{rX <- M}.
 @item ENTi
-Enter [rIi]. OPCODE = 48 + i, MOD = 2. @code{rIi <- M}.
+Enter @samp{M} in [rIi]. OPCODE = 48 + i, MOD = 2. @code{rIi <- M}.
 @item ENNA
-Enter negative [rA]. OPCODE = 48, MOD = 3. @code{rA <- -M}.
+Enter @samp{-M} in [rA]. OPCODE = 48, MOD = 3. @code{rA <- -M}.
 @item ENNX
-Enter negative [rX]. OPCODE = 55, MOD = 3. @code{rX <- -M}.
+Enter @samp{-M} in [rX]. OPCODE = 55, MOD = 3. @code{rX <- -M}.
 @item ENNi
-Enter negative [rIi]. OPCODE = 48 + i, MOD = 3. @code{rIi <- -M}.
+Enter @samp{-M} in [rIi]. OPCODE = 48 + i, MOD = 3. @code{rIi <- -M}.
 @item INCA
-Increase [rA]. OPCODE = 48, MOD = 0. @code{rA <- rA + M}.
+Increase [rA] by @samp{M}. OPCODE = 48, MOD = 0. @code{rA <- rA + M}.
 @item INCX
-Increase [rX]. OPCODE = 55, MOD = 0. @code{rX <- rX + M}.
+Increase [rX] by @samp{M}. OPCODE = 55, MOD = 0. @code{rX <- rX + M}.
 @item INCi
-Increase [rIi]. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi + M}.
+Increase [rIi] by @samp{M}. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi + M}.
 @item DECA
-Decrease [rA]. OPCODE = 48, MOD = 1. @code{rA <- rA - M}.
+Decrease [rA] by @samp{M}. OPCODE = 48, MOD = 1. @code{rA <- rA - M}.
 @item DECX
-Decrease [rX]. OPCODE = 55, MOD = 0. @code{rX <- rX - M}.
+Decrease [rX] by @samp{M}. OPCODE = 55, MOD = 0. @code{rX <- rX - M}.
 @item DECi
-Decrease [rIi]. OPCODE = 48 + i, MOD = 0. @code{rIi <- rIi - M}.
+Decrease [rIi] by @samp{M}. OPCODE = 48 + i, MaOD = 0. @code{rIi <- rIi - M}.
 @end ftable
 
 In the above instructions, the subfield @samp{ADDRESS} acts as an
@@ -562,7 +569,7 @@ counter}, which stores the address of the next instruction to be fetched
 and executed by the virtual CPU. You cannot directly modify the contents
 of this internal register with a load instruction: after fetching the
 current instruction from memory, it is automatically increased in one
-unit by the MIX. However, the is a set of instructions (which we call
+unit by the MIX. However, there is a set of instructions (which we call
 jump instructions) which can alter the contents of the location counter
 provided some condition is met. When this occurs, the value of the next
 instruction address that would have been fetched in the absence of the
@@ -620,7 +627,7 @@ using the following instructions:
 @itemx JANN
 @itemx JANZ
 @itemx JANP
-Jump if the contents of rA is, respectively, negative, zero, positive,
+Jump if the content of rA is, respectively, negative, zero, positive,
 non-negative, non-zero or non-positive. 
 OPCODE = 40, MOD = 0, 1, 2, 3, 4, 5.
 @item JXN
@@ -629,7 +636,7 @@ OPCODE = 40, MOD = 0, 1, 2, 3, 4, 5.
 @itemx JXNN
 @itemx JXNZ
 @itemx JXNP
-Jump if the contents of rX is, respectively, negative, zero, positive,
+Jump if the content of rX is, respectively, negative, zero, positive,
 non-negative, non-zero or non-positive. 
 OPCODE = 47, MOD = 0, 1, 2, 3, 4, 5.
 @item JiN
@@ -638,7 +645,7 @@ OPCODE = 47, MOD = 0, 1, 2, 3, 4, 5.
 @itemx JiNN
 @itemx JiNZ
 @itemx JiNP
-Jump if the contents of rIi is, respectively, negative, zero, positive,
+Jump if the content of rIi is, respectively, negative, zero, positive,
 non-negative, non-zero or non-positive. 
 OPCODE = 40 + i, MOD = 0, 1, 2, 3, 4, 5.
 @end ftable
@@ -705,7 +712,7 @@ OPCODE = 5, MOD = 1.
 @end ftable
 @noindent
 Digits are represented in MIX by the range of values 30-39 (digits
-9-0). Thus, if the contents of @samp{rA} and @samp{rX} is, for instance,
+0-9). Thus, if the contents of @samp{rA} and @samp{rX} are, for instance,
 
 @example
 [rA] = + 30 30 31 32 33
@@ -732,8 +739,8 @@ The following instructions perform byte-wise shifts of the contents of
 @itemx SRAX
 @itemx SLC
 @itemx SRC
-Shift rA or rAX left, right, or rAX circularly left or right. M
-specifies the number of bytes to be shifted.
+Shift rA or rAX left, right, or rAX circularly (see example below)
+left or right. M specifies the number of bytes to be shifted.
 OPCODE = 6, MOD = 0, 1, 2, 3, 4, 5.
 @end ftable
 @noindent
@@ -769,7 +776,7 @@ instructions which do not fit in any of the previous subsections:
 @ftable @code
 @item MOVE
 Move MOD words from M to the location stored in rI1.
-OPCODE = 7, MOD = no. of bytes.
+OPCODE = 7, MOD = no. of words.
 @item NOP
 No operation. OPCODE = 0, MOD = 0.
 @item HLT
@@ -892,24 +899,24 @@ Items between square brackets are optional, and
 
 @table @code
 @item LABEL
-Is an alphanumeric identifier (a @dfn{symbol}) which gets the current
+is an alphanumeric identifier (a @dfn{symbol}) which gets the current
 value of the location counter, and can be used in subsequent
-expressions.
+expressions,
 @item MNEMONIC
-Is a literal denoting the operation code of the instruction
+is a literal denoting the operation code of the instruction
 (e.g. @code{LDA}, @code{STA}; see @pxref{MIX instruction set}) or an
-assembly pseudoinstruction (e.g. @code{ORG}, @code{EQU}).
+assembly pseudoinstruction (e.g. @code{ORG}, @code{EQU}),
 @item ADDRESS
-Expression evaluating to the address subfield of the instruction.
+is an expression evaluating to the address subfield of the instruction,
 @item INDEX
-Expression evaluating to the index subfield of the instruction. It
+is an expression evaluating to the index subfield of the instruction, which
 defaults to 0 (i.e., no use of indexing) and can only be used when 
-@code{ADDRESS} is present.
+@code{ADDRESS} is present,
 @item MOD
-Expression evaluating to the mod subfield of the instruction. Its
-default value, when omitted, depends on @code{OPCODE}.
+is an expression evaluating to the mod subfield of the instruction. Its
+default value, when omitted, depends on @code{OPCODE},
 @item COMMENT
-Any number of spaces after the operand mark the beggining of a comment,
+any number of spaces after the operand mark the beggining of a comment,
 i.e. any text separated by white space from the operand is ignored by
 the assembler (note that spaces are not allowed within the
 @samp{OPERAND} field).
@@ -1056,7 +1063,7 @@ by the assembler.
 @end example
 
 As noted in the previous section, comments can also be located after the
-@code{MNEMONIC} field of an instruction, separated from it by white
+@code{OPERAND} field of an instruction, separated from it by white
 space, as in
 
 @example
@@ -1072,7 +1079,7 @@ LABEL     LDA   100  This is also a comment
 The @code{ADDRESS}, @code{INDEX} and @code{MOD} fields of a MIXAL
 instruction can be expressions, formed by numbers, identifiers and
 binary operators (@code{+ - * / // :}). @code{+} and @code{-} can also
-be used as unary operators. Order of evaluation is from left to right:
+be used as unary operators. Operator precedence is from left to right:
 there is no other operator precedence rule, and parentheses cannot be
 used for grouping. A stand-alone asterisk denotes the current memory
 location; thus, for instance,
@@ -1082,7 +1089,7 @@ location; thus, for instance,
 @end example
 
 @noindent
-evaluates to 4 plus two times the current memory location. White space
+evaluates to 6 (4 plus 2) times the current memory location. White space
 is not allowed within expressions.
 
 The special binary operator @code{:} has the same meaning as in fspecs,
@@ -1107,7 +1114,7 @@ to the same, multiplied by 64 to the fifth power) divided by
 Note that all MIXAL expressions evaluate to a MIX word (by definition).
 
 All symbols appearing within an expression must be previously defined. Future
-references are only allowed when appearing stand-alone (or modified by
+references are only allowed when appearing standalone (or modified by
 an unary operator) in the @code{ADDRESS} part of a MIXAL instruction,
 e.g.
 
@@ -1135,10 +1142,9 @@ w-expression is the following:
 @end example
 @noindent
 where @code{EXP} stands for an expression and square brackets denote
-optional items. Thus, a w-expression is made by a regular expression
-followed by an optional expression between parenthesis, followed by any
-number of similar constructs separated by commas. Sample w-expressions
-are:
+optional items. Thus, a w-expression is made by an expression, followed
+by an optional expression between parenthesis, followed by any number
+of similar constructs separated by commas. Sample w-expressions are:
 
 @example
 2000
@@ -1147,18 +1153,38 @@ S1+3(S2),3000
 S1,S2(3:5),23
 @end example
 
-W-expressions are evaluated as follows. First, all expressions are
-evaluated according to the rules given in the previous section. Thus, if
-we start with, say, @samp{S1+2(2:4)} where @samp{S1} equals 265230, we
-have @samp{265232(2:4)}. The expression between parenthesis must be a
-valid f-spec, for it specifies the bytes to be taken from the preceding
-word. In our example, we must take 3 bytes of the word @w{@samp{+ 00 01
-00 48 16}} (which is 265232), and store them in positions 2, 3 and 4 of
-the result, resulting in the new word @w{@samp{+ 00 00 48 16 00}} (i.e.,
-the decimal value 197632). When we have two expressions separated with a
-comma, we take, for each one, the subfield specified and compose the
-word to obtain the result. For instance, in the w-expression
+W-expressions are evaluated from left to right as follows:
+
+@itemize
+@item
+Start with an accumulated result @samp{w} equal to 0.
+@item
+Take the first expression of the comma-separated list and evaluate
+it. For instance, if the w-expression is @samp{S1+2(2:4),2000(S2)}, we
+evaluate first @samp{S1+2}; let's suppose that @samp{S1} equals
+265230: then @samp{S1+2 = 265232 = + 00 01 00 48 16}.
+@item
+Evaluate the expression within parenthesis, reducing it to an f-spec
+of the form @samp{L:R}. In our previous example, the expression
+between parenthesis already has the desired form: 2:4.
+@item
+Substitute the bytes of the accumulated result @samp{w} designated by
+the f-spec using those of the previous expression value. In our sample,
+@samp{w = + 00 00 00 00 00}, and we must substitute bytes 2, 3 and 4 of
+@samp{w} using values from 265232. We need 3 bytes, and we take the
+least significant ones: 00, 48, and 16, and insert them in positions
+2, 3 and 4 of @samp{w}, obtaining @samp{w = + 00 00 48 16 00}.
+@item
+Repeat this operation with the remaining terms, acting on the new
+value of @samp{w}. In our example, if, say, @samp{S2 = 1:1}, we must
+substitute the first byte of @samp{w} using one byte (the least
+significant) from 2000, that is, 16 (since 2000 = + 00 00 00 31 16)
+and, therefore, we obtain @samp{w = + 16 00 48 16 00}; summing up, we
+have obtained @samp{265232(1:4),2000(1:1) = + 16 00 48 16 00 =
+268633088}.
+@end itemize
 
+As a second example, in the w-expression
 @example
 1(1:2),66(4:5)
 @end example
@@ -1177,7 +1203,7 @@ As stated before, w-expressions can only appear as the operands of MIXAL
 directives taking a constant value (@code{ORIG}, @code{EQU}, @code{CON}
 and @code{END}). Future references are @emph{not} allowed within
 w-expressions (i.e., all symbols appearing in a w-expression must be
-defined before they are used).
+defined before it is used).
 
 @node Local symbols, Literal constants, W-expressions, MIXAL
 @comment  node-name,  next,  previous,  up
@@ -1247,22 +1273,22 @@ ST		NOP
 MIXAL allows the introduction of @dfn{literal constants}, which are
 automatically stored in memory addresses after the end of the program by
 the assembler. Literal constants are denoted as @code{=wexp=}, where
-@code{exp} is an w-expression (@pxref{W-expressions}). For instance, the
+@code{wexp} is a w-expression (@pxref{W-expressions}). For instance, the
 code
 
 @example
-L         EQU   10
+L         EQU   5
           LDA   =20-L=
 @end example
 
-causes the assembler to add after the program's end an instruction with
-contents 10, and to assemble the above code as the instruction @w{@code{
-LDA a}}, where @code{a} stands for the address in which the value 10 is
-stored. In other words, the compiled code is equivalent to the
-following:
+causes the assembler to add after the program's end an instruction
+with contents 15 (@samp{20-L}), and to assemble the above code as the
+instruction @w{@code{ LDA a}}, where @code{a} stands for the address
+in which the value 15 is stored. In other words, the compiled code is
+equivalent to the following:
 
 @example
-L         EQU  10
+L         EQU  5
           LDA  a
 @dots{}
 a         CON  20-L