mirror/nasm
2
0
Fork 0
mirror of https://github.com/netwide-assembler/nasm.git synced 2024-11-27 08:10:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

doc: latex -- Initial import

Browse Source 
It is an initial import for conversion of our documentation
to latex format. Note that latex additional packages needs
to be preinstalled, xelatex is used for pdf generation.

While I've been very carefull while converting the docs there
is a big probability that some indices might be screwed so
we need to review everything once again.

Then we need to create a converter for html backend, I started
working on it but didn't successed yet and I fear won't have
enough spare time in near future.

Also we need to autogenerate instruction table and warnings
from insns.dat and probably from scanning nasm sources.

To build nasm.pdf just run

	make -C doc/latex/

it doesn't require configuration and rather a standalone
builder out of our traditional build engine.

Signed-off-by: Cyrill Gorcunov <gorcunov@gmail.com>
This commit is contained in:
Cyrill Gorcunov 2019-03-31 19:33:08 +03:00
parent 982186a1a3
commit a384068a04
23 changed files with 11598 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/latex/.gitignore vendored Normal file
View File

@ -0,0 +1,2 @@
.git-ignore/
*.swp

66
doc/latex/Makefile Normal file
View File

@ -0,0 +1,66 @@
.PHONY: all .FORCE
.DEFAULT_GOAL := all
ifeq ($(strip $(V)),)
E := @echo
Q := @
else
E := @\#
Q :=
endif
export E Q
define msg-gen
$(E) " GEN " $(1)
endef
define msg-clean
$(E) " CLEAN " $(1)
endef
RM ?= rm -f
XELATEX ?= xelatex
XELATEX-OPTS ?= -output-driver="xdvipdfmx -V 3" -8bit
tex-d += src/16bit.tex
tex-d += src/32bit.tex
tex-d += src/64bit.tex
tex-d += src/changelog.tex
tex-d += src/contact.tex
tex-d += src/directive.tex
tex-d += src/idxconf.ist
tex-d += src/inslist.tex
tex-d += src/intro.tex
tex-d += src/language.tex
tex-d += src/macropkg.tex
tex-d += src/mixsize.tex
tex-d += src/nasmlogo.eps
tex-d += src/ndisasm.tex
tex-d += src/outfmt.tex
tex-d += src/preproc.tex
tex-d += src/running.tex
tex-d += src/source.tex
tex-d += src/trouble.tex
tex-d += src/version.tex
tex-y += src/nasm.tex
$(tex-y): $(tex-d)
@true
nasm.pdf: $(tex-y) .FORCE
$(call msg-gen,$@)
$(Q) $(XELATEX) $(XELATEX-OPTS) $^
$(Q) $(XELATEX) $(XELATEX-OPTS) $^
all-y += nasm.pdf
# Default target
all: $(all-y)
clean:
$(call msg-clean,nasm)
$(Q) $(RM) ./nasm.aux ./nasm.idx ./nasm.ilg ./nasm.ind ./nasm.log
$(Q) $(RM) ./nasm.out ./nasm.pdf ./nasm.toc
# Disable implicit rules in _this_ Makefile.
.SUFFIXES:

868
doc/latex/src/16bit.tex Normal file
View File

