===================================================================
RCS file: /cvs/djgpp/djgpp/src/utils/Attic/djasm.txi,v
retrieving revision 1.3
retrieving revision 1.4
diff -p -u -r1.3 -r1.4
--- djgpp/src/utils/Attic/djasm.txi	2001/02/11 16:13:27	1.3
+++ /cvs/djgpp/djgpp/src/utils/Attic/djasm.txi	2001/05/30 15:27:24	1.4
@@ -13,10 +13,10 @@
 @c %**end of header
 @end ignore
 
-@set EDITION 1.03
-@set VERSION 2.03
-@set UPDATED 13 January 2001
-@set UPDATED-MONTH January 2001
+@set EDITION 1.04
+@set DJGPP_VERSION 2.03
+@set UPDATED 30 May 2001
+@set UPDATED_MONTH May 2001
 
 @set NASM_HOME www.cryogen.com/Nasm
 @set BC_DJASM_DOC_DATE 19 November 1999
@@ -31,7 +31,7 @@
 @comment The following two commands start the copyright page.
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1999,2000,2001 DJ Delorie
+Copyright @copyright{} 1999, 2000, 2001 DJ Delorie
 @end titlepage
 
 @comment node-name, next, previous, up
@@ -40,29 +40,29 @@ Copyright @copyright{} 1999,2000,2001 DJ
 @end ignore
 
 @ifinfo
-@code{djasm} is a special-purpose 16-bit assembler used to compile
-the 16-bit stub that allows @sc{dos} to run the @code{coff} files
-generated by @sc{djgpp}.
+@code{djasm} is a special-purpose 16-bit assembler used to compile the
+16-bit stub that allows DOS to run the COFF files generated by DJGPP.
 
 This is Edition @value{EDITION}
 of the documentation for @code{djasm},
 @cite{The DJGPP 16-bit Assembler},
-last updated @value{UPDATED},
-for @acronym{DJGPP} Version @value{VERSION}.
+last updated @value{UPDATED_MONTH},
+for DJGPP version @value{DJGPP_VERSION}.
 This manual incorporates the information in Bill Currie's
 LyX documentation for @code{djasm}, dated @value{BC_DJASM_DOC_DATE}.
 @end ifinfo
 
 @menu
 * Introduction::                What is @code{djasm}?
-* Overview::                    Features, omissions, limitations, and
-                                        differences from other assemblers.
+* Overview::                    Features, differences, and limitations.
 * Invocation::                  Invoking @code{djasm}.
-* Language Reference::          Assembler language reference.
+* Language::                    Assembler language reference.
 * Examples::                    Programming examples.
 * Contributors::                Contributors.
+* References::                  Some useful references.
 * Topic Index::                 Index of topics.
 * Keyword Index::               Index of keywords.
+* Mnemonic Index::              Index of mnemonics.
 @end menu
 
 @comment node-name, next, previous, up
@@ -91,11 +91,9 @@ aspects of djasm.  We think it might des
 
 Some features described herein may be specific to Bill Currie's latest
 version of @code{djasm}, available at @url{@value{BC_DJASM_HOME}}, and
-may not (yet) have found their way into the official @sc{djgpp} release.
-
-Of course, the final authority regarding @code{djasm} is the Bison
-source file @file{djasm.y} in the file @file{djlsrNNN.zip}.
-Use the source, Luke.
+may not (yet) have found their way into the official DJGPP release.
+The final authority regarding @code{djasm} is the Bison source file
+@file{djasm.y} in the archive @file{djlsrNNN.zip}.
 
 @comment node-name, next, previous, up
 @node Description
@@ -103,23 +101,25 @@ Use the source, Luke.
 
 @code{djasm} is a restricted assembler that was developed for a single
 purpose: to compile the 16-bit startup stub that is prepended to all
-@sc{djgpp}-built executables.
+DJGPP-built executables.
 The purpose of the stub is to check for @sc{dpmi} services (and load
 @sc{cwsdpmi} if a @sc{dpmi} server is not found), switch into protected
-mode, and load and execute a @sc{djgpp}-generated @code{coff} image.
-With @code{djasm} the @sc{djgpp} distribution can be made completely
-self-contained; you don't need commercial (or otherwise non-@sc{djgpp})
-16-bit tools to build any part of the @sc{djgpp} distribution.
+mode, and load and execute a DJGPP-generated COFF image.
+With @code{djasm} the DJGPP distribution can be made completely
+self-contained; you don't need commercial (or otherwise non-DJGPP)
+16-bit tools to build any part of the DJGPP distribution.
 
 Be aware, however, that although @code{djasm} can be used in other
 applications, it is @emph{not} a full-featured assembler; if you need
