@ignore
\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename djasm.info
@settitle DJASM User's Guide
@setchapternewpage odd
@footnotestyle separate
@dircategory From djdevNNN.zip
@direntry
* djasm: (djasm).
        The DJGPP 16-bit Assembler.
@end direntry
@c %**end of header
@end ignore

@set EDITION 1.05
@set DJGPP_VERSION 2.03
@set UPDATED 19 June 2001
@set UPDATED_MONTH June 2001

@set NASM_HOME www.cryogen.com/Nasm
@set BC_DJASM_DOC_DATE 19 November 1999
@set BC_DJASM_HOME www.taniwha.org

@ignore
@titlepage
@sp 10
@comment The title is printed in a large font.
@center @titlefont{DJASM User's Guide}

@comment The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999, 2000, 2001 DJ Delorie
@end titlepage

@comment node-name, next, previous, up
@node Top
@top
@end ignore

@ifinfo
@code{djasm} is a special-purpose 16-bit assembler used to compile the
16-bit stub that allows @acronym{DOS} to run the @acronym{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_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, differences, and limitations.
* Invocation::                  Invoking @code{djasm}.
* 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
@node Introduction
@chapter What is @code{djasm}?

@menu
* Disclaimer::                  Caveat emptor, caveat lector.
* Description::                 Description.
* History::                     A brief history of @code{djasm}.
@end menu

@comment node-name, next, previous, up
@node Disclaimer
@section Disclaimer

@cindex disclaimer

@quotation
This is an UNREVIEWED and UNGUARANTEED document describing *some* of the
aspects of djasm.  We think it might describe djasm, but then it might not.
@flushright
---DJ
@end flushright
@end quotation

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 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
@section Description

@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
DJGPP-built executables.
The purpose of the stub is to (i) check for @acronym{DPMI} services,
(ii) load @acronym{CWSDPMI} if another @acronym{DPMI} server is not
found, (iii) switch into protected mode, and (iv) load and execute
a DJGPP-generated @acronym{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 consider using @acronym{AS}
(the @acronym{GNU} assembler) or @acronym{NASM} (the Netwide Assembler).
Give some thought to what you want to do,
and choose the right tool for the job.
The @acronym{GNU} assembler @acronym{AS} (@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 @acronym{GCC}.
The Netwide Assembler @acronym{NASM} lives at @url{@value{NASM_HOME}}.

@comment node-name, next, previous, up
@node History
@section A Brief History of @code{djasm}

@cindex history, of djasm
@cindex stub, DJGPP
@cindex NASM, Netwide assembler
@cindex Borland
@cindex Cygnus
@cindex DJGPP

The need for @code{djasm} arose when when Cygnus, a major user of
DJGPP for their @acronym{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 @file{go32.exe} program used by DJGPP 1.x.

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 DJGPP executables.
The stub could have been written to use @acronym{NASM}, but
(1) @acronym{NASM} wasn't around at the time, and
(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 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 DJGPP stub.

@comment node-name, next, previous, up
@node Overview
@chapter An Overview of @code{djasm}

@cindex overview, of djasm

@menu
* Features::                    What @code{djasm} can do.
* Differences::                 Differences from other assemblers.
* Limitations::                 What you don't get with @code{djasm}.
* Applications::                When would I want to use @code{djasm}?
@end menu

@comment node-name, next, previous, up
@node Features
@section What @code{djasm} can do

@cindex features, of djasm

Despite its limitations,
@code{djasm} does have some nice features:

@itemize @bullet{}
@item
The syntax was designed to be easy to parse,
so @code{djasm} is relatively easy to learn and use,
and code written for @code{djasm} tends to be straightforward.
@item
@code{djasm} is released under the terms of the @acronym{GPL} and comes
with DJGPP (@file{djdevNNN.zip}).
@item
@acronym{GCC}- and @acronym{AS}-generated @acronym{COFF} files can be
linked with the code (the linking is done by @code{djasm}).
@item
@code{djasm} produces 16-bit code
(currently this is the only available mode).
@item
There is support for several output formats, including raw hex output
for subsequent use with assembler and C code.
@item
C-style structure, union, and enumeration types are supported.
@item
Most instructions and addressing modes are supported.
@item
Full 32-bit addressing.
@end itemize

@comment node-name, next, previous, up
@node Differences
@section Differences between @code{djasm} and other assemblers

@cindex NASM, Netwide assembler
@cindex AS, GNU assembler
@cindex GAS, GNU assembler

There are some important differences between @code{djasm} and
other assemblers, such as @acronym{NASM} or the @acronym{GNU}
assembler @acronym{AS}.

@itemize @bullet{}
@item
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

@item
@code{djasm} generates 16-bit code, @acronym{AS} generates 32-bit code,
and @acronym{NASM} can generate both 16- and 32-bit code.
@item
@code{djasm} is incompletely documented and has incomplete opcode support;
@acronym{AS} and @acronym{NASM} are fully supported.
@item
@code{djasm} does not support macros.
@item
@code{djasm} is restricted in its output formats.
@item
@code{djasm} does not support multi-file programs,
so all source must be in a single file.
@item
@code{djasm} builds @file{.exe} and other executables directly;
there is no linker.
@item
Code generated by @code{djasm} cannot be linked with DJGPP programs;
both @acronym{NASM} and the @acronym{GNU} assembler @acronym{AS} can
produce standard @acronym{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 Limitations
@section What's missing from @code{djasm}?

Although @code{djasm} can do quite a bit as it stands, there are a number
of things that experienced assembly-language programmers will miss.
Future versions of @code{djasm} may add support for some or all of
these items, but again, if you need a sophisticated general-purpose
assembler, you should consider @acronym{AS} or @acronym{NASM}.

@itemize @bullet{}
@item
Complete instruction set support.
@item
Object files---what format(s)?
@item
A companion 16-bit linker.
@item
Segments.
(Is this really necessary?
Is it worth it?
Should one just use @acronym{NASM} instead?)
@item
Macros.
@item
More documentation.
@item
Finish support for the Tool Interface Standards (@acronym{TIS})
Relocatable Object Module Format (@acronym{OMF}).
@item
Better symbol handling (allow forward references in most expressions).
@item
Better section support.
At first, just being able to swap between the @code{.text}, @code{.data},
and @code{.bss} sections at will.
Later, maybe `real' segment support (especially 16/32-bit control).
@item
Finalize instruction support for 486.
@item
Pentium* instructions.

@end itemize

@comment node-name, next, previous, up
@node Invocation
@chapter Invoking @code{djasm}

Invoke @code{djasm} as follows:

@example
djasm @var{infile} [@var{outfile}] [@var{mapfile}]
@end example

@noindent
where @var{outfile} defaults to @file{@var{infile}.exe} after dropping
the extension from @var{infile}, and @var{mapfile} defaults to
@file{@var{infile}.map} after dropping the extension from @var{infile}.

The extension of @file{outfile} determines the format of the generated code.
The following output formats are supported:

@table @file
@item .exe
Generate a normal @acronym{DOS} @file{.exe}
executable (@acronym{MZ}-signature).
Does not support more than one segment.
This is the only output format that supports the @code{.copyright} directive.
@item .com
Generate a normal @acronym{DOS} @file{.com} file.
Program offset is at 0x100.
@item .bin
@itemx .sys
Generate binary files starting at offset 0.
The @file{.sys} format is supported so that device drivers can be built
directly (i.e., without needing to rename a @file{.bin} output file to
a @file{.sys} file).
@item .h
Produce a C-compilable array of bytes (without type declaration or
surrounding @{@}s).
@item .inc
Produce a @file{.db} array for other @code{djasm} @file{.asm} files.
@item .ah
Produce a @file{.byte} array for @acronym{AS} @file{.s} or @file{.S} files.
@end table

For the @file{.h}, @file{.inc}, and @file{.ah} output types,
the @code{.type} directive is used to determine which binary
type to emit (@pxref{General,.type}).

@comment node-name, next, previous, up
@node Applications
@section When would I want to use @code{djasm}?

Ordinarily, assembly language programmers should use @acronym{AS}, or a
16/32-bit assembler like @acronym{NASM}, for most programming purposes.
However, there are a few reasons why you might want to use @code{djasm}:

@itemize @bullet{}
@item
If you are looking for a free (@i{sensu} @acronym{GPL}) 16-bit assembler.
@item
To keep a project compatible with the spirit of DJGPP,
without requiring the use of @acronym{NASM} or some other assembler
to compile 16-bit code.
@item
For small 16-bit projects, such as device drivers, TSRs,
boot loaders, or micro-kernels.
@end itemize

@comment node-name, next, previous, up
@node Language
@chapter The @code{djasm} Language

@menu
* Syntax::                      Assembler syntax.
* General::                     General assembler directives.
* Data::                        Data directives.
* Structures::                  Structure, union, and enumeration types.
* Prefixes::                    Segment override prefixes.
* Mnemonics::                   Assembler mnemonics.
@end menu

@comment node-name, next, previous, up
@node Syntax
@section Assembler Syntax

As a general rule, @code{djasm} uses the same ordering of operands,
and usually the same instruction names, as do @acronym{TASM} and
@acronym{MASM}.

For ambiguous operand sizes, @code{djasm} uses operand suffixes
instead of the @code{word ptr}, etc., operand modifiers used by
other 16-bit assemblers.
For example, @code{djasm} uses @code{cmpb} instead of @code{cmp byte}.

Until documentation for @code{djasm} is completed, however, you
should examine the @code{bison} source for @code{djasm} (in the file
@file{djasm.y}) to learn exactly what the instruction mnemonics and
their arguments are.

@comment node-name, next, previous, up
@node General
@section General Directives

@pindex .align
@pindex .bss
@pindex .copyright
@pindex .id
@pindex .include
@pindex .linkcoff
@pindex .org
@pindex .stack
@pindex .start
@pindex .type

@table @code

@item .align
Usage:  .align @var{boundary} [, @var{fill}]

Emit bytes (if necessary) so that the program counter @var{cs:ip}
(denoted by @code{.}) is a multiple of @var{boundary}
(i.e., such that @var{cs:ip} % @var{boundary} == 0).
The argument @var{fill} specifies what bytes to emit;
the default is 0x90 (@acronym{NOP}).

@smallexample
.align 4       ; align on a 4-byte boundary, pad using 0x90
.align 16,0    ; align on a 16-byte boundary, pad using 0x00
@end smallexample

@item .bss
Usage:  .bss

Signifies the end of generated bytes.
No more bytes will be emitted into the image, but space will be
reserved so labels can be declared after this point to create
uninitialized variables.  

@item .copyright
Usage:  .copyright @var{string}

Inserts the copyright message @var{string} into the header of the
executable, starting approximately at offset 0x61 (there is also some
text with the generation details of the file starting at offset 0x28).
@var{string} is a standard C string.
Multiple @code{.copyright} directives concatenate.
This directive is currently supported only for the @file{.exe} output format.

@item .id
Usage:  .id

Emit @acronym{SCCS} and @acronym{RCS} identification strings into the
instruction stream.
These strings have the form:

@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
@end example

@item .include
Usage:  .include "@var{file}.inc"

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.
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 an @acronym{AS}-generated 32-bit @acronym{COFF} file
(e.g., the output from @code{gcc -c foo.c}).
Currently supports only i386 @acronym{COFF} files with @code{.text},
@code{.data}, and @code{.bss} sections; these @emph{must} be the
first three sections in the @acronym{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 @acronym{COFF} file.
The @code{.bss} section of the @acronym{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 @acronym{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},
but @var{file}.o itself can include a path specification.

@item .org
Usage:  .org @var{offset}

Sets the instruction pointer @var{ip} to @var{offset}.
The @var{ip} can only be increased using @code{.org}, never decreased.

@item .stack
Usage:  .stack

For @file{.exe} files only, sets the initial value of the stack pointer
@var{sp} to the current value of the instruction pointer @var{ip}.

@item .start
Usage:  .start

For @file{.exe} files only, sets the initial value of the instruction
pointer @var{ip} to the current value of the program counter @var{cs:ip}.

@item .type
Usage:  .type "@var{image}"

where @var{image} is one of
@file{com}, @file{bin}, @file{sys}, @file{h}, @file{inc}, or @file{ah}.
The following table summarizes the effect of various combinations of
output file extension and @code{.type} declaration.

@pindex .type, exe
@pindex .type, com
@pindex .type, bin
@pindex .type, sys
@pindex .type, h
@pindex .type, inc
@pindex .type, ah

@c This table is an ASCII hack, but `multitable' looks even worse.
@exampleindent 0
@example
+---------+-----------------------------------------------------+
| Output  | Value of @samp{.type}                                    |
|  file   +-----------------------------------------------------+
|extension| exe     com     bin     sys(b)  h       inc     ah  |
+---------+-----------------------------------------------------+
|  exe(c) | exe     exe(a)  exe     exe     exe     exe     exe |
|  com    | ---     com     ---     ---     ---     ---     --- |
|  bin    | bin     bin(a)  bin     bin     bin     bin     bin |
|  sys(b) | bin     bin(a)  bin     bin     bin     bin     bin |
|  h      | exe     com     bin     bin     exe     bin     bin |
|  inc    | exe     com     bin     bin     exe     bin     bin |
|  ah     | exe     com     bin     bin     exe     bin     bin |
+---------+-----------------------------------------------------+
@end example
@exampleindent 5

@enumerate a
@item
The first 0x100 bytes of the program are 0x90 (@acronym{NOP}),
followed by the generated code.
@item
The @file{.sys} type is a synonym for @file{.bin}.
@item
@file{.exe} is the default output file extension if no output file
(or output file extension) is specified.
@end enumerate

@end table

@comment node-name, next, previous, up
@node Data
@section Data Directives

@pindex .db
@pindex .dd
@pindex .dw
@pindex .dblist
@pindex .dwlist
@pindex .ddlist

The data directives are used to reserve space for byte (8-bit),
word (16-bit), and double word (32-bit) data.
The allocated space may be initialized or left indeterminate.
The general syntax of the data allocation directives is:

@example
.db [dblist [','dblist...]]
.dw [dwlist [','dwlist...]]
.dd [ddlist [','ddlist...]]
@end example

@table @code
@item .db
Define a byte of data.
@item .dd
Define a word of data.
@item .dw
Define a double word of data.
@item .dblist
@itemx .dwlist
@itemx .ddlist
List of byte, word, or double word data.

@end table

The data lists @code{dblist}, @code{dwlist}, and @code{ddlist} are
constructed from the following :

@table @code
@item constant
A decimal (e.g., 144), hexadecimal (e.g., 0x90),
or character (e.g., 'A') constant.
@item string
A C-style string constant, e.g., @code{"This is a string."}.
@item UID offset
This item is available only for the @code{dwlist} and @code{ddlist}
directives.
@item const .dup const
Repeat a block of data.
@end table

@comment node-name, next, previous, up
@node Structures
@section Structures

The following directives provide support for C-style @code{struct},
@code{union}, and @code{enum} constructs.

@table @code

@item .struct
Start a structure.

@item .union
Start a union.

@item .enum
Define an enumeration type.

@item .ends
End a structure, union, or enumeration.

@end table

@menu
* Structures and Unions::       Using structures and unions.
* Enumerations::                Using enumerations.
@end menu

@comment node-name, next, previous, up
@node Structures and Unions
@subsection Structures and Unions

@pindex .ends
@pindex .struct
@pindex .union
@cindex structure, struct
@cindex structure, union
@cindex type, struct
@cindex type, union
@cindex structure, ending

In their usage, @code{.struct} is the same as @code{struct} in C,
and @code{.union} is the same as @code{union} in C.
For example, the construct

@example
.struct FARPTR
        off     .dw
        seg     .dw
.ends
@end example

@noindent
defines the following symbols:

@smallexample
FARPTR     = 4          ; size of the `FARPTR' structure
FARPTR.off = 0          ; offset of `off' in the `FARPTR' structure
FARPTR.seg = 2          ; offset of `seg' in the `FARPTR' structure
@end smallexample

If, in the above example, the @code{.union} directive had been used
instead of @code{.struct}, a union would have been defined, capable
of holding an offset or a segment, but not both---thus the construct

@example
.union FARPTR
       off      .dw
       seg      .dw
.ends
@end example

@noindent
defines the following symbols:

@smallexample
FARPTR     = 2          ; size of the `FARPTR' union
FARPTR.off = 0          ; offset of `off' in the `FARPTR' union
FARPTR.seg = 0          ; offset of `seg' in the `FARPTR' union
@end smallexample

Nested structures are supported.
Here is an example of a nested structure @code{XMS_MOVE} that
uses the @code{FARPTR} structure from the previous example:

@smallexample
.struct XMS_MOVE
        length          .dd
        src_handle      .dw
        src_offset      .struct FARPTR
        dst_handle      .dw
        dst_offset      .struct FARPTR
.ends
@end smallexample

@noindent
This construct defines the following symbols and offsets (the members
of each structure have been indented to illustrate the nesting, and
the size in bytes of each member is given in brackets):

@smallexample
XMS_MOVE                    = 16        ; size of the XMS_MOVE structure
XMS_MOVE.length             =  0  [4]
XMS_MOVE.src_handle         =  4  [2]
  XMS_MOVE.src_offset       =  6
  XMS_MOVE.src_offset.off   =  6  [2]
  XMS_MOVE.src_offset.seg   =  8  [2]
XMS_MOVE.dst_handle         = 10  [2]
  XMS_MOVE.dst_offset       = 12
  XMS_MOVE.dst_offset.off   = 12  [2]
  XMS_MOVE.dst_offset.seg   = 14  [2]
@end smallexample

Note that @code{XMS_MOVE.src_offset} and @code{XMS_MOVE.src_offset.off}
share the same offset, as do @code{XMS_MOVE.dst_offset} and
@code{XMS_MOVE.dst_offset.off}---this is so that the offset of the
nested structure or union can be used directly.

When declaring the members of a structure or union,
@code{.struct} and @code{.union} can be used interchangably
without changing the resulting layout of the final construct.
In other words, @code{.struct} could be used when defining unions
and @code{.union} can be used when defining structures.
This practice is confusing and is @strong{not} recommended; the
appropriate directive should always be used, but this is not enforced
(mostly because there is no way of detecting it).

Variables can be declared to be structures or unions.
For example, the statement

@smallexample
xms_move_packet .struct XMS_MOVE
@end smallexample

@noindent
has the same effect as

@smallexample
xms_move_packet:
        xms_move_packet.length:
        .dd 0
        xms_move_packet.src_handle: 
        .dw 0
xms_move_packet.src_offset:
        xms_move_packet.src_offset.off:
        .dw 0
        xms_move_packet.src_offset.seg:
        .dw 0
        xms_move_packet.dst_handle:
        .dw 0
xms_move_packet.dst_offset:
        xms_move_packet.dst_offset.off:
        .dw 0
        xms_move_packet.dst_offset.seg:
        .dw 0
@end smallexample

It is sometimes desirable to place the structure at a specified location.
For this purpose, any valid expression using defined symbols is allowed,
not just @code{.token} or @code{.token-symbol}.
For example, the following two lines

@smallexample
xms_move_packet .struct XMS_MOVE (.) ; doesn't emit any bytes!
xms_move_packet .struct XMS_MOVE (.-sh_handle_cache)
@end smallexample

@noindent
have the same effect as @code{X}=@code{.} or
@code{X}=@code{.-sh_handle_cache}, respectively
(recall that @code{.} denotes the current program counter),
and generate the following structure:

@smallexample
xms_move_packet                = X
xms_move_packet.length         = X
xms_move_packet.src_handle     = X +  4
xms_move_packet.src_offset     = X +  6
xms_move_packet.src_offset.off = X +  6
xms_move_packet.src_offset.seg = X +  8
xms_move_packet.dst_handle     = X + 10
xms_move_packet.dst_offset     = X + 12
xms_move_packet.dst_offset.off = X + 12
xms_move_packet.dst_offset.seg = X + 14
@end smallexample

@cindex structure, initializing

The @code{(.)} form is useful for initializing structures---just
follow the declaration line by anonymous @code{.db} or @code{.dw}
or @code{.dd} lines.
Unfortunately this is prone to error, but it is currently the only
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 @acronym{PSP} structure or some of the
@acronym{DOS} system tables).

@comment node-name, next, previous, up
@node Enumerations
@subsection Enumerations

@pindex .enum
@cindex structure, enumeration
@cindex type, enumeration

The enumeration type allows arbitrary mnemonic identifiers (the
@dfn{enumeration constants}) to be mapped to a set of integer values.
The classical textbook example is that of defining a boolean variable.
The following construct defines @samp{boolean} as an enumeration
type that can take the values 0 (@samp{false}) or 1 (@samp{true}).

@example
.enum   boolean
        false
        true
.ends
@end example

@noindent
In this example, @samp{pets} is defined to be an enumeration type
having integral values 0 (@samp{bird}), 1 (@samp{cat}), 2 (@samp{dog}),
or 3 (@samp{rock}).

@example
.enum   pets
        bird
        cat
        dog
        rock
.ends
@end example

@noindent
In a @code{djasm} program the above enumeration types could
be referenced as follows:

@example
.start
        nop
        mov     ax,true                 ; ax <- 1
        mov     bx,pets.dog             ; bx <- 2
        mov     cx,pets.rock            ; cx <- 3
        mov     dx,pets.bird            ; dx <- 0
        int     0x20
@end example

If the enumeration constants are not explicitly initialized, then they
are assigned consecutive integer values starting with zero.
Explicitly and implicitly initialized enumeration constants can be
used within the same enumeration type, in which case an enumeration
constant without an initializer will be assigned the successor of the
previous enumeration constant.

In this example, the enumeration constants @samp{foo}, @samp{bar},
and @samp{e} are implicitly initialized.
A variable of enumeration type @samp{snafu} therefore takes one of the
following integer values: 0 (@samp{foo}), 1 (@samp{bar}), 1 (@samp{a}),
2 (@samp{b}), 4 (@samp{c}), 8 (@samp{d}), or 9 (@samp{e}).

@example
.enum   snafu
        foo
        bar
        a=1
        b=2
        c=4
        d=8
        e
.ends
@end example

@comment node-name, next, previous, up
@node Prefixes
@section Segment Override Prefixes

@pindex .addrsize
@pindex .opsize
@pindex .segcs
@pindex .segds
@pindex .seges
@pindex .segss
@pindex .segfs
@pindex .seggs

Each prefix directive causes the appropriate instruction prefix byte
to be emitted into the instruction stream.

Usage:

@example
prefix
instruction
@end example

@noindent
where @code{prefix} can be one of the following:

@table @code

@item .addrsize
toggles selection of 16- or 32-bit addressing

The address size prefix byte (0x67) is emitted---this tells @code{djasm}
to interpret the address as either a 32- or a 16-bit value.
For instance, it determines whether @code{di} or @code{edi}
is used as the index register for a string instruction.

@item .opsize
toggles selection of 16- or 32-bit operands

The data size prefix byte (0x66) is emitted.
This determines the size of the operands, distinguishing between
@code{mov ax,bx} and @code{mov eax,ebx}, for example.

The @code{.addrsize} and @code{.opsize} opcode prefix bytes are used
by @code{djasm} to express the 386's confusing opcode prefix scheme.
For backward compatibility with the 8086, instructions have both 16-bit
and 32-bit forms.
But, their opcodes are identical.
So in a 32-bit segment the 32-bit forms are used by default,
and in 16-bit segments the 16-bit forms are used by default.
These prefix bytes are used to force the compiler to use the non-default
form (e.g., issue a @code{mov ax,bx} within a 32-bit segment).

@item .segcs
code segment override

@item .segds
data segment override

@item .seges
extra segment override

@item .segss
stack segment override

@item .segfs
user segment `f' override

@item .seggs
user segment `g' override

@end table

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

@c [Not this release.]
@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

Some examples of programming with @code{djasm}.

@menu
* Hello world::                 ``Hello, world'' demo program.
* Enumeration types::           Examples of enumeration types.
* Opcode prefixes::             Example of opcode prefix usage.
@end menu

@comment node-name, next, previous, up
@node Hello world
@section ``Hello, world'' demo program

@example
.type   "com"
.org    0x100                   ; origin for .COM program

        mov dx, msg             ; point DX to message
        mov ah, 0x9             ; DOS print string function
        int 0x21
        mov ax, 0x4c00          ; DOS exit with errorlevel
        int 0x21
msg:    
        .db "hello, world\r\n$"
@end example

Enter the above code into a file @file{hello.asm},
then make a @acronym{DOS} @file{.com} executable using the command

@example
djasm hello.asm hello.com hello.map
@end example

@comment node-name, next, previous, up
@node Enumeration types
@section Examples of enumeration types

Here are a few examples of using enumeration types in @code{djasm}.
These are taken directly from the section on enumeration types
(@pxref{Enumerations}).

@enumerate

@item
Use an enumeration to define a new type, @samp{boolean}.
Load register @var{ax} with the value @samp{false} and
register @var{bx} with the value @samp{true}.

@example
.type   "com"
.org    0x100
.enum   boolean
        false
        true
.ends
        mov     ax,boolean.false
        mov     bx,boolean.true
        int     0x20
@end example


@noindent
If you assemble this program with @code{djasm},

@example
djasm.exe bool.asm bool.com bool.map
@end example

@noindent
and inspect the resulting @file{.map} file, you will find the
following enumeration definition:

@example
Address    Symbols by Value

0000:0000  __zero__ (?)
0000:0000  boolean.false (?)
0000:0001  boolean.true (?)
@end example

@noindent
If you inspect the assembled code using @acronym{DOS} @code{debug},
you will see that the registers are indeed loaded with the proper values:

@example
% debug bool.exe
-u 0100 l 08
1600:0100 B80000        MOV     AX,0000                            
1600:0103 BB0100        MOV     BX,0001                            
1600:0106 CD20          INT     20
-q
@end example

@item
This example defines an enumeration type @samp{snafu} and demonstrates
both implicit and explicit initialization of the enumeration constants.
In this example, the enumeration constants @samp{foo}, @samp{bar},
and @samp{e} are implicitly initialized with the values 0, 1, and 9,
respectively.

@example
.type   "com"
.org    0x100
.enum   snafu
        foo
        bar
        a=1
        b=2
        c=4
        d=8
        e
.ends
        int     0x20
@end example

@noindent
The @file{.map} file generated by @code{djasm} shows the enumeration
constants and how they were defined:

@example
Address    Symbols by Value

0000:0000  __zero__ (?)
0000:0000  snafu.foo (?)
0000:0001  snafu.a (?)
0000:0001  snafu.bar (?)
0000:0002  snafu.b (?)
0000:0004  snafu.c (?)
0000:0008  snafu.d (?)
0000:0009  snafu.e (?)
@end example

@end enumerate

@comment node-name, next, previous, up
@node Opcode prefixes
@section Example of opcode prefix usage

The following code fragment, taken from @file{stub.asm} in
the @file{djlsrNNN.zip} archive, illustrates the use of the
@code{.addrsize} and @code{.opsize} opcode prefixes.

@example
          :
        [32-bit instructions]
          :
        .addrsize
        rep
        stosd
          :
        [more 16-bit instructions]
          :
        .opsize
        jmpf    fs:[start_eip]          ; start program
@end example

Here, @code{.addrsize} toggles from the 32-bit addressing mode to the
16-bit mode, and forces the @code{stosd} instruction to use @code{di}
instead of @code{edi} as the index register.
The @code{.opsize} directive toggles between 16- and 32-bit operand sizes.
In this example it is being used to jump to a 32-bit address from
a 16-bit segment.

@comment node-name, next, previous, up
@node Contributors
@chapter Contributors to @code{djasm}

The following individuals (in alphabetical order) have contributed
to @code{djasm}, or to its documentation, or both.
If you have contributed to @code{djasm} in some way and are not
listed here, please make yourself known.
You can also let us know if your e-mail address is okay.

@itemize @bullet{}
@item @email{fighteer@@cs.com,John M. Aldrich}
@item @email{bill@@taniwha.org,Bill Currie}
@item @email{dj@@delorie.com,DJ Delorie}
@item @email{nate@@cartsys.com,Nate Eldredge}
@item @email{sandmann@@clio.rice.edu,Charles Sandmann}
@item @email{mschulter@@value.net,Margo Schulter}
@item @email{ams@@ludd.luth.se,Martin Str@"omberg}
@item @email{ucko@@vax1.rockhurst.edu,Aaron Ucko}
@item @email{tudor@@cam.org,Vic}
@item @email{terra@@diku.dk,Morten Welinder}
@item @email{jeffw@@darwin.sfbr.org,Jeff Williams}
@item @email{eliz@@is.elta.co.il,Eli Zaretskii}
@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

@printindex cp

@comment node-name, next, previous, up
@node Keyword Index
@chapter Keyword Index

@printindex pg

@comment node-name, next, previous, up
@node Mnemonic Index
@chapter Mnemonic Index

@printindex op

@c @contents

@bye