@ -0,0 +1,868 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{16bit}{Writing 16-bit Code (DOS, Windows 3/3.1)}
This chapter attempts to cover some of the common issues encountered
when writing 16-bit code to run under \code{MS-DOS} or \code{Windows 3.x}.
It covers how to link programs to produce \code{.EXE} or \code{.COM} files,
how to write \code{.SYS} device drivers, and how to interface assembly
language code with 16-bit C compilers and with Borland Pascal.
\xsection{exefiles}{Producing \codeindex{.EXE} Files}
Any large program written under DOS needs to be built as a \code{.EXE}
file: only \code{.EXE} files have the necessary internal structure
required to span more than one 64K segment. \textindex{Windows} programs,
also, have to be built as \code{.EXE} files, since Windows does not
support the \code{.COM} format.
In general, you generate \code{.EXE} files by using the \code{obj} output
format to produce one or more \codeindex{.OBJ} files, and then linking
them together using a linker. However, NASM also supports the direct
generation of simple DOS \code{.EXE} files using the \code{bin} output
format (by using \code{DB} and \code{DW} to construct the \code{.EXE} file
header), and a macro package is supplied to do this. Thanks to
Yann Guidon for contributing the code for this.
NASM may also support \code{.EXE} natively as another output format in
future releases.
\xsubsection{objexe}{Using the \code{obj} Format To Generate \code{.EXE} Files}
This section describes the usual method of generating \code{.EXE} files
by linking \code{.OBJ} files together.
Most 16-bit programming language packages come with a suitable
linker; if you have none of these, there is a free linker called
\textindex{VALX}\index{linker!VALX}, available as a part of
CC386 compiler on \href{http://ladsoft.tripod.com/cc386\_compiler.html}
{ladsoft.tripod.com}.
There is another `free' linker (though this one doesn't come with
sources) called \textindex{FREELINK}\index{linker!FREELINK}, available
from \href{http://www.pcorner.com/tpc/old/3-101.html}{www.pcorner.com}.
A third, \textindex{djlink}, written by DJ Delorie, is available at
\href{http://www.delorie.com/djgpp/16bit/djlink/}{www.delorie.com}.
A fourth linker, \textindex{ALINK}\index{linker!ALINK}, written by
Anthony A.J. Williams, is available at \href{http://alink.sourceforge.net}
{alink.sourceforge.net}.
When linking several \code{.OBJ} files into a \code{.EXE} file, you should
ensure that exactly one of them has a start point defined (using the
\index{program entry point}\codeindex{..start} special symbol defined by the
\code{obj} format: see \nref{dotdotstart}). If no module defines a start
point, the linker will not know what value to give the entry-point
field in the output file header; if more than one defines a start
point, the linker will not know \emph{which} value to use.
An example of a NASM source file which can be assembled to a
\code{.OBJ} file and linked on its own to a \code{.EXE} is given here. It
demonstrates the basic principles of defining a stack, initialising
the segment registers, and declaring a start point. This file is
also provided in the \index{test subdirectory}\code{test} subdirectory of
the NASM archives, under the name \code{objexe.asm}.
\begin{lstlisting}
segment code
..start:
mov ax,data
mov ds,ax
mov ax,stack
mov ss,ax
mov sp,stacktop
\end{lstlisting}
This initial piece of code sets up \code{DS} to point to the data
segment, and initializes \code{SS} and \code{SP} to point to the top of
the provided stack. Notice that interrupts are implicitly disabled
for one instruction after a move into \code{SS}, precisely for this
situation, so that there's no chance of an interrupt occurring
between the loads of \code{SS} and \code{SP} and not having a stack to
execute on.
Note also that the special symbol \code{..start} is defined at the
beginning of this code, which means that will be the entry point
into the resulting executable file.
\begin{lstlisting}
mov dx,hello
mov ah,9
int 0x21
\end{lstlisting}
The above is the main program: load \code{DS:DX} with a pointer to the
greeting message (\code{hello} is implicitly relative to the segment
\code{data}, which was loaded into \code{DS} in the setup code, so the
full pointer is valid), and call the DOS print-string function.
\begin{lstlisting}
mov ax,0x4c00
int 0x21
\end{lstlisting}
This terminates the program using another DOS system call.
\begin{lstlisting}
segment data
hello: db 'hello, world', 13, 10, '$'
\end{lstlisting}
The data segment contains the string we want to display.
\begin{lstlisting}
segment stack stack
resb 64
stacktop:
\end{lstlisting}
The above code declares a stack segment containing 64 bytes of
uninitialized stack space, and points \code{stacktop} at the top of it.
The directive \code{segment stack stack} defines a segment \emph{called}
\code{stack}, and also of \emph{type} \code{STACK}. The latter is not
necessary to the correct running of the program, but linkers are
likely to issue warnings or errors if your program has no segment of
type \code{STACK}.
The above file, when assembled into a \code{.OBJ} file, will link on
its own to a valid \code{.EXE} file, which when run will print `hello,
world' and then exit.
\xsubsection{binexe}{Using the \code{bin} Format To Generate \code{.EXE} Files}
The \code{.EXE} file format is simple enough that it's possible to
build a \code{.EXE} file by writing a pure-binary program and sticking
a 32-byte header on the front. This header is simple enough that it
can be generated using \code{DB} and \code{DW} commands by NASM itself,
so that you can use the \code{bin} output format to directly generate
\code{.EXE} files.
Included in the NASM archives, in the \index{misc subdirectory}\code{misc}
subdirectory, is a file \codeindex{exebin.mac} of macros. It defines three
macros: \codeindex{EXE\_begin}, \codeindex{EXE\_stack} and
\codeindex{EXE\_end}.
To produce a \code{.EXE} file using this method, you should start by
using \code{\%include} to load the \code{exebin.mac} macro package into
your source file. You should then issue the \code{EXE\_begin} macro call
(which takes no arguments) to generate the file header data. Then
write code as normal for the \code{bin} format - you can use all three
standard sections \code{.text}, \code{.data} and \code{.bss}. At the end of
the file you should call the \code{EXE\_end} macro (again, no arguments),
which defines some symbols to mark section sizes, and these symbols
are referred to in the header code generated by \code{EXE\_begin}.
In this model, the code you end up writing starts at \code{0x100}, just
like a \code{.COM} file - in fact, if you strip off the 32-byte header
from the resulting \code{.EXE} file, you will have a valid \code{.COM}
program. All the segment bases are the same, so you are limited to a
64K program, again just like a \code{.COM} file. Note that an \code{ORG}
directive is issued by the \code{EXE\_begin} macro, so you should not
explicitly issue one of your own.
You can't directly refer to your segment base value, unfortunately,
since this would require a relocation in the header, and things
would get a lot more complicated. So you should get your segment
base by copying it out of \code{CS} instead.
On entry to your \code{.EXE} file, \code{SS:SP} are already set up to
point to the top of a 2Kb stack. You can adjust the default stack
size of 2Kb by calling the \code{EXE\_stack} macro. For example, to
change the stack size of your program to 64 bytes, you would call
\code{EXE\_stack 64}.
A sample program which generates a \code{.EXE} file in this way is
given in the \code{test} subdirectory of the NASM archive, as
\code{binexe.asm}.
\xsection{comfiles}{Producing \codeindex{.COM} Files}
While large DOS programs must be written as \code{.EXE} files, small
ones are often better written as \code{.COM} files. \code{.COM} files are
pure binary, and therefore most easily produced using the \code{bin}
output format.
\xsubsection{combinfmt}{Using the \code{bin} Format To Generate \code{.COM} Files}
\code{.COM} files expect to be loaded at offset \code{100h} into their
segment (though the segment may change). Execution then begins at
\indexcode{ORG}\code{100h}, i.e. right at the start of the program.
So to write a \code{.COM} program, you would create a source file
looking like
\begin{lstlisting}
org 100h
section .text
start:
; put your code here
section .data
; put data items here
section .bss
; put uninitialized data here
\end{lstlisting}
The \code{bin} format puts the \code{.text} section first in the file,
so you can declare data or BSS items before beginning to write code if
you want to and the code will still end up at the front of the file
where it belongs.
The BSS (uninitialized data) section does not take up space in the
\code{.COM} file itself: instead, addresses of BSS items are resolved
to point at space beyond the end of the file, on the grounds that
this will be free memory when the program is run. Therefore you
should not rely on your BSS being initialized to all zeros when you
run.
To assemble the above program, you should use a command line like
\begin{lstlisting}
nasm myprog.asm -fbin -o myprog.com
\end{lstlisting}
The \code{bin} format would produce a file called \code{myprog} if no
explicit output file name were specified, so you have to override it
and give the desired file name.
\xsubsection{comobjfmt}{Using the \code{obj} Format To Generate \code{.COM} Files}
If you are writing a \code{.COM} program as more than one module, you
may wish to assemble several \code{.OBJ} files and link them together
into a \code{.COM} program. You can do this, provided you have a linker
capable of outputting \code{.COM} files directly (\textindex{TLINK} does this),
or alternatively a converter program such as \codeindex{EXE2BIN} to
transform the \code{.EXE} file output from the linker into a \code{.COM}
file.
If you do this, you need to take care of several things:
\begin{itemize}
\item{The first object file containing code should start its code
segment with a line like \code{RESB 100h}. This is to ensure
that the code begins at offset \code{100h} relative to the beginning
of the code segment, so that the linker or converter program does
not have to adjust address references within the file when generating
the \code{.COM} file. Other assemblers use an \codeindex{ORG} directive
for this purpose, but \code{ORG} in NASM is a format-specific directive
to the \code{bin} output format, and does not mean the same thing as
it does in MASM-compatible assemblers.}
\item{You don't need to define a stack segment.}
\item{All your segments should be in the same group, so that every time
your code or data references a symbol offset, all offsets are
relative to the same segment base. This is because, when a \code{.COM}
file is loaded, all the segment registers contain the same value.}
\end{itemize}
\xsection{sysfiles}{Producing \codeindex{.SYS} Files}
\textindex{MS-DOS device drivers} - \code{.SYS} files - are pure binary files,
similar to \code{.COM} files, except that they start at origin zero
rather than \code{100h}. Therefore, if you are writing a device driver
using the \code{bin} format, you do not need the \code{ORG} directive,
since the default origin for \code{bin} is zero. Similarly, if you are
using \code{obj}, you do not need the \code{RESB 100h} at the start of
your code segment.
\code{.SYS} files start with a header structure, containing pointers to
the various routines inside the driver which do the work. This
structure should be defined at the start of the code segment, even
though it is not actually code.
For more information on the format of \code{.SYS} files, and the data
which has to go in the header structure, a list of books is given in
the Frequently Asked Questions list for the newsgroup
\href{news:comp.os.msdos.programmer}{comp.os.msdos.programmer}.
\xsection{16c}{Interfacing to 16-bit C Programs}
This section covers the basics of writing assembly routines that
call, or are called from, C programs. To do this, you would
typically write an assembly module as a \code{.OBJ} file, and link it
with your C modules to produce a \textindex{mixed-language program}.
\xsubsection{16cunder}{External Symbol Names}
\index{C symbol names}\index{underscore!in C symbols}C compilers have the
convention that the names of all global symbols (functions or data)
they define are formed by prefixing an underscore to the name as it
appears in the C program. So, for example, the function a C
programmer thinks of as \code{printf} appears to an assembly language
programmer as \code{\_printf}. This means that in your assembly
programs, you can define symbols without a leading underscore, and
not have to worry about name clashes with C symbols.
If you find the underscores inconvenient, you can define macros to
replace the \code{GLOBAL} and \code{EXTERN} directives as follows:
\begin{lstlisting}
%macro cglobal 1
global _%1
%define %1 _%1
%endmacro
%macro cextern 1
extern _%1
%define %1 _%1
%endmacro
\end{lstlisting}
(These forms of the macros only take one argument at a time; a
\code{\%rep} construct could solve this.)
If you then declare an external like this:
\begin{lstlisting}
cextern printf
\end{lstlisting}
then the macro will expand it as
\begin{lstlisting}
extern _printf
%define printf _printf
\end{lstlisting}
Thereafter, you can reference \code{printf} as if it was a symbol, and
the preprocessor will put the leading underscore on where necessary.
The \code{cglobal} macro works similarly. You must use \code{cglobal}
before defining the symbol in question, but you would have had to do
that anyway if you used \code{GLOBAL}.
Also see \nref{opt-pfix}.
\xsubsection{16cmodels}{\textindexlc{Memory Models}}
NASM contains no mechanism to support the various C memory models
directly; you have to keep track yourself of which one you are
writing for. This means you have to keep track of the following
things:
\begin{itemize}
\item{In models using a single code segment (tiny, small and compact),
functions are near. This means that function pointers, when stored
in data segments or pushed on the stack as function arguments, are
16 bits long and contain only an offset field (the \code{CS} register
never changes its value, and always gives the segment part of the
full function address), and that functions are called using ordinary
near \code{CALL} instructions and return using \code{RETN} (which, in
NASM, is synonymous with \code{RET} anyway). This means both that you
should write your own routines to return with \code{RETN}, and that you
should call external C routines with near \code{CALL} instructions.}
\item{In models using more than one code segment (medium, large and
huge), functions are far. This means that function pointers are 32
bits long (consisting of a 16-bit offset followed by a 16-bit
segment), and that functions are called using \code{CALL FAR} (or
\code{CALL seg:offset}) and return using \code{RETF}. Again, you should
therefore write your own routines to return with \code{RETF} and use
\code{CALL FAR} to call external routines.}
\item{In models using a single data segment (tiny, small and medium),
data pointers are 16 bits long, containing only an offset field (the
\code{DS} register doesn't change its value, and always gives the
segment part of the full data item address).}
\item{In models using more than one data segment (compact, large and
huge), data pointers are 32 bits long, consisting of a 16-bit offset
followed by a 16-bit segment. You should still be careful not to
modify \code{DS} in your routines without restoring it afterwards, but
\code{ES} is free for you to use to access the contents of 32-bit data
pointers you are passed.}
\item{The huge memory model allows single data items to exceed 64K in
size. In all other memory models, you can access the whole of a data
item just by doing arithmetic on the offset field of the pointer you
are given, whether a segment field is present or not; in huge model,
you have to be more careful of your pointer arithmetic.}
\item{In most memory models, there is a \emph{default} data segment, whose
segment address is kept in \code{DS} throughout the program. This data
segment is typically the same segment as the stack, kept in \code{SS},
so that functions' local variables (which are stored on the stack)
and global data items can both be accessed easily without changing
\code{DS}. Particularly large data items are typically stored in other
segments. However, some memory models (though not the standard
ones, usually) allow the assumption that \code{SS} and \code{DS} hold the
same value to be removed. Be careful about functions' local
variables in this latter case.}
\end{itemize}
In models with a single code segment, the segment is called \codeindex{\_TEXT},
so your code segment must also go by this name in order to be linked into the
same place as the main code segment. In models with a single data segment,
or with a default data segment, it is called \codeindex{\_DATA}.
\xsubsection{16cfunc}{Function Definitions and Function Calls}
\index{functions!C calling convention}The \textindex{C calling convention}
in 16-bit programs is as follows. In the following description, the
words \emph{caller} and \emph{callee} are used to denote the function
doing the calling and the function which gets called.
\begin{itemize}
\item{The caller pushes the function's parameters on the stack, one
after another, in reverse order (right to left, so that the first
argument specified to the function is pushed last).}
\item{The caller then executes a \code{CALL} instruction to pass control
to the callee. This \code{CALL} is either near or far depending on the
memory model.}
\item{The callee receives control, and typically (although this is not
actually necessary, in functions which do not need to access their
parameters) starts by saving the value of \code{SP} in \code{BP} so as to
be able to use \code{BP} as a base pointer to find its parameters on
the stack. However, the caller was probably doing this too, so part
of the calling convention states that \code{BP} must be preserved by
any C function. Hence the callee, if it is going to set up \code{BP} as
a \emph{\textindex{frame pointer}}, must push the previous value first.}
\item{The callee may then access its parameters relative to \code{BP}.
The word at \code{[BP]} holds the previous value of \code{BP} as it was
pushed; the next word, at \code{[BP+2]}, holds the offset part of the
return address, pushed implicitly by \code{CALL}. In a small-model
(near) function, the parameters start after that, at \code{[BP+4]}; in
a large-model (far) function, the segment part of the return address
lives at \code{[BP+4]}, and the parameters begin at \code{[BP+6]}. The
leftmost parameter of the function, since it was pushed last, is
accessible at this offset from \code{BP}; the others follow, at
successively greater offsets. Thus, in a function such as \code{printf}
which takes a variable number of parameters, the pushing of the
parameters in reverse order means that the function knows where to
find its first parameter, which tells it the number and type of the
remaining ones.}
\item{The callee may also wish to decrease \code{SP} further, so as to
allocate space on the stack for local variables, which will then be
accessible at negative offsets from \code{BP}.}
\item{The callee, if it wishes to return a value to the caller, should
leave the value in \code{AL}, \code{AX} or \code{DX:AX} depending
on the size of the value. Floating-point results are sometimes
(depending on the compiler) returned in \code{ST0}.}
\item{Once the callee has finished processing, it restores \code{SP} from
\code{BP} if it had allocated local stack space, then pops the previous
value of \code{BP}, and returns via \code{RETN} or \code{RETF} depending on
memory model.}
\item{When the caller regains control from the callee, the function
parameters are still on the stack, so it typically adds an immediate
constant to \code{SP} to remove them (instead of executing a number of
slow \code{POP} instructions). Thus, if a function is accidentally
called with the wrong number of parameters due to a prototype
mismatch, the stack will still be returned to a sensible state since
the caller, which \emph{knows} how many parameters it pushed, does the
removing.}
\end{itemize}
It is instructive to compare this calling convention with that for
Pascal programs (described in \nref{16bpfunc}). Pascal has
a simpler convention, since no functions have variable numbers of parameters.
Therefore the callee knows how many parameters it should have been
passed, and is able to deallocate them from the stack itself by
passing an immediate argument to the \code{RET} or \code{RETF}
instruction, so the caller does not have to do it. Also, the
parameters are pushed in left-to-right order, not right-to-left,
which means that a compiler can give better guarantees about
sequence points without performance suffering.
Thus, you would define a function in C style in the following way.
The following example is for small model:
\begin{lstlisting}
global _myfunc
_myfunc:
push bp
mov bp,sp
sub sp,0x40 ; 64 bytes of local stack space
mov bx,[bp+4] ; first parameter to function
; some more code
mov sp,bp ; undo "sub sp,0x40" above
pop bp
ret
\end{lstlisting}
For a large-model function, you would replace \code{RET} by \code{RETF},
and look for the first parameter at \code{[BP+6]} instead of
\code{[BP+4]}. Of course, if one of the parameters is a pointer, then
the offsets of \emph{subsequent} parameters will change depending on
the memory model as well: far pointers take up four bytes on the
stack when passed as a parameter, whereas near pointers take up two.
At the other end of the process, to call a C function from your
assembly code, you would do something like this:
\begin{lstlisting}
extern _printf
; and then, further down...
push word [myint] ; one of my integer variables
push word mystring ; pointer into my data segment
call _printf
add sp,byte 4 ; `byte' saves space
; then those data items...
segment _DATA
myint dw 1234
mystring db 'This number -> %d <- should be 1234',10,0
\end{lstlisting}
This piece of code is the small-model assembly equivalent of the C
code
\begin{lstlisting}
int myint = 1234;
printf("This number -> %d <- should be 1234\n", myint);
\end{lstlisting}
In large model, the function-call code might look more like this. In
this example, it is assumed that \code{DS} already holds the segment
base of the segment \code{\_DATA}. If not, you would have to initialize
it first.
\begin{lstlisting}
push word [myint]
push word seg mystring ; Now push the segment, and...
push word mystring ; ... offset of "mystring"
call far _printf
add sp,byte 6
\end{lstlisting}
The integer value still takes up one word on the stack, since large
model does not affect the size of the \code{int} data type. The first
argument (pushed last) to \code{printf}, however, is a data pointer,
and therefore has to contain a segment and offset part. The segment
should be stored second in memory, and therefore must be pushed
first. (Of course, \code{PUSH DS} would have been a shorter instruction
than \code{PUSH WORD SEG mystring}, if \code{DS} was set up as the above
example assumed.) Then the actual call becomes a far call, since
functions expect far calls in large model; and \code{SP} has to be
increased by 6 rather than 4 afterwards to make up for the extra
word of parameters.
\xsubsection{16cdata}{Accessing Data Items}
To get at the contents of C variables, or to declare variables which
C can access, you need only declare the names as \code{GLOBAL} or
\code{EXTERN}. (Again, the names require leading underscores, as stated
in \nref{16cunder}.) Thus, a C variable declared as \code{int i}
can be accessed from assembler as
\begin{lstlisting}
extern _i
mov ax,[_i]
\end{lstlisting}
And to declare your own integer variable which C programs can access
as \code{extern int j}, you do this (making sure you are assembling in
the \code{\_DATA} segment, if necessary):
\begin{lstlisting}
global _j
_j dw 0
\end{lstlisting}
To access a C array, you need to know the size of the components of
the array. For example, \code{int} variables are two bytes long, so if
a C program declares an array as \code{int a[10]}, you can access
\code{a[3]} by coding \code{mov ax,[\_a+6]}. (The byte offset 6 is obtained
by multiplying the desired array index, 3, by the size of the array
element, 2.) The sizes of the C base types in 16-bit compilers are:
1 for \code{char}, 2 for \code{short} and \code{int}, 4 for \code{long}
and \code{float}, and 8 for \code{double}.
To access a C \textindex{data structure}, you need to know the offset from
the base of the structure to the field you are interested in. You
can either do this by converting the C structure definition into a
NASM structure definition (using \codeindex{STRUC}), or by calculating the
one offset and using just that.
To do either of these, you should read your C compiler's manual to
find out how it organizes data structures. NASM gives no special
alignment to structure members in its own \code{STRUC} macro, so you
have to specify alignment yourself if the C compiler generates it.
Typically, you might find that a structure like
\begin{lstlisting}
struct {
char c;
int i;
} foo;
\end{lstlisting}
might be four bytes long rather than three, since the \code{int} field
would be aligned to a two-byte boundary. However, this sort of
feature tends to be a configurable option in the C compiler, either
using command-line options or \code{\#pragma} lines, so you have to find
out how your own compiler does it.
\xsubsection{16cmacro}{\codeindex{c16.mac}: Helper Macros for the 16-bit C Interface}
Included in the NASM archives, in the \index{misc subdirectory}\code{misc}
directory, is a file \code{c16.mac} of macros. It defines three macros:
\codeindex{proc}, \codeindex{arg} and \codeindex{endproc}. These are intended
to be used for C-style procedure definitions, and they automate a lot of
the work involved in keeping track of the calling convention.
(An alternative, TASM compatible form of \code{arg} is also now built
into NASM's preprocessor. See \nref{stackrel} for details.)
An example of an assembly function using the macro set is given
here:
\begin{lstlisting}
proc _nearproc
%$i arg
%$j arg
mov ax,[bp + %$i]
mov bx,[bp + %$j]
add ax,[bx]
endproc
\end{lstlisting}
This defines \code{\_nearproc} to be a procedure taking two arguments,
the first (\code{i}) an integer and the second (\code{j}) a pointer to an
integer. It returns \code{i + *j}.
Note that the \code{arg} macro has an \code{EQU} as the first line of its
expansion, and since the label before the macro call gets prepended
to the first line of the expanded macro, the \code{EQU} works, defining
\code{\%\$i} to be an offset from \code{BP}. A context-local variable is
used, local to the context pushed by the \code{proc} macro and popped
by the \code{endproc} macro, so that the same argument name can be used
in later procedures. Of course, you don't \emph{have} to do that.
The macro set produces code for near functions (tiny, small and
compact-model code) by default. You can have it generate far
functions (medium, large and huge-model code) by means of coding
\indexcode{FARCODE}\code{\%define FARCODE}. This changes the kind of
return instruction generated by \code{endproc}, and also changes the
starting point for the argument offsets. The macro set contains no
intrinsic dependency on whether data pointers are far or not.
\code{arg} can take an optional parameter, giving the size of the
argument. If no size is given, 2 is assumed, since it is likely that
many function parameters will be of type \code{int}.
The large-model equivalent of the above function would look like this:
\begin{lstlisting}
%define FARCODE
proc _farproc
%$i arg
%$j arg 4
mov ax,[bp + %$i]
mov bx,[bp + %$j]
mov es,[bp + %$j + 2]
add ax,[bx]
endproc
\end{lstlisting}
This makes use of the argument to the \code{arg} macro to define a
parameter of size 4, because \code{j} is now a far pointer. When we
load from \code{j}, we must load a segment and an offset.
\xsection{16bp}{Interfacing to \textindex{Borland Pascal} Programs}
Interfacing to Borland Pascal programs is similar in concept to
interfacing to 16-bit C programs. The differences are:
\begin{itemize}
\item{The leading underscore required for interfacing to C programs is
not required for Pascal.}
\item{The memory model is always large: functions are far, data
pointers are far, and no data item can be more than 64K long.
(Actually, some functions are near, but only those functions that
are local to a Pascal unit and never called from outside it. All
assembly functions that Pascal calls, and all Pascal functions that
assembly routines are able to call, are far.) However, all static
data declared in a Pascal program goes into the default data
segment, which is the one whose segment address will be in \code{DS}
when control is passed to your assembly code. The only things that
do not live in the default data segment are local variables (they
live in the stack segment) and dynamically allocated variables. All
data \emph{pointers}, however, are far.}
\item{The function calling convention is different - described below.}
\item{Some data types, such as strings, are stored differently.}
\item{There are restrictions on the segment names you are allowed to
use - Borland Pascal will ignore code or data declared in a segment
it doesn't like the name of. The restrictions are described below.}
\end{itemize}
\xsubsection{16bpfunc}{The Pascal Calling Convention}
\index{functions!Pascal calling convention}\index{Pascal calling
convention}The 16-bit Pascal calling convention is as follows. In
the following description, the words \emph{caller} and \emph{callee} are
used to denote the function doing the calling and the function which
gets called.
\begin{itemize}
\item{The caller pushes the function's parameters on the stack, one
after another, in normal order (left to right, so that the first
argument specified to the function is pushed first).}
\item{The caller then executes a far \code{CALL} instruction to pass
control to the callee.}
\item{The callee receives control, and typically (although this is not
actually necessary, in functions which do not need to access their
parameters) starts by saving the value of \code{SP} in \code{BP} so as to
be able to use \code{BP} as a base pointer to find its parameters on
the stack. However, the caller was probably doing this too, so part
of the calling convention states that \code{BP} must be preserved by
any function. Hence the callee, if it is going to set up \code{BP} as a
\textindex{frame pointer}, must push the previous value first.}
\item{The callee may then access its parameters relative to \code{BP}.
The word at \code{[BP]} holds the previous value of \code{BP} as it was
pushed. The next word, at \code{[BP+2]}, holds the offset part of the
return address, and the next one at \code{[BP+4]} the segment part. The
parameters begin at \code{[BP+6]}. The rightmost parameter of the
function, since it was pushed last, is accessible at this offset
from \code{BP}; the others follow, at successively greater offsets.}
\item{The callee may also wish to decrease \code{SP} further, so as to
allocate space on the stack for local variables, which will then be
accessible at negative offsets from \code{BP}.}
\item{The callee, if it wishes to return a value to the caller, should
leave the value in \code{AL}, \code{AX} or \code{DX:AX} depending on
the size of the value. Floating-point results are returned in \code{ST0}.
Results of type \code{Real} (Borland's own custom floating-point data
type, not handled directly by the FPU) are returned in \code{DX:BX:AX}.
To return a result of type \code{String}, the caller pushes a pointer
to a temporary string before pushing the parameters, and the callee
places the returned string value at that location. The pointer is
not a parameter, and should not be removed from the stack by the
\code{RETF} instruction.}
\item{Once the callee has finished processing, it restores \code{SP} from
\code{BP} if it had allocated local stack space, then pops the previous
value of \code{BP}, and returns via \code{RETF}. It uses the form of
\code{RETF} with an immediate parameter, giving the number of bytes
taken up by the parameters on the stack. This causes the parameters
to be removed from the stack as a side effect of the return
instruction.}
\item{When the caller regains control from the callee, the function
parameters have already been removed from the stack, so it needs to
do nothing further.}
\end{itemize}
Thus, you would define a function in Pascal style, taking two
\code{Integer}-type parameters, in the following way:
\begin{lstlisting}
global myfunc
myfunc:
push bp
mov bp,sp
sub sp,0x40 ; 64 bytes of local stack space
mov bx,[bp+8] ; first parameter to function
mov bx,[bp+6] ; second parameter to function
; some more code
mov sp,bp ; undo "sub sp,0x40" above
pop bp
retf 4 ; total size of params is 4
\end{lstlisting}
At the other end of the process, to call a Pascal function from your
assembly code, you would do something like this:
\begin{lstlisting}
extern SomeFunc
; and then, further down...
push word seg mystring ; Now push the segment, and...
push word mystring ; ... offset of "mystring"
push word [myint] ; one of my variables
call far SomeFunc
\end{lstlisting}
This is equivalent to the Pascal code
\begin{lstlisting}
procedure SomeFunc(String: PChar; Int: Integer);
SomeFunc(@mystring, myint);
\end{lstlisting}
\xsubsection{16bpseg}{Borland Pascal Segment Name Restrictions}
\index{segment names!Borland Pascal}
Since Borland Pascal's internal unit file format is completely
different from \code{OBJ}, it only makes a very sketchy job of actually
reading and understanding the various information contained in a
real \code{OBJ} file when it links that in. Therefore an object file
intended to be linked to a Pascal program must obey a number of
restrictions:
\begin{itemize}
\item{Procedures and functions must be in a segment whose name is
either \code{CODE}, \code{CSEG}, or something ending in
\code{\_TEXT}.}
\item{initialized data must be in a segment whose name is either
\code{CONST} or something ending in \code{\_DATA}.}
\item{Uninitialized data must be in a segment whose name is either
\code{DATA}, \code{DSEG}, or something ending in \code{\_BSS}.}
\item{Any other segments in the object file are completely ignored.
\code{GROUP} directives and segment attributes are also ignored.}
\end{itemize}
\xsubsection{16bpmacro}{Using \codeindex{c16.mac} With Pascal Programs}
The \code{c16.mac} macro package, described in \nref{16cmacro},
can also be used to simplify writing functions to be called from Pascal
programs, if you code \indexcode{PASCAL}\code{\%define PASCAL}. This
definition ensures that functions are far (it implies \codeindex{FARCODE}),
and also causes procedure return instructions to be generated with
an operand.
Defining \code{PASCAL} does not change the code which calculates the
argument offsets; you must declare your function's arguments in
reverse order. For example:
\begin{lstlisting}
%define PASCAL
proc _pascalproc
%$j arg 4
%$i arg
mov ax,[bp + %$i]
mov bx,[bp + %$j]
mov es,[bp + %$j + 2]
add ax,[bx]
endproc
\end{lstlisting}
This defines the same routine, conceptually, as the example in
\nref{16cmacro}: it defines a function taking two arguments,
an integer and a pointer to an integer, which returns the sum of
the integer and the contents of the pointer. The only difference
between this code and the large-model C version is that \code{PASCAL}
is defined instead of \code{FARCODE}, and that the arguments are
declared in reverse order.

539
doc/latex/src/32bit.tex Normal file
View File

@ -0,0 +1,539 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{32bit}{Writing 32-bit Code (Unix, Win32, DJGPP)}
This chapter attempts to cover some of the common issues involved
when writing 32-bit code, to run under \textindex{Win32} or Unix,
or to be linked with C code generated by a Unix-style C compiler such as
\textindex{DJGPP}. It covers how to write assembly code to interface with
32-bit C routines, and how to write position-independent code for
shared libraries.
Almost all 32-bit code, and in particular all code running under
\code{Win32}, \code{DJGPP} or any of the PC Unix variants, runs in
\index{flat memory model}\emph{flat} memory model. This means that
the segment registers and paging have already been set up to give
you the same 32-bit 4Gb address space no matter what segment you
work relative to, and that you should ignore all segment registers
completely. When writing flat-model application code, you never
need to use a segment override or modify any segment register,
and the code-section addresses you pass to \code{CALL} and
\code{JMP} live in the same address space as the data-section addresses
you access your variables by and the stack-section addresses you access
local variables and procedure parameters by. Every address is 32 bits
long and contains only an offset part.
\xsection{32c}{Interfacing to 32-bit C Programs}
A lot of the discussion in \nref{16c}, about interfacing to
16-bit C programs, still applies when working in 32 bits. The absence of
memory models or segmentation worries simplifies things a lot.
\xsubsection{32cunder}{External Symbol Names}
Most 32-bit C compilers share the convention used by 16-bit
compilers, that the names of all global symbols (functions or data)
they define are formed by prefixing an underscore to the name as it
appears in the C program. However, not all of them do: the \code{ELF}
specification states that C symbols do \emph{not} have a leading
underscore on their assembly-language names.
The older Linux \code{a.out} C compiler, all \code{Win32} compilers,
\code{DJGPP}, and \code{NetBSD} and \code{FreeBSD}, all use the leading
underscore; for these compilers, the macros \code{cextern} and
\code{cglobal}, as given in \nref{16cunder}, will still work.
For \code{ELF}, though, the leading underscore should not be used.
See also \nref{opt-pfix}.
\xsubsection{32cfunc}{Function Definitions and Function Calls}
\index{functions!C calling convention}The \textindex{C calling convention}
in 32-bit programs is as follows. In the following description,
the words \emph{caller} and \emph{callee} are used to denote
the function doing the calling and the function which gets called.
\begin{itemize}
\item{The caller pushes the function's parameters on the stack, one
after another, in reverse order (right to left, so that the first
argument specified to the function is pushed last).}
\item{The caller then executes a near \code{CALL} instruction to pass
control to the callee.}
\item{The callee receives control, and typically (although this
is not actually necessary, in functions which do not need to
access their parameters) starts by saving the value of \code{ESP}
in \code{EBP} so as to be able to use \code{EBP} as a base pointer
to find its parameters on the stack. However, the caller was
probably doing this too, so part of the calling convention states
that \code{EBP} must be preserved by any C function. Hence the
callee, if it is going to set up \code{EBP} as a \textindex{frame
pointer}, must push the previous value first.}
\item{The callee may then access its parameters relative to \code{EBP}.
The doubleword at \code{[EBP]} holds the previous value of
\code{EBP} as it was pushed; the next doubleword, at \code{[EBP+4]},
holds the return address, pushed implicitly by \code{CALL}.
The parameters start after that, at \code{[EBP+8]}. The leftmost
parameter of the function, since it was pushed last, is accessible
at this offset from \code{EBP}; the others follow, at successively
greater offsets. Thus, in a function such as \code{printf} which
takes a variable number of parameters, the pushing of the
parameters in reverse order means that the function knows where
to find its first parameter, which tells it the number and type
of the remaining ones.}
\item{The callee may also wish to decrease \code{ESP} further, so as
to allocate space on the stack for local variables, which will
then be accessible at negative offsets from \code{EBP}.}
\item{The callee, if it wishes to return a value to the caller,
should leave the value in \code{AL}, \code{AX} or \code{EAX}
depending on the size of the value. Floating-point results
are typically returned in \code{ST0}.}
\item{Once the callee has finished processing, it restores
\code{ESP} from \code{EBP} if it had allocated local stack space,
then pops the previous value of \code{EBP}, and returns via
\code{RET} (equivalently, \code{RETN}).}
\item{When the caller regains control from the callee, the function
parameters are still on the stack, so it typically adds an
immediate constant to \code{ESP} to remove them (instead of
executing a number of slow \code{POP} instructions). Thus,
if a function is accidentally called with the wrong number
of parameters due to a prototype mismatch, the stack will
still be returned to a sensible state since the caller, which
\emph{knows} how many parameters it pushed, does the
removing.}
\end{itemize}
There is an alternative calling convention used by Win32 programs
for Windows API calls, and also for functions called \emph{by} the
Windows API such as window procedures: they follow what Microsoft
calls the \code{\_\_stdcall} convention. This is slightly closer to the
Pascal convention, in that the callee clears the stack by passing a
parameter to the \code{RET} instruction. However, the parameters are
still pushed in right-to-left order.
Thus, you would define a function in C style in the following way:
\begin{lstlisting}
global _myfunc
_myfunc:
push ebp
mov ebp,esp
sub esp,0x40 ; 64 bytes of local stack space
mov ebx,[ebp+8] ; first parameter to function
; some more code
leave ; mov esp,ebp / pop ebp
ret
\end{lstlisting}
At the other end of the process, to call a C function from your
assembly code, you would do something like this:
\begin{lstlisting}
extern _printf
; and then, further down...
push dword [myint] ; one of my integer variables
push dword mystring ; pointer into my data segment
call _printf
add esp,byte 8 ; `byte' saves space
; then those data items...
segment _DATA
myint dd 1234
mystring db 'This number -> %d <- should be 1234',10,0
\end{lstlisting}
This piece of code is the assembly equivalent of the C code
\begin{lstlisting}
int myint = 1234;
printf("This number -> %d <- should be 1234\n", myint);
\end{lstlisting}
\xsubsection{32cdata}{Accessing Data Items}
To get at the contents of C variables, or to declare variables which
C can access, you need only declare the names as \code{GLOBAL} or
\code{EXTERN}. (Again, the names require leading underscores, as stated
in \nref{32cunder}.) Thus, a C variable declared as \code{int i}
can be accessed from assembler as
\begin{lstlisting}
extern _i
mov eax,[_i]
\end{lstlisting}
And to declare your own integer variable which C programs can access
as \code{extern int j}, you do this (making sure you are assembling in
the \code{\_DATA} segment, if necessary):
\begin{lstlisting}
global _j
_j dd 0
\end{lstlisting}
To access a C array, you need to know the size of the components of
the array. For example, \code{int} variables are four bytes long, so if
a C program declares an array as \code{int a[10]}, you can access
\code{a[3]} by coding \code{mov ax,[\_a+12]}. (The byte offset 12 is
obtained by multiplying the desired array index, 3, by the size of
the array element, 4.) The sizes of the C base types in 32-bit compilers
are: 1 for \code{char}, 2 for \code{short}, 4 for \code{int}, \code{long}
and \code{float}, and 8 for \code{double}. Pointers, being 32-bit
addresses, are also 4 bytes long.
To access a C \textindex{data structure}, you need to know the offset from
the base of the structure to the field you are interested in. You
can either do this by converting the C structure definition into a
NASM structure definition (using \code{STRUC}), or by calculating the
one offset and using just that.
To do either of these, you should read your C compiler's manual to
find out how it organizes data structures. NASM gives no special
alignment to structure members in its own \codeindex{STRUC} macro,
so you have to specify alignment yourself if the C compiler generates it.
Typically, you might find that a structure like
\begin{lstlisting}
struct {
char c;
int i;
} foo;
\end{lstlisting}
might be eight bytes long rather than five, since the \code{int} field
would be aligned to a four-byte boundary. However, this sort of
feature is sometimes a configurable option in the C compiler, either
using command-line options or \code{\#pragma} lines, so you have to find
out how your own compiler does it.
\xsubsection{32cmacro}{\codeindex{c32.mac}: Helper Macros for the 32-bit C Interface}
Included in the NASM archives, in the \index{misc directory}\code{misc}
directory, is a file \code{c32.mac} of macros. It defines three macros:
\codeindex{proc}, \codeindex{arg} and \codeindex{endproc}. These are
intended to be used for C-style procedure definitions, and they automate
a lot of the work involved in keeping track of the calling convention.
An example of an assembly function using the macro set is given
here:
\begin{lstlisting}
proc _proc32
%$i arg
%$j arg
mov eax,[ebp + %$i]
mov ebx,[ebp + %$j]
add eax,[ebx]
endproc
\end{lstlisting}
This defines \code{\_proc32} to be a procedure taking two arguments, the
first (\code{i}) an integer and the second (\code{j}) a pointer to an
integer. It returns \code{i + *j}.
Note that the \code{arg} macro has an \code{EQU} as the first line of its
expansion, and since the label before the macro call gets prepended
to the first line of the expanded macro, the \code{EQU} works, defining
\code{\%\$i} to be an offset from \code{BP}. A context-local variable is
used, local to the context pushed by the \code{proc} macro and popped
by the \code{endproc} macro, so that the same argument name can be used
in later procedures. Of course, you don't \emph{have} to do that.
\code{arg} can take an optional parameter, giving the size of the
argument. If no size is given, 4 is assumed, since it is likely that
many function parameters will be of type \code{int} or pointers.
\xsection{picdll}{Writing NetBSD/FreeBSD/OpenBSD and Linux/ELF}
\index{Shared Libraries}
\code{ELF} replaced the older \code{a.out} object file format under Linux
because it contains support for \textindex{position-independent code}
(\textindex{PIC}), which makes writing shared libraries much easier. NASM
supports the \code{ELF} position-independent code features, so you can
write Linux \code{ELF} shared libraries in NASM.
\textindex{NetBSD}, and its close cousins \textindex{FreeBSD} and
\textindex{OpenBSD}, take a different approach by hacking PIC support
into the \code{a.out} format. NASM supports this as the \codeindex{aoutb}
output format, so you can write \textindex{BSD} shared libraries in
NASM too.
The operating system loads a PIC shared library by memory-mapping
the library file at an arbitrarily chosen point in the address space
of the running process. The contents of the library's code section
must therefore not depend on where it is loaded in memory.
Therefore, you cannot get at your variables by writing code like
this:
\begin{lstlisting}
mov eax,[myvar] ; WRONG
\end{lstlisting}
Instead, the linker provides an area of memory called the
\textindex{global offset table}, or \textindex{GOT}; the GOT is situated
at a constant distance from your library's code, so if you can find out
where your library is loaded (which is typically done using a \code{CALL}
and \code{POP} combination), you can obtain the address of the GOT, and
you can then load the addresses of your variables out of linker-generated
entries in the GOT.
The \emph{data} section of a PIC shared library does not have these
restrictions: since the data section is writable, it has to be
copied into memory anyway rather than just paged in from the library
file, so as long as it's being copied it can be relocated too. So
you can put ordinary types of relocation in the data section without
too much worry (but see \nref{picglobal} for a caveat).
\xsubsection{picgot}{Obtaining the Address of the GOT}
Each code module in your shared library should define the GOT as an
external symbol:
\begin{lstlisting}
extern _GLOBAL_OFFSET_TABLE_ ; in ELF
extern __GLOBAL_OFFSET_TABLE_ ; in BSD a.out
\end{lstlisting}
At the beginning of any function in your shared library which plans
to access your data or BSS sections, you must first calculate the
address of the GOT. This is typically done by writing the function
in this form:
\begin{lstlisting}
func:
push ebp
mov ebp,esp
push ebx
call .get_GOT
.get_GOT:
pop ebx
add ebx,_GLOBAL_OFFSET_TABLE_+$$-.get_GOT wrt ..gotpc
; the function body comes here
mov ebx,[ebp-4]
mov esp,ebp
pop ebp
ret
\end{lstlisting}
(For BSD, again, the symbol \code{\_GLOBAL\_OFFSET\_TABLE} requires a
second leading underscore.)
The first two lines of this function are simply the standard C
prologue to set up a stack frame, and the last three lines are
standard C function epilogue. The third line, and the fourth to last
line, save and restore the \code{EBX} register, because PIC shared
libraries use this register to store the address of the GOT.
The interesting bit is the \code{CALL} instruction and the following
two lines. The \code{CALL} and \code{POP} combination obtains the address
of the label \code{.get\_GOT}, without having to know in advance where
the program was loaded (since the \code{CALL} instruction is encoded
relative to the current position). The \code{ADD} instruction makes use
of one of the special PIC relocation types: \textindex{GOTPC relocation}.
With the \codeindex{WRT ..gotpc} qualifier specified, the symbol
referenced (here \code{\_GLOBAL\_OFFSET\_TABLE\_}, the special symbol
assigned to the GOT) is given as an offset from the beginning of the
section. (Actually, \code{ELF} encodes it as the offset from the operand
field of the \code{ADD} instruction, but NASM simplifies this
deliberately, so you do things the same way for both \code{ELF} and
\code{BSD}.) So the instruction then \emph{adds} the beginning of the
section, to get the real address of the GOT, and subtracts the value of
\code{.get\_GOT} which it knows is in \code{EBX}. Therefore, by the time
that instruction has finished, \code{EBX} contains the address of the GOT.
If you didn't follow that, don't worry: it's never necessary to
obtain the address of the GOT by any other means, so you can put
those three instructions into a macro and safely ignore them:
\begin{lstlisting}
%macro get_GOT 0
call %%getgot
%%getgot:
pop ebx
add ebx,_GLOBAL_OFFSET_TABLE_+$$-%%getgot wrt ..gotpc
%endmacro
\end{lstlisting}
\xsubsection{piclocal}{Finding Your Local Data Items}
Having got the GOT, you can then use it to obtain the addresses of
your data items. Most variables will reside in the sections you have
declared; they can be accessed using the \index{GOTOFF relocation}
\code{..gotoff} special \indexcode{WRT ..gotoff}\code{WRT} type. The
way this works is like this:
\begin{lstlisting}
lea eax,[ebx+myvar wrt ..gotoff]
\end{lstlisting}
The expression \code{myvar wrt ..gotoff} is calculated, when the shared
library is linked, to be the offset to the local variable \code{myvar}
from the beginning of the GOT. Therefore, adding it to \code{EBX} as
above will place the real address of \code{myvar} in \code{EAX}.
If you declare variables as \code{GLOBAL} without specifying a size for
them, they are shared between code modules in the library, but do
not get exported from the library to the program that loaded it.
They will still be in your ordinary data and BSS sections, so you
can access them in the same way as local variables, using the above
\code{..gotoff} mechanism.
Note that due to a peculiarity of the way BSD \code{a.out} format
handles this relocation type, there must be at least one non-local
symbol in the same section as the address you're trying to access.
\xsubsection{picextern}{Finding External and Common Data Items}
If your library needs to get at an external variable (external to
the \emph{library}, not just to one of the modules within it), you must
use the \index{GOT relocations}\indexcode{WRT ..got}\code{..got} type
to get at it. The \code{..got} type, instead of giving you the offset from
the GOT base to the variable, gives you the offset from the GOT base to
a GOT \emph{entry} containing the address of the variable. The linker
will set up this GOT entry when it builds the library, and the
dynamic linker will place the correct address in it at load time. So
to obtain the address of an external variable \code{extvar} in \code{EAX},
you would code
\begin{lstlisting}
mov eax,[ebx+extvar wrt ..got]
\end{lstlisting}
This loads the address of \code{extvar} out of an entry in the GOT. The
linker, when it builds the shared library, collects together every
relocation of type \code{..got}, and builds the GOT so as to ensure it
has every necessary entry present.
Common variables must also be accessed in this way.
\xsubsection{picglobal}{Exporting Symbols to the Library User}
If you want to export symbols to the user of the library, you have
to declare whether they are functions or data, and if they are data,
you have to give the size of the data item. This is because the
dynamic linker has to build \index{PLT}\textindex{procedure linkage table}
entries for any exported functions, and also moves exported data
items away from the library's data section in which they were
declared.
So to export a function to users of the library, you must use
\begin{lstlisting}
global func:function ; declare it as a function
func:
push ebp
; etc.
\end{lstlisting}
And to export a data item such as an array, you would have to code
\begin{lstlisting}
global array:data array.end-array ; give the size too
array: resd 128
.end:
\end{lstlisting}
Be careful: If you export a variable to the library user, by
declaring it as \code{GLOBAL} and supplying a size, the variable will
end up living in the data section of the main program, rather than
in your library's data section, where you declared it. So you will
have to access your own global variable with the \code{..got} mechanism
rather than \code{..gotoff}, as if it were external (which,
effectively, it has become).
Equally, if you need to store the address of an exported global in
one of your data sections, you can't do it by means of the standard
sort of code:
\begin{lstlisting}
dataptr: dd global_data_item ; WRONG
\end{lstlisting}
NASM will interpret this code as an ordinary relocation, in which
\code{global\_data\_item} is merely an offset from the beginning of the
\code{.data} section (or whatever); so this reference will end up
pointing at your data section instead of at the exported global
which resides elsewhere.
Instead of the above code, then, you must write
\begin{lstlisting}
dataptr: dd global_data_item wrt ..sym
\end{lstlisting}
which makes use of the special \code{WRT} type \indexcode{WRT ..sym}
\code{..sym} to instruct NASM to search the symbol table for a particular
symbol at that address, rather than just relocating by section base.
Either method will work for functions: referring to one of your
functions by means of
\begin{lstlisting}
funcptr: dd my_function
\end{lstlisting}
will give the user the address of the code you wrote, whereas
\begin{lstlisting}
funcptr: dd my_function wrt ..sym
\end{lstlisting}
will give the address of the procedure linkage table for the
function, which is where the calling program will \emph{believe} the
function lives. Either address is a valid way to call the function.
\xsubsection{picproc}{Calling Procedures Outside the Library}
Calling procedures outside your shared library has to be done by
means of a \textindex{procedure linkage table}, or \textindex{PLT}.
The PLT is placed at a known offset from where the library is loaded,
so the library code can make calls to the PLT in a position-independent
way. Within the PLT there is code to jump to offsets contained in
the GOT, so function calls to other shared libraries or to routines
in the main program can be transparently passed off to their real
destinations.
To call an external routine, you must use another special PIC
relocation type, \index{PLT relocations}\codeindex{WRT ..plt}. This is
much easier than the GOT-based ones: you simply replace calls such as
\code{CALL printf} with the PLT-relative version \code{CALL printf WRT
..plt}.
\xsubsection{link}{Generating the Library File}
Having written some code modules and assembled them to \code{.o} files,
you then generate your shared library with a command such as
\begin{lstlisting}
ld -shared -o library.so module1.o module2.o # for ELF
ld -Bshareable -o library.so module1.o module2.o # for BSD
\end{lstlisting}
For ELF, if your shared library is going to reside in system
directories such as \code{/usr/lib} or \code{/lib}, it is usually worth
using the \codeindex{-soname} flag to the linker, to store the final
library file name, with a version number, into the library:
\begin{lstlisting}
ld -shared -soname library.so.1 -o library.so.1.2 *.o
\end{lstlisting}
You would then copy \code{library.so.1.2} into the library directory,
and create \code{library.so.1} as a symbolic link to it.

204
doc/latex/src/64bit.tex Normal file
View File

@ -0,0 +1,204 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{64bit}{Writing 64-bit Code (Unix, Win64)}
This chapter attempts to cover some of the common issues involved when
writing 64-bit code, to run under \textindex{Win64} or Unix. It covers
how to write assembly code to interface with 64-bit C routines, and
how to write position-independent code for shared libraries.
All 64-bit code uses a flat memory model, since segmentation is not
available in 64-bit mode. The one exception is the \code{FS} and
\code{GS} registers, which still add their bases.
Position independence in 64-bit mode is significantly simpler, since
the processor supports \code{RIP}-relative addressing directly; see the
\code{REL} keyword (\nref{effaddr}). On most 64-bit platforms,
it is probably desirable to make that the default, using the directive
\code{DEFAULT REL} (\nref{default}).
64-bit programming is relatively similar to 32-bit programming, but
of course pointers are 64 bits long; additionally, all existing
platforms pass arguments in registers rather than on the stack.
Furthermore, 64-bit platforms use SSE2 by default for floating point.
Please see the ABI documentation for your platform.
64-bit platforms differ in the sizes of the C/C++ fundamental
datatypes, not just from 32-bit platforms but from each other. If a
specific size data type is desired, it is probably best to use the
types defined in the standard C header \code{<inttypes.h>}.
All known 64-bit platforms except some embedded platforms require that
the stack is 16-byte aligned at the entry to a function. In order to
enforce that, the stack pointer (\code{RSP}) needs to be aligned on an
\code{odd} multiple of 8 bytes before the \code{CALL} instruction.
In 64-bit mode, the default instruction size is still 32 bits. When
loading a value into a 32-bit register (but not an 8- or 16-bit
register), the upper 32 bits of the corresponding 64-bit register are
set to zero.
\xsection{reg64}{Register Names in 64-bit Mode}
NASM uses the following names for general-purpose registers in 64-bit
mode, for 8-, 16-, 32- and 64-bit references, respectively:
\begin{lstlisting}
AL/AH, CL/CH, DL/DH, BL/BH, SPL, BPL, SIL, DIL, R8B-R15B
AX, CX, DX, BX, SP, BP, SI, DI, R8W-R15W
EAX, ECX, EDX, EBX, ESP, EBP, ESI, EDI, R8D-R15D
RAX, RCX, RDX, RBX, RSP, RBP, RSI, RDI, R8-R15
\end{lstlisting}
This is consistent with the AMD documentation and most other
assemblers. The Intel documentation, however, uses the names
\code{R8L-R15L} for 8-bit references to the higher registers. It is
possible to use those names by definiting them as macros; similarly,
if one wants to use numeric names for the low 8 registers, define them
as macros. The standard macro package \code{altreg} (see
\nref{pkgaltreg}) can be used for this purpose.
\xsection{id64}{Immediates and Displacements in 64-bit Mode}
In 64-bit mode, immediates and displacements are generally only 32
bits wide. NASM will therefore truncate most displacements and
immediates to 32 bits.
The only instruction which takes a full \textindex{64-bit immediate} is:
\begin{lstlisting}
mov reg64,imm64
\end{lstlisting}
NASM will produce this instruction whenever the programmer uses
\code{MOV} with an immediate into a 64-bit register. If this is not
desirable, simply specify the equivalent 32-bit register, which will
be automatically zero-extended by the processor, or specify the
immediate as \code{DWORD}:
\begin{lstlisting}
mov rax,foo ; 64-bit immediate
mov rax,qword foo ; (identical)
mov eax,foo ; 32-bit immediate, zero-extended
mov rax,dword foo ; 32-bit immediate, sign-extended
\end{lstlisting}
The length of these instructions are 10, 5 and 7 bytes, respectively.
If optimization is enabled and NASM can determine at assembly time
that a shorter instruction will suffice, the shorter instruction will
be emitted unless of course \code{STRICT QWORD} or \code{STRICT DWORD}
is specified (see \nref{strict}):
\begin{lstlisting}
mov rax,1 ; Assembles as "mov eax,1" (5 bytes)
mov rax,strict qword 1 ; Full 10-byte instruction
mov rax,strict dword 1 ; 7-byte instruction
mov rax,symbol ; 10 bytes, not known at assembly time
lea rax,[rel symbol] ; 7 bytes, usually preferred by the ABI
\end{lstlisting}
Note that \code{lea rax,[rel symbol]} is position-independent, whereas
\code{mov rax,symbol} is not. Most ABIs prefer or even require
position-independent code in 64-bit mode. However, the \code{MOV}
instruction is able to reference a symbol anywhere in the 64-bit
address space, whereas \code{LEA} is only able to access a symbol within
within 2 GB of the instruction itself (see below.)
The only instructions which take a full \textindex{64-bit displacement}
is loading or storing, using \code{MOV}, \code{AL}, \code{AX}, \code{EAX}
or \code{RAX} (but no other registers) to an absolute 64-bit address.
Since this is a relatively rarely used instruction (64-bit code
generally uses relative addressing), the programmer has to explicitly
declare the displacement size as \code{ABS QWORD}:
\begin{lstlisting}
default abs
mov eax,[foo] ; 32-bit absolute disp, sign-extended
mov eax,[a32 foo] ; 32-bit absolute disp, zero-extended
mov eax,[qword foo] ; 64-bit absolute disp
default rel
mov eax,[foo] ; 32-bit relative disp
mov eax,[a32 foo] ; d:o, address truncated to 32 bits(!)
mov eax,[qword foo] ; error
mov eax,[abs qword foo] ; 64-bit absolute disp
\end{lstlisting}
A sign-extended absolute displacement can access from -2 GB to +2 GB;
a zero-extended absolute displacement can access from 0 to 4 GB.
\xsection{unix64}{Interfacing to 64-bit C Programs (Unix)}
On Unix, the 64-bit ABI as well as the x32 ABI (32-bit ABI with the
CPU in 64-bit mode) is defined by the documents at
\href{http://www.nasm.us/abi/unix64}{http://www.nasm.us/abi/unix64}
Although written for AT\&T-syntax assembly, the concepts apply equally
well for NASM-style assembly. What follows is a simplified summary.
The first six integer arguments (from the left) are passed in \code{RDI},
\code{RSI}, \code{RDX}, \code{RCX}, \code{R8}, and \code{R9}, in that
order. Additional integer arguments are passed on the stack. These
registers, plus \code{RAX}, \code{R10} and \code{R11} are destroyed
by function calls, and thus are available for use by the function
without saving.
Integer return values are passed in \code{RAX} and \code{RDX},
in that order.
Floating point is done using SSE registers, except for \code{long double},
which is 80 bits (\code{TWORD}) on most platforms (Android is
one exception; there \code{long double} is 64 bits and treated the same
as \code{double}.) Floating-point arguments are passed in \code{XMM0} to
\code{XMM7}; return is \code{XMM0} and \code{XMM1}. \code{long double}
are passed on the stack, and returned in \code{ST0} and \code{ST1}.
All SSE and x87 registers are destroyed by function calls.
On 64-bit Unix, \code{long} is 64 bits.
Integer and SSE register arguments are counted separately, so
for the case of
\begin{lstlisting}
void foo(long a, double b, int c)
\end{lstlisting}
\code{a} is passed in \code{RDI}, \code{b} in \code{XMM0},
and \code{c} in \code{ESI}.
\xsection{win64}{Interfacing to 64-bit C Programs (Win64)}
The Win64 ABI is described by the document at
\href{http://www.nasm.us/abi/win64}{http://www.nasm.us/abi/win64}
What follows is a simplified summary.
The first four integer arguments are passed in \code{RCX}, \code{RDX},
\code{R8} and \code{R9}, in that order. Additional integer arguments are
passed on the stack. These registers, plus \code{RAX}, \code{R10} and
\code{R11} are destroyed by function calls, and thus are available for
use by the function without saving.
Integer return values are passed in \code{RAX} only.
Floating point is done using SSE registers, except for \code{long
double}. Floating-point arguments are passed in \code{XMM0}
to \code{XMM3}; return is \code{XMM0} only.
On Win64, \code{long} is 32 bits; \code{long long} or \code{\_int64}
is 64 bits.
Integer and SSE register arguments are counted together, so
for the case of
\begin{lstlisting}
void foo(long long a, double b, int c)
\end{lstlisting}
\code{a} is passed in \code{RCX}, \code{b} in \code{XMM1},
and \code{c} in \code{R8D}.

2304
doc/latex/src/changelog.tex Normal file
View File

File diff suppressed because it is too large Load Diff

111
doc/latex/src/contact.tex Normal file
View File

@ -0,0 +1,111 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{contact}{Contact Information}
\xsection{website}{Website}
NASM has a \textindex{website} at \href{http://www.nasm.us/}{http://www.nasm.us/}.
\textindexlc{New releases}, \textindex{release candidates}, and
\index{snapshots!daily development}\textindex{daily development snapshots}
of NASM are available from the official web site in source form as well
as binaries for a number of common platforms.
\xsubsection{forums}{User Forums}
Users of NASM may find the Forums on the website useful. These are,
however, not frequented much by the developers of NASM, so they are
not suitable for reporting bugs.
\xsubsection{develcom}{Development Community}
The development of NASM is coordinated primarily though the
\codeindex{nasm-devel} mailing list. If you wish to participate in
development of NASM, please join this mailing list. Subscription
links and archives of past posts are available on the website.
\xsection{bugs}{Reporting Bugs}
\index{bugs}
To report bugs in NASM, please use the \textindex{bug tracker} at
\href{http://www.nasm.us/}{http://www.nasm.us/} (click on "Bug Tracker"),
or if that fails then through one of the contacts in \nref{website}.
Please read \nref{qstart} first, and don't report the bug if it's
listed in there as a deliberate feature. (If you think the feature
is badly thought out, feel free to send us reasons why you think it
should be changed, but don't just send us mail saying `This is a
bug' if the documentation says we did it on purpose.) Then read
\nref{problems}, and don't bother reporting the bug if it's
listed there.
If you do report a bug, \emph{please} make sure your bug report includes
the following information:
\begin{itemize}
\item{What operating system you're running NASM under. Linux,
FreeBSD, NetBSD, MacOS X, Win16, Win32, Win64, MS-DOS, OS/2, VMS,
whatever.}
\item{If you compiled your own executable from a source archive, compiled
your own executable from \code{git}, used the standard distribution
binaries from the website, or got an executable from somewhere else
(e.g. a Linux distribution.) If you were using a locally built
executable, try to reproduce the problem using one of the standard
binaries, as this will make it easier for us to reproduce your problem
prior to fixing it.}
\item{Which version of NASM you're using, and exactly how you invoked
it. Give us the precise command line, and the contents of the
\code{NASMENV} environment variable if any.}
\item{Which versions of any supplementary programs you're using, and
how you invoked them. If the problem only becomes visible at link
time, tell us what linker you're using, what version of it you've
got, and the exact linker command line. If the problem involves
linking against object files generated by a compiler, tell us what
compiler, what version, and what command line or options you used.
(If you're compiling in an IDE, please try to reproduce the problem
with the command-line version of the compiler.)}
\item{If at all possible, send us a NASM source file which exhibits the
problem. If this causes copyright problems (e.g. you can only
reproduce the bug in restricted-distribution code) then bear in mind
the following two points: firstly, we guarantee that any source code
sent to us for the purposes of debugging NASM will be used \emph{only}
for the purposes of debugging NASM, and that we will delete all our
copies of it as soon as we have found and fixed the bug or bugs in
question; and secondly, we would prefer \emph{not} to be mailed large
chunks of code anyway. The smaller the file, the better. A
three-line sample file that does nothing useful \emph{except}
demonstrate the problem is much easier to work with than a
fully fledged ten-thousand-line program. (Of course, some errors
\emph{do} only crop up in large files, so this may not be possible.)}
\item{A description of what the problem actually \emph{is}. `It doesn't
work' is \emph{not} a helpful description! Please describe exactly what
is happening that shouldn't be, or what isn't happening that should.
Examples might be: `NASM generates an error message saying Line 3
for an error that's actually on Line 5'; `NASM generates an error
message that I believe it shouldn't be generating at all'; `NASM
fails to generate an error message that I believe it \emph{should} be
generating'; `the object file produced from this source code crashes
my linker'; `the ninth byte of the output file is 66 and I think it
should be 77 instead'.}
\item{If you believe the output file from NASM to be faulty, send it to
us. That allows us to determine whether our own copy of NASM
generates the same file, or whether the problem is related to
portability issues between our development platforms and yours. We
can handle binary files mailed to us as MIME attachments, uuencoded,
and even BinHex. Alternatively, we may be able to provide an FTP
site you can upload the suspect files to; but mailing them is easier
for us.}
\item{Any other information or data files that might be helpful. If,
for example, the problem involves NASM failing to generate an object
file while TASM can generate an equivalent file without trouble,
then send us \emph{both} object files, so we can see what TASM is doing
differently from us.}
\end{itemize}

541
doc/latex/src/directive.tex Normal file
View File

@ -0,0 +1,541 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{directive}{\textindexlc{Assembler Directives}}
NASM, though it attempts to avoid the bureaucracy of assemblers like
MASM and TASM, is nevertheless forced to support a \emph{few}
directives. These are described in this chapter.
NASM's directives come in two types: \index{directives!user-level}
\emph{user-level} directives and \index{directives!primitive}
\emph{primitive} directives. Typically, each directive has a
user-level form and a primitive form. In almost all cases, we
recommend that users use the user-level forms of the directives,
which are implemented as macros which call the primitive forms.
Primitive directives are enclosed in square brackets; user-level
directives are not.
In addition to the universal directives described in this chapter,
each object file format can optionally supply extra directives in
order to control particular features of that file format. These
\index{directives!format-specific}\emph{format-specific} directives are
documented along with the formats that implement them, in
\nref{outfmt}.
\xsection{bits}{\codeindex{BITS}: Specifying Target \textindexlc{Processor Mode}}
The \code{BITS} directive specifies whether NASM should generate code
\index{16-bit mode, versus 32-bit mode}designed to run on a processor
operating in 16-bit mode, 32-bit mode or 64-bit mode. The syntax is
\code{BITS XX}, where XX is 16, 32 or 64.
In most cases, you should not need to use \code{BITS} explicitly. The
\code{aout}, \code{coff}, \code{elf32}, \code{elf64}, \code{macho32},
\code{macho64}, \code{win32} and \code{win64} object formats, which
are designed for use in 32-bit or 64-bit operating systems, all cause
NASM to select 32-bit or 64-bit mode, respectively, by default.
The \code{obj} object format allows you to specify each segment
you define as either \code{USE16} or \code{USE32}, and NASM will
set its operating mode accordingly, so the use of the \code{BITS}
directive is once again unnecessary.
The most likely reason for using the \code{BITS} directive is to write
32-bit or 64-bit code in a flat binary file; this is because the \code{bin}
output format defaults to 16-bit mode in anticipation of it being
used most frequently to write DOS \code{.COM} programs, DOS \code{.SYS}
device drivers and boot loader software.
The \code{BITS} directive can also be used to generate code for
a different mode than the standard one for the output format.
You do \emph{not} need to specify \code{BITS 32} merely in order
to use 32-bit instructions in a 16-bit DOS program; if you do, the
assembler will generate incorrect code because it will be writing
code targeted at a 32-bit platform, to be run on a 16-bit one.
When NASM is in \code{BITS 16} mode, instructions which use 32-bit
data are prefixed with an 0x66 byte, and those referring to 32-bit
addresses have an 0x67 prefix. In \code{BITS 32} mode, the reverse is
true: 32-bit instructions require no prefixes, whereas instructions
using 16-bit data need an 0x66 and those working on 16-bit
addresses need an 0x67.
When NASM is in \code{BITS 64} mode, most instructions operate the same
as they do for \code{BITS 32} mode. However, there are 8 more general and
SSE registers, and 16-bit addressing is no longer supported.
The default address size is 64 bits; 32-bit addressing can be selected
with the 0x67 prefix. The default operand size is still 32 bits,
however, and the 0x66 prefix selects 16-bit operand size.
The \code{REX} prefix is used both to select 64-bit operand size, and
to access the new registers. NASM automatically inserts REX prefixes
when necessary.
When the \code{REX} prefix is used, the processor does not know how to
address the AH, BH, CH or DH (high 8-bit legacy) registers. Instead,
it is possible to access the the low 8-bits of the SP, BP SI and DI
registers as SPL, BPL, SIL and DIL, respectively; but only when the
REX prefix is used.
The \code{BITS} directive has an exactly equivalent primitive form,
\code{[BITS 16]}, \code{[BITS 32]} and \code{[BITS 64]}. The user-level
form is a macro which has no function other than to call the primitive form.
Note that the space is neccessary, e.g. \code{BITS32} will \emph{not} work!
\xsubsection{use163264}{\codeindex{USE16}, \codeindex{USE32}
and \codeindex{USE64}: Aliases for BITS}
The \code{USE16}, \code{USE32} and \code{USE64} directives can be used
in place of \code{BITS 16}, \code{BITS 32} and \code{BITS 64}, for
compatibility with other assemblers.
\xsection{default}{\codeindex{DEFAULT}: Change the assembler defaults}
The \code{DEFAULT} directive changes the assembler defaults. Normally,
NASM defaults to a mode where the programmer is expected to explicitly
specify most features directly. However, this is occasionally obnoxious,
as the explicit form is pretty much the only one one wishes to use.
Currently, \code{DEFAULT} can be set to \code{REL}, \code{ABS}, \code{BND}
and \code{NOBND}.
\xsubsection{relabs}{\codeindex{REL} and \codeindex{ABS}: RIP-relative addressing}
This sets whether registerless instructions in 64-bit mode are
\code{RIP}-relative or not. By default, they are absolute unless
overridden with the \codeindex{REL} specifier (see \nref{effaddr}).
However, if \code{DEFAULT REL} is specified, \code{REL} is default, unless
overridden with the \code{ABS} specifier, \emph{except when used with an
FS or GS segment override}.
The special handling of \code{FS} and \code{GS} overrides are due to the
fact that these registers are generally used as thread pointers or
other special functions in 64-bit mode, and generating
\code{RIP}-relative addresses would be extremely confusing.
\code{DEFAULT REL} is disabled with \code{DEFAULT ABS}.
\xsubsection{bndnobnd}{\codeindex{BND} and \codeindex{NOBND}: \code{BND} prefix}
If \code{DEFAULT BND} is set, all bnd-prefix available instructions
following this directive are prefixed with bnd. To override it,
\code{NOBND} prefix can be used.
\begin{lstlisting}
DEFAULT BND
call foo ; BND will be prefixed
nobnd call foo ; BND will NOT be prefixed
\end{lstlisting}
\code{DEFAULT NOBND} can disable \code{DEFAULT BND} and then
\code{BND} prefix will be added only when explicitly specified
in code.
\code{DEFAULT BND} is expected to be the normal configuration
for writing MPX-enabled code.
\xsection{section}{\codeindex{SECTION} or \codeindex{SEGMENT}: Changing and
\textindexlc{Defining Sections}}
\index{sections!changing}\index{sections!switching between}
The \code{SECTION} directive (\code{SEGMENT} is an exactly equivalent
synonym) changes which section of the output file the code you write
will be assembled into. In some object file formats, the number and
names of sections are fixed; in others, the user may make up as many
as they wish. Hence \code{SECTION} may sometimes give an error message,
or may define a new section, if you try to switch to a section that does
not (yet) exist.
The Unix object formats, and the \code{bin} object format (but see
\nref{multisec}), all support the \index{sections!standardized names}
standardized names \code{.text}, \code{.data} and \code{.bss} for the code,
data and uninitialized-data sections. The \code{obj} format, by contrast,
does not recognize these section names as being special, and indeed will
strip off the leading period of any section name that has one.
\xsubsection{sectmac}{The \codeindex{\_\_SECT\_\_} Macro}
The \code{SECTION} directive is unusual in that its user-level form
functions differently from its primitive form. The primitive form,
\code{[SECTION xyz]}, simply switches the current target section to the
one given. The user-level form, \code{SECTION xyz}, however, first
defines the single-line macro \code{\_\_SECT\_\_} to be the primitive
\code{[SECTION]} directive which it is about to issue, and then issues
it. So the user-level directive
\begin{lstlisting}
SECTION .text
\end{lstlisting}
expands to the two lines
\begin{lstlisting}
%define __SECT__ [SECTION .text]
[SECTION .text]
\end{lstlisting}
Users may find it useful to make use of this in their own macros.
For example, the \code{writefile} macro defined in \nref{mlmacgre}
can be usefully rewritten in the following more sophisticated form:
\begin{lstlisting}
%macro writefile 2+
[section .data]
%%str: db %2
%%endstr:
__SECT__
mov dx, %%str
mov cx, %%endstr-%%str
mov bx, %1
mov ah, 0x40
int 0x21
%endmacro
\end{lstlisting}
This form of the macro, once passed a string to output, first
switches temporarily to the data section of the file, using the
primitive form of the \code{SECTION} directive so as not to modify
\code{\_\_SECT\_\_}. It then declares its string in the data section,
and then invokes \code{\_\_SECT\_\_} to switch back to \emph{whichever}
section the user was previously working in. It thus avoids the need,
in the previous version of the macro, to include a \code{JMP} instruction
to jump over the data, and also does not fail if, in a complicated
\code{OBJ} format module, the user could potentially be assembling the
code in any of several separate code sections.
\xsection{absolute}{\codeindex{ABSOLUTE}: Defining Absolute Labels}
The \code{ABSOLUTE} directive can be thought of as an alternative form
of \code{SECTION}: it causes the subsequent code to be directed at no
physical section, but at the hypothetical section starting at the
given absolute address. The only instructions you can use in this
mode are the \code{RESB} family.
\code{ABSOLUTE} is used as follows:
\begin{lstlisting}
absolute 0x1A
kbuf_chr resw 1
kbuf_free resw 1
kbuf resw 16
\end{lstlisting}
This example describes a section of the PC BIOS data area, at
segment address 0x40: the above code defines \code{kbuf\_chr} to be
0x1A, \code{kbuf\_free} to be 0x1C, and \code{kbuf} to be 0x1E.
The user-level form of \code{ABSOLUTE}, like that of \code{SECTION},
redefines the \codeindex{\_\_SECT\_\_} macro when it is invoked.
\codeindex{STRUC} and \codeindex{ENDSTRUC} are defined as macros
which use \code{ABSOLUTE} (and also \code{\_\_SECT\_\_}).
\code{ABSOLUTE} doesn't have to take an absolute constant as an
argument: it can take an expression (actually, a \textindex{critical
expression}: see \nref{crit}) and it can be a value in a segment.
For example, a TSR can re-use its setup code as run-time BSS like this:
\begin{lstlisting}
org 100h ; it's a .COM program
jmp setup ; setup code comes last
; the resident part of the TSR goes here
; ...
setup:
; now write the code that installs the TSR here
; ...
absolute setup
runtimevar1 resw 1
runtimevar2 resd 20
tsr_end:
\end{lstlisting}
This defines some variables ``on top of'' the setup code, so that
after the setup has finished running, the space it took up can be
re-used as data storage for the running TSR. The symbol
\code{tsr\_end} can be used to calculate the total size of
the part of the TSR that needs to be made resident.
\xsection{extern}{\codeindex{EXTERN}: \textindexlc{Importing Symbols} from Other Modules}
\code{EXTERN} is similar to the MASM directive \code{EXTRN} and
the C keyword \code{extern}: it is used to declare a symbol which
is not defined anywhere in the module being assembled, but is assumed
to be defined in some other module and needs to be referred to by this
one. Not every object-file format can support external variables:
the \code{bin} format cannot.
The \code{EXTERN} directive takes as many arguments as you like.
Each argument is the name of a symbol:
\begin{lstlisting}
extern _printf
extern _sscanf,_fscanf
\end{lstlisting}
Some object-file formats provide extra features to the \code{EXTERN}
directive. In all cases, the extra features are used by suffixing a
colon to the symbol name followed by object-format specific text.
For example, the \code{obj} format allows you to declare that the
default segment base of an external should be the group \code{dgroup}
by means of the directive
\begin{lstlisting}
extern _variable:wrt dgroup
\end{lstlisting}
The primitive form of \code{EXTERN} differs from the user-level form
only in that it can take only one argument at a time: the support
for multiple arguments is implemented at the preprocessor level.
You can declare the same variable as \code{EXTERN} more than once: NASM
will quietly ignore the second and later redeclarations.
If a variable is declared both \code{GLOBAL} and \code{EXTERN}, or
if it is declared as \code{EXTERN} and then defined, it will be
treated as \code{GLOBAL}. If a variable is declared both as
\code{COMMON} and \code{EXTERN}, it will be treated as \code{COMMON}.
\xsection{global}{\codeindex{GLOBAL}: \textindexlc{Exporting Symbols} to Other Modules}
\code{GLOBAL} is the other end of \code{EXTERN}: if one module declares a
symbol as \code{EXTERN} and refers to it, then in order to prevent
linker errors, some other module must actually \emph{define} the
symbol and declare it as \code{GLOBAL}. Some assemblers use the name
\codeindex{PUBLIC} for this purpose.
\code{GLOBAL} uses the same syntax as \code{EXTERN}, except that it must
refer to symbols which \emph{are} defined in the same module as the
\code{GLOBAL} directive. For example:
\begin{lstlisting}
global _main
_main:
; some code
\end{lstlisting}
\code{GLOBAL}, like \code{EXTERN}, allows object formats to define private
extensions by means of a colon. The \code{elf} object format, for
example, lets you specify whether global data items are functions or
data:
\begin{lstlisting}
global hashlookup:function, hashtable:data
\end{lstlisting}
Like \code{EXTERN}, the primitive form of \code{GLOBAL} differs
from the user-level form only in that it can take only one argument
at a time.
\xsection{common}{\codeindex{COMMON}: Defining Common Data Areas}
The \code{COMMON} directive is used to declare \textindex{\emph{common
variables}}. A common variable is much like a global variable declared
in the uninitialized data section, so that
\begin{lstlisting}
common intvar 4
\end{lstlisting}
is similar in function to
\begin{lstlisting}
global intvar
section .bss
intvar resd 1
\end{lstlisting}
The difference is that if more than one module defines the same
common variable, then at link time those variables will be
\emph{merged}, and references to \code{intvar} in all modules
will point at the same piece of memory.
Like \code{GLOBAL} and \code{EXTERN}, \code{COMMON} supports
object-format specific extensions. For example, the \code{obj}
format allows common variables to be NEAR or FAR, and the \code{elf}
format allows you to specify the alignment requirements of
a common variable:
\begin{lstlisting}
common commvar 4:near ; works in OBJ
common intarray 100:4 ; works in ELF: 4 byte aligned
\end{lstlisting}
Once again, like \code{EXTERN} and \code{GLOBAL}, the primitive form of
\code{COMMON} differs from the user-level form only in that it can take
only one argument at a time.
\xsection{static}{\codeindex{STATIC}: Local Symbols within Modules}
Opposite to \code{EXTERN} and \code{GLOBAL}, \code{STATIC} is local
symbol, but should be named according to the global mangling rules
(named by analogy with the C keyword \code{static} as applied to
functions or global variables).
\begin{lstlisting}
static foo
foo:
; codes
\end{lstlisting}
Unlike \code{GLOBAL}, \code{STATIC} does not allow object formats
to accept private extensions mentioned in \nref{global}.
\xsection{mangling}{\codeindex{(G|L)PREFIX}, \codeindex{(G|L)POSTFIX}:
Mangling Symbols}
\code{PREFIX}, \code{GPREFIX}, \code{LPREFIX}, \code{POSTFIX},
\code{GPOSTFIX}, and \code{LPOSTFIX} directives can prepend or
append the given argument to a certain type of symbols. The directive
should be as a preprocess statement. Each usage is:
\begin{itemize}
\item{\code{PREFIX}|\code{GPREFIX}: Prepend the argument to all
\code{EXTERN} \code{COMMON}, \code{STATIC}, and
\code{GLOBAL} symbols}
\item{\code{LPREFIX}: Prepend the argument to all other symbols
such as Local Labels, and backend defined symbols}
\item{\code{POSTFIX}|\code{GPOSTFIX}: Append the argument to
all \code{EXTERN} \code{COMMON}, \code{STATIC}, and
\code{GLOBAL} symbols}
\item{\code{LPOSTFIX}: Append the argument to all other symbols
such as Local Labels, and backend defined symbols}
\end{itemize}
This is a macro implemented as a \code{\%pragma}:
\begin{lstlisting}
%pragma macho lprefix L_
\end{lstlisting}
Commandline option is also possible. See also \nref{opt-pfix}.
Some toolchains is aware of a particular prefix for its own optimization
options, such as code elimination. For instance, Mach-O backend has a
linker that uses a simplistic naming scheme to chunk up sections into a
meta section. When the \code{subsections\_via\_symbols} directive
(\nref{macho-ssvs}) is declared, each symbol is the start of a
separate block. The meta section is, then, defined to include sections
before the one that starts with a 'L'. \code{LPREFIX} is useful here to
mark all local symbols with the 'L' prefix to be excluded to the meta
section. It converts local symbols compatible with the particular
toolchain. Note that local symbols declared with \code{STATIC}
(\nref{static}) are excluded from the symbol mangling and also
not marked as global.
\xsection{gen-namespace}{\codeindex{OUTPUT}, \codeindex{DEBUG}:
Generic Namespaces}
\code{OUTPUT} and \code{DEBUG} are generic \code{\%pragma} namespaces
that are supposed to redirect to the current output and debug formats.
For example, when mangling local symbols via the generic namespace:
\begin{lstlisting}
%pragma output gprefix _
\end{lstlisting}
This is useful when the directive is needed to be output format
agnostic.
The example is also euquivalent to this, when the output format is
\code{elf}:
\begin{lstlisting}
%pragma elf gprefix _
\end{lstlisting}
\xsection{cpu}{\codeindex{CPU}: Defining CPU Dependencies}
The \code{CPU} directive restricts assembly to those instructions which
are available on the specified CPU.
Options are:
\begin{tabular}{ l l }
\code{CPU 8086} & Assemble only 8086 instruction set \\
\code{CPU 186} & Assemble instructions up to the 80186 instruction set \\
\code{CPU 286} & Assemble instructions up to the 286 instruction set \\
\code{CPU 386} & Assemble instructions up to the 386 instruction set \\
\code{CPU 486} & 486 instruction set \\
\code{CPU 586} & Pentium instruction set \\
\code{CPU PENTIUM} & Same as 586 \\
\code{CPU 686} & P6 instruction set \\
\code{CPU PPRO} & Same as 686 \\
\code{CPU P2} & Same as 686 \\
\code{CPU P3} & Pentium III (Katmai) instruction sets \\
\code{CPU KATMAI} & Same as P3 \\
\code{CPU P4} & Pentium 4 (Willamette) instruction set \\
\code{CPU WILLAMETTE} & Same as P4 \\
\code{CPU PRESCOTT} & Prescott instruction set \\
\code{CPU X64} & x86-64 (x64/AMD64/Intel 64) instruction set \\
\code{CPU IA64} & IA64 CPU (in x86 mode) instruction set \\
\end{tabular}
All options are case insensitive. All instructions will be selected
only if they apply to the selected CPU or lower. By default, all
instructions are available.
\xsection{float}{\codeindex{FLOAT}: Handling of \index{constants!floating-point}
floating-point constants}
By default, floating-point constants are rounded to nearest, and IEEE
denormals are supported. The following options can be set to alter
this behaviour:
\begin{tabular}{ l l }
\code{FLOAT DAZ} & Flush denormals to zero \\
\code{FLOAT NODAZ} & Do not flush denormals to zero (default) \\
\code{FLOAT NEAR} & Round to nearest (default) \\
\code{FLOAT UP} & Round up (toward +Infinity) \\
\code{FLOAT DOWN} & Round down (toward -Infinity) \\
\code{FLOAT ZERO} & Round toward zero \\
\code{FLOAT DEFAULT} & Restore default settings \\
\end{tabular}
The standard macros \codeindex{\_\_FLOAT\_DAZ\_\_},
\codeindex{\_\_FLOAT\_ROUND\_\_}, and \codeindex{\_\_FLOAT\_\_} contain
the current state, as long as the programmer has avoided the use
of the brackeded primitive form, (\code{[FLOAT]}).
\code{\_\_FLOAT\_\_} contains the full set of floating-point settings;
this value can be saved away and invoked later to restore the setting.
\xsection{asmdir-warning}{\codeindex{[WARNING]}: Enable or disable warnings}
The \code{[WARNING]} directive can be used to enable or disable classes
of warnings in the same way as the \code{-w} option, see \nref{opt-w}
for more details about warning classes.
\begin{itemize}
\item{\code{[warning +\emph{warning-class}]} enables warnings for
\emph{warning-class}}.
\item{\code{[warning -\emph{warning-class}]} disables warnings for
\emph{warning-class}}.
\item{\code{[warning *\emph{warning-class}]} restores \emph{warning-class} to
the original value, either the default value or as specified on the
command line.}
\item{\code{[warning push]} saves the current warning state on a stack.}
\item{\code{[warning pop]} restores the current warning state from the stack.}
\end{itemize}
The \code{[WARNING]} directive also accepts the \code{all}, \code{error} and
\code{error=}\emph{warning-class} specifiers.
No ``user form'' (without the brackets) currently exists.

9
doc/latex/src/idxconf.ist Normal file
View File

@ -0,0 +1,9 @@
%
% vim: ts=4 sw=4 et
%
headings_flag 1
heading_prefix "\\textcolor{hcolor}{\\textbf{"
heading_suffix "}}\\nopagebreak\n"
delim_0 " \\dotfill "
delim_1 " \\dotfill "
delim_2 " \\dotfill "

14
doc/latex/src/inslist.tex Normal file
View File

@ -0,0 +1,14 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{inslist}{\textindexlc{Instruction List}}
\xsection{inslistintro}{Introduction}
The following sections show the instructions which NASM currently supports. For each
instruction, there is a separate entry for each supported addressing mode. The third
column shows the processor type in which the instruction was introduced and,
when appropriate, one or more usage flags.
%
% FIXME: Read instruction list

55
doc/latex/src/intro.tex Normal file
View File

@ -0,0 +1,55 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{intro}{Introduction}
\xsection{whatis}{What Is NASM?}
The Netwide Assembler, NASM, is an 80x86 and x86-64 assembler designed
for portability and modularity. It supports a range of object file
formats, including Linux and ``*BSD a.out'', ``ELF'', ``COFF'',
``Mach-O'', 16-bit and 32-bit ``OBJ'' (OMF) format, ``Win32'' and
``Win64''. It will also output plain binary files, Intel hex and
Motorola S-Record formats. Its syntax is designed to be simple and
easy to understand, similar to the syntax in the Intel Software
Developer Manual with minimal complexity. It supports all currently
known x86 architectural extensions, and has strong support for macros.
NASM also comes with a set of utilities for handling the ``RDOFF''
custom object-file format.
\xsection{license}{License Conditions}
Please see the file \index{license} ``LICENSE'', supplied as part
of any NASM distribution archive, for the license conditions under
which you may use NASM. NASM is now under the so-called 2-clause
BSD license, also known as the simplified BSD license.
Copyright 1996-2017 the NASM Authors - All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
\begin{itemize}
\item{Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.}
\item{Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.}
\end{itemize}
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

945
doc/latex/src/language.tex Normal file
View File

@ -0,0 +1,945 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{lang}{The NASM Language}
\xsection{syntax}{Layout of a NASM Source Line}
Like most assemblers, each NASM source line contains (unless it
is a macro, a preprocessor directive or an assembler directive: see
\nref{preproc} and \nref{directive}) some combination
of the four fields
\begin{lstlisting}
label: instruction operands ; comment
\end{lstlisting}
As usual, most of these fields are optional; the presence or absence
of any combination of a label, an instruction and a comment is allowed.
Of course, the operand field is either required or forbidden by the
presence and nature of the instruction field.
NASM uses backslash (\code{\textbackslash}) as the line continuation character;
if a line ends with backslash, the next line is considered to be
a part of the backslash-ended line.
NASM places no restrictions on white space within a line: labels may
have white space before them, or instructions may have no space
before them, or anything. The \textindex{colon} after a label is also
optional. (Note that this means that if you intend to code \code{lodsb}
alone on a line, and type \code{lodab} by accident, then that's still a
valid source line which does nothing but define a label. Running
NASM with the command-line option \index{orphan-labels}\code{-w+orphan-labels}
will cause it to warn you if you define a label alone on a line without
a \textindex{trailing colon}.)
\textindex{Valid characters} in labels are letters, numbers, \code{\_},
\code{\$}, \code{\#}, \code{\@}, \code{~}, \code{.}, and \code{?}.
The only characters which may be used as the \emph{first} character of
an identifier are letters, \code{\.} (with special meaning: see
\nref{locallab}), \code{\_} and \code{?}.
An identifier may also be prefixed with a \codeindex{\$} to indicate
that it is intended to be read as an identifier and not a reserved word;
thus, if some other module you are linking with defines a symbol called
\code{eax}, you can refer to \code{\$eax} in NASM code to distinguish
the symbol from the register. Maximum length of an identifier is
4095 characters.
The instruction field may contain any machine instruction: Pentium
and P6 instructions, FPU instructions, MMX instructions and even
undocumented instructions are all supported. The instruction may be
prefixed by \code{LOCK}, \code{REP}, \code{REPE}/\code{REPZ},
\code{REPNE}/\code{REPNZ}, \code{XACQUIRE}/\code{XRELEASE} or
\code{BND}/\code{NOBND}, in the usual way. Explicit
\index{address-size!prefixes}address-size and \textindex{operand-size!prefixes}
\codeindex{A16}, \codeindex{A32}, \codeindex{A64}, \codeindex{O16}
and \codeindex{O32}, \codeindex{O64} are provided~-- one example of their
use is given in \nref{mixsize}. You can also use the name of a
\index{segment override}segment register as an instruction prefix: coding
\code{es mov [bx],ax} is equivalent to coding \code{mov [es:bx],ax}.
We recommend the latter syntax, since it is consistent with other syntactic
features of the language, but for instructions such as \code{LODSB}, which
has no operands and yet can require a segment override, there is no clean
syntactic way to proceed apart from \code{es lodsb}.
An instruction is not required to use a prefix: prefixes such as
\code{CS}, \code{A32}, \code{LOCK} or \code{REPE} can appear on
a line by themselves, and NASM will just generate the prefix bytes.
In addition to actual machine instructions, NASM also supports a
number of pseudo-instructions, described in \k{pseudop}.
Instruction \textindex{operands} may take a number of forms: they can be
registers, described simply by the register name (e.g. \code{ax},
\code{bp}, \code{ebx}, \code{cr0}: NASM does not use the \code{gas}-style
syntax in which register names must be prefixed by a \code{\%} sign),
or they can be \textindex{effective addresses} (see \nref{effaddr}),
constants (\nref{const}) or expressions (\nref{expr}).
For x87 \textindex{floating-point} instructions, NASM accepts a wide
range of syntaxes: you can use two-operand forms like MASM supports,
or you can use NASM's native single-operand forms in most cases.
% Details of all forms of each supported instruction are given in
% \nref{iref}.
For example, you can code:
\begin{lstlisting}
fadd st1 ; this sets st0 := st0 + st1
fadd st0,st1 ; so does this
fadd st1,st0 ; this sets st1 := st1 + st0
fadd to st1 ; so does this
\end{lstlisting}
Almost any x87 floating-point instruction that references memory must
use one of the prefixes \codeindex{DWORD}, \codeindex{QWORD} or
\codeindex{TWORD} to indicate what size of \textindex{memory operand}
it refers to.
\xsection{pseudop}{\textindexlc{Pseudo-Instructions}}
Pseudo-instructions are things which, though not real x86 machine
instructions, are used in the instruction field anyway because that's
the most convenient place to put them. The current pseudo-instructions
are \codeindex{DB}, \codeindex{DW}, \codeindex{DD}, \codeindex{DQ},
\codeindex{DT}, \codeindex{DO}, \codeindex{DY} and \codeindex{DZ};
their \textindex{uninitialized} counterparts \codeindex{RESB},
\codeindex{RESW}, \codeindex{RESD}, \codeindex{RESQ},
\codeindex{REST}, \codeindex{RESO}, \codeindex{RESY} and
\codeindex{RESZ}; the \codeindex{INCBIN} command, the \codeindex{EQU}
command, and the \codeindex{TIMES} prefix.
\xsubsection{db}{DB and Friends: Declaring Initialized Data}
\codeindex{DB}, \codeindex{DW}, \codeindex{DD}, \codeindex{DQ},
\codeindex{DT}, \codeindex{DO}, \codeindex{DY} and \codeindex{DZ}
are used, much as in MASM, to declare initialized data in
the output file. They can be invoked in a wide range of ways:
\index{constants!floating-point}
\index{constants!character}
\index{constants!string}
\begin{lstlisting}
db 0x55 ; just the byte 0x55
db 0x55,0x56,0x57 ; three bytes in succession
db 'a',0x55 ; character constants are OK
db 'hello',13,10,'$' ; so are string constants
dw 0x1234 ; 0x34 0x12
dw 'a' ; 0x61 0x00 (it's just a number)
dw 'ab' ; 0x61 0x62 (character constant)
dw 'abc' ; 0x61 0x62 0x63 0x00 (string)
dd 0x12345678 ; 0x78 0x56 0x34 0x12
dd 1.234567e20 ; floating-point constant
dq 0x123456789abcdef0 ; eight byte constant
dq 1.234567e20 ; double-precision float
dt 1.234567e20 ; extended-precision float
\end{lstlisting}
\code{DT}, \code{DO}, \code{DY} and \code{DZ} do not accept
numeric constants as operands.
\index{constants!numeric}
\xsubsection{resb}{RESB and Friends: Declaring \textindexlc{Uninitialized} Data}
\codeindex{RESB}, \codeindex{RESW}, \codeindex{RESD}, \codeindex{RESQ},
\codeindex{REST}, \codeindex{RESO}, \codeindex{RESY} and \codeindex{RESZ}
are designed to be used in the BSS section of a module: they declare
\emph{uninitialized} storage space. Each takes a single operand, which is
the number of bytes, words, doublewords or whatever to reserve. As stated
in \nref{qsother}, NASM does not support the MASM/TASM syntax of
reserving uninitialized space by writing \index{?}\code{DW ?} or similar
things: this is what it does instead. The operand to a \code{RESB}-type
pseudo-instruction is a \textindex{critical expression}:
see \nref{crit}.
For example:
\begin{lstlisting}
buffer: resb 64 ; reserve 64 bytes
wordvar: resw 1 ; reserve a word
realarray resq 10 ; array of ten reals
ymmval: resy 1 ; one YMM register
zmmvals: resz 32 ; 32 ZMM registers
\end{lstlisting}
\xsubsection{incbin}{\codeindex{INCBIN}: Including External \textindexlc{Binary Files}}
\code{INCBIN} is borrowed from the old Amiga assembler \textindex{DevPac}:
it includes a binary file verbatim into the output file. This can be handy
for (for example) including \textindex{graphics} and \textindex{sound} data
directly into a game executable file. It can be called in one of these
three ways:
\begin{lstlisting}
incbin "file.dat" ; include the whole file
incbin "file.dat",1024 ; skip the first 1024 bytes
incbin "file.dat",1024,512 ; skip the first 1024, and
\end{lstlisting}
\code{INCBIN} is both a directive and a standard macro; the standard
macro version searches for the file in the include file search path
and adds the file to the dependency lists. This macro can be
overridden if desired.
\xsubsection{equ}{\codeindex{EQU}: Defining Constants}
\code{EQU} defines a symbol to a given constant value: when \code{EQU} is
used, the source line must contain a label. The action of \code{EQU} is
to define the given label name to the value of its (only) operand.
This definition is absolute, and cannot change later. So, for
example,
\begin{lstlisting}
message db 'hello, world'
msglen equ $-message
\end{lstlisting}
defines \code{msglen} to be the constant 12. \code{msglen} may
not then be redefined later. This is not a \textindex{preprocessor}
definition either: the value of \code{msglen} is evaluated \code{once},
using the value of \code{\$} (see \nref{expr} for an explanation
of \code{\$}) at the point of definition, rather than being evaluated
wherever it is referenced and using the value of \code{\$} at
the point of reference.
\xsubsection{times}{\codeindex{TIMES}: \textindexlc{Repeating} Instructions or Data}
The \code{TIMES} prefix causes the instruction to be assembled multiple
times. This is partly present as NASM's equivalent of the \codeindex{DUP}
syntax supported by \textindex{MASM}-compatible assemblers, in that you can
code
\begin{lstlisting}
zerobuf: times 64 db 0
\end{lstlisting}
or similar things; but \code{TIMES} is more versatile than that. The
argument to \code{TIMES} is not just a numeric constant, but a numeric
\emph{expression}, so you can do things like
\begin{lstlisting}
buffer: db 'hello, world'
times 64-$+buffer db ' '
\end{lstlisting}
which will store exactly enough spaces to make the total length of
\code{buffer} up to 64. Finally, \code{TIMES} can be applied to ordinary
instructions, so you can code trivial \textindex{unrolled loops} in it:
\begin{lstlisting}
times 100 movsb
\end{lstlisting}
Note that there is no effective difference between \code{times 100 resb
1} and \code{resb 100}, except that the latter will be assembled about
100 times faster due to the internal structure of the assembler.
The operand to \code{TIMES} is a critical expression (\nref{crit}).
Note also that \code{TIMES} can't be applied to \textindex{macros}: the reason
for this is that \code{TIMES} is processed after the macro phase, which
allows the argument to \code{TIMES} to contain expressions such as
\code{64-\$+buffer} as above. To repeat more than one line of code,
or a complex macro, use the preprocessor \codeindex{\%rep} directive.
\xsection{effaddr}{Effective Addresses}
An \textindex{effective address} is any operand to an instruction which
\index{memory reference}references memory. Effective addresses, in NASM,
have a very simple syntax: they consist of an expression evaluating
to the desired address, enclosed in \textindex{square brackets}. For
example:
\begin{lstlisting}
wordvar dw 123
mov ax,[wordvar]
mov ax,[wordvar+1]
mov ax,[es:wordvar+bx]
\end{lstlisting}
Anything not conforming to this simple system is not a valid memory
reference in NASM, for example \code{es:wordvar[bx]}.
More complicated effective addresses, such as those involving more
than one register, work in exactly the same way:
\begin{lstlisting}
mov eax,[ebx*2+ecx+offset]
mov ax,[bp+di+8]
\end{lstlisting}
NASM is capable of doing \textindex{algebra} on these effective addresses,
so that things which don't necessarily \emph{look} legal are perfectly
all right:
\begin{lstlisting}
mov eax,[ebx*5] ; assembles as [ebx*4+ebx]
mov eax,[label1*2-label2] ; ie [label1+(label1-label2)]
\end{lstlisting}
Some forms of effective address have more than one assembled form;
in most such cases NASM will generate the smallest form it can. For
example, there are distinct assembled forms for the 32-bit effective
addresses \code{[eax*2+0]} and \code{[eax+eax]}, and NASM will
generally generate the latter on the grounds that the former requires
four bytes to store a zero offset.
NASM has a hinting mechanism which will cause \code{[eax+ebx]} and
\code{[ebx+eax]} to generate different opcodes; this is occasionally
useful because \code{[esi+ebp]} and \code{[ebp+esi]} have different
default segment registers.
However, you can force NASM to generate an effective address in a
particular form by the use of the keywords \code{BYTE}, \code{WORD},
\code{DWORD} and \code{NOSPLIT}. If you need \code{[eax+3]} to be
assembled using a double-word offset field instead of the one byte NASM
will normally generate, you can code \code{[dword eax+3]}. Similarly, you
can force NASM to use a byte offset for a small value which it hasn't seen
on the first pass (see \nref{crit} for an example of such a code
fragment) by using \code{[byte eax+offset]}. As special cases, \code{[byte eax]}
will code \code{[eax+0]} with a byte offset of zero, and \code{[dword eax]}
will code it with a double-word offset of zero. The normal form, \code{[eax]},
will be coded with no offset field.
The form described in the previous paragraph is also useful if you
are trying to access data in a 32-bit segment from within 16 bit code.
For more information on this see the section on mixed-size addressing
(\nref{mixaddr}). In particular, if you need to access data with
a known offset that is larger than will fit in a 16-bit value, if you don't
specify that it is a dword offset, nasm will cause the high word of
the offset to be lost.
Similarly, NASM will split \code{[eax*2]} into \code{[eax+eax]} because
that allows the offset field to be absent and space to be saved; in fact,
it will also split \code{[eax*2+offset]} into \code{[eax+eax+offset]}.
You can combat this behaviour by the use of the \code{NOSPLIT} keyword:
\code{[nosplit eax*2]} will force \code{[eax*2+0]} to be generated literally.
\code{[nosplit eax*1]} also has the same effect. In another way, a split EA
form \code{[0, eax*2]} can be used, too. However, \code{NOSPLIT} in
\code{[nosplit eax+eax]} will be ignored because user's intention here
is considered as \code{[eax+eax]}.
In 64-bit mode, NASM will by default generate absolute addresses. The
\codeindex{REL} keyword makes it produce \code{RIP}-relative addresses.
Since this is frequently the normally desired behaviour, see the \code{DEFAULT}
directive (\nref{default}). The keyword \codeindex{ABS} overrides
\codeindex{REL}.
A new form of split effective addres syntax is also supported. This is
mainly intended for mib operands as used by MPX instructions, but can
be used for any memory reference. The basic concept of this form is
splitting base and index.
\begin{lstlisting}
mov eax,[ebx+8,ecx*4] ; ebx=base, ecx=index, 4=scale, 8=disp
\end{lstlisting}
For mib operands, there are several ways of writing effective address
depending on the tools. NASM supports all currently possible ways of
mib syntax:
\begin{lstlisting}
; bndstx
; next 5 lines are parsed same
; base=rax, index=rbx, scale=1, displacement=3
bndstx [rax+0x3,rbx], bnd0 ; NASM - split EA
bndstx [rbx*1+rax+0x3], bnd0 ; GAS - '*1' indecates an index reg
bndstx [rax+rbx+3], bnd0 ; GAS - without hints
bndstx [rax+0x3], bnd0, rbx ; ICC-1
bndstx [rax+0x3], rbx, bnd0 ; ICC-2
\end{lstlisting}
When broadcasting decorator is used, the opsize keyword should match
the size of each element.
\begin{lstlisting}
vdivps zmm4, zmm5, dword [rbx]{1to16} ; single-precision float
vdivps zmm4, zmm5, zword [rbx] ; packed 512 bit memory
\end{lstlisting}
\xsection{const}{\textindexlc{Constants}}
NASM understands four different types of constant: numeric,
character, string and floating-point.
\xsubsection{numconst}{Numeric Constants}
\index{constants!numeric}
\index{constants!hexadecimal}
\index{constants!decimal}
\index{constants!octal}
\index{constants!binary}
A numeric constant is simply a number. NASM allows you to specify
numbers in a variety of number bases, in a variety of ways: you can
suffix \code{H} or \code{X}, \code{D} or \code{T}, \code{Q} or
\code{O}, and \code{B} or \code{Y} for hexadecimal, decimal, octal and
binary respectively, or you can prefix \code{0x}, for hexadecimal in
the style of C, or you can prefix \code{\$} for hexadecimal in the style
of Borland Pascal or Motorola Assemblers. Note, though, that the \index{prefix}
\codeindex{\$} prefix does double duty as a prefix on identifiers (see \nref{syntax}),
so a hex number prefixed with a \code{\$} sign must have a digit after the
\code{\$} rather than a letter. In addition, current versions of NASM accept
the prefix \code{0h} for hexadecimal, \code{0d} or \code{0t} for decimal,
\code{0o} or \code{0q} for octal, and \code{0b} or \code{0y} for binary.
Please note that unlike C, a \code{0} prefix by itself does \emph{not} imply
an octal constant!
Numeric constants can have underscores (\code{\_}) interspersed to break
up long strings.
Some examples (all producing exactly the same code):
\begin{lstlisting}
mov ax,200 ; decimal
mov ax,0200 ; still decimal
mov ax,0200d ; explicitly decimal
mov ax,0d200 ; also decimal
mov ax,0c8h ; hex
mov ax,$0c8 ; hex again: the 0 is required
mov ax,0xc8 ; hex yet again
mov ax,0hc8 ; still hex
mov ax,310q ; octal
mov ax,310o ; octal again
mov ax,0o310 ; octal yet again
mov ax,0q310 ; octal yet again
mov ax,11001000b ; binary
mov ax,1100_1000b ; same binary constant
mov ax,1100_1000y ; same binary constant once more
mov ax,0b1100_1000 ; same binary constant yet again
mov ax,0y1100_1000 ; same binary constant yet again
\end{lstlisting}
\xsubsection{strings}{\index{strings}Character Strings}
A character string consists of up to eight characters enclosed in
either single quotes (\code{'...'}), double quotes (\code{"..."}) or
backquotes (\code{`...`}). Single or double quotes are equivalent to
NASM (except of course that surrounding the constant with single
quotes allows double quotes to appear within it and vice versa); the
contents of those are represented verbatim. Strings enclosed in
backquotes support C-style \code{\textbackslash}-escapes for
special characters.
The following \textindex{escape sequences} are recognized by
backquoted strings:
\begin{lstlisting}
\' single quote (')
\" double quote (")
\` backquote (`)
\\ backslash (\)
\? question mark (?)
\a BEL (ASCII 7)
\b BS (ASCII 8)
\t TAB (ASCII 9)
\n LF (ASCII 10)
\v VT (ASCII 11)
\f FF (ASCII 12)
\r CR (ASCII 13)
\e ESC (ASCII 27)
\377 Up to 3 octal digits - literal byte
\xFF Up to 2 hexadecimal digits - literal byte
\u1234 4 hexadecimal digits - Unicode character
\U12345678 8 hexadecimal digits - Unicode character
\end{lstlisting}
All other escape sequences are reserved. Note that \code{\textbackslash 0},
meaning a \code{NUL} character (ASCII 0), is a special case of
the octal escape sequence.
\textindex{Unicode} characters specified with \code{\textbackslash u}
or \code{\textbackslash U} are converted to \textindex{UTF-8}.
For example, the following lines are all equivalent:
\begin{lstlisting}
db `\u263a` ; UTF-8 smiley face
db `\xe2\x98\xba` ; UTF-8 smiley face
db 0E2h, 098h, 0BAh ; UTF-8 smiley face
\end{lstlisting}
\xsubsection{chrconst}{Character Constants}
\index{constants!character}
A character constant consists of a string up to eight bytes long, used
in an expression context. It is treated as if it was an integer.
A character constant with more than one byte will be arranged
with \textindex{little-endian} order in mind: if you code
\begin{lstlisting}
mov eax,'abcd'
\end{lstlisting}
then the constant generated is not \code{0x61626364}, but \code{0x64636261},
so that if you were then to store the value into memory, it would read
\code{abcd} rather than \code{dcba}. This is also the sense of character
constants understood by the Pentium's \codeindex{CPUID} instruction.
\xsubsection{strconst}{String Constants}
\index{constants!string}
String constants are character strings used in the context of some
pseudo-instructions, namely the \indexcode{DW}\indexcode{DD}\indexcode{DQ}
\indexcode{DT}\indexcode{DO}\indexcode{DY}\codeindex{DB} family and
\codeindex{INCBIN} (where it represents a filename.) They are also used in
certain preprocessor directives.
A string constant looks like a character constant, only longer. It
is treated as a concatenation of maximum-size character constants
for the conditions. So the following are equivalent:
\begin{lstlisting}
db 'hello' ; string constant
db 'h','e','l','l','o' ; equivalent character constants
\end{lstlisting}
And the following are also equivalent:
\begin{lstlisting}
dd 'ninechars' ; doubleword string constant
dd 'nine','char','s' ; becomes three doublewords
db 'ninechars',0,0,0 ; and really looks like this
\end{lstlisting}
Note that when used in a string-supporting context, quoted strings are
treated as a string constants even if they are short enough to be a
character constant, because otherwise \code{db 'ab'} would have the same
effect as \code{db 'a'}, which would be silly. Similarly, three-character
or four-character constants are treated as strings when they are
operands to \code{DW}, and so forth.
\xsubsection{unicode}{Unicode Constants}
\index{constants!unicode}
\index{UTF-16}
\index{UTF-32}
The special operators \codeindex{\_\_utf16\_\_}, \codeindex{\_\_utf16le\_\_},
\codeindex{\_\_utf16be\_\_}, \codeindex{\_\_utf32\_\_}, \codeindex{\_\_utf32le\_\_}
and \codeindex{\_\_utf32be\_\_} allows definition of Unicode strings.
They take a string in UTF-8 format and converts it to UTF-16 or UTF-32,
respectively. Unless the \code{be} forms are specified, the output is
littleendian.
For example:
\begin{lstlisting}
%define u(x) __utf16__(x)
%define w(x) __utf32__(x)
dw u('C:\WINDOWS'), 0 ; Pathname in UTF-16
dd w(`A + B = \u206a`), 0 ; String in UTF-32
\end{lstlisting}
The UTF operators can be applied either to strings passed to the
\code{DB} family instructions, or to character constants in an expression
context.
\xsubsection{fltconst}{Floating-Point Constants}
\index{constants!floating-point}
\textindexlc{Floating-point} constants are acceptable only as arguments to
\codeindex{DB}, \codeindex{DW}, \codeindex{DD}, \codeindex{DQ}, \codeindex{DT},
and \codeindex{DO}, or as arguments to the special operators \codeindex{\_\_float8\_\_},
\codeindex{\_\_float16\_\_}, \codeindex{\_\_float32\_\_}, \codeindex{\_\_float64\_\_},
\codeindex{\_\_float80m\_\_}, \codeindex{\_\_float80e\_\_}, \codeindex{\_\_float128l\_\_},
and \codeindex{\_\_float128h\_\_}.
Floating-point constants are expressed in the traditional form:
digits, then a period, then optionally more digits, then optionally an
\code{E} followed by an exponent. The period is mandatory, so that NASM
can distinguish between \code{dd 1}, which declares an integer constant,
and \code{dd 1.0} which declares a floating-point constant.
NASM also support C99-style hexadecimal floating-point: \code{0x},
hexadecimal digits, period, optionally more hexadeximal digits, then
optionally a \code{P} followed by a \emph{binary} (not hexadecimal)
exponent in decimal notation. As an extension, NASM additionally
supports the \code{0h} and \code{\$} prefixes for hexadecimal,
as well binary and octal floating-point, using the \code{0b} or
\code{0y} and \code{0o} or \code{0q} prefixes, respectively.
Underscores to break up groups of digits are permitted in
floating-point constants as well.
Some examples:
\begin{lstlisting}
db -0.2 ; "Quarter precision"
dw -0.5 ; IEEE 754r/SSE5 half precision
dd 1.2 ; an easy one
dd 1.222_222_222 ; underscores are permitted
dd 0x1p+2 ; 1.0x2^2 = 4.0
dq 0x1p+32 ; 1.0x2^32 = 4 294 967 296.0
dq 1.e10 ; 10 000 000 000.0
dq 1.e+10 ; synonymous with 1.e10
dq 1.e-10 ; 0.000 000 000 1
dt 3.141592653589793238462 ; pi
do 1.e+4000 ; IEEE 754r quad precision
\end{lstlisting}
The 8-bit "quarter-precision" floating-point format is
sign:exponent:mantissa = 1:4:3 with an exponent bias of 7. This
appears to be the most frequently used 8-bit floating-point format,
although it is not covered by any formal standard. This is sometimes
called a ``\textindex{minifloat}''.
The special operators are used to produce floating-point numbers in
other contexts. They produce the binary representation of a specific
floating-point number as an integer, and can use anywhere integer
constants are used in an expression. \code{\_\_float80m\_\_} and
\code{\_\_float80e\_\_} produce the 64-bit mantissa and 16-bit
exponent of an 80-bit floating-point number, and \code{\_\_float128l\_\_}
and \code{\_\_float128h\_\_} produce the lower and upper 64-bit halves
of a 128-bit floating-point number, respectively.
For example:
\begin{lstlisting}
mov rax,__float64__(3.141592653589793238462)
\end{lstlisting}
would assign the binary representation of pi as a 64-bit floating
point number into \code{RAX}. This is exactly equivalent to:
\begin{lstlisting}
mov rax,0x400921fb54442d18
\end{lstlisting}
NASM cannot do compile-time arithmetic on floating-point constants.
This is because NASM is designed to be portable - although it always
generates code to run on x86 processors, the assembler itself can
run on any system with an ANSI C compiler. Therefore, the assembler
cannot guarantee the presence of a floating-point unit capable of
handling the \textindexlc{Intel number formats}, and so for NASM
to be able to do floating arithmetic it would have to include its
own complete set of floating-point routines, which would significantly
increase the size of the assembler for very little benefit.
The special tokens \codeindex{\_\_Infinity\_\_}, \codeindex{\_\_QNaN\_\_} (or
\codeindex{\_\_NaN\_\_}) and \codeindex{\_\_SNaN\_\_} can be used to generate
\index{infinity}infinities, quiet \textindex{NaN}s, and signalling NaNs,
respectively. These are normally used as macros:
\begin{lstlisting}
%define Inf __Infinity__
%define NaN __QNaN__
dq +1.5, -Inf, NaN ; Double-precision constants
\end{lstlisting}
The \code{\%use fp} standard macro package contains a set of convenience
macros. See \nref{pkgfp}.
\xsubsection{bcdconst}{Packed BCD Constants}
\index{constants!packed BCD}
x87-style packed BCD constants can be used in the same contexts as
80-bit floating-point numbers. They are suffixed with \code{p} or
prefixed with \code{0p}, and can include up to 18 decimal digits.
As with other numeric constants, underscores can be used
to separate digits.
For example:
\begin{lstlisting}
dt 12_345_678_901_245_678p
dt -12_345_678_901_245_678p
dt +0p33
dt 33p
\end{lstlisting}
\xsection{expr}{\textindex{Expressions}}
Expressions in NASM are similar in syntax to those in C. Expressions
are evaluated as 64-bit integers which are then adjusted to the
appropriate size.
NASM supports two special tokens in expressions, allowing
calculations to involve the current assembly position: the
\index{\$}\index{here}\code{\$} and \codeindex{\$\$} tokens.
\code{\$} evaluates to the assembly position at the beginning
of the line containing the expression; so you can code an
\textindex{infinite loop} using \code{JMP \$}. \code{\$\$}
evaluates to the beginning of the current section; so you can
tell how far into the section you are by using \code{(\$-\$\$)}.
The arithmetic \textindex{operators} provided by NASM are listed here,
in increasing order of \textindex{precedence}.
\xsubsection{expor}{\codeindex{|}: Bitwise OR Operator}
\index{bitwise!OR}
The \code{|} operator gives a bitwise OR, exactly as performed by the
\code{OR} machine instruction. Bitwise OR is the lowest-priority
arithmetic operator supported by NASM.
\xsubsection{expxor}{\codeindex{\textasciicircum}: Bitwise XOR Operator}
\index{bitwise!XOR}
The \code{\textasciicircum} operator provides the bitwise XOR operation.
\xsubsection{expand}{\codeindex{\&}: Bitwise AND Operator}
\index{bitwise!AND}
The \code{\&} operator provides the bitwise AND operation.
\xsubsection{expshift}{\codeindex{<<} and \codeindex{>>}: \textindexlc{Bit Shift} Operators}
\code{<<} gives a bit-shift to the left, just as it does in C.
So \code{5<<3} evaluates to 5 times 8, or 40. \code{>>} gives
a bit-shift to the right; in NASM, such a shift is \emph{always}
unsigned, so that the bits shifted in from the left-hand end
are filled with zero rather than a sign-extension of the
previous highest bit.
\xsubsection{expplmi}{\codeindex{+} and \codeindex{-}:
\textindexlc{Addition} and \textindexlc{Subtraction} Operators}
The \code{+} and \code{-} operators do perfectly ordinary addition
and subtraction.
\xsubsection{expmul}{\codeindex{*}, \codeindex{/},
\codeindex{//} and \codeindex{\%\%}:
\textindexlc{Multiplication} and \textindexlc{Division}}
\code{*} is the multiplication operator. \code{/} and \code{//} are both
division operators: \code{/} is \textindex{unsigned division} and
\code{//} is \textindex{signed division}. Similarly, \code{\%} and
\code{\%\%} provide \index{unsigned modulo}\index{modulo operators}unsigned
and \textindex{signed modulo} operators respectively.
NASM, like ANSI C, provides no guarantees about the sensible
operation of the signed modulo operator.
Since the \code{\%} character is used extensively by the macro
\textindex{preprocessor}, you should ensure that both the signed
and unsigned modulo operators are followed by white space wherever
they appear.
\xsubsection{expunary}{\textindex{Unary Operators}}
\index{unary!+}
\index{unary!-}
\index{unary!\textasciitilde}
\index{unary!seg}
The highest-priority operators in NASM's expression grammar are those
which only apply to one argument. These are \codeindex{+},
\codeindex{-}, \codeindex{\textasciitilde}, \codeindex{!},
\codeindex{SEG}, and the \textindex{integer functions} operators.
\code{-} negates its operand, \code{+} does nothing (it's provided for
symmetry with \code{-}), \code{\textasciitilde} computes the
\textindex{one's complement} of its operand, \code{!} is the
\textindex{logical negation} operator.
\code{SEG} provides the \textindex{segment address}
of its operand (explained in more detail in \nref{segwrt}).
A set of additional operators with leading and trailing double
underscores are used to implement the integer functions of the
\code{ifunc} macro package, see \nref{pkgifunc}.
\xsection{segwrt}{\codeindex{SEG} and \codeindex{WRT}}
When writing large 16-bit programs, which must be split into
multiple \textindex{segments}, it is often necessary to be able
to refer to the \index{segment address}segment part of the address
of a symbol. NASM supports the \code{SEG} operator to perform
this function.
The \code{SEG} operator returns the \emph{\textindex{preferred}}
segment base of a symbol, defined as the segment base relative
to which the offset of the symbol makes sense. So the code
\begin{lstlisting}
mov ax,seg symbol
mov es,ax
mov bx,symbol
\end{lstlisting}
will load \code{ES:BX} with a valid pointer to the symbol
\code{symbol}.
Things can be more complex than this: since 16-bit segments and
\textindex{groups} may \index{overlapping segments}overlap,
you might occasionally want to refer to some symbol using
a different segment base from the preferred one. NASM lets you
do this, by the use of the \code{WRT} (With Reference To) keyword.
So you can do things like
\begin{lstlisting}
mov ax,weird_seg ; weird_seg is a segment base
mov es,ax
mov bx,symbol wrt weird_seg
\end{lstlisting}
to load \code{ES:BX} with a different, but functionally equivalent,
pointer to the symbol \code{symbol}.
NASM supports far (inter-segment) calls and jumps by means of the
syntax \code{call segment:offset}, where \code{segment}
and \code{offset} both represent immediate values. So to call
a far procedure, you could code either of
\begin{lstlisting}
call (seg procedure):procedure
call weird_seg:(procedure wrt weird_seg)
\end{lstlisting}
(The parentheses are included for clarity, to show the intended
parsing of the above instructions. They are not necessary in
practice.)
NASM supports the syntax \indexcode{CALL FAR}\code{call far procedure}
as a synonym for the first of the above usages. \code{JMP} works
identically to \code{CALL} in these examples.
To declare a \textindex{far pointer} to a data item in a data
segment, you must code
\begin{lstlisting}
dw symbol, seg symbol
\end{lstlisting}
NASM supports no convenient synonym for this, though you can always
invent one using the macro processor.
\xsection{strict}{\codeindex{STRICT}: Inhibiting Optimization}
When assembling with the optimizer set to level 2 or higher (see
\nref{opt-O}), NASM will use size specifiers (\code{BYTE},
\code{WORD}, \code{DWORD}, \code{QWORD}, \code{TWORD}, \code{OWORD},
\code{YWORD} or \code{ZWORD}), but will give them the smallest possible
size. The keyword \code{STRICT} can be used to inhibit optimization
and force a particular operand to be emitted in the specified size.
For example, with the optimizer on, and in \code{BITS 16} mode,
\begin{lstlisting}
push dword 33
\end{lstlisting}
is encoded in three bytes \code{66 6A 21}, whereas
\begin{lstlisting}
push strict dword 33
\end{lstlisting}
is encoded in six bytes, with a full dword immediate operand
\code{66 68 21 00 00 00}.
With the optimizer off, the same code (six bytes) is generated whether
the \code{STRICT} keyword was used or not.
\xsection{crit}{\textindexlc{Critical Expressions}}
Although NASM has an optional multi-pass optimizer, there are some
expressions which must be resolvable on the first pass. These are
called \emph{Critical Expressions}.
The first pass is used to determine the size of all the assembled
code and data, so that the second pass, when generating all the
code, knows all the symbol addresses the code refers to. So one
thing NASM can't handle is code whose size depends on the value
of a symbol declared after the code in question. For example,
\begin{lstlisting}
times (label-$) db 0
label: db 'Where am I?'
\end{lstlisting}
The argument to \codeindex{TIMES} in this case could equally legally
evaluate to anything at all; NASM will reject this example because
it cannot tell the size of the \code{TIMES} line when it first sees it.
It will just as firmly reject the slightly \index{paradox}paradoxical
code
\begin{lstlisting}
times (label-$+1) db 0
label: db 'NOW where am I?'
\end{lstlisting}
in which \emph{any} value for the \code{TIMES} argument
is by definition wrong!
NASM rejects these examples by means of a concept called a
\emph{critical expression}, which is defined to be an
expression whose value is required to be computable in
the first pass, and which must therefore depend only
on symbols defined before it. The argument to the \code{TIMES}
prefix is a critical expression.
\xsection{locallab}{\textindexlc{Local Labels}}
NASM gives special treatment to symbols beginning with a \textindex{period}.
A label beginning with a single period is treated as a \emph{local}
label, which means that it is associated with the previous non-local
label. So, for example:
\begin{lstlisting}
label1 ; some code
.loop
; some more code
jne .loop
ret
label2 ; some code
.loop
; some more code
jne .loop
ret
\end{lstlisting}
In the above code fragment, each \code{JNE} instruction jumps to the
line immediately before it, because the two definitions of
\code{.loop} are kept separate by virtue of each being associated
with the previous non-local label.
This form of local label handling is borrowed from the old Amiga
assembler \textindex{DevPac}; however, NASM goes one step further,
in allowing access to local labels from other parts of the code. This
is achieved by means of \emph{defining} a local label in terms of the
previous non-local label: the first definition of \code{.loop} above is
really defining a symbol called \code{label1.loop}, and the second
defines a symbol called \code{label2.loop}. So, if you really needed
to, you could write
\begin{lstlisting}
label3 ; some more code
; and some more
jmp label1.loop
\end{lstlisting}
Sometimes it is useful - in a macro, for instance - to be able to
define a label which can be referenced from anywhere but which
doesn't interfere with the normal local-label mechanism. Such a
label can't be non-local because it would interfere with subsequent
definitions of, and references to, local labels; and it can't be
local because the macro that defined it wouldn't know the label's
full name. NASM therefore introduces a third type of label, which is
probably only useful in macro definitions: if a label begins with
the \index{label prefix}special prefix \codeindex{..@}, then it
does nothing to the local label mechanism. So you could code
\begin{lstlisting}
label1: ; a non-local label
.local: ; this is really label1.local
..@foo: ; this is a special symbol
label2: ; another non-local label
.local: ; this is really label2.local
jmp ..@foo ; this will jump three lines up
\end{lstlisting}
NASM has the capacity to define other special symbols beginning with
a double period: for example, \code{..start} is used to specify the
entry point in the \code{obj} output format (see \nref{dotdotstart}),
\code{..imagebase} is used to find out the offset from a base address
of the current image in the \code{win64} output format
(see \nref{win64pic}). So just keep in mind that symbols
beginning with a double period are special.

127
doc/latex/src/macropkg.tex Normal file
View File

@ -0,0 +1,127 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{macropkg}{\textindexlc{Standard Macro Packages}}
The \codeindex{\%use} directive (see \nref{use}) includes one of
the standard macro packages included with the NASM distribution and compiled
into the NASM binary. It operates like the \code{\%include} directive (see
\nref{include}), but the included contents is provided by NASM itself.
The names of standard macro packages are case insensitive, and can be
quoted or not.
\xsection{pkgaltreg}{\codeindex{altreg}: \textindexlc{Alternate Register Names}}
The \code{altreg} standard macro package provides alternate register
names. It provides numeric register names for all registers (not just
\code{R8}-\code{R15}), the Intel-defined aliases \code{R8L}-\code{R15L}
for the low bytes of register (as opposed to the NASM/AMD standard names
\code{R8B}-\code{R15B}), and the names \code{R0H}-\code{R3H} (by analogy
with \code{R0L}-\code{R3L}) for \code{AH}, \code{CH}, \code{DH},
and \code{BH}.
Example use:
\begin{lstlisting}
%use altreg
proc:
mov r0l,r3h ; mov al,bh
ret
\end{lstlisting}
See also \nref{reg64}.
\xsection{pkgsmartalign}{\codeindex{smartalign}\index{align, smart}: Smart \code{ALIGN} Macro}
The \code{smartalign} standard macro package provides for an
\codeindex{ALIGN} macro which is more powerful than the default (and
backwards-compatible) one (see \nref{align}). When the
\code{smartalign} package is enabled, when \code{ALIGN} is used without
a second argument, NASM will generate a sequence of instructions more
efficient than a series of \code{NOP}. Furthermore, if the padding
exceeds a specific threshold, then NASM will generate a jump over
the entire padding sequence.
The specific instructions generated can be controlled with the
new \codeindex{ALIGNMODE} macro. This macro takes two parameters: one mode,
and an optional jump threshold override. If (for any reason) you need
to turn off the jump completely just set jump threshold value to -1
(or set it to \code{nojmp}). The following modes are possible:
\begin{itemize}
\item{\code{generic}: Works on all x86 CPUs and should have
reasonable performance. The default jump threshold is 8.
This is the default.}
\item{\code{nop}: Pad out with \code{NOP} instructions. The only
difference compared to the standard \code{ALIGN} macro is that NASM
can still jump over a large padding area. The default jump
threshold is 16.}
\item{\code{k7}: Optimize for the AMD K7 (Athlon/Althon XP).
These instructions should still work on all x86 CPUs. The default
jump threshold is 16.}
\item{\code{k8}: Optimize for the AMD K8 (Opteron/Althon 64).
These instructions should still work on all x86 CPUs. The default
jump threshold is 16.}
\item{\code{p6}: Optimize for Intel CPUs. This uses the long
\code{NOP} instructions first introduced in Pentium Pro. This
is incompatible with all CPUs of family 5 or lower, as well as
some VIA CPUs and several virtualization solutions. The default
jump threshold is 16.}
\end{itemize}
The macro \codeindex{\_\_ALIGNMODE\_\_} is defined to contain the
current alignment mode. A number of other macros beginning with
\code{\_\_ALIGN\_} are used internally by this macro package.
\xsection{pkgfp}{\codeindex{fp}: Floating-point macros}
This packages contains the following floating-point convenience macros:
\begin{lstlisting}
%define Inf __Infinity__
%define NaN __QNaN__
%define QNaN __QNaN__
%define SNaN __SNaN__
%define float8(x) __float8__(x)
%define float16(x) __float16__(x)
%define float32(x) __float32__(x)
%define float64(x) __float64__(x)
%define float80m(x) __float80m__(x)
%define float80e(x) __float80e__(x)
%define float128l(x) __float128l__(x)
%define float128h(x) __float128h__(x)
\end{lstlisting}
\xsection{pkgifunc}{\codeindex{ifunc}: \textindexlc{Integer functions}}
This package contains a set of macros which implement integer
functions. These are actually implemented as special operators, but
are most conveniently accessed via this macro package.
\xsubsection{ilog2}{\textindexlc{Integer logarithms}}
These functions calculate the integer logarithm base 2 of their
argument, considered as an unsigned integer. The only differences
between the functions is their respective behavior if the argument
provided is not a power of two.
The function \codeindex{ilog2e()} (alias \codeindex{ilog2()}) generates
an error if the argument is not a power of two.
The function \codeindex{ilog2f()} rounds the argument down to the nearest
power of two; if the argument is zero it returns zero.
The function \codeindex{ilog2c()} rounds the argument up to the nearest
power of two.
The functions \codeindex{ilog2fw()} (alias \codeindex{ilog2w()}) and
\codeindex{ilog2cw()} generate a warning if the argument is not a power of
two, but otherwise behaves like \codeindex{ilog2f()} and \codeindex{ilog2c()},
respectively.

185
doc/latex/src/mixsize.tex Normal file
View File

@ -0,0 +1,185 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{mixsize}{Mixing 16 and 32 Bit Code}
This chapter tries to cover some of the issues, largely related to
unusual forms of addressing and jump instructions, encountered when
writing operating system code such as protected-mode initialisation
routines, which require code that operates in mixed segment sizes,
such as code in a 16-bit segment trying to modify data in a 32-bit
one, or jumps between different-size segments.
\xsection{mixjump}{Mixed-Size Jumps}
\index{jumps!mixed-size}
\index{operating system, writing}
\index{writing operating systems}
The most common form of \textindex{mixed-size instruction} is the one
used when writing a 32-bit OS: having done your setup in 16-bit mode,
such as loading the kernel, you then have to boot it by switching into
protected mode and jumping to the 32-bit kernel start address. In a
fully 32-bit OS, this tends to be the \emph{only} mixed-size
instruction you need, since everything before it can be done in pure
16-bit code, and everything after it can be pure 32-bit.
This jump must specify a 48-bit far address, since the target
segment is a 32-bit one. However, it must be assembled in a 16-bit
segment, so just coding, for example,
\begin{lstlisting}
jmp 0x1234:0x56789ABC ; wrong!
\end{lstlisting}
will not work, since the offset part of the address will be
truncated to \code{0x9ABC} and the jump will be an ordinary 16-bit far
one.
The Linux kernel setup code gets round the inability of \code{as86} to
generate the required instruction by coding it manually, using
\code{DB} instructions. NASM can go one better than that, by actually
generating the right instruction itself. Here's how to do it right:
\begin{lstlisting}
jmp dword 0x1234:0x56789ABC ; right
\end{lstlisting}
\indexcode{JMP DWORD}The \code{DWORD} prefix (strictly speaking,
it should come \emph{after} the colon, since it is declaring the
\emph{offset} field to be a doubleword; but NASM will accept either
form, since both are unambiguous) forces the offset part to be treated
as far, in the assumption that you are deliberately writing a jump from
a 16-bit segment to a 32-bit one.
You can do the reverse operation, jumping from a 32-bit segment to a
16-bit one, by means of the \code{WORD} prefix:
\begin{lstlisting}
jmp word 0x8765:0x4321 ; 32 to 16 bit
\end{lstlisting}
If the \code{WORD} prefix is specified in 16-bit mode, or the
\code{DWORD} prefix in 32-bit mode, they will be ignored, since each is
explicitly forcing NASM into a mode it was in anyway.
\xsection{mixaddr}{Addressing Between Different-Size Segments}
\index{addressing!mixed-size}
\index{mixed-size addressing}
If your OS is mixed 16 and 32-bit, or if you are writing a DOS
extender, you are likely to have to deal with some 16-bit segments
and some 32-bit ones. At some point, you will probably end up
writing code in a 16-bit segment which has to access data in a
32-bit segment, or vice versa.
If the data you are trying to access in a 32-bit segment lies within
the first 64K of the segment, you may be able to get away with using
an ordinary 16-bit addressing operation for the purpose; but sooner
or later, you will want to do 32-bit addressing from 16-bit mode.
The easiest way to do this is to make sure you use a register for
the address, since any effective address containing a 32-bit
register is forced to be a 32-bit address. So you can do
\begin{lstlisting}
mov eax,offset_into_32_bit_segment_specified_by_fs
mov dword [fs:eax],0x11223344
\end{lstlisting}
This is fine, but slightly cumbersome (since it wastes an
instruction and a register) if you already know the precise offset
you are aiming at. The x86 architecture does allow 32-bit effective
addresses to specify nothing but a 4-byte offset, so why shouldn't
NASM be able to generate the best instruction for the purpose?
It can. As in \nref{mixjump}, you need only prefix the address
with the \code{DWORD} keyword, and it will be forced to be a 32-bit
address:
\begin{lstlisting}
mov dword [fs:dword my_offset],0x11223344
\end{lstlisting}
Also as in \nref{mixjump}, NASM is not fussy about whether the
\code{DWORD} prefix comes before or after the segment override, so
arguably a nicer-looking way to code the above instruction is
\begin{lstlisting}
mov dword [dword fs:my_offset],0x11223344
\end{lstlisting}
Don't confuse the \code{DWORD} prefix \emph{outside} the square brackets,
which controls the size of the data stored at the address, with the
one \code{inside} the square brackets which controls the length of the
address itself. The two can quite easily be different:
\begin{lstlisting}
mov word [dword 0x12345678],0x9ABC
\end{lstlisting}
This moves 16 bits of data to an address specified by a 32-bit
offset.
You can also specify \code{WORD} or \code{DWORD} prefixes along with the
\code{FAR} prefix to indirect far jumps or calls. For example:
\begin{lstlisting}
call dword far [fs:word 0x4321]
\end{lstlisting}
This instruction contains an address specified by a 16-bit offset;
it loads a 48-bit far pointer from that (16-bit segment and 32-bit
offset), and calls that address.
\xsection{mixother}{Other Mixed-Size Instructions}
The other way you might want to access data might be using the
string instructions (\code{LODSx}, \code{STOSx} and so on) or the
\code{XLATB} instruction. These instructions, since they take no
parameters, might seem to have no easy way to make them perform
32-bit addressing when assembled in a 16-bit segment.
This is the purpose of NASM's \codeindex{a16}, \codeindex{a32} and
\codeindex{a64} prefixes. If you are coding \code{LODSB} in a 16-bit
segment but it is supposed to be accessing a string in a 32-bit segment,
you should load the desired address into \code{ESI} and then code
\begin{lstlisting}
a32 lodsb
\end{lstlisting}
The prefix forces the addressing size to 32 bits, meaning that
\code{LODSB} loads from \code{[DS:ESI]} instead of \code{[DS:SI]}.
To access a string in a 16-bit segment when coding in a 32-bit one,
the corresponding \code{a16} prefix can be used.
The \code{a16}, \code{a32} and \code{a64} prefixes can be applied to
any instruction in NASM's instruction table, but most of them can
generate all the useful forms without them. The prefixes are necessary
only for instructions with implicit addressing: \code{CMPSx},
\code{SCASx}, \code{LODSx}, \code{STOSx}, \code{MOVSx}, \code{INSx},
\code{OUTSx}, and \code{XLATB}. Also, the various push and pop
instructions (\code{PUSHA} and \code{POPF} as well as the more usual
\code{PUSH} and \code{POP}) can accept \code{a16}, \code{a32} or
\code{a64} prefixes to force a particular one of \code{SP}, \code{ESP} or
\code{RSP} to be used as a stack pointer, in case the stack segment in
use is a different size from the code segment.
\code{PUSH} and \code{POP}, when applied to segment registers in 32-bit
mode, also have the slightly odd behaviour that they push and pop 4
bytes at a time, of which the top two are ignored and the bottom two
give the value of the segment register being manipulated. To force
the 16-bit behaviour of segment-register push and pop instructions,
you can use the operand-size prefix \codeindex{o16}:
\begin{lstlisting}
o16 push ss
o16 push ds
\end{lstlisting}
This code saves a doubleword of stack space by fitting two segment
registers into the space which would normally be consumed by pushing
one.
(You can also use the \codeindex{o32} prefix to force the 32-bit behaviour
when in 16-bit mode, but this seems less useful.)

163
doc/latex/src/nasm.tex Normal file
View File

@ -0,0 +1,163 @@
%
% vim: ts=4 sw=4 et
%
\documentclass[oneside,openany]{book}
\usepackage[a4paper,margin=72pt]{geometry}
\usepackage{listings} % nasm listings
\usepackage{imakeidx} % indexing
\usepackage{hyperref} % pdf bookmarks and such
\usepackage[Sonny]{fncychap} % chapter style
\usepackage{parskip} % no indent on first line
\usepackage{fontspec} % selecting fonts
\usepackage{xunicode} % unicode support
\usepackage{xcolor} % coloring
\usepackage{xspace} % spacing
\usepackage{appendix} % appendix
%\usepackage{xstring} % strings for code
\usepackage{sectsty} % colors for sections
\usepackage{graphicx} % images
\usepackage[titles]{tocloft} % coloring TOC
\title{NASM -- The Netwide Assembler}
\author{The NASM Development Team}
\date{1996 -- 2018}
\input{src/version.tex}
%
% No rectangles
\makeatletter
\hypersetup{
pdfauthor=\@author,
pdftitle=\@title,
pdfkeywords={NASM,Netwide Assembler},
hidelinks,
}
\makeatother
%
% Up to 4 levels nesting in menu
\setcounter{tocdepth}{4}
%
% Highlight listings
\definecolor{light-gray}{gray}{0.96}
%
% Setup document fonts
\setmainfont{Source Sans Pro}
\setmonofont{FreeMono}
% Listings font and settings
\newfontfamily{\lstsansserif}{FreeMono}
\lstset{
keepspaces=true,
backgroundcolor=\color{light-gray},
basicstyle=\lstsansserif,
breaklines=true,
breakatwhitespace=true,
framesep=10pt,
framexleftmargin=10pt,
frame=tb,
framerule=0pt,
xleftmargin=10pt,
xrightmargin=10pt,
aboveskip=10pt,
belowskip=5pt,
literate={-}{{-}}1
}
%
% Heading colors
\definecolor{hcolor}{RGB}{8,96,168}
\chapterfont{\color{hcolor}}
\sectionfont{\color{hcolor}}
\subsectionfont{\color{hcolor}}
%
% Formatting macros
\newcommand{\textindex}[1]{#1\index{#1}\xspace}
\newcommand{\textindexlc}[1]{#1\index{\MakeLowercase{#1}}\xspace}
\newcommand{\code}[1]{{\texttt{#1}}\xspace}
\newcommand{\indexcode}[1]{\index{#1@\texttt{#1}}\xspace}
\newcommand{\codeindex}[1]{\texttt{#1}\index{#1@\texttt{#1}}\xspace}
\newcommand{\fullref}[1]{``\hyperref[{#1}]{\ref*{#1}\xspace\nameref*{#1}}''\xspace}
\newcommand{\nref}[1]{\textcolor{hcolor}{\hyperref[{#1}]{\ref*{#1}\xspace}}}
\newcommand{\xchapter}[2]{\chapter{#2}\label{#1}\xspace}
\newcommand{\xsection}[2]{\section{#2}\label{#1}\xspace}
\newcommand{\xsubsection}[2]{\subsection{#2}\label{#1}\xspace}
%
% Convertion table
%
% \C{name} -> \xchapter{label}{name}
% \H{name} -> \xsection{label}{name}
% \S{name} -> \xsubsection{label}{name}
% \c{name} -> \code{name}
% \c name -> \begin{lstlisting}
% name
% \end{lstlisting}
% \i{name} -> \textindexlc{name}
% \I{name} -> \index{name}
% \I\c{name} -> \indexcode{name}
% \i\c{name} -> \codeindex{name}
% \k{name} -> \nref{name}
%
% Index into TOC
\makeindex[title=Index,columns=2,intoc,options=-s src/idxconf.ist]
%
% TOC headers
\renewcommand{\cftchapfont}{\bfseries\color{hcolor}}
\renewcommand{\cfttoctitlefont}{\huge\bfseries\color{hcolor}}
\begin{document}
\raggedright
\makeatletter
\begin{titlepage}
\color{hcolor}
\begin{center} \vspace*{\fill}
\begin{flushleft}
{\huge \bfseries {\@title}} \\
\end{flushleft}
\noindent\makebox[\linewidth]{\rule{\textwidth}{2pt}} \\
\begin{flushright}
{\large \bfseries \emph{version \version}} \\[8ex]
\end{flushright}
\includegraphics[width=6cm]{src/nasmlogo.eps}
\vspace*{\fill} \end{center}
\end{titlepage}
\makeatother
\thispagestyle{empty}
\tableofcontents
\addtocontents{toc}{~\hfill\textcolor{hcolor}{\textbf{Page}}\par}
%
% Document chapters
\input{src/intro.tex}
\input{src/running.tex}
\input{src/language.tex}
\input{src/preproc.tex}
\input{src/macropkg.tex}
\input{src/directive.tex}
\input{src/outfmt.tex}
\input{src/16bit.tex}
\input{src/32bit.tex}
\input{src/mixsize.tex}
\input{src/64bit.tex}
\input{src/trouble.tex}
\begin{appendices}
\input{src/ndisasm.tex}
\input{src/inslist.tex}
\input{src/changelog.tex}
\input{src/source.tex}
\input{src/contact.tex}
\end{appendices}
\printindex
\end{document}

212
doc/latex/src/nasmlogo.eps Normal file
View File

@ -0,0 +1,212 @@
%!PS-Adobe-3.0 EPSF-3.0
%%Creator: cairo 1.10.2 (http://cairographics.org)
%%CreationDate: Sun Feb 26 02:08:42 2012
%%Pages: 1
%%BoundingBox: 44 42 306 306
%%DocumentData: Clean7Bit
%%LanguageLevel: 2
%%EndComments
%%BeginProlog
/cairo_eps_state save def
/dict_count countdictstack def
/op_count count 1 sub def
userdict begin
/q { gsave } bind def
/Q { grestore } bind def
/cm { 6 array astore concat } bind def
/w { setlinewidth } bind def
/J { setlinecap } bind def
/j { setlinejoin } bind def
/M { setmiterlimit } bind def
/d { setdash } bind def
/m { moveto } bind def
/l { lineto } bind def
/c { curveto } bind def
/h { closepath } bind def
/re { exch dup neg 3 1 roll 5 3 roll moveto 0 rlineto
0 exch rlineto 0 rlineto closepath } bind def
/S { stroke } bind def
/f { fill } bind def
/f* { eofill } bind def
/n { newpath } bind def
/W { clip } bind def
/W* { eoclip } bind def
/BT { } bind def
/ET { } bind def
/pdfmark where { pop globaldict /?pdfmark /exec load put }
{ globaldict begin /?pdfmark /pop load def /pdfmark
/cleartomark load def end } ifelse
/BDC { mark 3 1 roll /BDC pdfmark } bind def
/EMC { mark /EMC pdfmark } bind def
/cairo_store_point { /cairo_point_y exch def /cairo_point_x exch def } def
/Tj { show currentpoint cairo_store_point } bind def
/TJ {
{
dup
type /stringtype eq
{ show } { -0.001 mul 0 cairo_font_matrix dtransform rmoveto } ifelse
} forall
currentpoint cairo_store_point
} bind def
/cairo_selectfont { cairo_font_matrix aload pop pop pop 0 0 6 array astore
cairo_font exch selectfont cairo_point_x cairo_point_y moveto } bind def
/Tf { pop /cairo_font exch def /cairo_font_matrix where
{ pop cairo_selectfont } if } bind def
/Td { matrix translate cairo_font_matrix matrix concatmatrix dup
/cairo_font_matrix exch def dup 4 get exch 5 get cairo_store_point
/cairo_font where { pop cairo_selectfont } if } bind def
/Tm { 2 copy 8 2 roll 6 array astore /cairo_font_matrix exch def
cairo_store_point /cairo_font where { pop cairo_selectfont } if } bind def
/g { setgray } bind def
/rg { setrgbcolor } bind def
/d1 { setcachedevice } bind def
%%EndProlog
%%Page: 1 1
%%BeginPageSetup
%%PageBoundingBox: 44 42 306 306
%%EndPageSetup
q 44 42 262 264 rectclip q
0.501961 g
279.656 304.422 m 265.238 304.422 253.559 292.734 253.559 278.32 c
253.559 273.254 255.023 268.539 257.523 264.535 c 240.906 247.918 l
220.031 266.812 192.352 278.32 161.977 278.32 c 96.988 278.32 44.297
225.633 44.297 160.64 c 44.297 95.648 96.988 42.965 161.977 42.965 c
226.969 42.965 279.656 95.648 279.656 160.64 c 279.656 191.012 268.145
218.695 249.254 239.574 c 265.871 256.191 l 269.875 253.691 274.59
252.223 279.66 252.223 c 294.07 252.223 305.754 263.906 305.754 278.32
c 305.754 292.73 294.07 304.422 279.656 304.422 c h
279.656 304.422 m f
1 g
107.184 140.832 m 107 140.492 106.547 140.324 105.816 140.324 c 97.219
140.324 l 96.07 140.324 95.5 140.871 95.5 141.965 c 95.5 145.406 95.508
148.82 95.535 152.207 c 95.562 155.594 95.574 159.008 95.574 162.445 c
95.574 164.637 95.195 166.187 94.441 167.098 c 93.684 168.008 92.469
168.465 90.805 168.465 c 89.555 168.465 88.199 168.164 86.742 167.566 c
85.281 166.965 84.086 166.508 83.145 166.195 c 83.145 141.965 l 83.145
141.547 83.051 141.172 82.871 140.828 c 82.688 140.492 82.234 140.324
81.504 140.324 c 72.984 140.324 l 72.309 140.324 71.852 140.465 71.617
140.754 c 71.379 141.039 71.266 141.445 71.266 141.965 c 71.266 177.14
l 71.266 177.664 71.379 178.078 71.617 178.39 c 71.852 178.703 72.309
178.863 72.984 178.863 c 81.504 178.863 l 82.23 178.863 82.688 178.676
82.871 178.312 c 83.055 177.949 83.145 177.558 83.145 177.14 c 83.145
175.265 l 83.195 175.265 83.238 175.25 83.262 175.226 c 83.289 175.199
83.324 175.187 83.379 175.187 c 85.098 176.492 87.105 177.547 89.398
178.351 c 91.688 179.16 93.773 179.566 95.648 179.566 c 98.414 179.566
100.59 179.109 102.176 178.199 c 103.77 177.285 104.953 176.086 105.734
174.601 c 106.52 173.117 106.996 171.461 107.18 169.637 c 107.363
167.812 107.453 165.988 107.453 164.168 c 107.453 141.965 l 107.461
141.547 107.367 141.172 107.184 140.832 c h
107.184 140.832 m f
137.324 145.015 m 136.281 144.078 135.16 143.269 133.965 142.594 c
132.766 141.914 131.543 141.355 130.289 140.914 c 129.039 140.469
127.812 140.16 126.613 139.976 c 125.414 139.793 124.32 139.703 123.332
139.703 c 121.039 139.703 119.176 140.027 117.742 140.68 c 116.309
141.328 115.199 142.18 114.422 143.223 c 113.637 144.262 113.102
145.473 112.82 146.855 c 112.531 148.234 112.391 149.68 112.391 151.195
c 112.336 153.594 112.66 155.621 113.367 157.293 c 114.07 158.961
115.074 160.301 116.375 161.316 c 117.68 162.332 119.27 163.066 121.145
163.508 c 123.02 163.949 125.105 164.172 127.398 164.172 c 136.391
164.172 l 136.391 165.422 l 136.391 166.254 136.293 166.961 136.117
167.531 c 135.93 168.105 135.594 168.574 135.102 168.937 c 134.605
169.305 133.914 169.578 133.027 169.762 c 132.141 169.941 130.969
170.035 129.512 170.035 c 128.938 170.035 128.219 170.008 127.359
169.957 c 126.5 169.902 125.605 169.851 124.664 169.797 c 123.727
169.746 122.785 169.668 121.848 169.562 c 120.91 169.461 120.051
169.379 119.27 169.328 c 118.176 169.226 117.457 169.226 117.121
169.328 c 116.781 169.433 116.508 169.879 116.301 170.66 c 115.441
174.723 l 115.336 175.398 115.43 175.957 115.715 176.402 c 116 176.844
116.742 177.301 117.941 177.769 c 118.828 178.086 119.855 178.355
121.031 178.594 c 122.203 178.828 123.402 179.023 124.625 179.18 c
125.852 179.336 127.062 179.453 128.262 179.531 c 129.461 179.609
130.504 179.644 131.391 179.644 c 135.035 179.644 137.969 179.308
140.184 178.629 c 142.398 177.953 144.09 176.988 145.266 175.738 c
146.438 174.488 147.203 172.949 147.57 171.125 c 147.934 169.301
148.117 167.219 148.117 164.871 c 148.117 152.523 l 148.117 151.687
148.156 151.035 148.238 150.566 c 148.312 150.098 148.457 149.746
148.664 149.512 c 148.871 149.277 149.16 149.105 149.523 149.004 c
149.887 148.898 150.383 148.82 151.008 148.769 c 151.688 148.715
152.129 148.598 152.336 148.418 c 152.547 148.234 152.652 147.91
152.652 147.441 c 152.652 142.433 l 152.652 141.394 151.895 140.715
150.383 140.402 c 148.926 140.039 147.309 139.855 145.535 139.855 c
143.609 139.855 141.914 140.183 140.453 140.832 c 138.996 141.484
138.004 142.851 137.484 144.937 c h
136.152 156.586 m 129.121 156.586 l 127.66 156.586 126.512 156.246
125.68 155.57 c 124.844 154.89 124.426 153.637 124.426 151.816 c
124.426 150.617 124.676 149.781 125.172 149.316 c 125.664 148.848
126.59 148.609 127.945 148.609 c 129.145 148.609 130.539 148.894
132.129 149.469 c 133.719 150.039 135.062 150.668 136.156 151.344 c
136.156 156.586 l h
136.152 156.586 m f
187.52 152.488 m 187.52 150.043 187.035 148 186.074 146.367 c 185.105
144.726 183.82 143.414 182.203 142.426 c 180.586 141.437 178.746
140.726 176.691 140.281 c 174.633 139.844 172.484 139.621 170.242
139.621 c 169.305 139.621 168.289 139.66 167.195 139.734 c 166.102
139.812 164.992 139.93 163.875 140.082 c 162.754 140.238 161.684
140.418 160.668 140.629 c 159.652 140.832 158.754 141.066 157.969
141.328 c 156.668 141.793 155.832 142.269 155.469 142.762 c 155.105
143.25 155.051 144.015 155.312 145.047 c 156.172 148.769 l 156.328
149.496 156.562 149.941 156.879 150.094 c 157.191 150.254 157.789
150.254 158.676 150.094 c 160.5 149.781 162.477 149.535 164.613 149.351
c 166.754 149.168 168.5 149.078 169.855 149.078 c 171.832 149.078
173.238 149.301 174.074 149.746 c 174.91 150.191 175.324 150.933
175.324 151.98 c 175.324 153.129 175.012 153.898 174.391 154.293 c
173.762 154.683 172.617 154.984 170.949 155.191 c 168.812 155.508
166.816 155.875 164.965 156.289 c 163.117 156.707 161.488 157.336
160.082 158.172 c 158.676 159.008 157.57 160.133 156.758 161.543 c
155.949 162.953 155.551 164.808 155.551 167.105 c 155.551 169.195
155.949 171.023 156.754 172.59 c 157.551 174.156 158.652 175.465
160.051 176.508 c 161.449 177.555 163.121 178.336 165.066 178.859 c
167.004 179.383 169.125 179.64 171.418 179.64 c 172.305 179.64 173.281
179.601 174.352 179.523 c 175.418 179.445 176.5 179.34 177.594 179.211
c 178.688 179.078 179.746 178.906 180.762 178.699 c 181.777 178.484
182.703 178.226 183.535 177.91 c 184.578 177.543 185.348 177.16 185.84
176.765 c 186.336 176.371 186.453 175.676 186.191 174.676 c 185.332
170.656 l 185.125 169.926 184.906 169.48 184.668 169.324 c 184.434
169.168 183.875 169.14 182.988 169.246 c 182.102 169.351 181.141
169.465 180.098 169.598 c 179.055 169.726 178.027 169.832 177.012
169.91 c 175.996 169.988 175.039 170.055 174.156 170.105 c 173.27
170.156 172.516 170.183 171.891 170.183 c 169.91 170.234 168.668
170.012 168.176 169.519 c 167.68 169.027 167.434 168.363 167.434
167.531 c 167.434 166.543 167.891 165.91 168.809 165.625 c 169.723
165.336 170.887 165.066 172.301 164.805 c 174.34 164.547 176.273
164.219 178.105 163.832 c 179.938 163.441 181.547 162.805 182.934
161.922 c 184.316 161.035 185.43 159.855 186.266 158.371 c 187.102
156.89 187.52 154.93 187.52 152.488 c h
187.52 152.488 m f
250.336 140.832 m 250.152 140.492 249.723 140.324 249.047 140.324 c
240.449 140.324 l 239.77 140.324 239.312 140.469 239.078 140.754 c
238.844 141.039 238.727 141.445 238.727 141.965 c 238.727 162.527 l
238.727 164.922 238.363 166.512 237.633 167.293 c 236.902 168.078
235.809 168.465 234.352 168.465 c 233.414 168.465 232.266 168.219
230.91 167.723 c 229.555 167.23 228.383 166.719 227.391 166.199 c
227.391 141.965 l 227.391 141.551 227.301 141.172 227.117 140.832 c
226.938 140.492 226.48 140.324 225.75 140.324 c 217.152 140.324 l
216.523 140.324 216.098 140.469 215.863 140.754 c 215.629 141.039
215.512 141.445 215.512 141.965 c 215.512 162.762 l 215.512 164.949
215.16 166.445 214.449 167.254 c 213.738 168.062 212.676 168.469
211.262 168.469 c 210.312 168.469 209.172 168.234 207.836 167.765 c
206.496 167.293 205.277 166.773 204.176 166.199 c 204.176 141.969 l
204.176 141.551 204.07 141.176 203.863 140.832 c 203.656 140.496
203.191 140.328 202.465 140.328 c 193.926 140.328 l 193.301 140.328
192.875 140.469 192.641 140.758 c 192.406 141.039 192.297 141.449
192.297 141.969 c 192.297 177.144 l 192.297 177.664 192.406 178.082
192.641 178.394 c 192.875 178.707 193.301 178.867 193.926 178.867 c
202.465 178.867 l 203.191 178.867 203.656 178.68 203.863 178.316 c
204.07 177.953 204.176 177.562 204.176 177.144 c 204.176 175.348 l
204.332 175.269 l 206 176.621 207.824 177.68 209.801 178.433 c 211.781
179.187 213.789 179.566 215.824 179.566 c 218.168 179.566 220.223
179.14 221.996 178.277 c 223.766 177.418 225.074 176.074 225.906 174.25
c 227.73 175.762 229.801 177.027 232.117 178.043 c 234.438 179.058
236.77 179.566 239.113 179.566 c 241.879 179.566 244.027 179.109
245.562 178.199 c 247.102 177.285 248.25 176.101 249.004 174.644 c
249.758 173.183 250.215 171.543 250.371 169.719 c 250.527 167.894
250.605 166.07 250.605 164.246 c 250.605 141.965 l 250.609 141.547
250.52 141.172 250.336 140.832 c h
250.336 140.832 m f
Q Q
showpage
%%Trailer
count op_count sub {pop} repeat
countdictstack dict_count sub {end} repeat
cairo_eps_state restore
%%EOF

174
doc/latex/src/ndisasm.tex Normal file
View File

@ -0,0 +1,174 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{ndisasm}{Ndisasm}
The Netwide Disassembler, NDISASM.
\xsection{ndisintro}{Introduction}
The Netwide Disassembler is a small companion program to the Netwide
Assembler, NASM. It seemed a shame to have an x86 assembler,
complete with a full instruction table, and not make as much use of
it as possible, so here's a disassembler which shares the
instruction table (and some other bits of code) with NASM.
The Netwide Disassembler does nothing except to produce
disassemblies of \emph{binary} source files. NDISASM does not have any
understanding of object file formats, like \code{objdump}, and it will
not understand \code{DOS .EXE} files like \code{debug} will. It just
disassembles.
\xsection{ndisrun}{Running NDISASM}
To disassemble a file, you will typically use a command of the form
\begin{lstlisting}
ndisasm -b {16|32|64} filename
\end{lstlisting}
NDISASM can disassemble 16-, 32- or 64-bit code equally easily,
provided of course that you remember to specify which it is to work
with. If no \codeindex{-b} switch is present, NDISASM works in 16-bit mode
by default. The \codeindex{-u} switch (for USE32) also invokes 32-bit mode.
Two more command line options are \codeindex{-r} which reports the version
number of NDISASM you are running, and \codeindex{-h} which gives a short
summary of command line options.
\xsubsection{ndiscom}{COM Files: Specifying an Origin}
To disassemble a \code{DOS .COM} file correctly, a disassembler must
assume that the first instruction in the file is loaded at address
\code{0x100}, rather than at zero. NDISASM, which assumes by default
that any file you give it is loaded at zero, will therefore need
to be informed of this.
The \codeindex{-o} option allows you to declare a different origin
for the file you are disassembling. Its argument may be expressed
in any of the NASM numeric formats: decimal by default, if it begins
with `\code{\$}' or `\code{0x}' or ends in `\code{H}' it's \code{hex},
if it ends in `\code{Q}' it's \code{octal}, and if it ends in
`\code{B}' it's \code{binary}.
Hence, to disassemble a \code{.COM} file:
\begin{lstlisting}
ndisasm -o100h filename.com
\end{lstlisting}
will do the trick.
\xsubsection{ndissync}{Code Following Data: Synchronisation}
Suppose you are disassembling a file which contains some data which
isn't machine code, and \emph{then} contains some machine code. NDISASM
will faithfully plough through the data section, producing machine
instructions wherever it can (although most of them will look
bizarre, and some may have unusual prefixes, e.g. `\code{FS OR AX,0x240A}'),
and generating `DB' instructions ever so often if it's totally stumped.
Then it will reach the code section.
Supposing NDISASM has just finished generating a strange machine
instruction from part of the data section, and its file position is
now one byte \emph{before} the beginning of the code section. It's
entirely possible that another spurious instruction will get
generated, starting with the final byte of the data section, and
then the correct first instruction in the code section will not be
seen because the starting point skipped over it. This isn't really
ideal.
To avoid this, you can specify a `\codeindex{synchronisation}' point, or indeed
as many synchronisation points as you like (although NDISASM can
only handle 2147483647 sync points internally). The definition of a sync
point is this: NDISASM guarantees to hit sync points exactly during
disassembly. If it is thinking about generating an instruction which
would cause it to jump over a sync point, it will discard that
instruction and output a `\code{db}' instead. So it \emph{will} start
disassembly exactly from the sync point, and so you \emph{will} see all
the instructions in your code section.
Sync points are specified using the \codeindex{-s} option: they are measured
in terms of the program origin, not the file position. So if you
want to synchronize after 32 bytes of a \codeindex{.COM} file, you would have to
do
\begin{lstlisting}
ndisasm -o100h -s120h file.com
\end{lstlisting}
rather than
\begin{lstlisting}
ndisasm -o100h -s20h file.com
\end{lstlisting}
As stated above, you can specify multiple sync markers if you need
to, just by repeating the \code{-s} option.
\xsubsection{ndisisync}{Mixed Code and Data: Automatic (Intelligent)
Synchronisation}
\indexcode{auto-sync}
Suppose you are disassembling the boot sector of a \code{DOS} floppy (maybe
it has a virus, and you need to understand the virus so that you
know what kinds of damage it might have done you). Typically, this
will contain a \code{JMP} instruction, then some data, then the rest of the
code. So there is a very good chance of NDISASM being \emph{misaligned}
when the data ends and the code begins. Hence a sync point is
needed.
On the other hand, why should you have to specify the sync point
manually? What you'd do in order to find where the sync point would
be, surely, would be to read the \code{JMP} instruction, and then to use
its target address as a sync point. So can NDISASM do that for you?
The answer, of course, is yes: using either of the synonymous
switches \codeindex{-a} (for automatic sync) or \codeindex{-i}
(for intelligent sync) will enable \code{auto-sync} mode. Auto-sync
mode automatically generates a sync point for any forward-referring
PC-relative jump or call instruction that NDISASM encounters. (Since
NDISASM is one-pass, if it encounters a PC-relative jump whose target
has already been processed, there isn't much it can do about it...)
Only PC-relative jumps are processed, since an absolute jump is
either through a register (in which case NDISASM doesn't know what
the register contains) or involves a segment address (in which case
the target code isn't in the same segment that NDISASM is working
in, and so the sync point can't be placed anywhere useful).
For some kinds of file, this mechanism will automatically put sync
points in all the right places, and save you from having to place
any sync points manually. However, it should be stressed that
auto-sync mode is \emph{not} guaranteed to catch all the sync points, and
you may still have to place some manually.
Auto-sync mode doesn't prevent you from declaring manual sync
points: it just adds automatically generated ones to the ones you
provide. It's perfectly feasible to specify \code{-i} \emph{and}
some \code{-s} options.
Another caveat with auto-sync mode is that if, by some unpleasant
fluke, something in your data section should disassemble to a
PC-relative call or jump instruction, NDISASM may obediently place a
sync point in a totally random place, for example in the middle of
one of the instructions in your code section. So you may end up with
a wrong disassembly even if you use auto-sync. Again, there isn't
much I can do about this. If you have problems, you'll have to use
manual sync points, or use the \code{-k} option (documented below) to
suppress disassembly of the data area.
\xsubsection{ndisother}{Other Options}
The \codeindex{-e} option skips a header on the file, by ignoring the first N
bytes. This means that the header is \emph{not} counted towards the
disassembly offset: if you give \code{-e10 -o10}, disassembly will start
at byte 10 in the file, and this will be given offset 10, not 20.
The \codeindex{-k} option is provided with two comma-separated numeric
arguments, the first of which is an assembly offset and the second
is a number of bytes to skip. This \emph{will} count the skipped bytes
towards the assembly offset: its use is to suppress disassembly of a
data section which wouldn't contain anything you wanted to see
anyway.

1606
doc/latex/src/outfmt.tex Normal file
View File

File diff suppressed because it is too large Load Diff

2400
doc/latex/src/preproc.tex Normal file
View File

File diff suppressed because it is too large Load Diff

902
doc/latex/src/running.tex Normal file
View File

@ -0,0 +1,902 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{run}{Running NASM}
\xsection{cmdline}{NASM \textindexlc{Command-Line} Syntax}
To assemble a file, you issue a command of the form
\begin{lstlisting}
nasm -f <format> <filename> [-o <output>]
\end{lstlisting}
For example,
\begin{lstlisting}
nasm -f elf myfile.asm
\end{lstlisting}
will assemble \code{myfile.asm} into an ``ELF'' object
file \code{myfile.o}. And
\begin{lstlisting}
nasm -f bin myfile.asm -o myfile.com
\end{lstlisting}
will assemble ``myfile.asm'' into a raw binary file ``myfile.com''.
To produce a listing file, with the hex codes output from NASM
displayed on the left of the original sources, use the \code{-l}
option to give a listing file name, for example:
\begin{lstlisting}
nasm -f coff myfile.asm -l myfile.lst
\end{lstlisting}
To get further usage instructions from NASM, try typing
\begin{lstlisting}
nasm -h
\end{lstlisting}
The option \code{--help} is an alias for the \c{-h} option.
The option \code{-hf} will also list the available output
file formats, and what they are.
If you use Linux but aren't sure whether your system is
``a.out'' or ``ELF'', type
\begin{lstlisting}
file nasm
\end{lstlisting}
(in the directory in which you put the NASM binary when you
installed it). If it says something like
\begin{lstlisting}
nasm: ELF 32-bit LSB executable i386 (386 and up) Version 1
\end{lstlisting}
then your system is ``ELF'', and you should use the option \code{-f elf}
when you want NASM to produce Linux object files. If it says
\begin{lstlisting}
nasm: Linux/i386 demand-paged executable (QMAGIC)
\end{lstlisting}
or something similar, your system is ``a.out'', and you should use
\code{-f aout} instead (Linux ``a.out'' systems have long been
obsolete, and are rare these days.)
Like Unix compilers and assemblers, NASM is silent unless it
goes wrong: you won't see any output at all, unless it gives error
messages.
\xsubsection{opt-o}{The \codeindex{-o} Option: Specifying the
\textindexlc{Output File Name}}
NASM will normally choose the name of your output file for you;
precisely how it does this is dependent on the object file format.
For Microsoft object file formats (\code{obj}, \code{win32}
and \code{win64}), it will remove the ``.asm'' \textindex{extension}
(or whatever extension you like to use~-- NASM doesn't care) from your
source file name and substitute ``.obj''. For Unix object file formats
(\code{aout}, \code{as86}, \code{coff}, \code{elf32}, \code{elf64},
\code{elfx32}, \code{ieee}, \code{macho32} and \code{macho64})
it will substitute ``.o''.
For \code{dbg}, \code{rdf}, \code{ith} and \code{srec}, it will use
``.dbg'', ``.rdf'', ``.ith'' and ``.srec'', respectively, and for
the \code{bin} format it will simply remove the extension, so that
``myfile.asm'' produces the output file ``myfile''.
If the output file already exists, NASM will overwrite it, unless it
has the same name as the input file, in which case it will give a
warning and use ``\textindex{nasm.out}'' as the output
file name instead.
For situations in which this behaviour is unacceptable, NASM
provides the \code{-o} command-line option, which allows you to
specify your desired output file name. You invoke \code{-o} by
following it with the name you wish for the output file, either
with or without an intervening space. For example:
\begin{lstlisting}
nasm -f bin program.asm -o program.com
nasm -f bin driver.asm -o driver.sys
\end{lstlisting}
Note that this is a small \code{-o}, and is different from a capital
\code{-O}, which is used to specify the number of optimisation passes
required. See \nref{opt-O}.
\xsubsection{opt-f}{The \codeindex{-f} Option: Specifying the
\textindexlc{Output File Format}}
If you do not supply the \code{-f} option to NASM, it will choose an
output file format for you itself. In the distribution versions of
NASM, the default is always \codeindex{bin}; if you've compiled
your own copy of NASM, you can redefine \codeindex{OF\_DEFAULT}
at compile time and choose what you want the default to be.
Like \code{-o}, the intervening space between \code{-f} and the output
file format is optional; so \code{-f elf} and \code{-felf} are both valid.
A complete list of the available output file formats can be given by
issuing the command \codeindex{nasm -hf}.
\xsubsection{opt-l}{The \codeindex{-l} Option: Generating a \textindexlc{Listing File}}
If you supply the \code{-l} option to NASM, followed (with the usual
optional space) by a file name, NASM will generate a \textindex{source-listing file}
for you, in which addresses and generated code are listed on the left, and the
actual source code, with expansions of multi-line macros (except those which
specifically request no expansion in source listings: see \nref{nolist})
on the right. For example:
\begin{lstlisting}
nasm -f elf myfile.asm -l myfile.lst
\end{lstlisting}
If a list file is selected, you may turn off listing for a section of your
source with \code{[list -]}, and turn it back on with \code{[list +]},
(the default, obviously). There is no ``user form'' (without the brackets).
This can be used to list only sections of interest, avoiding excessively
long listings.
\xsubsection{opt-M}{The \codeindex{-M} Option: Generate
\textindexlc{Makefile Dependencies}}
This option can be used to generate makefile dependencies on stdout.
This can be redirected to a file for further processing. For example:
\begin{lstlisting}
nasm -M myfile.asm > myfile.dep
\end{lstlisting}
\xsubsection{opt-MG}{The \codeindex{-MG} Option: Generate
\textindexlc{Makefile Dependencies}}
This option can be used to generate makefile dependencies on stdout.
This differs from the \code{-M} option in that if a nonexisting file is
encountered, it is assumed to be a generated file and is added to the
dependency list without a prefix.
\xsubsection{opt-MF}{The \codeindex{-MF} Option: Set Makefile Dependency File}
This option can be used with the \code{-M} or \code{-MG} options
to send the output to a file, rather than to stdout. For example:
\begin{lstlisting}
nasm -M -MF myfile.dep myfile.asm
\end{lstlisting}
\xsubsection{opt-MD}{The \codeindex{-MD} Option: Assemble
and Generate Dependencies}
The \code{-MD} option acts as the combination of the \code{-M}
and \code{-MF} options (i.e. a filename has to be specified).
However, unlike the \code{-M} or \code{-MG} options, \code{-MD}
does \emph{not} inhibit the normal operation of the assembler.
Use this to automatically generate updated dependencies with
every assembly session. For example:
\begin{lstlisting}
nasm -f elf -o myfile.o -MD myfile.dep myfile.asm
\end{lstlisting}
If the argument after \code{-MD} is an option rather than
a filename, then the output filename is the first applicable one of:
\begin{itemize}
\item{the filename set in the \code{-MF} option;}
\item{the output filename from the \code{-o} option with \code{.d} appended;}
\item{the input filename with the extension set to \code{.d}.}
\end{itemize}
\xsubsection{opt-MT}{The \codeindex{-MT} Option:
Dependency Target Name}
The \code{-MT} option can be used to override the default name of the
dependency target. This is normally the same as the output filename,
specified by the \code{-o} option.
\xsubsection{opt-MQ}{The \codeindex{-MQ} Option:
Dependency Target Name (Quoted)}
The \code{-MQ} option acts as the \code{-MT} option, except
it tries to quote characters that have special meaning in Makefile
syntax. This is not foolproof, as not all characters with special
meaning are quotable in Make. The default output (if no \code{-MT} or
\code{-MQ} option is specified) is automatically quoted.
\xsubsection{opt-MP}{The \codeindex{-MP} Option:
Emit phony targets}
When used with any of the dependency generation options, the
\code{-MP} option causes NASM to emit a phony target without
dependencies for each header file. This prevents Make from
complaining if a header file has been removed.
\xsubsection{opt-MW}{The \codeindex{-MW} Option: Watcom Make quoting style}
This option causes NASM to attempt to quote dependencies according to
Watcom Make conventions rather than POSIX Make conventions (also used
by most other Make variants). This quotes \code{\#} as \code{\$\#} rather
than \code{\textbackslash\#}, uses \code{\&} rather than \code{\textbackslash}
for continuation lines, and encloses filenames containing whitespace in
double quotes.
\xsubsection{opt-F}{The \codeindex{-F} Option:
Selecting a \textindexlc{Debug Information Format}}
This option is used to select the format of the debug information
emitted into the output file, to be used by a debugger (or \emph{will}
be). Prior to version 2.03.01, the use of this switch did \emph{not}
enable output of the selected debug info format. Use \codeindex{-g},
see \nref{opt-g}, to enable output. Versions 2.03.01 and later
automatically enable \code{-g} if \code{-F} is specified.
A complete list of the available debug file formats for an output
format can be seen by issuing the command \code{nasm -f <format> -y}.
Not all output formats currently support debugging output.
See \nref{opt-y}.
This should not be confused with the \code{-f dbg} output format option,
see \nref{dbgfmt}.
\xsubsection{opt-g}{The \codeindex{-g} Option:
Enabling \textindexlc{Debug Information}}
This option can be used to generate debugging information in the specified
format. See \nref{opt-F}. Using \code{-g} without \code{-F}
results in emitting debug info in the default format, if any, for the
selected output format. If no debug information is currently implemented
in the selected output format, \code{-g} is \emph{silently ignored}.
\xsubsection{opt-X}{The \codeindex{-X} Option:
Selecting an \textindexlc{Error Reporting Format}}
This option can be used to select an error reporting format for any
error messages that might be produced by NASM.
Currently, two error reporting formats may be selected. They are
the \code{-Xvc} option and the \code{-Xgnu} option.
The GNU format is the default and looks like this:
\begin{lstlisting}
filename.asm:65: error: specific error message
\end{lstlisting}
where \code{filename.asm} is the name of the source file in
which the error was detected, \code{65} is the source file
line number on which the error was detected, \code{error}
is the severity of the error (this could be \code{warning}),
and \code{specific error message} is a more detailed text message
which should help pinpoint the exact problem.
The other format, specified by \code{-Xvc} is the style used by
Microsoft Visual C++ and some other programs. It looks like this:
\begin{lstlisting}
filename.asm(65) : error: specific error message
\end{lstlisting}
where the only difference is that the line number is in parentheses
instead of being delimited by colons.
See also the \code{Visual C++} output format, \nref{win32fmt}.
\xsubsection{opt-Z}{The \codeindex{-Z} Option:
Send Errors to a File}
Under ``MS-\textindex{DOS}'' it can be difficult (though there are
ways) to redirect the standard-error output of a program to a file.
Since NASM usually produces its warning and \textindex{error messages}
on \codeindex{stderr}, this can make it hard to capture the
errors if (for example) you want to load them into an editor.
NASM therefore provides the \code{-Z} option, taking a filename argument
which causes errors to be sent to the specified files rather than standard
error. Therefore you can \index{redirecting errors}redirect the errors
into a file by typing
\begin{lstlisting}
nasm -Z myfile.err -f obj myfile.asm
\end{lstlisting}
In earlier versions of NASM, this option was called \code{-E},
but it was changed since \code{-E} is an option conventionally
used for preprocessing only, with disastrous results.
See \nref{opt-E}.
\xsubsection{opt-s}{The \codeindex{-s} Option:
Send Errors to \codeindex{stdout}}
The \code{-s} option redirects \textindexlc{error messages} to
\code{stdout} rather than \code{stderr}, so it can be redirected
under ``MS-\textindex{DOS}''. To assemble the file \code{myfile.asm}
and pipe its output to the \code{more} program, you can type:
\begin{lstlisting}
nasm -s -f obj myfile.asm | more
\end{lstlisting}
See also the \code{-Z} option, \nref{opt-Z}.
\xsubsection{opt-i}{The \codeindex{-i}\indexcode{-I} Option:
Include File Search Directories}
When NASM sees the \codeindex{\%include} or \codeindex{\%pathsearch} directive
in a source file (see \nref{include}, \nref{pathsearch} or
\nref{incbin}), it will search for the given file not only in the
current directory, but also in any directories specified on the command
line by the use of the \code{-i} option. Therefore you can include files
from a \textindex{macro library}, for example, by typing
\begin{lstlisting}
nasm -ic:\macrolib\ -f obj myfile.asm
\end{lstlisting}
(As usual, a space between \code{-i} and the path name is allowed, and
optional).
Prior NASM 2.14 a path provided in the option has been considered as
a verbatim copy and providing a path separator been up to a caller.
One could implicitly concatenate a search path together with a filename.
Still this was rather a trick than something useful. Now the trailing
path separator is made to always present, thus \code{-ifoo} will be
considered as the \code{-ifoo/} directory.
If you want to define a \emph{standard} \textindex{include search path},
similar to \code{/usr/include} on Unix systems, you should place one or
more \code{-i} directives in the \code{NASMENV} environment variable (see
\nref{nasmenv}).
For Makefile compatibility with many C compilers, this option can also
be specified as \code{-I}.
\xsubsection{opt-p}{The \codeindex{-p}\indexcode{-P} Option:
Pre-Include a File}
\index{pre-including files}
\indexcode{\%include}NASM allows you to specify files to be \emph{pre-included} into
your source file, by the use of the \code{-p} option. So running
\begin{lstlisting}
nasm myfile.asm -p myinc.inc
\end{lstlisting}
is equivalent to running \code{nasm myfile.asm} and placing the
directive \code{\%include "myinc.inc"} at the start of the file.
\code{--include} option is also accepted.
For consistency with the \code{-I}, \code{-D} and \code{-U} options,
this option can also be specified as \code{-P}.
\xsubsection{opt-d}{The \codeindex{-d}\indexcode{-D} Option:
Pre-Define a Macro}
\index{pre-defining macros}
\indexcode{\%define}Just as the \code{-p} option gives an alternative to placing
\code{\%include} directives at the start of a source file, the \code{-d}
option gives an alternative to placing a \code{\%define} directive. You
could code
\begin{lstlisting}
nasm myfile.asm -dFOO=100
\end{lstlisting}
as an alternative to placing the directive
\begin{lstlisting}
%define FOO 100
\end{lstlisting}
at the start of the file. You can miss off the macro value, as well:
the option \code{-dFOO} is equivalent to coding \code{\%define FOO}.
This form of the directive may be useful for selecting \textindex{assembly-time
options} which are then tested using \code{\%ifdef}, for example \code{-dDEBUG}.
For Makefile compatibility with many C compilers, this option can also
be specified as \code{-D}.
\xsubsection{opt-u}{The \codeindex{-u}\indexcode{-U} Option:
Undefine a Macro}
\index{undefining macros}
\indexcode{\%undef}The \code{-u} option undefines a macro that would otherwise
have been pre-defined, either automatically or by a \code{-p} or \code{-d}
option specified earlier on the command lines.
For example, the following command line:
\begin{lstlisting}
nasm myfile.asm -dFOO=100 -uFOO
\end{lstlisting}
would result in \code{FOO} \emph{not} being a predefined macro in the
program. This is useful to override options specified at a different
point in a Makefile.
For Makefile compatibility with many C compilers, this option can also
be specified as \code{-U}.
\xsubsection{opt-E}{The \codeindex{-E}\indexcode{-e} Option: Preprocess Only}
NASM allows the \textindex{preprocessor} to be run on its own, up to a
point. Using the \code{-E} option (which requires no arguments) will
cause NASM to preprocess its input file, expand all the macro references,
remove all the comments and preprocessor directives, and print the resulting
file on standard output (or save it to a file, if the \code{-o} option
is also used).
This option cannot be applied to programs which require the
preprocessor to evaluate \index{preprocessor expressions}
\textindex{expressions} which depend on the values of symbols:
so code such as
\begin{lstlisting}
%assign tablesize ($-tablestart)
\end{lstlisting}
will cause an error in \textindex{preprocess-only mode}.
For compatiblity with older version of NASM, this option can also be
written \code{-e}. \code{-E} in older versions of NASM was the equivalent
of the current \code{-Z} option, \nref{opt-Z}.
\xsubsection{opt-a}{The \codeindex{-a} Option: Don't Preprocess At All}
If NASM is being used as the back end to a compiler, it might be
desirable to \index{suppressing preprocessing}suppress preprocessing
completely and assume the compiler has already done it, to save time
and increase compilation speeds. The \code{-a} option, requiring no
argument, instructs NASM to replace its powerful \textindex{preprocessor}
with a \textindex{stub preprocessor} which does nothing.
\xsubsection{opt-O}{The \codeindex{-O} Option: Specifying
\textindexlc{Multipass Optimization}}
Using the \code{-O} option, you can tell NASM to carry out different
levels of optimization. Multiple flags can be specified after the
\code{-O} options, some of which can be combined in a single option,
e.g. \code{-Oxv}.
\begin{itemize}
\item{\code{-O0}: No optimization. All operands take their
long forms, if a short form is not specified, except conditional
jumps. This is intended to match NASM 0.98 behavior.}
\item{\code{-O1}: Minimal optimization. As above, but immediate
operands which will fit in a signed byte are optimized,
unless the long form is specified. Conditional jumps default
to the long form unless otherwise specified.}
\item{\code{-Ox} (where \code{x} is the actual letter \code{x}):
Multipass optimization. Minimize branch offsets and signed immediate
bytes, overriding size specification unless the \code{strict} keyword
has been used (see \nref{strict}). For compatibility with earlier
releases, the letter \code{x} may also be any number greater than
one. This number has no effect on the actual number of passes.}
\item{\code{-Ov}: At the end of assembly, print the number of passes
actually executed.}
\end{itemize}
The \code{-Ox} mode is recommended for most uses, and is the default
since NASM 2.09.
Note that this is a capital \code{O}, and is different from a small \code{o},
which is used to specify the output file name. See \nref{opt-o}.
\xsubsection{opt-t}{The \codeindex{-t} Option: Enable TASM Compatibility Mode}
NASM includes a limited form of compatibility with Borland's \textindex{TASM}.
When NASM's \code{-t} option is used, the following changes are made:
\begin{itemize}
\item{local labels may be prefixed with \code{@@} instead of \code{.};}
\item{size override is supported within brackets. In TASM compatible mode,
a size override inside square brackets changes the size of the operand,
and not the address type of the operand as it does in NASM syntax. E.g.
\code{mov eax,[DWORD val]} is valid syntax in TASM compatibility mode.
Note that you lose the ability to override the default address type for
the instruction;}
\item{unprefixed forms of some directives supported (\code{arg}, \code{elif},
\code{else}, \code{endif}, \code{if}, \code{ifdef}, \code{ifdifi},
\code{ifndef}, \code{include}, \code{local}).}
\end{itemize}
\xsubsection{opt-w}{The \codeindex{-w} and \codeindex{-W} Options:
Enable or Disable Assembly \textindexlc{Warnings}}
NASM can observe many conditions during the course of assembly which
are worth mentioning to the user, but not a sufficiently severe
error to justify NASM refusing to generate an output file. These
conditions are reported like errors, but come up with the word
``warning'' before the message. Warnings do not prevent NASM from
generating an output file and returning a success status to the
operating system.
Some conditions are even less severe than that: they are only
sometimes worth mentioning to the user. Therefore NASM supports the
\code{-w} command-line option, which enables or disables certain
classes of assembly warning. Such warning classes are described by a
name, for example \code{orphan-labels}; you can enable warnings of
this class by the command-line option \code{-w+orphan-labels} and
disable it by \code{-w-orphan-labels}.
The current \textindex{warning classes} are:
\begin{itemize}
\item \codeindex{other} specifies any warning not otherwise
specified in any class. Enabled by default.
\item \codeindex{macro-params} covers warnings about
\textindex{multi-line macros} being invoked with the wrong number
of parameters. Enabled by default, see \nref{mlmacover}
for an example of why you might want to disable it.
\item \codeindex{macro-selfref} warns if a macro references itself.
Disabled by default.
\item \codeindex{macro-defaults} warns when a macro has more
default parameters than optional parameters. Enabled by default,
see \nref{mlmacdef} for why you might want to disable it.
\item \codeindex{orphan-labels} covers warnings about source lines
which contain no instruction but define a label without a trailing colon.
NASM warns about this somewhat obscure condition by default,
see \nref{syntax} for more information.
\item \codeindex{number-overflow} covers warnings about numeric
constants which don't fit in 64 bits. Enabled by default.
\item \codeindex{gnu-elf-extensions} warns if 8-bit or 16-bit
relocations are used in \code{-f elf} format. The GNU extensions
allow this. Disabled by default.
\item \codeindex{float-overflow} warns about floating point overflow.
Enabled by default.
\item \codeindex{float-denorm} warns about floating point denormals.
Disabled by default.
\item \codeindex{float-underflow} warns about floating point underflow.
Disabled by default.
\item \codeindex{float-toolong} warns about too many digits in
floating-point numbers. Enabled by default.
\item \codeindex{user} controls \code{\%warning} directives (see
\nref{pperror}). Enabled by default.
\item \codeindex{lock} warns about \code{LOCK} prefixes on unlockable
instructions. Enabled by default.
\item \codeindex{hle} warns about invalid use of the HLE \code{XACQUIRE}
or \code{XRELEASE} prefixes. Enabled by default.
\item \codeindex{bnd} warns about ineffective use of the \code{BND}
prefix when a relaxed form of jmp instruction becomes jmp short form.
Enabled by default.
\item \codeindex{zext-reloc} warns that a relocation has been
zero-extended due to limitations in the output format. Enabled by default.
\item \codeindex{ptr} warns about keywords used in other assemblers that might
indicate a mistake in the source code. Currently only the MASM
\code{PTR} keyword is recognized. Enabled by default.
\item \codeindex{bad-pragma} warns about a malformed or otherwise unparsable
\code{\%pragma} directive. Disabled by default.
\item \codeindex{unknown-pragma} warns about an unknown \code{\%pragma} directive.
This is not yet implemented. Disabled by default.
\item \codeindex{not-my-pragma} warns about a \code{\%pragma} directive which is
not applicable to this particular assembly session. This is not yet
implemented. Disabled by default.
\item \codeindex{unknown-warning} warns about a \code{-w} or \code{-W} option or a
\code{[WARNING]} directive that contains an unknown warning name or is
otherwise not possible to process. Disabled by default.
\item \codeindex{all} is an alias for \emph{all} suppressible warning classes.
Thus, \code{-w+all} enables all available warnings, and \code{-w-all}
disables warnings entirely (since NASM 2.13).
\end{itemize}
Since version 2.00, NASM has also supported the \code{gcc}-like syntax
\code{-Wwarning-class} and \code{-Wno-warning-class} instead of
\code{-w+warning-class} and \code{-w-warning-class}, respectively; both
syntaxes work identically.
The option \code{-w+error} or \codeindex{-Werror} can be used to treat warnings
as errors. This can be controlled on a per warning class basis
(\code{-w+error=}\emph{warning-class} or \code{-Werror=}\emph{warning-class});
if no \emph{warning-class} is specified NASM treats it as
\code{-w+error=all}; the same applies to \code{-w-error} or
\codeindex{-Wno-error}, of course.
In addition, you can control warnings in the source code itself, using
the \codeindex{[WARNING]} directive. See \nref{asmdir-warning}.
\xsubsection{opt-v}{The \codeindex{-v} Option: Display \textindexlc{Version} Info}
Typing \code{NASM -v} will display the version of NASM which you are using,
and the date on which it was compiled.
You will need the version number if you report a bug.
For command-line compatibility with Yasm, the form \codeindex{--v} is also
accepted for this option starting in NASM version 2.11.05.
\xsubsection{opt-y}{The \codeindex{-y} Option: Display Available Debug Info Formats}
Typing \code{nasm -f <option> -y} will display a list of the available
debug info formats for the given output format. The default format
is indicated by an asterisk. For example:
\begin{lstlisting}
nasm -f elf -y
valid debug formats for 'elf32' output format are
('*' denotes default):
* stabs ELF32 (i386) stabs debug format for Linux
dwarf elf32 (i386) dwarf debug format for Linux
\end{lstlisting}
\xsubsection{opt-pfix}{The \codeindex{--(g|l)prefix}, \codeindex{--(g|l)postfix} Options}
The \code{--(g)prefix} options prepend the given argument
to all \code{extern}, \code{common}, \code{static}, and
\code{global} symbols, and the \code{--lprefix} option prepends
to all other symbols. Similarly, \code{--(g)postfix} and \code{--lpostfix}
options append the argument in the exactly same way as the \code{--xxprefix}
options does.
Running this:
\begin{lstlisting}
nasm -f macho --gprefix _
\end{lstlisting}
is equivalent to place the directive with \code{\%pragma macho gprefix \_}
at the start of the file (\nref{mangling}). It will prepend the underscore
to all global and external variables, as C requires it in some, but not all,
system calling conventions.
\xsubsection{opt-pragma}{The \codeindex{--pragma} Option}
NASM accepts an argument as \code{\%pragma} option, which is like placing
a \code{\%pragma} preprocess statement at the beginning of the source.
Running this:
\begin{lstlisting}
nasm -f macho --pragma "macho gprefix _"
\end{lstlisting}
is equivalent to the example in \nref{opt-pfix}.
\xsubsection{opt-before}{The \codeindex{--before} Option}
A preprocess statement can be accepted with this option. The example
shown in \nref{opt-pragma} is the same as running this:
\begin{lstlisting}
nasm -f macho --before "%pragma macho gprefix _"
\end{lstlisting}
\xsubsection{opt-limit}{The \codeindex{--limit-X} Option}
This option allows user to setup various maximum values for these:
\begin{itemize}
\item{\code{--limit-passes}: Number of maximum allowed passes. Default is
effectively unlimited.}
\item{\code{--limit-stalled-passes}: Maximum number of allowed unfinished
passes. Default is 1000.}
\item{\code{--limit-macro-levels}: Define maximum depth of macro expansion
(in preprocess). Default is 1000000.}
\item{\code{--limit-rep}: Maximum number of allowed preprocessor loop, defined
under \code{\%rep}. Default is 1000000.}
\item{\code{--limit-eval}: This number sets the boundary condition of allowed
expression length. Default is 1000000.}
\item{\code{--limit-lines}: Total number of source lines as allowed to be
processed. Default is 2000000000.}
\end{itemize}
In example, running this limits the maximum line count to be 1000.
\begin{lstlisting}
nasm --limit-lines 1000
\end{lstlisting}
\xsubsection{opt-keep-all}{The \codeindex{--keep-all} Option}
This option prevents NASM from deleting any output files even if an
error happens.
\xsubsection{opt-no-line}{The \codeindex{--no-line} Option}
If this option is given, all \codeindex{\%line} directives in the source code
are ignored. This can be useful for debugging already preprocessed
code. See \nref{line}.
\xsubsection{nasmenv}{The \codeindex{NASMENV} \textindex{Environment} Variable}
If you define an environment variable called \code{NASMENV}, the program
will interpret it as a list of extra command-line options, which are
processed before the real command line. You can use this to define
standard search directories for include files, by putting \code{-i}
options in the \code{NASMENV} variable.
The value of the variable is split up at white space, so that the
value \code{-s -ic:\textbackslash nasmlib\textbackslash} will be
treated as two separate options. However, that means that the value
\code{-dNAME="my name"} won't do what you might want, because it
will be split at the space and the NASM command-line processing
will get confused by the two nonsensical words \code{-dNAME="my}
and \code{name"}.
To get round this, NASM provides a feature whereby, if you begin the
\code{NASMENV} environment variable with some character that isn't
a minus sign, then NASM will treat this character as the
\textindex{separator character} for options. So setting the \code{NASMENV}
variable to the value \code{!-s!-ic:\textbackslash nasmlib\textbackslash}
is equivalent to setting it to \code{-s -ic:\textbackslash nasmlib\textbackslash},
but \code{!-dNAME="my name"} will work.
This environment variable was previously called \code{NASM}. This was
changed with version 0.98.31.
\xsection{qstart}{\textindex{Quick Start} for \textindex{MASM} Users}
If you're used to writing programs with MASM, or with \textindex{TASM} in
MASM-compatible (non-Ideal) mode, or with \textindex{a86}, this section
attempts to outline the major differences between MASM's syntax and
NASM's. If you're not already used to MASM, it's probably worth
skipping this section.
\xsubsection{qscs}{NASM Is \index{case sensitivity}Case-Sensitive}
One simple difference is that NASM is case-sensitive. It makes a
difference whether you call your label \code{foo}, \code{Foo} or
\code{FOO}. If you're assembling to DOS or OS/2 ``.OBJ'' files,
you can invoke the \codeindex{UPPERCASE} directive (documented in
\nref{objfmt}) to ensure that all symbols exported to other
code modules are forced to be upper case; but even then, \emph{within}
a single module, NASM will distinguish between labels differing only
in case.
\xsubsection{qsbrackets}{NASM Requires \textindexlc{Square Brackets}
For \textindexlc{Memory References}}
NASM was designed with simplicity of syntax in mind. One of the
\textindex{design goals} of NASM is that it should be possible,
as far as is practical, for the user to look at a single line of
NASM code and tell what opcode is generated by it. You can't do
this in MASM: if you declare, for example,
\begin{lstlisting}
foo equ 1
bar dw 2
\end{lstlisting}
then the two lines of code
\begin{lstlisting}
mov ax,foo
mov ax,bar
\end{lstlisting}
generate completely different opcodes, despite having
identical-looking syntaxes.
NASM avoids this undesirable situation by having a much simpler
syntax for memory references. The rule is simply that any access to
the \emph{contents} of a memory location requires square brackets
around the address, and any access to the \emph{address} of a variable
doesn't. So an instruction of the form \code{mov ax,foo} will
\emph{always} refer to a compile-time constant, whether it's an \code{EQU}
or the address of a variable; and to access the \emph{contents} of the
variable \code{bar}, you must code \code{mov ax,[bar]}.
This also means that NASM has no need for MASM's \codeindex{OFFSET}
keyword, since the MASM code \code{mov ax,offset bar} means exactly the
same thing as NASM's \code{mov ax,bar}. If you're trying to get
large amounts of MASM code to assemble sensibly under NASM, you
can always code \code{\%idefine offset} to make the preprocessor
treat the \code{OFFSET} keyword as a no-op.
This issue is even more confusing in \textindex{a86}, where declaring a
label with a trailing colon defines it to be a `label' as opposed to
a `variable' and causes a86 to adopt NASM-style semantics; so in
a86, \code{mov ax,var} has different behaviour depending on whether
\code{var} was declared as \code{var: dw 0} (a label) or
\code{var dw 0} (a word-size variable). NASM is very simple by
comparison: \emph{everything} is a label.
NASM, in the interests of simplicity, also does not support the
\textindex{hybrid syntaxes} supported by MASM and its clones, such as
\code{mov ax,table[bx]}, where a memory reference is denoted by one
portion outside square brackets and another portion inside. The
correct syntax for the above is \code{mov ax,[table+bx]}. Likewise,
\code{mov ax,es:[di]} is wrong and \code{mov ax,[es:di]} is right.
\xsubsection{qstypes}{NASM Doesn't Store \textindexlc{Variable Types}}
NASM, by design, chooses not to remember the types of variables you
declare. Whereas MASM will remember, on seeing \code{var dw 0}, that
you declared \code{var} as a word-size variable, and will then be able
to fill in the \textindex{ambiguity} in the size of the instruction
\code{mov var,2}, NASM will deliberately remember nothing about
the symbol \code{var} except where it begins, and so you must
explicitly code \code{mov word [var],2}.
For this reason, NASM doesn't support the \code{LODS}, \code{MOVS},
\code{STOS}, \code{SCAS}, \code{CMPS}, \code{INS}, or \code{OUTS}
instructions, but only supports the forms such as \code{LODSB},
\code{MOVSW}, and \code{SCASD}, which explicitly specify the size
of the components of the strings being manipulated.
\xsubsection{qsassume}{NASM Doesn't \codeindex{ASSUME}}
As part of NASM's drive for simplicity, it also does not support the
\code{ASSUME} directive. NASM will not keep track of what values you
choose to put in your segment registers, and will never \emph{automatically}
generate a \textindex{segment override} prefix.
\xsubsection{qsmodel}{NASM Doesn't Support \textindexlc{Memory Models}}
NASM also does not have any directives to support different 16-bit
memory models. The programmer has to keep track of which functions
are supposed to be called with a \textindex{far call} and which with a
\textindex{near call}, and is responsible for putting the correct form of
\code{RET} instruction (\code{RETN} or \code{RETF}; NASM accepts
\code{RET} itself as an alternate form for \code{RETN}); in addition,
the programmer is responsible for coding CALL FAR instructions where
necessary when calling \emph{external} functions, and must also keep
track of which external variable definitions are far and which are
near.
\xsubsection{qsfpu}{\textindexlc{Floating-Point} Differences}
NASM uses different names to refer to floating-point registers from
MASM: where MASM would call them \code{ST(0)}, \code{ST(1)} and
so on, and \textindex{a86} would call them simply \code{0}, \code{1}
and so on, NASM chooses to call them \code{st0}, \code{st1} etc.
As of version 0.96, NASM now treats the instructions with
`\textindex{nowait}' forms in the same way as MASM-compatible assemblers.
The idiosyncratic treatment employed by 0.95 and earlier was based
on a misunderstanding by the authors.
\xsubsection{qsother}{Other Differences}
For historical reasons, NASM uses the keyword \codeindex{TWORD} where
MASM and compatible assemblers use \codeindex{TBYTE}.
NASM does not declare \textindex{uninitialized storage} in the same way
as MASM: where a MASM programmer might use \code{stack db 64 dup (?)},
NASM requires \code{stack resb 64}, intended to be read as \emph{reserve 64
bytes}. For a limited amount of compatibility, since NASM treats
\code{?} as a valid character in symbol names, you can code \code{? equ 0}
and then writing \code{dw ?} will at least do something vaguely useful.
\index{RESB}\codeindex{DUP} is still not a supported syntax, however.
In addition to all of this, macros and directives work completely
differently to MASM. See \nref{preproc} and \nref{directive}
for further details.

53
doc/latex/src/source.tex Normal file
View File

@ -0,0 +1,53 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{source}{Building NASM from Source}
The source code for NASM is available from our website,
\href{http://www.nasm.us/}{http://wwww.nasm.us/},
see \nref{website}.
\xsection{tarball}{Building from a Source Archive}
The source archives available on the web site should be capable of
building on a number of platforms. This is the recommended method for
building NASM to support platforms for which executables are not
available.
On a system which has Unix shell (\code{sh}), run:
\begin{lstlisting}
sh configure
make everything
\end{lstlisting}
A number of options can be passed to \code{configure}; see
\code{sh configure --help}.
A set of Makefiles for some other environments are also available;
please see the file \code{Mkfiles/README}.
To build the installer for the Windows platform, you will need the
Nullsoft Scriptable Installer, \textindex{NSIS}, installed.
To build the documentation, you will need a set of additional tools.
The documentation is not likely to be able to build on non-Unix
systems.
\xsection{git}{Building from the \codeindex{git} Repository}
The NASM development tree is kept in a source code repository using
the \code{git} distributed source control system. The link is available
on the website. This is recommended only to participate in the
development of NASM or to assist with testing the development code.
To build NASM from the \code{git} repository you will need a Perl and, if
building on a Unix system, GNU autoconf.
To build on a Unix system, run:
\begin{lstlisting}
sh autogen.sh
\end{lstlisting}
to create the \code{configure} script and then build as listed above.

114
doc/latex/src/trouble.tex Normal file
View File

@ -0,0 +1,114 @@
%
% vim: ts=4 sw=4 et
%
\xchapter{trouble}{Troubleshooting}
This chapter describes some of the common problems that users have
been known to encounter with NASM, and answers them. If you think you
have found a bug in NASM, please see \nref{bugs}.
\xsection{problems}{Common Problems}
\xsubsection{inefficient}{NASM Generates \textindexlc{Inefficient Code}}
We sometimes get `bug' reports about NASM generating inefficient, or
even `wrong', code on instructions such as \code{ADD ESP,8}. This is a
deliberate design feature, connected to predictability of output:
NASM, on seeing \code{ADD ESP,8}, will generate the form of the
instruction which leaves room for a 32-bit offset. You need to code
\indexcode{BYTE}\code{ADD ESP,BYTE 8} if you want the space-efficient
form of the instruction. This isn't a bug, it's user error: if you
prefer to have NASM produce the more efficient code automatically enable
optimization with the \code{-O} option (see \nref{opt-O}).
\xsubsection{jmprange}{My Jumps are Out of Range}
\index{out of range!jumps}
Similarly, people complain that when they issue \textindex{conditional
jumps} (which are \code{SHORT} by default) that try to jump too far,
NASM reports `short jump out of range' instead of making the jumps
longer.
This, again, is partly a predictability issue, but in fact has a
more practical reason as well. NASM has no means of being told what
type of processor the code it is generating will be run on; so it
cannot decide for itself that it should generate \codeindex{Jcc NEAR}
type instructions, because it doesn't know that it's working for a 386 or
above. Alternatively, it could replace the out-of-range short
\code{JNE} instruction with a very short \code{JE} instruction that jumps
over a \code{JMP NEAR}; this is a sensible solution for processors
below a 386, but hardly efficient on processors which have good
branch prediction \emph{and} could have used \code{JNE NEAR} instead. So,
once again, it's up to the user, not the assembler, to decide what
instructions should be generated. See \nref{opt-O}.
\xsubsection{proborg}{\codeindex{ORG} Doesn't Work}
People writing \textindex{boot sector} programs in the \code{bin} format often
complain that \code{ORG} doesn't work the way they'd like: in order to
place the \code{0xAA55} signature word at the end of a 512-byte boot
sector, people who are used to MASM tend to code
\begin{lstlisting}
ORG 0
; some boot sector code
ORG 510
DW 0xAA55
\end{lstlisting}
This is not the intended use of the \code{ORG} directive in NASM, and
will not work. The correct way to solve this problem in NASM is to
use the \codeindex{TIMES} directive, like this:
\begin{lstlisting}
ORG 0
; some boot sector code
TIMES 510-($-$$) DB 0
DW 0xAA55
\end{lstlisting}
The \code{TIMES} directive will insert exactly enough zero bytes into
the output to move the assembly point up to 510. This method also
has the advantage that if you accidentally fill your boot sector too
full, NASM will catch the problem at assembly time and report it, so
you won't end up with a boot sector that you have to disassemble to
find out what's wrong with it.
\xsubsection{probtimes}{\codeindex{TIMES} Doesn't Work}
The other common problem with the above code is people who write the
\code{TIMES} line as
\begin{lstlisting}
TIMES 510-$ DB 0
\end{lstlisting}
by reasoning that \code{\$} should be a pure number, just like 510, so
the difference between them is also a pure number and can happily be
fed to \code{TIMES}.
NASM is a \emph{modular} assembler: the various component parts are
designed to be easily separable for re-use, so they don't exchange
information unnecessarily. In consequence, the \code{bin} output
format, even though it has been told by the \code{ORG} directive that
the \code{.text} section should start at 0, does not pass that
information back to the expression evaluator. So from the
evaluator's point of view, \code{\$} isn't a pure number: it's an offset
from a section base. Therefore the difference between \code{\$} and 510
is also not a pure number, but involves a section base. Values
involving section bases cannot be passed as arguments to \code{TIMES}.
The solution, as in the previous section, is to code the \code{TIMES}
line in the form
\begin{lstlisting}
TIMES 510-($-$$) DB 0
\end{lstlisting}
in which \code{\$} and \code{\$\$} are offsets from the same section base,
and so their difference is a pure number. This will solve the
problem and generate sensible code.

4
doc/latex/src/version.tex Normal file
View File

@ -0,0 +1,4 @@
%
% vim: ts=4 sw=4 et
%
\newcommand{\version}{2.14.01-272-gb3f7c8eb}