-a sophisticated, general-purpose assembler then use @sc{gas} (the GNU
-Assembler) or @sc{nasm} (the Netwide Assembler).
-Give some thought to what you want to do, and use the right tool for the job.
-@sc{gas} (@file{as.exe}) is part of the @sc{djgpp} @file{bnuXXXb.zip}
-archive and should be available in the @file{bin} subdirectory of your
-@sc{djgpp} tree (i.e., in @file{$DJDIR/bin}) if you have installed @sc{gcc}.
-@sc{nasm} lives at @url{@value{NASM_HOME}}.
+a sophisticated, general-purpose assembler then consider using @sc{gas}
+(the GNU Assembler) or @sc{nasm} (the Netwide Assembler).
+Give some thought to what you want to do,
+and choose the right tool for the job.
+The GNU assembler @sc{gas} (@file{as.exe}) is part of the DJGPP
+@file{bnuNNNb.zip} archive and should be available in the @file{bin}
+subdirectory of your DJGPP tree (i.e., in @file{$DJDIR/bin}) if you
+have installed @sc{gcc}.
+The Netwide Assembler @sc{nasm} lives at @url{@value{NASM_HOME}}.
 
 @comment node-name, next, previous, up
 @node History
@@ -133,29 +133,29 @@ archive and should be available in the @
 @cindex DJGPP
 
 The need for @code{djasm} arose when when Cygnus, a major user of
-@sc{djgpp} for their @sc{dos}-based products, requested a version of
-@sc{djgpp} that was fully independent and self-bootstrapping.
-The existing @sc{djgpp} 1.x system didn't entirely meet their need,
+DJGPP for their DOS-based products, requested a version of
+DJGPP that was fully independent and self-bootstrapping.
+The existing DJGPP 1.x system didn't entirely meet their need,
 however, because a Borland 16-bit compiler (Turbo C 2.0) was required
-to build the @code{go32} program used by @sc{djgpp} 1.x.
+to build the @file{go32.exe} program used by DJGPP 1.x.
 
-The first task, therefore, in making a version 2.x of @sc{djgpp} that
+The first task, therefore, in making a version 2.x of DJGPP that
 would be entirely self-contained was to write an assembler that could
-compile the 16-bit stub required by all @sc{djgpp} executables.
+compile the 16-bit stub required by all DJGPP executables.
 The stub could have been written to use @sc{nasm}, but
 (1) @sc{nasm} wasn't around at the time, and
-(2) a dedicated 16-bit compiler would make @sc{djgpp} independent of
+(2) a dedicated 16-bit compiler would make DJGPP independent of
 any other product.
 Thus @code{djasm} was designed and written for a specific purpose---to
-compile the 16-bit code for @sc{djgpp}'s startup stub and enable
-@emph{everything} needed to build @sc{djgpp} to be distributed freely.
+compile the 16-bit code for DJGPP's startup stub and enable
+@emph{everything} needed to build DJGPP to be distributed freely.
 
 The @code{djasm} compiler was to have no other purpose in life, and was
 never intended to be a generic utility, until some of the developers got
 carried away and introduced support for many additional opcodes that had
 not yet been used.
 As a result, @code{djasm} has become sufficiently powerful to be
-useful for more 16-bit applications than just the @sc{djgpp} stub.
+useful for more 16-bit applications than just the DJGPP stub.
 
 @comment node-name, next, previous, up
 @node Overview
@@ -166,7 +166,7 @@ useful for more 16-bit applications than
 @menu
 * Features::                    What @code{djasm} can do.
 * Differences::                 Differences from other assemblers.
-* Omissions and Limitations::   What you don't get with @code{djasm}.
+* Limitations::                 What you don't get with @code{djasm}.
 * Applications::                When would I want to use @code{djasm}?
 @end menu
 
@@ -176,7 +176,7 @@ useful for more 16-bit applications than
 
 @cindex features, of djasm
 
-Despite many limitations and some glaring omissions,
+Despite its limitations,
 @code{djasm} does have some nice features:
 
 @itemize @bullet{}
