@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.03
@set VERSION 2.03
@set UPDATED 13 January 2001
@set UPDATED-MONTH January 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 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 @sc{dos} to run the @code{coff} files
generated by @sc{djgpp}.

This is Edition @value{EDITION}
of documentation for @code{djasm},
@cite{The DJGPP 16-bit Assembler},
last updated @value{UPDATED}.
@c for @code{DJGPP} Version 2.03.
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.
* Invocation::                  Invoking @code{djasm}.
* Reference::                   Assembler language reference.
* Examples::                    Programming examples.
* Contributors::                Contributors.
@c * Index::                    Keyword index.
@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

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

@c @display
To paraphrase DJ:
``This is an @emph{UNREVIEWED} and @emph{UNGUARANTEED} document
describing @strong{some} of the aspects of @code{djasm}.
It might describe @code{djasm}, but then again, it might not.''
@c @end display

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.

@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
@sc{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.

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}}.

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

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,
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.

The first task, therefore, in making a version 2.x of @sc{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.
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
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.

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.

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

@menu
* Features::                    What @code{djasm} can do.
* Differences::                 Differences from other assemblers.
* Omissions and 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

Despite many limitations and some glaring omissions,
@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 @sc{gpl} and comes
with @sc{djgpp} (@file{djdevXXX.zip}).
@item
@sc{gcc}/@sc{gas}-generated @code{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 @sc{c} code.
@item
Support for @sc{c}-style structures and unions.
@item
Most instructions and addressing modes are supported
(a few are still missing).
@item
Full 32-bit addressing.
@end itemize

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

There are some important differences between @code{djasm} and
other assemblers, such as @sc{gas} (the GNU Assembler) and
@sc{nasm} (Netwide Assembler).

@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.
@item
@code{djasm} generates 16-bit code, @sc{gas} generates 32-bit code,
and @sc{nasm} can generate both 16- and 32-bit code.
@item
@code{djasm} is incompletely documented and has incomplete opcode support;
@sc{gas} and @sc{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 @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.
@end itemize

@comment node-name, next, previous, up
@node Omissions and 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 general-purpose assembler, you
should consider @sc{gas} or @sc{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 @sc{nasm} instead?)
@item
Macros.
@item
Complete documentation.

@item
Finish omf support (do you still want that, DJ?).
@item
Enums (Done!).
@item
Better symbol handling (allow forward references in most expressions).
@item
Better section support---first stage, being able to swap between .text,
.data and .bss at will; later, maybe `real' segment support (esp 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 @sc{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.
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 @sc{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 @sc{gas} @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 @sc{gas}, or a
16/32-bit assembler like @sc{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} @sc{gpl}) 16-bit assembler.
@item
To keep a project compatible with the spirit of @sc{djgpp},
without requiring the use of @sc{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 Reference
@chapter The @code{djasm} Language

@menu
* Syntax::                      Assembler syntax.
* Directives::                  Assembler directives.
@end menu

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

As a general rule, @code{djasm} uses the @sc{tasm}/@sc{masm}
ordering of operands, and usually the same instruction names.

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 @sc{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 Directives
@section Assembler Directives

@menu
* General::                     General directives.
* Data::                        Data directives.
* Structures and Unions::       Structures and unions.
* Prefixes::                    Segment override prefixes.
@end menu

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

@table @code

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

Emit bytes (if necessary) so that the program counter @sc{cs:ip}
(denoted by `.') is a multiple of @var{boundary}
(i.e., such that @sc{cs:ip} % @var{boundary} == 0).
The argument @var{fill} specifies what bytes to emit;
the default is 0x90 (@sc{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 @sc{c} string.
Multiple @code{.copyright} directives concatenate.
This directive is currently supported only for the @file{.exe} output format.

@item .id
Usage:  .id

Emit an @sc{rcs}-style identification string into the instruction stream.
The id has the form:

@c use `@w{Id}' below to prevent RCS from recognizing the keyword.
@c the `Cederqvist' uses `$@asis{}Author$' constructions; does it matter?
@c NB 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.
@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
(e.g., the output from @code{gcc -c foo.c}).
Currently supports only i386 @code{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
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
output image by emitting the appropriate number of zeros---this means
that the @code{.bss} section from the @code{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 @sc{ip} to @var{offset}.
The @sc{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
@sc{sp} to the current value of the instruction pointer @sc{ip}.

@item .start
Usage:  .start

For @file{.exe} files only, sets the initial value of the instruction
pointer @sc{ip} to the current value of the program counter @sc{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.

@c @end table
@c End table here to avoid excessive indentation of following table.

@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

@enumerate a
@item
The first 0x100 bytes of the program are 0x90 (@sc{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
@subsection Data Directives

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 @sc{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 and Unions
@subsection Structures and Unions

The following directives provide support for @sc{c}-style @code{struct}
and @code{union} constructs.

@table @code

@item .struct
Start a structure.

@item .union
Start a union.

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

@end table

In their usage, @code{.struct} is the same as @code{struct} in @sc{c},
and @code{.union} is the same as @code{union} in @sc{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
@c        src_offset      .struct FARPTR ; @code{.union} would also be valid here
        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, but this
practice can be confusing and is 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.
@c (and note that the above message about @code{.struct} and @code{.union}
@c applies here as well).
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

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 @sc{psp} structure or some of the @sc{dos}
system tables).

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

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{.segXX} prefixes seem to be most appropriate when used with
the string instructions such as @code{movs}, @code{stos}, etc.).

@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.
* 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 @samp{hello.asm},
then make a @sc{dos} @file{.com} executable using the command

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

@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!  

@itemize @bullet{}
@item @email{fighteer@@cs.com,John M. Aldrich}
@item @email{billc@@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{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

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

Here be the index (eventually).

@bye
@end ignore