@@ -186,9 +186,9 @@ so @code{djasm} is relatively easy to le
 and code written for @code{djasm} tends to be straightforward.
 @item
 @code{djasm} is released under the terms of the @sc{gpl} and comes
-with @sc{djgpp} (@file{djdevNNN.zip}).
+with DJGPP (@file{djdevNNN.zip}).
 @item
-@sc{gcc}/@sc{gas}-generated @code{coff} files can be linked with the
+@sc{gcc}/@sc{gas}-generated COFF files can be linked with the
 code (the linking is done by @code{djasm}).
 @item
 @code{djasm} produces 16-bit code
@@ -199,8 +199,7 @@ for subsequent use with assembler and C
 @item
 Support for C-style structure, union, and enumeration types.
 @item
-Most instructions and addressing modes are supported
-(a few are still missing).
+Most instructions and addressing modes are supported.
 @item
 Full 32-bit addressing.
 @end itemize
@@ -218,11 +217,9 @@ other assemblers, such as @sc{gas} (the
 
 @itemize @bullet{}
 @item
-Like most assemblers, @code{djasm} has its own syntax; in general
-it is similar to the Intel syntax, but there are some differences.
-@sc{gas} uses the @sc{at&t} syntax.
-Porting code to @code{djasm} shouldn't be difficult but will generally
-require a bit of editing.
+Like most assemblers, @code{djasm} has its own syntactic idiosyncrasies.
+In general, @code{djasm} syntax is similar to Intel syntax,
+and porting code to @code{djasm} shouldn't be difficult.
 
 @cindex syntax, Intel
 @cindex syntax, ATT
@@ -244,13 +241,14 @@ so all source must be in a single file.
 @code{djasm} builds @file{.exe} and other executables directly;
 there is no linker.
 @item
-Code generated by @code{djasm} cannot be linked with @sc{djgpp} programs;
-@sc{gas} and @sc{nasm} can produce standard @code{coff} objects.
-However, @code{djasm} can build a raw binary image for inclusion in other code.
+Code generated by @code{djasm} cannot be linked with DJGPP programs;
+@sc{gas} and @sc{nasm} can produce standard COFF objects.
+However, @code{djasm} @strong{can} build a raw binary image for
+inclusion in other code.
 @end itemize
 
 @comment node-name, next, previous, up
-@node Omissions and Limitations
+@node Limitations
 @section What's missing from @code{djasm}?
 
 Although @code{djasm} can do quite a bit as it stands, there are a number
@@ -276,7 +274,7 @@ Macros.
 @item
 More documentation.
 @item
-Finish omf support (do you still want that, DJ?).
+Finish omf support.
 @item
 Better symbol handling (allow forward references in most expressions).
 @item
@@ -311,11 +309,11 @@ The following output formats are support
 
 @table @file
 @item .exe
-Generate a normal @sc{dos} @file{.exe} (@sc{mz} signature) executable.
+Generate a normal DOS @file{.exe} (@sc{mz}-signature) executable.
 Does not support more than one segment.
 This is the only output format that supports the @code{.copyright} directive.
 @item .com
-Generate a normal @sc{dos} @file{.com} file.
+Generate a normal DOS @file{.com} file.
 Program offset is at 0x100.
 @item .bin
 @itemx .sys
@@ -348,7 +346,7 @@ However, there are a few reasons why you
 @item
 If you are looking for a free (@i{sensu} @sc{gpl}) 16-bit assembler.
 @item
-To keep a project compatible with the spirit of @sc{djgpp},
+To keep a project compatible with the spirit of DJGPP,
 without requiring the use of @sc{nasm} or some other assembler
 to compile 16-bit code.
 @item
@@ -357,7 +355,7 @@ boot loaders, or micro-kernels.
 @end itemize
 
 @comment node-name, next, previous, up
-@node Language Reference
+@node Language
 @chapter The @code{djasm} Language
 
 @menu
@@ -366,6 +364,7 @@ boot loaders, or micro-kernels.
 * Data::                        Data directives.
 * Structures::                  Structure, union, and enumeration types.
 * Prefixes::                    Segment override prefixes.
+* Mnemonics::                   Assembler mnemonics.
 @end menu
 
 @comment node-name, next, previous, up
@@ -436,12 +435,14 @@ This directive is currently supported on
 @item .id
 Usage:  .id
 
-Emit an @sc{rcs}-style identification string into the instruction stream.
-The id has the form:
+Emit @sc{sccs} and @sc{rcs} identification strings into the
+instruction stream.
+These strings have the form:
 
-@c use `@w{Id}' below to prevent RCS from recognizing the keyword.
+@c using `@w{Id}' below to prevent RCS from recognizing the keyword.
 @c the `Cederqvist' uses `$@asis{}Author$' constructions; does it matter?
 @c SCCS groks the `@(#)' sequence (Cederqvist, p.70).
+
 @example
 $@w{Id}: djasm.lyx,v 1.2 1999/06/22 07:08:56 bill Exp $
 @@(#) foo.asm built 10/04/97 14:03:30 by djasm
@@ -454,25 +455,24 @@ Include a text file for assembly.
 @code{djasm} pushes the current file location, starts processing the
 included file, then pops the old location when the end of the included
 file is reached.
-@c No path searching is performed to find @var{file}.inc.
 No path searching is performed to find the @code{.include}ed file,
 but @var{file}.inc itself can include a path specification.
 
 @item .linkcoff
 Usage:  .linkcoff "@var{file}.o"
 
-Link in a @sc{gas}-generated 32-bit @code{coff} file
+Link in a @sc{gas}-generated 32-bit COFF file
 (e.g., the output from @code{gcc -c foo.c}).
-Currently supports only i386 @code{coff} files with @code{.text},
+Currently supports only i386 COFF files with @code{.text},
 @code{.data}, and @code{.bss} sections; these @emph{must} be the
-first three sections in the @code{coff} file and @emph{must} appear
+first three sections in the COFF file and @emph{must} appear
 in that order.
 Any other sections will be ignored.
 These three sections will be placed into the output image in the same
-order as in the @code{coff} file.
-The @code{.bss} section of the @code{coff} file will be placed into the
+order as in the COFF file.
+The @code{.bss} section of the COFF file will be placed into the
 output image by emitting the appropriate number of zeros---this means
-that the @code{.bss} section from the @code{coff} file will occupy space
+that the @code{.bss} section from the COFF file will occupy space
 in the output image rather than being implicit.
 
 As with @code{.include}, no path searching is done for @code{.linkcoff},
@@ -512,8 +512,8 @@ output file extension and @code{.type} d
 @pindex .type, inc
 @pindex .type, ah
 
-@c This table is an ASCII hack, but trying to use `multitable'
-@c is even worse.
+@c This table is an ASCII hack, but `multitable' looks even worse.
+@exampleindent 0
 @example
 +---------+-----------------------------------------------------+
 | Output  | Value of @samp{.type}                                    |
@@ -529,6 +529,7 @@ output file extension and @code{.type} d
 |  ah     | exe     com     bin     bin     exe     bin     bin |
 +---------+-----------------------------------------------------+
 @end example
+@exampleindent 5
 
 @enumerate a
 @item
@@ -684,7 +685,6 @@ uses the @code{FARPTR} structure from th
 .struct XMS_MOVE
         length          .dd
         src_handle      .dw
-@c        src_offset      .struct FARPTR ; @code{.union} would also be valid here
         src_offset      .struct FARPTR
         dst_handle      .dw
         dst_offset      .struct FARPTR
@@ -724,8 +724,6 @@ appropriate directive should always be u
 (mostly because there is no way of detecting it).
 
 Variables can be declared to be structures or unions.
-@c (and note that the above message about @code{.struct} and @code{.union}
-@c applies here as well).
 For example, the statement
 
 @smallexample
@@ -793,7 +791,7 @@ Unfortunately this is prone to error, bu
 way of doing this.
 Any expression that @code{djasm} can handle as a relocation is permitted
 in the parentheses; this can be useful for declaring structures at some
-specific address (e.g., the @sc{psp} structure or some of the @sc{dos}
+specific address (e.g., the @sc{psp} structure or some of the DOS
 system tables).
 
 @comment node-name, next, previous, up
@@ -943,9 +941,122 @@ user segment `g' override
 
 @end table
 
-The @code{.segXX} prefixes seem to be most appropriate when used with
+The @code{.seg??} prefixes seem to be most appropriate when used with
 the string instructions such as @code{movs}, @code{stos}, etc.).
 
+@defindex op
+
+@comment node-name, next, previous, up
+@node Mnemonics
+@section Mnemonics
+
+This section documents and describes the @code{djasm} assembler mnemonics.
+For convenience, the organization and classification of the mnemonics
+generally follows that of Triebel (1992) (@pxref{Triebel-1992}).
+
+@menu
+* Data Transfer Instructions::
+* Arithmetic Instructions::
+* Logic Instructions::
+* Shift Instructions::
+* Rotate Instructions::
+* Bit Test and Bit Scan Instructions::
+* Flag Control Instructions::
+* Compare and Set Instructions::
+* Jump Instructions::
+* Subroutine Handling Instructions::
+* Loop Handling Instructions::
+* String Handling Instructions::
+@end menu
+
+@comment node-name, next, previous, up
+@node Data Transfer Instructions
+@subsection Data Transfer Instructions
+
+[Not this release.]
+@c @include xfer.txi
+
+@comment node-name, next, previous, up
+@node Arithmetic Instructions
+@subsection Arithmetic Instructions
+
+[Not this release.]
+@c @include add.txi
+@c @include sub.txi
+@c @include muldiv.txi
+
+@comment node-name, next, previous, up
+@node Logic Instructions
+@subsection Logic Instructions
+
+[Not this release.]
+@c @include logic.txi
+
+@comment node-name, next, previous, up
+@node Shift Instructions
+@subsection Shift Instructions
+
+[Not this release.]
+@c @include shift.txi
+
+@comment node-name, next, previous, up
+@node Rotate Instructions
+@subsection Rotate Instructions
+
+[Not this release.]
+@c @include rotate.txi
+
+@comment node-name, next, previous, up
+@node Bit Test and Bit Scan Instructions
+@subsection Bit Test and Bit Scan Instructions
+
+[Not this release.]
+@c @include bit.txi
+
+@comment node-name, next, previous, up
+@node Flag Control Instructions
+@subsection Flag Control Instructions
+
+[Not this release.]
+@c @include flag.txi
+
+@comment node-name, next, previous, up
+@node Compare and Set Instructions
+@subsection Compare and Set Instructions
+
+[Not this release.]
+@c @include cmp.txi
+@c @include set.txi
+
+@comment node-name, next, previous, up
+@node Jump Instructions
+@subsection Jump Instructions
+
+[Not this release.]
+@c @include jmp.txi
+@c @include jcc.txi
+
+@comment node-name, next, previous, up
+@node Subroutine Handling Instructions
+@subsection Subroutine Handling Instructions
+
+[Not this release.]
+@c @include subr.txi
+
+@comment node-name, next, previous, up
+@node Loop Handling Instructions
+@subsection Loop Handling Instructions
+
+[Not this release.]
+@c @include loop.txi
+
+@comment node-name, next, previous, up
+@node String Handling Instructions
+@subsection String Handling Instructions
+
+[Not this release.]
+@c @include string.txi
+
 @comment node-name, next, previous, up
 @node Examples
 @chapter Programming Examples
@@ -963,7 +1074,8 @@ Some examples of programming with @code{
 
 @example
 .type   "com"
-.org 0x100                      ; origin for .COM program
+.org    0x100                   ; origin for .COM program
+
         mov dx, msg             ; point DX to message
         mov ah, 0x9             ; DOS print string function
         int 0x21
@@ -973,8 +1085,8 @@ msg:
         .db "hello, world\r\n$"
 @end example
 
-Enter the above code into a file @samp{hello.asm},
-then make a @sc{dos} @file{.com} executable using the command
+Enter the above code into a file @file{hello.asm},
+then make a DOS @file{.com} executable using the command
 
 @example
 djasm hello.asm hello.com hello.map
@@ -1035,6 +1147,22 @@ You can also let us know if your e-mail
 @end itemize
 
 @comment node-name, next, previous, up
+@node References
+@chapter References
+
+@enumerate
+
+@anchor{Triebel-1992}
+@item
+Triebel, Walter A.
+1992.
+The 80386DX microprocessor:  hardware, software, and interfacing.
+Englewood Cliffs, NJ: Prentice-Hall.
+ISBN 0-13-249566-X.
+
+@end enumerate
+
+@comment node-name, next, previous, up
 @node Topic Index
 @chapter Topic Index
 
@@ -1046,4 +1174,12 @@ You can also let us know if your e-mail
 
 @printindex pg
 
+@comment node-name, next, previous, up
+@node Mnemonic Index
+@chapter Mnemonic Index
+
+@printindex op
+
+@c @contents
+
 @bye