aboutsummaryrefslogtreecommitdiffstats
path: root/doc/latex/src
diff options
context:
space:
mode:
Diffstat (limited to 'doc/latex/src')
-rw-r--r--doc/latex/src/16bit.tex868
-rw-r--r--doc/latex/src/32bit.tex539
-rw-r--r--doc/latex/src/64bit.tex204
-rw-r--r--doc/latex/src/changelog.tex2304
-rw-r--r--doc/latex/src/contact.tex111
-rw-r--r--doc/latex/src/directive.tex541
-rw-r--r--doc/latex/src/idxconf.ist9
-rw-r--r--doc/latex/src/inslist.tex14
-rw-r--r--doc/latex/src/intro.tex55
-rw-r--r--doc/latex/src/language.tex945
-rw-r--r--doc/latex/src/macropkg.tex127
-rw-r--r--doc/latex/src/mixsize.tex185
-rw-r--r--doc/latex/src/nasm.tex163
-rw-r--r--doc/latex/src/nasmlogo.eps212
-rw-r--r--doc/latex/src/ndisasm.tex174
-rw-r--r--doc/latex/src/outfmt.tex1606
-rw-r--r--doc/latex/src/preproc.tex2400
-rw-r--r--doc/latex/src/running.tex902
-rw-r--r--doc/latex/src/source.tex53
-rw-r--r--doc/latex/src/trouble.tex114
-rw-r--r--doc/latex/src/version.tex4
21 files changed, 11530 insertions, 0 deletions
diff --git a/doc/latex/src/16bit.tex b/doc/latex/src/16bit.tex
new file mode 100644
index 00000000..79bebcb9
--- /dev/null
+++ b/doc/latex/src/16bit.tex
@@ -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.
diff --git a/doc/latex/src/32bit.tex b/doc/latex/src/32bit.tex
new file mode 100644
index 00000000..47c27466
--- /dev/null
+++ b/doc/latex/src/32bit.tex
@@ -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.
diff --git a/doc/latex/src/64bit.tex b/doc/latex/src/64bit.tex
new file mode 100644
index 00000000..5aaf20f6
--- /dev/null
+++ b/doc/latex/src/64bit.tex
@@ -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}.
diff --git a/doc/latex/src/changelog.tex b/doc/latex/src/changelog.tex
new file mode 100644
index 00000000..4a03a6be
--- /dev/null
+++ b/doc/latex/src/changelog.tex
@@ -0,0 +1,2304 @@
+%
+% vim: ts=4 sw=4 et
+%
+\xchapter{changelog}{\textindexlc{NASM Version History}}
+
+\xsection{cl-2.xx}{NASM 2 Series}
+
+The NASM 2 series supports x86-64, and is the production version of NASM
+since 2007.
+
+\xsubsection{cl-2.15}{Version 2.15}
+
+\begin{itemize}
+ \item{The state of warnings can now be saved and restored via
+ the \code{[WARNING PUSH]} and \code{[WARNING POP]} directives.
+ See \nref{asmdir-warning}}.
+\end{itemize}
+
+\xsubsection{cl-2.14.03}{Version 2.14.03}
+
+\begin{itemize}
+ \item{Suppress nuisance "\code{label changed during code
+ generation}" messages after a real error.}
+\end{itemize}
+
+\xsubsection{cl-2.14.02}{Version 2.14.02}
+
+\begin{itemize}
+ \item{Fix crash due to multiple errors or warnings during the code
+ generation pass if a list file is specified.}
+\end{itemize}
+
+\xsubsection{cl-2.14.01}{Version 2.14.01}
+
+\begin{itemize}
+ \item{Create all system-defined macros defore processing command-line
+ given preprocessing directives (\code{-p}, \code{-d}, \code{-u}, \code{--pragma},
+ \code{--before}).}
+
+ \item{If debugging is enabled, define a \code{\_\_DEBUG\_FORMAT\_\_} predefined
+ macro. See \nref{dfmtm}.}
+
+ \item{Fix an assert for the case in the \code{obj} format when a \code{SEG}
+ operator refers to an \code{EXTERN} symbol declared further down in the
+ code.}
+
+ \item{Fix a corner case in the floating-point code where a binary, octal
+ or hexadecimal floating-point having at least 32, 11, or 8 mantissa
+ digits could produce slightly incorrect results under very specific
+ conditions.}
+
+ \item{Support \code{-MD} without a filename, for \code{gcc} compatibility.
+ \code{-MF} can be used to set the dependencies output filename.
+ See \nref{opt-MD}.}
+
+ \item{Fix \code{-E} in combination with \code{-MD}. See \nref{opt-E}.}
+
+ \item{Fix missing errors on redefined labels; would cause convergence
+ failure instead which is very slow and not easy to debug.}
+
+ \item{Duplicate definitions of the same label \emph{with the same value} is now
+ explicitly permitted (2.14 would allow it in some circumstances.)}
+
+ \item{Add the option \code{--no-line} to ignore \code{\%line} directives in the
+ source. See \nref{opt-no-line} and \nref{line}.}
+\end{itemize}
+
+\xsubsection{cl-2.14}{Version 2.14}
+
+\begin{itemize}
+ \item{Changed \code{-I} option semantics by adding a trailing path
+ separator unconditionally.}
+
+ \item{Fixed null dereference in corrupted invalid single line macros.}
+
+ \item{Fixed division by zero which may happen if source code is malformed.}
+
+ \item{Fixed out of bound access in processing of malformed segment override.}
+
+ \item{Fixed out of bound access in certain \code{EQU} parsing.}
+
+ \item{Fixed buffer underflow in float parsing.}
+
+ \item{Added \code{SGX} (Intel Software Guard Extensions) instructions.}
+
+ \item{Added \code{+n} syntax for multiple contiguous registers.}
+
+ \item{Fixed \code{subsections\_via\_symbols} for \code{macho} object format.}
+
+ \item{Added the \code{--gprefix}, \code{--gpostfix}, \code{--lprefix}, and
+ \code{--lpostfix} command line options, to allow command line base symbol
+ renaming. See \nref{opt-pfix}.}
+
+ \item{Allow label renaming to be specified by \code{\%pragma} in addition to
+ from the command line. See \nref{mangling}.}
+
+ \item{Supported generic \code{\%pragma} namespaces, \code{output} and \code{debug}.
+ See \nref{gen-namespace}.}
+
+ \item{Added the \code{--pragma} command line option to inject a \code{\%pragma}
+ directive. See \nref{opt-pragma}.}
+
+ \item{Added the \code{--before} command line option to accept preprocess
+ statement before input. See \nref{opt-before}.}
+
+ \item{Added \code{AVX512} \code{VBMI2} (Additional Bit Manipulation), \code{VNNI}
+ (Vector Neural Network), \code{BITALG} (Bit Algorithm), and \code{GFNI} (Galois
+ Field New Instruction) instructions.}
+
+ \item{Added the \code{STATIC} directive for local symbols that should be
+ renamed using global-symbol rules. See \nref{static}.}
+
+ \item{Allow a symbol to be defined as \code{EXTERN} and then later
+ overridden as \code{GLOBAL} or \code{COMMON}. Furthermore, a symbol
+ declared \code{EXTERN} and then defined will be treated as \code{GLOBAL}.
+ See \nref{extern}.}
+
+ \item{The \code{GLOBAL} directive no longer is required to precede the
+ definition of the symbol.}
+
+ \item{Support \code{private\_extern} as \code{macho} specific extension to the
+ \code{GLOBAL} directive. See \nref{macho-pext}.}
+
+ \item{Updated \code{UD0} encoding to match with the specification}
+
+ \item{Added the \code{--limit-X} command line option to set execution
+ limits. See \nref{opt-limit}.}
+
+ \item{Updated the \code{Codeview} version number to be aligned with \code{MASM}.}
+
+ \item{Added the \code{--keep-all} command line option to preserve output
+ files. See \nref{opt-keep-all}.}
+
+ \item{Added the \code{--include} command line option, an alias to \code{-P}
+ (\nref{opt-p}).}
+
+ \item{Added the \code{--help} command line option as an alias to \code{-h}
+ (\nref{syntax}).}
+
+ \item{Added \code{-W}, \code{-D}, and \code{-Q} suffix aliases for \code{RET}
+ instructions so the operand sizes of these instructions can be
+ encoded without using \code{o16}, \code{o32} or \code{o64}.}
+\end{itemize}
+
+\xsubsection{cl-2.13.03}{Version 2.13.03}
+
+\begin{itemize}
+ \item{Added AVX and AVX512 \code{VAES*} and \code{VPCLMULQDQ} instructions.}
+ \item{Fixed missing dwarf record in x32 ELF output format.}
+\end{itemize}
+
+\xsubsection{cl-2.13.02}{Version 2.13.02}
+
+\begin{itemize}
+ \item{Fix false positive in testing of numeric overflows.}
+
+ \item{Fix generation of \code{PEXTRW} instruction.}
+
+ \item{Fix \code{smartalign} package which could trigger an error during
+ optimization if the alignment code expanded too much due to
+ optimization of the previous code.}
+
+ \item{Fix a case where negative value in \code{TIMES} directive causes
+ panic instead of an error.}
+
+ \item{Always finalize \code{.debug\_abbrev} section with a null in
+ \code{dwarf} output format.}
+
+ \item{Support \code{debug} flag in section attributes for \code{macho}
+ output format. See \nref{machosect}.}
+
+ \item{Support up to 16 characters in section names for \code{macho}
+ output format.}
+
+ \item{Fix missing update of global \code{BITS} setting if \code{SECTION}
+ directive specified a bit size using output format-specific
+ extensions (e.g. \code{USE32} for the \code{obj} output format.)}
+
+ \item{Fix the incorrect generation of VEX-encoded instruction when static
+ mode decorators are specified on scalar instructions, losing the
+ decorators as they require EVEX encoding.}
+
+ \item{Option \code{-MW} to quote dependency outputs according to Watcom
+ Make conventions instead of POSIX Make conventions. See \nref{opt-MW}.}
+
+ \item{The \code{obj} output format now contains embedded dependency file
+ information, unless disabled with \code{\%pragma obj nodepend}. See
+ \nref{objdepend}.}
+
+ \item{Fix generation of dependency lists.}
+
+ \item{Fix a number of null pointer reference and memory allocation errors.}
+
+ \item{Always generate symbol-relative relocations for the \code{macho64}
+ output format; at least some versions of the XCode/LLVM linker fails
+ for section-relative relocations.}
+\end{itemize}
+
+\xsubsection{cl-2.13.01}{Version 2.13.01}
+
+\begin{itemize}
+ \item{Fix incorrect output for some types of \code{FAR} or \code{SEG}
+ references in the \code{obj} output format, and possibly other 16-bit
+ output formats.}
+
+ \item{Fix the address in the list file for an instruction containing a
+ \code{TIMES} directive.}
+
+ \item{Fix error with \code{TIMES} used together with an instruction which
+ can vary in size, e.g. \code{JMP}.}
+
+ \item{Fix breakage on some uses of the \code{DZ} pseudo-op.}
+\end{itemize}
+
+\xsubsection{cl-2.13}{Version 2.13}
+
+\begin{itemize}
+ \item{Support the official forms of the \code{UD0} and \code{UD1} instructions.}
+
+ \item{Allow self-segment-relative expressions in immediates and
+ displacements, even when combined with an external or otherwise
+ out-of-segment special symbol, e.g.:
+\begin{lstlisting}
+extern foo
+mov eax,[foo - $ + ebx] ; Now legal
+\end{lstlisting}}
+
+ \item{Handle a 64-bit origin in NDISASM.}
+
+ \item{NASM can now generate sparse output files for relevant output
+ formats, if the underlying operating system supports them.}
+
+ \item{The \code{macho} object format now supports the
+ \code{subsections\_via\_symbols} and \code{no\_dead\_strip}
+ directives, see \nref{macho-ssvs}.}
+
+ \item{The \code{macho} object format now supports the \code{no\_dead\_strip},
+ \code{live\_support} and \code{strip\_static\_syms} section flags,
+ see \nref{machosect}.}
+
+ \item{The \code{macho} object format now supports the \code{dwarf} debugging
+ format, as required by newer toolchains.}
+
+ \item{All warnings can now be suppressed if desired; warnings not
+ otherwise part of any warning class are now considered its own
+ warning class called \code{other} (e.g. \code{-w-other}). Furthermore,
+ warning-as-error can now be controlled on a per warning class
+ basis, using the syntax \code{-w+error=}\emph{warning-class} and its
+ equivalent for all other warning control options. See \nref{opt-w}
+ for the command-line options and warning classes and
+ \nref{asmdir-warning} for the \code{[WARNING]} directive.}
+
+ \item{Fix a number of bugs related to AVX-512 decorators.}
+
+ \item{Significant improvements to building NASM with Microsoft Visual
+ Studio via \code{Mkfiles/msvc.mak}. It is now possible to build the
+ full Windows installer binary as long as the necessary
+ prerequisites are installed; see \code{Mkfiles/README}}
+
+ \item{To build NASM with custom modifications (table changes) or from the
+ git tree now requires Perl 5.8 at the very minimum, quite possibly
+ a higher version (Perl 5.24.1 tested.) There is no requirement to
+ have Perl on your system at all if all you want to do is build
+ unmodified NASM from source archives.}
+
+ \item{Fix the \code{\{z\}} decorator on AVX-512 \code{VMOVDQ*}
+ instructions.}
+
+ \item{Add new warnings for certain dangerous constructs which never ought
+ to have been allowed. In particular, the \code{RESB} family of
+ instructions should have been taking a critical expression all
+ along.}
+
+ \item{Fix the EVEX (AVX-512) versions of the \code{VPBROADCAST}, \code{VPEXTR},
+ and \code{VPINSR} instructions.}
+
+ \item{Support contracted forms of additional instructions. As a general
+ rule, if an instruction has a non-destructive source immediately
+ after a destination register that isn't used as an input, NASM
+ supports omitting that source register, using the destination
+ register as that value. This among other things makes it easier to
+ convert SSE code to the equivalent AVX code:
+\begin{lstlisting}
+addps xmm1,xmm0 ; SSE instruction
+vaddps ymm1,ymm1,ymm0 ; AVX official long form
+vaddps ymm1,ymm0 ; AVX contracted form
+\end{lstlisting}}
+
+ \item{Fix Codeview malformed compiler version record.}
+
+ \item{Add the \code{CLWB} and \code{PCOMMIT} instructions. Note that the
+ \code{PCOMMIT} instruction has been deprecated and will never be
+ included in a shipping product; it is included for completeness
+ only.}
+
+ \item{Add the \code{\%pragma} preprocessor directive for
+ soft-error directives.}
+
+ \item{Add the \code{RDPID} instruction.}
+\end{itemize}
+
+\xsubsection{cl-2.12.02}{Version 2.12.02}
+
+\begin{itemize}
+ \item{Fix preprocessor errors, especially \code{\%error} and
+ \code{\%warning}, inside \code{\%if} statements.}
+
+ \item{Fix relative relocations in 32-bit Mach-O.}
+
+ \item{More Codeview debug format fixes.}
+
+ \item{If the MASM \code{PTR} keyword is encountered, issue a warning. This is
+ much more likely to indicate a MASM-ism encountered in NASM than it
+ is a valid label. This warning can be suppressed with \code{-w-ptr},
+ the \code{[warning]} directive (see \nref{opt-w}) or by the macro
+ definition \code{\%idefine ptr \$\%} (see \nref{selfref}).}
+
+ \item{When an error or a warning comes from the expansion of a multi-line
+ macro, display the file and line numbers for the expanded macros.
+ Macros defined with \code{.nolist} do not get displayed.}
+
+ \item{Add macros \code{ilog2fw()} and \code{ilog2cw()} to the \code{ifunc} macro
+ package. See \nref{ilog2}.}
+\end{itemize}
+
+\xsubsection{cl-2.12.01}{Version 2.12.01}
+
+\begin{itemize}
+ \item{Portability fixes for some platforms.}
+ \item{Fix error when not specifying a list file.}
+ \item{Correct the handling of macro-local labels in the Codeview debugging format.}
+ \item{Add \code{CLZERO}, \code{MONITORX} and \code{MWAITX} instructions.}
+\end{itemize}
+
+\xsubsection{cl-2.12}{Version 2.12}
+
+\begin{itemize}
+ \item{Major fixes to the \code{macho} backend (\nref{machofmt}); earlier versions
+ would produce invalid symbols and relocations on a regular basis.}
+
+ \item{Support for thread-local storage in Mach-O.}
+
+ \item{Support for arbitrary sections in Mach-O.}
+
+ \item{Fix wrong negative size treated as a big positive value passed into
+ backend causing NASM to crash.}
+
+ \item{Fix handling of zero-extending unsigned relocations, we have been printing
+ wrong message and forgot to assign segment with predefined value before
+ passing it into output format.}
+
+ \item{Fix potential write of oversized (with size greater than allowed in
+ output format) relative relocations.}
+
+ \item{Portability fixes for building NASM with the LLVM compiler.}
+
+ \item{Add support of Codeview version 8 (\code{cv8}) debug format for
+ \code{win32} and \code{win64} formats in the \code{COFF} backend,
+ see \nref{codeview}.}
+
+ \item{Allow 64-bit outputs in 16/32-bit only backends. Unsigned 64-bit
+ relocations are zero-extended from 32-bits with a warning
+ (suppressible via \code{-w-zext-reloc}); signed 64-bit relocations are
+ an error.}
+
+ \item{Line numbers in list files now correspond to the lines in the source
+ files, instead of simply being sequential.}
+
+ \item{There is now an official 64-bit (x64 a.k.a. x86-64) build for Windows.}
+\end{itemize}
+
+\xsubsection{cl-2.11.09}{Version 2.11.09}
+
+\begin{itemize}
+ \item{Fix potential stack overwrite in \code{macho32} backend.}
+
+ \item{Fix relocation records in \code{macho64} backend.}
+
+ \item{Fix symbol lookup computation in \code{macho64} backend.}
+
+ \item{Adjust \code{.symtab} and \code{.rela.text} sections alignments to 8 bytes
+ in \code{elf64} backed.}
+
+ \item{Fix section length computation in \code{bin} backend which leaded in incorrect
+ relocation records.}
+\end{itemize}
+
+\xsubsection{cl-2.11.08}{Version 2.11.08}
+
+\begin{itemize}
+ \item{Fix section length computation in \code{bin} backend which leaded in incorrect
+ relocation records.}
+
+ \item{Add a warning for numeric preprocessor definitions passed via command
+ line which might have unexpected results otherwise.}
+
+ \item{Add ability to specify a module name record in \code{rdoff} linker with
+ \code{-mn} option.}
+
+ \item{Increase label length capacity up to 256 bytes in \code{rdoff} backend for
+ FreePascal sake, which tends to generate very long labels for procedures.}
+
+ \item{Fix segmentation failure when rip addressing is used in \code{macho64} backend.}
+
+ \item{Fix access on out of memory when handling strings with a single
+ grave. We have sixed similar problem in previous release but not
+ all cases were covered.}
+
+ \item{Fix NULL dereference in disassembled on \code{BND} instruction.}
+\end{itemize}
+
+\xsubsection{cl-2.11.07}{Version 2.11.07}
+
+\begin{itemize}
+ \item{Fix 256 bit \code{VMOVNTPS} instruction.}
+
+ \item{Fix \code{-MD} option handling, which was rather broken in previous
+ release changing command line api.}
+
+ \item{Fix access to unitialized space when handling strings with
+ a single grave.}
+
+ \item{Fix nil dereference in handling memory reference parsing.}
+\end{itemize}
+
+\xsubsection{cl-2.11.06}{Version 2.11.06}
+
+\begin{itemize}
+ \item{Update AVX512 instructions based on the Extension Reference (319433-021 Sept 2014).}
+ \item{Fix the behavior of \code{-MF} and \code{-MD} options (Bugzilla 3392280)}
+ \item{Updated Win32 Makefile to fix issue with build}
+\end{itemize}
+
+\xsubsection{cl-2.11.05}{Version 2.11.05}
+
+\begin{itemize}
+ \item{Add \code{--v} as an alias for \code{-v} (see \nref{opt-v}), for
+ command-line compatibility with Yasm.}
+ \item{Fix a bug introduced in 2.11.03 whereby certain instructions would
+ contain multiple REX prefixes, and thus be corrupt.}
+\end{itemize}
+
+\xsubsection{cl-2.11.04}{Version 2.11.04}
+
+\begin{itemize}
+ \item{Removed an invalid error checking code. Sometimes a memref only with
+ a displacement can also set an evex flag. For example:
+\begin{lstlisting}
+vmovdqu32 [0xabcd]{k1}, zmm0
+\end{lstlisting}}
+
+ \item{Fixed a bug in disassembler that EVEX.L'L vector length was not matched
+ when EVEX.b was set because it was simply considered as EVEC.RC.
+ Separated EVEX.L'L case from EVEX.RC which is ignored in matching.}
+\end{itemize}
+
+\xsubsection{cl-2.11.03}{Version 2.11.03}
+
+\begin{itemize}
+ \item{Fix a bug there REX prefixes were missing on instructions
+ inside a \code{TIMES} statement.}
+\end{itemize}
+
+\xsubsection{cl-2.11.02}{Version 2.11.02}
+
+\begin{itemize}
+ \item{Add the \code{XSAVEC}, \code{XSAVES} and \code{XRSTORS} family instructions.}
+ \item{Add the \code{CLFLUSHOPT} instruction.}
+\end{itemize}
+
+\xsubsection{cl-2.11.01}{Version 2.11.01}
+
+\begin{itemize}
+ \item{Allow instructions which implicitly uses \code{XMM0} (\code{VBLENDVPD},
+ \code{VBLENDVPS}, \code{PBLENDVB} and \code{SHA256RNDS2}) to be specified
+ without an explicit \code{xmm0} on the assembly line. In other words,
+ the following two lines produce the same output:
+\begin{lstlisting}
+vblendvpd xmm2,xmm1,xmm0 ; Last operand is fixed xmm0
+vblendvpd xmm2,xmm1 ; Implicit xmm0 omitted
+\end{lstlisting}}
+
+ \item{In the ELF backends, don't crash the assembler if \code{section align}
+ is specified without a value.}
+\end{itemize}
+
+\xsubsection{cl-2.11}{Version 2.11}
+
+\begin{itemize}
+ \item{Add support for the Intel AVX-512 instruction set:}
+
+ \item{16 new, 512-bit SIMD registers. Total 32 \code{(ZMM0 \textasciitilde ZMM31)}}
+
+ \item{8 new opmask registers \code{(K0 \textasciitilde K7)}.
+ One of 7 registers \code{(K1 \textasciitilde K7)} can
+ be used as an opmask for conditional execution.}
+
+ \item{A new EVEX encoding prefix. EVEX is based on VEX and provides more
+ capabilities: opmasks, broadcasting, embedded rounding and compressed
+ displacements.
+\begin{lstlisting}
+; opmask: conditional vector operation
+; using opmask k1 and {z} is for zero-masking
+ VDIVPD zmm0{k1}{z}, zmm1, zmm3
+
+; broadcasting: load single-precision float and
+; replicate it 16 times. 32 * 16 = 512
+ VDIVPS zmm4, zmm5, [rbx]{1to16}
+
+; embedded rounding: round toward zero. note that
+: it is used as if a separate operand. it comes after
+; the last SIMD operand
+ VCVTSI2SD xmm6, xmm7, {rz-sae}, rax
+\end{lstlisting}}
+
+ \item{Add support for \code{ZWORD} (512 bits), \code{DZ} and \code{RESZ}.}
+
+ \item{Add support for the MPX and SHA instruction sets.}
+
+ \item{Better handling of section redefinition.}
+
+ \item{Generate manpages when running \code{'make dist'}.}
+
+ \item{Handle all token chains in mmacro params range.}
+
+ \item{Support split [base,index] effective address:
+\begin{lstlisting}
+; eax=base, ecx=index, 4=scale, 8=disp
+mov eax,[eax+8,ecx*4]
+\end{lstlisting}
+ This is expected to be most useful for the MPX instructions.}
+
+ \item{Support \code{BND} prefix for branch instructions (for MPX).}
+
+ \item{The \code{DEFAULT} directive can now take \code{BND} and \code{NOBND}
+ options to indicate whether all relevant branches should be getting
+ \code{BND} prefixes. This is expected to be the normal for use in MPX
+ code.}
+
+ \item{Add \code{{evex}}, \code{{vex3}} and \code{{vex2}} instruction prefixes to
+ have NASM encode the corresponding instruction, if possible, with an EVEX,
+ 3-byte VEX, or 2-byte VEX prefix, respectively.}
+
+ \item{Support for section names longer than 8 bytes in Win32/Win64 COFF.}
+
+ \item{The \code{NOSPLIT} directive by itself no longer forces a single
+ register to become an index register, unless it has an explicit
+ multiplier.
+\begin{lstlisting}
+mov eax,[nosplit eax] ; eax as base register
+mov eax,[nosplit eax*1] ; eax as index register
+\end{lstlisting}}
+\end{itemize}
+
+\xsubsection{cl-2.10.09}{Version 2.10.09}
+
+\begin{itemize}
+ \item{Pregenerate man pages.}
+\end{itemize}
+
+\xsubsection{cl-2.10.08}{Version 2.10.08}
+
+\begin{itemize}
+ \item{Fix \code{VMOVNTDQA}, \code{MOVNTDQA} and \code{MOVLPD} instructions.}
+ \item{Fix collision for \code{VGATHERQPS}, \code{VPGATHERQD} instructions.}
+ \item{Fix \code{VPMOVSXBQ}, \code{VGATHERQPD}, \code{VSPLLW} instructions.}
+ \item{Add a bunch of AMD TBM instructions.}
+ \item{Fix potential stack overwrite in numbers conversion.}
+ \item{Allow byte size in \code{PREFETCHTx} instructions.}
+ \item{Make manual pages up to date.}
+ \item{Make \code{F3} and \code{F2} SSE prefixes to override \code{66}.}
+ \item{Support of AMD SVM instructions in 32 bit mode.}
+ \item{Fix near offsets code generation for \code{JMP}, \code{CALL} instrictions in long mode.}
+ \item{Fix preprocessor parse regression when id is expanding to a whitespace.}
+\end{itemize}
+
+\xsubsection{cl-2.10.07}{Version 2.10.07}
+
+\begin{itemize}
+ \item{Fix line continuation parsing being broken in previous version.}
+\end{itemize}
+
+\xsubsection{cl-2.10.06}{Version 2.10.06}
+
+\begin{itemize}
+ \item{Always quote the dependency source names when using the automatic
+ dependency generation options.}
+ \item{If no dependency target name is specified via the \code{-MT} or
+ \code{-MQ} options, quote the default output name.}
+ \item{Fix assembly of shift operations in \code{CPU 8086} mode.}
+ \item{Fix incorrect generation of explicit immediate byte for shift by 1
+ under certain circumstances.}
+ \item{Fix assembly of the \code{VPCMPGTQ} instruction.}
+ \item{Fix RIP-relative relocations in the \code{macho64} backend.}
+\end{itemize}
+
+\xsubsection{cl-2.10.05}{Version 2.10.05}
+
+\begin{itemize}
+ \item{Add the \code{CLAC} and \code{STAC} instructions.}
+\end{itemize}
+
+\xsubsection{cl-2.10.04}{Version 2.10.04}
+
+\begin{itemize}
+ \item{Add back the inadvertently deleted 256-bit version of the \code{VORPD} instruction.}
+ \item{Correct disassembly of instructions starting with byte \code{82} hex.}
+ \item{Fix corner cases in token pasting, for example:
+\begin{lstlisting}
+%define N 1e%++%+ 5
+dd N, 1e+5
+\end{lstlisting}}
+\end{itemize}
+
+\xsubsection{cl-2.10.03}{Version 2.10.03}
+
+\begin{itemize}
+ \item{Correct the assembly of the instruction:
+\begin{lstlisting}
+XRELEASE MOV [absolute],AL
+\end{lstlisting}
+ Previous versions would incorrectly generate \code{F3 A2} for this
+ instruction and issue a warning; correct behavior is to emit \code{F3 88 05}.}
+\end{itemize}
+
+\xsubsection{cl-2.10.02}{Version 2.10.02}
+
+\begin{itemize}
+ \item{Add the \code{ifunc} macro package with integer functions, currently
+ only integer logarithms. See \nref{pkgifunc}.}
+ \item{Add the \code{RDSEED}, \code{ADCX} and \code{ADOX} instructions.}
+\end{itemize}
+
+\xsubsection{cl-2.10.01}{Version 2.10.01}
+
+\begin{itemize}
+ \item{Add missing VPMOVMSKB instruction with reg32, ymmreg operands.}
+\end{itemize}
+
+\xsubsection{cl-2.10}{Version 2.10}
+
+\begin{itemize}
+ \item{When optimization is enabled, \code{mov r64,imm} now optimizes to the
+ shortest form possible between:
+\begin{lstlisting}
+mov r32,imm32 ; 5 bytes
+mov r64,imm32 ; 7 bytes
+mov r64,imm64 ; 10 bytes
+\end{lstlisting}
+ To force a specific form, use the \code{STRICT} keyword, see \nref{strict}.}
+ \item{Add support for the Intel AVX2 instruction set.}
+ \item{Add support for Bit Manipulation Instructions 1 and 2.}
+ \item{Add support for Intel Transactional Synchronization Extensions (TSX).}
+ \item{Add support for x32 ELF (32-bit ELF with the CPU in 64-bit mode.) See \nref{elffmt}.}
+ \item{Add support for bigendian UTF-16 and UTF-32. See \nref{unicode}.}
+\end{itemize}
+
+\xsubsection{cl-2.09.10}{Version 2.09.10}
+
+\begin{itemize}
+ \item{Fix up NSIS script to protect uninstaller against registry keys
+ absence or corruption. It brings in a few additional questions
+ to a user during deinstallation procedure but still it is better
+ than unpredictable file removal.}
+\end{itemize}
+
+\xsubsection{cl-2.09.09}{Version 2.09.09}
+
+\begin{itemize}
+ \item{Fix initialization of section attributes of \code{bin} output format.}
+ \item{Fix \code{mach64} output format bug that crashes NASM due to NULL symbols.}
+\end{itemize}
+
+\xsubsection{cl-2.09.08}{Version 2.09.08}
+
+\begin{itemize}
+ \item{Fix \code{\_\_OUTPUT\_FORMAT\_\_} assignment when output driver alias
+ is used. For example when \code{-f elf} is used \code{\_\_OUTPUT\_FORMAT\_\_}
+ must be set to \code{elf}, if \code{-f elf32} is used \code{\_\_OUTPUT\_FORMAT\_\_}
+ must be assigned accordingly, i.e. to \code{elf32}. The rule applies to
+ all output driver aliases. See \nref{ofmtm}.}
+\end{itemize}
+
+\xsubsection{cl-2.09.07}{Version 2.09.07}
+
+\begin{itemize}
+ \item{Fix attempts to close same file several times when \code{-a} option is used.}
+ \item{Fixes for VEXTRACTF128, VMASKMOVPS encoding.}
+\end{itemize}
+
+\xsubsection{cl-2.09.06}{Version 2.09.06}
+
+\begin{itemize}
+ \item{Fix missed section attribute initialization in \code{bin} output target.}
+\end{itemize}
+
+\xsubsection{cl-2.09.05}{Version 2.09.05}
+
+\begin{itemize}
+ \item{Fix arguments encoding for VPEXTRW instruction.}
+ \item{Remove invalid form of VPEXTRW instruction.}
+ \item{Add \code{VLDDQU} as alias for \code{VLDQQU} to match specification.}
+\end{itemize}
+
+\xsubsection{cl-2.09.04}{Version 2.09.04}
+
+\begin{itemize}
+ \item{Fix incorrect labels offset for VEX intructions.}
+ \item{Eliminate bogus warning on implicit operand size override.}
+ \item{\code{\%if} term could not handle 64 bit numbers.}
+ \item{The COFF backend was limiting relocations number to 16 bits even if
+ in real there were a way more relocations.}
+\end{itemize}
+
+\xsubsection{cl-2.09.03}{Version 2.09.03}
+
+\begin{itemize}
+ \item{Print \code{\%macro} name inside \code{\%rep} blocks on error.}
+ \item{Fix preprocessor expansion behaviour. It happened sometime
+ too early and sometime simply wrong. Move behaviour back to
+ the origins (down to NASM 2.05.01).}
+ \item{Fix unitialized data dereference on OMF output format.}
+ \item{Issue warning on unterminated \code{\%\{} construct.}
+ \item{Fix for documentation typo.}
+\end{itemize}
+
+\xsubsection{cl-2.09.02}{Version 2.09.02}
+
+\begin{itemize}
+ \item{Fix reversed tokens when \code{\%deftok} produces more than one output token.}
+ \item{Fix segmentation fault on disassembling some VEX instructions.}
+ \item{Missing \code{\%endif} did not always cause error.}
+ \item{Fix typo in documentation.}
+ \item{Compound context local preprocessor single line macro identifiers
+ were not expanded early enough and as result lead to unresolved symbols.}
+\end{itemize}
+
+\xsubsection{cl-2.09.01}{Version 2.09.01}
+
+\begin{itemize}
+ \item{Fix NULL dereference on missed \code{\%deftok} second parameter.}
+ \item{Fix NULL dereference on invalid \code{\%substr} parameters.}
+\end{itemize}
+
+\xsubsection{cl-2.09}{Version 2.09}
+
+\begin{itemize}
+ \item{Fixed assignment the magnitude of \code{\%rep} counter.
+ It is limited to 62 bits now.}
+ \item{Fixed NULL dereference if argument of \code{\%strlen} resolves
+ to whitespace. For example if nonexistent macro parameter is used.}
+ \item{\code{\%ifenv}, \code{\%elifenv}, \code{\%ifnenv}, and
+ \code{\%elifnenv} directives introduced. See \nref{ifenv}.}
+ \item{Fixed NULL dereference if environment variable is missed.}
+ \item{Updates of new AVX v7 Intel instructions.}
+ \item{\code{PUSH imm32} is now officially documented.}
+ \item{Fix for encoding the LFS, LGS and LSS in 64-bit mode.}
+ \item{Fixes for compatibility with OpenWatcom compiler and DOS 8.3 file format limitation.}
+ \item{Macros parameters range expansion introduced. See \nref{mlmacrange}.}
+ \item{Backward compatibility on expanging of local sigle macros restored.}
+ \item{8 bit relocations for \code{elf} and \code{bin} output formats are introduced.}
+ \item{Short intersegment jumps are permitted now.}
+ \item{An alignment more than 64 bytes are allowed for \code{win32},
+ \code{win64} output formats.}
+ \item{\code{SECTALIGN} directive introduced. See \nref{sectalign}.}
+ \item{\code{nojmp} option introduced in \code{smartalign} package. See
+ \nref{pkgsmartalign}.}
+ \item{Short aliases \code{win}, \code{elf} and \code{macho} for output formats are
+ introduced. Each stands for \code{win32}, \code{elf32} and \code{macho32}
+ accordingly.}
+ \item{Faster handling of missing directives implemented.}
+ \item{Various small improvements in documentation.}
+ \item{No hang anymore if unable to open malloc.log file.}
+ \item{The environments without vsnprintf function are able to build nasm again.}
+ \item{AMD LWP instructions updated.}
+ \item{Tighten EA checks. We warn a user if there overflow in EA addressing.}
+ \item{Make \code{-Ox} the default optimization level. For the legacy
+ behavior, specify \code{-O0} explicitly. See \nref{opt-O}.}
+ \item{Environment variables read with \code{\%!} or tested with \code{\%ifenv}
+ can now contain non-identifier characters if surrounded by quotes.
+ See \nref{getenv}.}
+ \item{Add a new standard macro package \code{\%use fp} for floating-point
+ convenience macros. See \nref{pkgfp}.}
+\end{itemize}
+
+\xsubsection{cl-2.08.02}{Version 2.08.02}
+
+\begin{itemize}
+ \item{Fix crash under certain circumstances when using
+ the \code{\%+} operator.}
+\end{itemize}
+
+\xsubsection{cl-2.08.01}{Version 2.08.01}
+
+\begin{itemize}
+ \item{Fix the \code{\%use} statement, which was broken in 2.08.}
+\end{itemize}
+
+\xsubsection{cl-2.08}{Version 2.08}
+
+\begin{itemize}
+ \item{A number of enhancements/fixes in macros area.}
+ \item{Support for converting strings to tokens. See \nref{deftok}.}
+ \item{Fuzzy operand size logic introduced.}
+ \item{Fix COFF stack overrun on too long export identifiers.}
+ \item{Fix Macho-O alignment bug.}
+ \item{Fix crashes with \code{-fwin32} on file with many exports.}
+ \item{Fix stack overrun for too long [DEBUG id].}
+ \item{Fix incorrect sbyte usage in IMUL (hit only if optimization flag passed).}
+ \item{Append ending token for \code{.stabs} records in the ELF output format.}
+ \item{New NSIS script which uses ModernUI and MultiUser approach.}
+ \item{Visual Studio 2008 NASM integration (rules file).}
+ \item{Warn a user if a constant is too long (and as result will be stripped).}
+ \item{The obsoleted pre-XOP AMD SSE5 instruction set which was never actualized was removed.}
+ \item{Fix stack overrun on too long error file name passed from the command line.}
+ \item{Bind symbols to the .text section by default (ie in case if
+ \code{SECTION} directive was omitted) in the ELF output format.}
+ \item{Fix sync points array index wrapping.}
+ \item{A few fixes for FMA4 and XOP instruction templates.}
+ \item{Add AMD Lightweight Profiling (LWP) instructions.}
+ \item{Fix the offset for \code{\%arg} in 64-bit mode.}
+ \item{An undefined local macro (\code{\%\$}) no longer matches a global macro
+ with the same name.}
+ \item{Fix NULL dereference on too long local labels.}
+\end{itemize}
+
+\xsubsection{cl-2.07}{Version 2.07}
+
+\begin{itemize}
+ \item{NASM is now under the 2-clause BSD license. See \nref{license}.}
+ \item{Fix the section type for the \code{.strtab} section in the \code{elf64}
+ output format.}
+ \item{Fix the handling of \code{COMMON} directives in the \code{obj} output format.}
+ \item{New \code{ith} and \code{srec} output formats; these are variants of the
+ \code{bin} output format which output Intel hex and Motorola S-records,
+ respectively. See \nref{ithfmt} and \nref{srecfmt}.}
+ \item{\code{rdf2ihx} replaced with an enhanced \code{rdf2bin}, which can output
+ binary, COM, Intel hex or Motorola S-records.}
+ \item{The Windows installer now puts the NASM directory first in the
+ \code{PATH} of the ``NASM Shell''.}
+ \item{Revert the early expansion behavior of \code{\%+} to
+ pre-2.06 behavior: \code{\%+} is only expanded late.}
+ \item{Yet another Mach-O alignment fix.}
+ \item{Don't delete the list file on errors. Also, include error and
+ warning information in the list file.}
+ \item{Support for 64-bit Mach-O output, see \nref{machofmt}.}
+ \item{Fix assert failure on certain operations that involve strings with
+ high-bit bytes.}
+\end{itemize}
+
+\xsubsection{cl-2.06}{Version 2.06}
+
+\begin{itemize}
+ \item{This release is dedicated to the memory of Charles A. Crayne, long
+ time NASM developer as well as moderator of \code{comp.lang.asm.x86} and
+ author of the book \emph{Serious Assembler}. We miss you, Chuck.}
+ \item{Support for indirect macro expansion (\code{\%[...]}). See \nref{indmacro}.}
+ \item{\code{\%pop} can now take an argument, see \nref{pushpop}.}
+ \item{The argument to \code{\%use} is no longer macro-expanded. Use
+ \code{\%[...]} if macro expansion is desired.}
+ \item{Support for thread-local storage in ELF32 and ELF64. See \nref{elftls}.}
+ \item{Fix crash on \code{\%ifmacro} without an argument.}
+ \item{Correct the arguments to the \code{POPCNT} instruction.}
+ \item{Fix section alignment in the Mach-O format.}
+ \item{Update AVX support to version 5 of the Intel specification.}
+ \item{Fix the handling of accesses to context-local macros from higher
+ levels in the context stack.}
+ \item{Treat \code{WAIT} as a prefix rather than as an instruction, thereby
+ allowing constructs like \code{O16 FSAVE} to work correctly.}
+ \item{Support for structures with a non-zero base offset. See \nref{struc}.}
+ \item{Correctly handle preprocessor token concatenation (see \nref{concat})
+ involving floating-point numbers.}
+ \item{The \code{PINSR} series of instructions have been corrected and rationalized.}
+ \item{Removed AMD SSE5, replaced with the new XOP/FMA4/CVT16 (rev 3.03) spec.}
+ \item{The ELF backends no longer automatically generate a \code{.comment} section.}
+ \item{Add additional "well-known" ELF sections with default attributes. See \nref{elfsect}.}
+\end{itemize}
+
+\xsubsection{cl-2.05.01}{Version 2.05.01}
+
+\begin{itemize}
+ \item{Fix the \code{-w}/\code{-W} option parsing, which was broken in NASM 2.05.}
+\end{itemize}
+
+\xsubsection{cl-2.05}{Version 2.05}
+
+\begin{itemize}
+ \item{Fix redundant REX.W prefix on \code{JMP reg64}.}
+ \item{Make the behaviour of \code{-O0} match NASM 0.98 legacy behavior.
+ See \nref{opt-O}.}
+ \item{\code{-w-user} can be used to suppress the output of \code{\%warning} directives.
+ See \nref{opt-w}.}
+ \item{Fix bug where \code{ALIGN} would issue a full alignment datum instead of
+ zero bytes.}
+ \item{Fix offsets in list files.}
+ \item{Fix \code{\%include} inside multi-line macros or loops.}
+ \item{Fix error where NASM would generate a spurious warning on valid
+ optimizations of immediate values.}
+ \item{Fix arguments to a number of the \code{CVT} SSE instructions.}
+ \item{Fix RIP-relative offsets when the instruction carries an immediate.}
+ \item{Massive overhaul of the ELF64 backend for spec compliance.}
+ \item{Fix the Geode \code{PFRCPV} and \code{PFRSQRTV} instruction.}
+ \item{Fix the SSE 4.2 \code{CRC32} instruction.}
+\end{itemize}
+
+
+\xsubsection{cl-2.04}{Version 2.04}
+
+\begin{itemize}
+ \item{Sanitize macro handing in the \code{\%error} directive.}
+ \item{New \code{\%warning} directive to issue user-controlled warnings.}
+ \item{\code{\%error} directives are now deferred to the final assembly phase.}
+ \item{New \code{\%fatal} directive to immediately terminate assembly.}
+ \item{New \code{\%strcat} directive to join quoted strings together.}
+ \item{New \code{\%use} macro directive to support standard macro directives. See \nref{use}.}
+ \item{Excess default parameters to \code{\%macro} now issues a warning by default.
+ See \nref{mlmacro}.}
+ \item{Fix \code{\%ifn} and \code{\%elifn}.}
+ \item{Fix nested \code{\%else} clauses.}
+ \item{Correct the handling of nested \code{\%rep}s.}
+ \item{New \code{\%unmacro} directive to undeclare a multi-line macro.
+ See \nref{unmacro}.}
+ \item{Builtin macro \code{\_\_PASS\_\_} which expands to the current assembly pass.
+ See \nref{passdef}.}
+ \item{\code{\_\_utf16\_\_} and \code{\_\_utf32\_\_} operators to generate
+ UTF-16 and UTF-32 strings. See \nref{unicode}.}
+ \item{Fix bug in case-insensitive matching when compiled on platforms that
+ don't use the \code{configure} script. Of the official release binaries,
+ that only affected the OS/2 binary.}
+ \item{Support for x87 packed BCD constants. See \nref{bcdconst}.}
+ \item{Correct the \code{LTR} and \code{SLDT} instructions in 64-bit mode.}
+ \item{Fix unnecessary REX.W prefix on indirect jumps in 64-bit mode.}
+ \item{Add AVX versions of the AES instructions (\code{VAES}...).}
+ \item{Fix the 256-bit FMA instructions.}
+ \item{Add 256-bit AVX stores per the latest AVX spec.}
+ \item{VIA XCRYPT instructions can now be written either with or without
+ \code{REP}, apparently different versions of the VIA spec wrote them
+ differently.}
+ \item{Add missing 64-bit \code{MOVNTI} instruction.}
+ \item{Fix the operand size of \code{VMREAD} and \code{VMWRITE}.}
+ \item{Numerous bug fixes, especially to the AES, AVX and VTX instructions.}
+ \item{The optimizer now always runs until it converges. It also runs even
+ when disabled, but doesn't optimize. This allows most forward references
+ to be resolved properly.}
+ \item{\code{\%push} no longer needs a context identifier; omitting the context
+ identifier results in an anonymous context.}
+\end{itemize}
+
+\xsubsection{cl-2.03.01}{Version 2.03.01}
+
+\begin{itemize}
+ \item{Fix buffer overflow in the listing module.}
+ \item{Fix the handling of hexadecimal escape codes in `...` strings.}
+ \item{The Postscript/PDF documentation has been reformatted.}
+ \item{The \code{-F} option now implies \code{-g}.}
+\end{itemize}
+
+\xsubsection{cl-2.03}{Version 2.03}
+
+\begin{itemize}
+ \item{Add support for Intel AVX, CLMUL and FMA instructions,
+ including YMM registers.}
+ \item{\code{dy}, \code{resy} and \code{yword} for 32-byte operands.}
+ \item{Fix some SSE5 instructions.}
+ \item{Intel \code{INVEPT}, \code{INVVPID} and \code{MOVBE} instructions.}
+ \item{Fix checking for critical expressions when the optimizer is enabled.}
+ \item{Support the DWARF debugging format for ELF targets.}
+ \item{Fix optimizations of signed bytes.}
+ \item{Fix operation on bigendian machines.}
+ \item{Fix buffer overflow in the preprocessor.}
+ \item{\code{SAFESEH} support for Win32, \code{IMAGEREL} for Win64 (SEH).}
+ \item{\code{\%?} and \code{\%??} to refer to the name of a macro itself.
+ In particular, \code{\%idefine keyword \$\%?} can be used to make
+ a keyword "disappear".}
+ \item{New options for dependency generation: \code{-MD}, \code{-MF},
+ \code{-MP}, \code{-MT}, \code{-MQ}.}
+ \item{New preprocessor directives \code{\%pathsearch} and \code{\%depend};
+ \code{INCBIN} reimplemented as a macro.}
+ \item{\code{\%include} now resolves macros in a sane manner.}
+ \item{\code{\%substr} can now be used to get other than one-character substrings.}
+ \item{New type of character/string constants, using backquotes (\code{`...`}),
+ which support C-style escape sequences.}
+ \item{\code{\%defstr} and \code{\%idefstr} to stringize macro definitions
+ before creation.}
+ \item{Fix forward references used in \code{EQU} statements.}
+\end{itemize}
+
+\xsubsection{cl-2.02}{Version 2.02}
+
+\begin{itemize}
+ \item{Additional fixes for MMX operands with explicit \code{qword}, as well as
+ (hopefully) SSE operands with \code{oword}.}
+ \item{Fix handling of truncated strings with \code{DO}.}
+ \item{Fix segfaults due to memory overwrites when floating-point constants were used.}
+ \item{Fix segfaults due to missing include files.}
+ \item{Fix OpenWatcom Makefiles for DOS and OS/2.}
+ \item{Add autogenerated instruction list back into the documentation.}
+ \item{ELF: Fix segfault when generating stabs, and no symbols have been defined.}
+ \item{ELF: Experimental support for DWARF debugging information.}
+ \item{New compile date and time standard macros.}
+ \item{\code{\%ifnum} now returns true for negative numbers.}
+ \item{New \code{\%iftoken} test for a single token.}
+ \item{New \code{\%ifempty} test for empty expansion.}
+ \item{Add support for the \code{XSAVE} instruction group.}
+ \item{Makefile for Netware/gcc.}
+ \item{Fix issue with some warnings getting emitted way too many times.}
+ \item{Autogenerated instruction list added to the documentation.}
+\end{itemize}
+
+\xsubsection{cl-2.01}{Version 2.01}
+
+\begin{itemize}
+ \item{Fix the handling of MMX registers with explicit \code{qword} tags on
+ memory (broken in 2.00 due to 64-bit changes.)}
+ \item{Fix the PREFETCH instructions.}
+ \item{Fix the documentation.}
+ \item{Fix debugging info when using \code{-f elf}
+ (backwards compatibility alias for \code{-f elf32}).}
+ \item{Man pages for rdoff tools (from the Debian project.)}
+ \item{ELF: handle large numbers of sections.}
+ \item{Fix corrupt output when the optimizer runs out of passes.}
+\end{itemize}
+
+\xsubsection{cl-2.00}{Version 2.00}
+
+\begin{itemize}
+ \item{Added c99 data-type compliance.}
+ \item{Added general x86-64 support.}
+ \item{Added win64 (x86-64 COFF) output format.}
+ \item{Added \code{\_\_BITS\_\_} standard macro.}
+ \item{Renamed the \code{elf} output format to \code{elf32} for clarity.}
+ \item{Added \code{elf64} and \code{macho} (MacOS X) output formats.}
+ \item{Added Numeric constants in \code{dq} directive.}
+ \item{Added \code{oword}, \code{do} and \code{reso} pseudo operands.}
+ \item{Allow underscores in numbers.}
+ \item{Added 8-, 16- and 128-bit floating-point formats.}
+ \item{Added binary, octal and hexadecimal floating-point.}
+ \item{Correct the generation of floating-point constants.}
+ \item{Added floating-point option control.}
+ \item{Added Infinity and NaN floating point support.}
+ \item{Added ELF Symbol Visibility support.}
+ \item{Added setting OSABI value in ELF header directive.}
+ \item{Added Generate Makefile Dependencies option.}
+ \item{Added Unlimited Optimization Passes option.}
+ \item{Added \code{\%ifn} and \code{\%elifn} support.}
+ \item{Added Logical Negation Operator.}
+ \item{Enhanced Stack Relative Preprocessor Directives.}
+ \item{Enhanced ELF Debug Formats.}
+ \item{Enhanced Send Errors to a File option.}
+ \item{Added SSSE3, SSE4.1, SSE4.2, SSE5 support.}
+ \item{Added a large number of additional instructions.}
+ \item{Significant performance improvements.}
+ \item{\code{-w+warning} and \code{-w-warning} can now be written
+ as -Wwarning and -Wno-warning, respectively. See \nref{opt-w}.}
+ \item{Add \code{-w+error} to treat warnings as errors. See \nref{opt-w}.}
+ \item{Add \code{-w+all} and \code{-w-all} to enable or disable all suppressible
+ warnings. See \nref{opt-w}.}
+\end{itemize}
+
+\xsection{cl-0.98.xx}{NASM 0.98 Series}
+
+The 0.98 series was the production versions of NASM from 1999 to 2007.
+
+\xsubsection{cl-0.98.39}{Version 0.98.39}
+
+\begin{itemize}
+ \item{fix buffer overflow}
+ \item{fix outas86's \code{.bss} handling}
+ \item{"make spotless" no longer deletes config.h.in.}
+ \item{\code{\%(el)if(n)idn} insensitivity to string quotes difference (\#809300).}
+ \item{(nasm.c)\code{\_\_OUTPUT\_FORMAT\_\_} changed to string value instead of symbol.}
+\end{itemize}
+
+\xsubsection{cl-0.98.38}{Version 0.98.38}
+
+\begin{itemize}
+ \item{Add Makefile for 16-bit DOS binaries under OpenWatcom, and modify
+ \code{mkdep.pl} to be able to generate completely pathless dependencies, as
+ required by OpenWatcom wmake (it supports path searches, but not
+ explicit paths.)}
+ \item{Fix the \code{STR} instruction.}
+ \item{Fix the ELF output format, which was broken under certain
+ circumstances due to the addition of stabs support.}
+ \item{Quick-fix Borland format debug-info for \code{-f obj}}
+ \item{Fix for \code{\%rep} with no arguments (\#560568)}
+ \item{Fix concatenation of preprocessor function call (\#794686)}
+ \item{Fix long label causes coredump (\#677841)}
+ \item{Use autoheader as well as autoconf to keep configure from generating
+ ridiculously long command lines.}
+ \item{Make sure that all of the formats which support debugging output
+ actually will suppress debugging output when \code{-g} not specified.}
+\end{itemize}
+
+\xsubsection{cl-0.98.37}{Version 0.98.37}
+
+\begin{itemize}
+ \item{Paths given in \code{-I} switch searched for \code{incbin}-ed as
+ well as \code{\%include}-ed files.}
+ \item{Added stabs debugging for the ELF output format, patch from
+ Martin Wawro.}
+ \item{Fix \code{output/outbin.c} to allow origin > 80000000h.}
+ \item{Make \code{-U} switch work.}
+ \item{Fix the use of relative offsets with explicit prefixes, e.g.
+ \code{a32 loop foo}.}
+ \item{Remove \code{backslash()}.}
+ \item{Fix the \code{SMSW} and \code{SLDT} instructions.}
+ \item{\code{-O2} and \code{-O3} are no longer aliases for \code{-O10} and \code{-O15}.
+ If you mean the latter, please say so! :)}
+\end{itemize}
+
+\xsubsection{cl-0.98.36}{Version 0.98.36}
+
+\begin{itemize}
+ \item{Update rdoff - librarian/archiver - common rec - docs!}
+ \item{Fix signed/unsigned problems.}
+ \item{Fix \code{JMP FAR label} and \code{CALL FAR label}.}
+ \item{Add new multisection support - map files - fix align bug}
+ \item{Fix sysexit, movhps/movlps reg,reg bugs in insns.dat}
+ \item{\code{Q} or \code{O} suffixes indicate octal}
+ \item{Support Prescott new instructions (PNI).}
+ \item{Cyrix \code{XSTORE} instruction.}
+\end{itemize}
+
+
+\xsubsection{cl-0.98.35}{Version 0.98.35}
+
+\begin{itemize}
+ \item{Fix build failure on 16-bit DOS (Makefile.bc3 workaround for compiler bug.)}
+ \item{Fix dependencies and compiler warnings.}
+ \item{Add "const" in a number of places.}
+ \item{Add -X option to specify error reporting format (use -Xvc to
+ integrate with Microsoft Visual Studio.)}
+ \item{Minor changes for code legibility.}
+ \item{Drop use of tmpnam() in rdoff (security fix.)}
+\end{itemize}
+
+\xsubsection{cl-0.98.34}{Version 0.98.34}
+
+\begin{itemize}
+ \item{Correct additional address-size vs. operand-size confusions.}
+ \item{Generate dependencies for all Makefiles automatically.}
+ \item{Add support for unimplemented (but theoretically available)
+ registers such as tr0 and cr5. Segment registers 6 and 7 are called
+ segr6 and segr7 for the operations which they can be represented.}
+ \item{Correct some disassembler bugs related to redundant address-size prefixes.
+ Some work still remains in this area.}
+ \item{Correctly generate an error for things like "SEG eax".}
+ \item{Add the JMPE instruction, enabled by "CPU IA64".}
+ \item{Correct compilation on newer gcc/glibc platforms.}
+ \item{Issue an error on things like "jmp far eax".}
+\end{itemize}
+
+\xsubsection{cl-0.98.33}{Version 0.98.33}
+
+\begin{itemize}
+ \item{New \_\_NASM\_PATCHLEVEL\_\_ and \_\_NASM\_VERSION\_ID\_\_ standard macros
+ to round out the version-query macros. version.pl now understands
+ X.YYplWW or X.YY.ZZplWW as a version number, equivalent to
+ X.YY.ZZ.WW (or X.YY.0.WW, as appropriate).}
+ \item{New keyword "strict" to disable the optimization of specific operands.}
+ \item{Fix the handing of size overrides with JMP instructions
+ (instructions such as "jmp dword foo".)}
+ \item{Fix the handling of "ABSOLUTE label", where "label" points into a
+ relocatable segment.}
+ \item{Fix OBJ output format with lots of externs.}
+ \item{More documentation updates.}
+ \item{Add -Ov option to get verbose information about optimizations.}
+ \item{Undo a braindead change which broke \code{\%elif} directives.}
+ \item{Makefile updates.}
+\end{itemize}
+
+\xsubsection{cl-0.98.32}{Version 0.98.32}
+
+\begin{itemize}
+ \item{Fix NASM crashing when \code{\%macro} directives were left unterminated.}
+ \item{Lots of documentation updates.}
+ \item{Complete rewrite of the PostScript/PDF documentation generator.}
+ \item{The MS Visual C++ Makefile was updated and corrected.}
+ \item{Recognize .rodata as a standard section name in ELF.}
+ \item{Fix some obsolete Perl4-isms in Perl scripts.}
+ \item{Fix configure.in to work with autoconf 2.5x.}
+ \item{Fix a couple of "make cleaner" misses.}
+ \item{Make the normal "./configure \&\& make" work with Cygwin.}
+\end{itemize}
+
+\xsubsection{cl-0.98.31}{Version 0.98.31}
+
+\begin{itemize}
+ \item{Correctly build in a separate object directory again.}
+ \item{Derive all references to the version number from the version file.}
+ \item{New standard macros \code{\_\_NASM\_SUBMINOR\_\_} and
+ \code{\_\_NASM\_VER\_\_} macros.}
+ \item{Lots of Makefile updates and bug fixes.}
+ \item{New \code{\%ifmacro} directive to test for multiline macros.}
+ \item{Documentation updates.}
+ \item{Fixes for 16-bit OBJ format output.}
+ \item{Changed the NASM environment variable to NASMENV.}
+\end{itemize}
+
+\xsubsection{cl-0.98.30}{Version 0.98.30}
+
+\begin{itemize}
+ \item{Changed doc files a lot: completely removed old READMExx and
+ Wishlist files, incorporating all information in CHANGES and TODO.}
+ \item{I waited a long time to rename zoutieee.c to (original) outieee.c}
+ \item{moved all output modules to output/ subdirectory.}
+ \item{Added 'make strip' target to strip debug info from nasm \& ndisasm.}
+ \item{Added INSTALL file with installation instructions.}
+ \item{Added -v option description to nasm man.}
+ \item{Added dist makefile target to produce source distributions.}
+ \item{16-bit support for ELF output format (GNU extension, but useful.)}
+\end{itemize}
+
+
+\xsubsection{cl-0.98.28}{Version 0.98.28}
+
+\begin{itemize}
+ \item{Fastcooked this for Debian's Woody release:
+ Frank applied the \code{INCBIN} bug patch to 0.98.25alt
+ and called it 0.98.28 to not confuse poor little apt-get.}
+\end{itemize}
+
+\xsubsection{cl-0.98.26}{Version 0.98.26}
+
+\begin{itemize}
+ \item{Reorganised files even better from 0.98.25alt}
+\end{itemize}
+
+
+\xsubsection{cl-0.98.25alt}{Version 0.98.25alt}
+
+\begin{itemize}
+ \item{Prettified the source tree. Moved files to more reasonable places.}
+ \item{Added findleak.pl script to misc/ directory.}
+ \item{Attempted to fix doc.}
+\end{itemize}
+
+\xsubsection{cl-0.98.25}{Version 0.98.25}
+
+\begin{itemize}
+ \item{Line continuation character \code{\\}.}
+ \item{Docs inadvertantly reverted - "dos packaging".}
+\end{itemize}
+
+
+\xsubsection{cl-0.98.24p1}{Version 0.98.24p1}
+
+\begin{itemize}
+ \item{FIXME: Someone, document this please.}
+\end{itemize}
+
+\xsubsection{cl-0.98.24}{Version 0.98.24}
+
+\begin{itemize}
+ \item{Documentation - Ndisasm doc added to Nasm.doc.}
+\end{itemize}
+
+\xsubsection{cl-0.98.23}{Version 0.98.23}
+
+\begin{itemize}
+ \item{Attempted to remove rdoff version1}
+ \item{Lino Mastrodomenico's patches to preproc.c (\%\$\$ bug?).}
+\end{itemize}
+
+
+\xsubsection{cl-0.98.22}{Version 0.98.22}
+
+\begin{itemize}
+ \item{Update rdoff2 - attempt to remove v1.}
+\end{itemize}
+
+\xsubsection{cl-0.98.21}{Version 0.98.21}
+
+\begin{itemize}
+ \item{Optimization fixes.}
+\end{itemize}
+
+\xsubsection{cl-0.98.20}{Version 0.98.20}
+
+\begin{itemize}
+ \item{Optimization fixes.}
+\end{itemize}
+
+\xsubsection{cl-0.98.19}{Version 0.98.19}
+
+\begin{itemize}
+ \item{H. J. Lu's patch back out.}
+\end{itemize}
+
+\xsubsection{cl-0.98.18}{Version 0.98.18}
+
+\begin{itemize}
+ \item{Added ".rdata" to "-f win32".}
+\end{itemize}
+
+\xsubsection{cl-0.98.17}{Version 0.98.17}
+
+\begin{itemize}
+ \item{H. J. Lu's "bogus elf" patch. (Red Hat problem?)}
+\end{itemize}
+
+
+\xsubsection{cl-0.98.16}{Version 0.98.16}
+
+\begin{itemize}
+ \item{Fix whitespace before \code{[section \dots]} bug.}
+\end{itemize}
+
+\xsubsection{cl-0.98.15}{Version 0.98.15}
+
+\begin{itemize}
+ \item{Rdoff changes (?).}
+ \item{Fix fixes to memory leaks.}
+\end{itemize}
+
+\xsubsection{cl-0.98.14}{Version 0.98.14}
+
+\begin{itemize}
+ \item{Fix memory leaks.}
+\end{itemize}
+
+\xsubsection{cl-0.98.13}{Version 0.98.13}
+
+\begin{itemize}
+ \item{There was no 0.98.13}
+\end{itemize}
+
+
+\xsubsection{cl-0.98.12}{Version 0.98.12}
+
+\begin{itemize}
+ \item{Update optimization (new function of \code{-O1}).}
+ \item{Changes to test/bintest.asm (?).}
+\end{itemize}
+
+\xsubsection{cl-0.98.11}{Version 0.98.11}
+
+\begin{itemize}
+ \item{Optimization changes.}
+ \item{Ndisasm fixed.}
+\end{itemize}
+
+\xsubsection{cl-0.98.10}{Version 0.98.10}
+
+\begin{itemize}
+ \item{There was no 0.98.10}
+\end{itemize}
+
+\xsubsection{cl-0.98.09}{Version 0.98.09}
+
+\begin{itemize}
+ \item{Add multiple sections support to \code{-f bin}.}
+ \item{Changed \code{GLOBAL\_TEMP\_BASE} in outelf.c from 6 to 15.}
+ \item{Add \code{-v} as an alias to the \code{-r} switch.}
+ \item{Remove \code{\#ifdef} from Tasm compatibility options.}
+ \item{Remove redundant size-overrides on \code{mov ds, ex}, etc.}
+ \item{Fixes to SSE2, other insns.dat (?).}
+ \item{Enable uppercase "I" and "P" switches.}
+ \item{Case insinsitive \code{seg} and \code{wrt}.}
+ \item{Update install.sh (?).}
+ \item{Allocate tokens in blocks.}
+ \item{Improve "invalid effective address" messages.}
+\end{itemize}
+
+\xsubsection{cl-0.98.08}{Version 0.98.08}
+
+\begin{itemize}
+ \item{Add \code{\%strlen} and \code{\%substr} macro operators.}
+ \item{Fixed broken c16.mac.}
+ \item{Unterminated string error reported.}
+ \item{Fixed bugs as per 0.98bf}
+\end{itemize}
+
+\xsubsection{cl-0.98.09b}{Version 0.98.09b with John Coffman patches released 28-Oct-2001}
+
+Changes from 0.98.07 release to 98.09b as of 28-Oct-2001
+
+\begin{itemize}
+ \item{More closely compatible with 0.98 when \code{-O0} is implied
+ or specified. Not strictly identical, since backward
+ branches in range of short offsets are recognized, and signed
+ byte values with no explicit size specification will be
+ assembled as a single byte.}
+ \item{More forgiving with the PUSH instruction. 0.98 requires
+ a size to be specified always. 0.98.09b will imply the size
+ from the current BITS setting (16 or 32).}
+ \item{Changed definition of the optimization flag
+ \begin{itemize}
+ \item{\code{-O0}: strict two-pass assembly, JMP and Jcc are
+ handled more like 0.98, except that back ward JMPs are
+ short, if possible.}
+ \item{\code{-O1}: strict two-pass assembly, but forward
+ branches are assembled with code guaranteed
+ to reach; may produce larger code than
+ \code{-O0}, but will produce successful assembly
+ more often if branch offset sizes are not
+ specified.}
+ \item{\code{-O2}: multi-pass optimization, minimize branch
+ offsets; also will minimize signed immediate bytes,
+ overriding size specification.}
+ \item{\code{-O3}: like \code{-O2}, but more passes taken,
+ if needed}
+ \end{itemize}}
+\end{itemize}
+
+\xsubsection{cl-0.98.07}{Version 0.98.07 released 01/28/01}
+
+\begin{itemize}
+ \item{Added Stepane Denis' SSE2 instructions to a \emph{working}
+ version of the code - some earlier versions were based on
+ broken code - sorry 'bout that. version "0.98.07"}
+ \item{Cosmetic modifications to nasm.c, nasm.h, AUTHORS, MODIFIED}
+\end{itemize}
+
+\xsubsection{cl-0.98.06f}{Version 0.98.06f released 01/18/01}
+
+\begin{itemize}
+ \item{Add "metalbrain"s jecxz bug fix in insns.dat}
+ \item{Alter nasmdoc.src to match - version "0.98.06f"}
+\end{itemize}
+
+\xsubsection{cl-0.98.06e}{Version 0.98.06e released 01/09/01}
+
+\begin{itemize}
+ \item{Removed the "outforms.h" file - it appears to be
+ someone's old backup of "outform.h". version "0.98.06e"}
+ \item{fbk - finally added the fix for the "multiple \code{\%include} bug",
+ known since 7/27/99 - reported originally (?) and sent to
+ us by Austin Lunnen - he reports that John Fine had a fix
+ within the day. Here it is...}
+ \item{Nelson Rush resigns from the group. Big thanks to Nelson for
+ his leadership and enthusiasm in getting these changes
+ incorporated into Nasm!}
+ \item{fbk - \code{[list +]}, \code{[list -]} directives - ineptly implemented,
+ should be re-written or removed, perhaps.}
+ \item{Brian Raiter / fbk - "elfso bug" fix - applied to aoutb format
+ as well - testing might be desirable...}
+ \item{James Seter - -postfix, -prefix command line switches.}
+ \item{Yuri Zaporozhets - rdoff utility changes.}
+\end{itemize}
+
+\xsubsection{cl-0.98p1}{Version 0.98p1}
+
+\begin{itemize}
+ \item{GAS-like palign (Panos Minos)}
+ \item{FIXME: Someone, fill this in with details}
+\end{itemize}
+
+\xsubsection{cl-0.98bf}{Version 0.98bf (bug-fixed)}
+
+\begin{itemize}
+ \item{Fixed - elf and aoutb bug - shared libraries}
+ \item{multiple \code{\%include} bug in "-f obj"}
+ \item{jcxz, jecxz bug}
+ \item{unrecognized option bug in ndisasm}
+\end{itemize}
+
+\xsubsection{cl-0.98.03}{Version 0.98.03 with John Coffman's changes released 27-Jul-2000}
+
+\begin{itemize}
+ \item{Added signed byte optimizations for the 0x81/0x83 class
+ of instructions: ADC, ADD, AND, CMP, OR, SBB, SUB, XOR:
+ when used as 'ADD reg16,imm' or 'ADD reg32,imm.' Also
+ optimization of signed byte form of 'PUSH imm' and 'IMUL
+ reg,imm'/'IMUL reg,reg,imm.' No size specification is needed.}
+ \item{Added multi-pass JMP and Jcc offset optimization. Offsets
+ on forward references will preferentially use the short form,
+ without the need to code a specific size (short or near) for
+ the branch. Added instructions for 'Jcc label' to use the
+ form 'Jnotcc \$+3/JMP label', in cases where a short offset
+ is out of bounds. If compiling for a 386 or higher CPU, then
+ the 386 form of Jcc will be used instead.
+
+ This feature is controlled by a new command-line switch: "O",
+ (upper case letter O). "-O0" reverts the assembler to no
+ extra optimization passes, "-O1" allows up to 5 extra passes,
+ and "-O2"(default), allows up to 10 extra optimization passes.}
+ \item{Added a new directive: 'cpu XXX', where XXX is any of:
+ 8086, 186, 286, 386, 486, 586, pentium, 686, PPro, P2, P3 or
+ Katmai. All are case insensitive. All instructions will
+ be selected only if they apply to the selected cpu or lower.
+ Corrected a couple of bugs in cpu-dependence in 'insns.dat'.}
+ \item{Added to 'standard.mac', the "use16" and "use32" forms of
+ the "bits 16/32" directive. This is nothing new, just conforms
+ to a lot of other assemblers. (minor)}
+ \item{Changed label allocation from 320/32 (10000 labels @ 200K+)
+ to 32/37 (1000 labels); makes running under DOS much easier.
+ Since additional label space is allocated dynamically, this
+ should have no effect on large programs with lots of labels.
+ The 37 is a prime, believed to be better for hashing. (minor)}
+\end{itemize}
+
+\xsubsection{cl-0.98.03}{Version 0.98.03}
+
+"Integrated patchfile 0.98-0.98.01. I call this version 0.98.03 for
+historical reasons: 0.98.02 was trashed." --John Coffman
+<johninsd@san.rr.com>, 27-Jul-2000
+
+\begin{itemize}
+ \item{Kendall Bennett's SciTech MGL changes}
+ \item{Note that you must define "TASM\_COMPAT" at compile-time
+ to get the Tasm Ideal Mode compatibility.}
+ \item{All changes can be compiled in and out using the TASM\_COMPAT macros,
+ and when compiled without TASM\_COMPAT defined we get the exact same
+ binary as the unmodified 0.98 sources.}
+ \item{standard.mac, macros.c: Added macros to ignore TASM directives before
+ first include}
+ \item{nasm.h: Added extern declaration for tasm\_compatible\_mode}
+ \item{nasm.c: Added global variable tasm\_compatible\_mode}
+ \item{Added command line switch for TASM compatible mode (-t)}
+ \item{Changed version command line to reflect when compiled with TASM additions}
+ \item{Added response file processing to allow all arguments on a single
+ line (response file is @resp rather than -@resp for NASM format).}
+ \item{labels.c: Changes islocal() macro to support TASM style @@local labels.}
+ \item{Added islocalchar() macro to support TASM style @@local labels.}
+ \item{parser.c: Added support for TASM style memory references (ie: mov
+ [DWORD eax],10 rather than the NASM style mov DWORD [eax],10).}
+ \item{preproc.c: Added new directives, \code{\%arg}, \code{\%local},
+ \code{\%stacksize} to directives table}
+ \item{Added support for TASM style directives without a leading \% symbol.}
+ \item{Integrated a block of changes from Andrew Zabolotny <bit@eltech.ru>:}
+ \item{A new keyword \code{\%xdefine} and its case-insensitive counterpart
+ \code{\%ixdefine}. They work almost the same way as \code{\%define} and
+ \code{\%idefine} but expand the definition immediately, not on the invocation.
+ Something like a cross between \code{\%define} and \code{\%assign}. The "x"
+ suffix stands for "eXpand", so "xdefine" can be deciphered as "expand-and-define".
+ Thus you can do things like this:
+\begin{lstlisting}
+%assign ofs 0
+
+%macro arg 1
+ %xdefine %1 dword [esp+ofs]
+ %assign ofs ofs+4
+%endmacro
+\end{lstlisting}}
+ \item{Changed the place where the expansion of \%\$name macros are expanded.
+ Now they are converted into ..@ctxnum.name form when detokenizing, so
+ there are no quirks as before when using \%\$name arguments to macros,
+ in macros etc. For example:
+\begin{lstlisting}
+%macro abc 1
+ %define %1 hello
+%endm
+ abc %$here
+%$here
+\end{lstlisting}
+ Now last line will be expanded into "hello" as expected. This also allows
+ for lots of goodies, a good example are extended "proc" macros included
+ in this archive.}
+
+ \item{Added a check for "cstk" in smacro\_defined() before calling get\_ctx() -
+ this allows for things like:
+\begin{lstlisting}
+%ifdef %$abc
+%endif
+\end{lstlisting}
+ work without warnings even in no context.}
+ \item{Added a check for "cstk" in \%if*ctx and \%elif*ctx directives -
+ this allows to use \code{\%ifctx} without excessive warnings. If there is
+ no active context, \code{\%ifctx} goes through "false" branch.}
+ \item{Removed "user error: " prefix with \code{\%error} directive: it just clobbers the
+ output and has absolutely no functionality. Besides, this allows to write
+ macros that does not differ from built-in functions in any way.}
+ \item{Added expansion of string that is output by \code{\%error} directive. Now you
+ can do things like:
+\begin{lstlisting}
+%define hello(x) Hello, x!
+
+%define %$name andy
+%error "hello(%$name)"
+\end{lstlisting}
+ Same happened with \code{\%include} directive.}
+ \item{Now all directives that expect an identifier will try to expand and
+ concatenate everything without whitespaces in between before usage.
+ For example, with "unfixed" nasm the commands
+\begin{lstlisting}
+%define %$abc hello
+%define __%$abc goodbye
+__%$abc
+\end{lstlisting}
+ would produce "incorrect" output: last line will expand to
+\begin{lstlisting}
+hello goodbyehello
+\end{lstlisting}
+ Not quite what you expected, eh? :-) The answer is that preprocessor
+ treats the \code{\%define} construct as if it would be
+\begin{lstlisting}
+%define __ %$abc goodbye
+\end{lstlisting}
+ (note the white space between \_\_ and \%\$abc). After my "fix" it
+ will "correctly" expand into
+\begin{lstlisting}
+goodbye
+\end{lstlisting}
+ as expected. Note that I use quotes around words "correct", "incorrect"
+ etc because this is rather a feature not a bug; however current behaviour
+ is more logical (and allows more advanced macro usage :-).
+
+ Same change was applied to: \code{\%push},\code{\%macro},\code{\%imacro},
+ \code{\%define},\code{\%idefine},\code{\%xdefine},\code{\%ixdefine},
+ \code{\%assign},\code{\%iassign},\code{\%undef}}
+ \item{A new directive \code{[WARNING {+|-}warning-id]} have been added. It works only
+ if the assembly phase is enabled (i.e. it doesn't work with nasm -e).}
+ \item{A new warning type: macro-selfref. By default this warning is disabled;
+ when enabled NASM warns when a macro self-references itself; for example
+ the following source:
+\begin{lstlisting}
+[WARNING macro-selfref]
+%macro push 1-*
+ %rep %0
+ push %1
+ %rotate 1
+ %endrep
+%endmacro
+
+ push eax,ebx,ecx
+\end{lstlisting}
+ will produce a warning, but if we remove the first line we won't see it
+ anymore (which is The Right Thing To Do \texttrademark IMHO since C
+ preprocessor eats such constructs without warnings at all).}
+ \item{Added a "error" routine to preprocessor which always will set ERR\_PASS1
+ bit in severity\_code. This removes annoying repeated errors on first
+ and second passes from preprocessor.}
+ \item{Added the \%+ operator in single-line macros for concatenating two
+ identifiers. Usage example:
+\begin{lstlisting}
+%define _myfunc _otherfunc
+%define cextern(x) _ %+ x
+cextern (myfunc)
+\end{lstlisting}
+ After first expansion, third line will become "\_myfunc". After this
+ expansion is performed again so it becomes "\_otherunc".}
+ \item{Now if preprocessor is in a non-emitting state, no warning or error
+ will be emitted. Example:
+\begin{lstlisting}
+%if 1
+ mov eax,ebx
+%else
+ put anything you want between these two brackets,
+ even macro-parameter references %1 or local
+ labels %$zz or macro-local labels %%zz - no
+ warning will be emitted.
+%endif
+\end{lstlisting}}
+ \item{Context-local variables on expansion as a last resort are looked up
+ in outer contexts. For example, the following piece:
+\begin{lstlisting}
+%push outer
+%define %$a [esp]
+
+ %push inner
+ %$a
+ %pop
+%pop
+\end{lstlisting}
+ will expand correctly the fourth line to [esp]; if we'll define another
+ \%\$a inside the "inner" context, it will take precedence over outer
+ definition. However, this modification has been applied only to
+ expand\_smacro and not to smacro\_define: as a consequence expansion
+ looks in outer contexts, but \code{\%ifdef} won't look in outer contexts.
+
+ This behaviour is needed because we don't want nested contexts to
+ act on already defined local macros. Example:
+\begin{lstlisting}
+%define %$arg1 [esp+4]
+test eax,eax
+if nz
+ mov eax,%$arg1
+endif
+\end{lstlisting}
+ In this example the "if" mmacro enters into the "if" context, so \%\$arg1
+ is not valid anymore inside "if". Of course it could be worked around
+ by using explicitely \%\$\$arg1 but this is ugly IMHO.}
+ \item{Fixed memory leak in \code{\%undef}. The origline wasn't freed before exiting on success.}
+ \item{Fixed trap in preprocessor when line expanded to empty set of tokens.
+ This happens, for example, in the following case:
+\begin{lstlisting}
+#define SOMETHING
+SOMETHING
+\end{lstlisting}}
+\end{itemize}
+
+\xsubsection{cl-0.98}{Version 0.98}
+
+All changes since NASM 0.98p3 have been produced by H. Peter Anvin <hpa@zytor.com>.
+
+\begin{itemize}
+ \item{The documentation comment delimiter is \code{\textbackslash \#} not \code{\#}.}
+ \item{Allow EQU definitions to refer to external labels; reported by Pedro Gimeno.}
+ \item{Re-enable support for RDOFF v1; reported by Pedro Gimeno.}
+ \item{Updated License file per OK from Simon and Julian.}
+\end{itemize}
+
+\xsubsection{cl-0.98p9}{Version 0.98p9}
+
+\begin{itemize}
+ \item{Update documentation (although the instruction set reference will
+ have to wait; I don't want to hold up the 0.98 release for it.)}
+ \item{Verified that the NASM implementation of the PEXTRW and PMOVMSKB
+ instructions is correct. The encoding differs from what the Intel
+ manuals document, but the Pentium III behaviour matches NASM, not
+ the Intel manuals.}
+ \item{Fix handling of implicit sizes in PSHUFW and PINSRW, reported by
+ Stefan Hoffmeister.}
+ \item{Resurrect the -s option, which was removed when changing the
+ diagnostic output to stdout.}
+\end{itemize}
+
+\xsubsection{cl-0.98p8}{Version 0.98p8}
+
+\begin{itemize}
+ \item{Fix for "DB" when NASM is running on a bigendian machine.}
+ \item{Invoke insns.pl once for each output script, making Makefile.in
+ legal for "make -j".}
+ \item{Improve the Unix configure-based makefiles to make package
+ creation easier.}
+ \item{Included an RPM .spec file for building RPM (RedHat Package Manager)
+ packages on Linux or Unix systems.}
+ \item{Fix Makefile dependency problems.}
+ \item{Change src/rdsrc.pl to include sectioning information in info
+ output; required for install-info to work.}
+ \item{Updated the RDOFF distribution to version 2 from Jules; minor
+ massaging to make it compile in my environment.}
+ \item{Split doc files that can be built by anyone with a Perl interpreter off
+ into a separate archive.}
+ \item{"Dress rehearsal" release!}
+\end{itemize}
+
+\xsubsection{cl-0.98p7}{Version 0.98p7}
+
+\begin{itemize}
+ \item{Fixed opcodes with a third byte-sized immediate argument to not
+ complain if given "byte" on the immediate.}
+ \item{Allow \code{\%undef} to remove single-line macros with arguments. This
+ matches the behaviour of \#undef in the C preprocessor.}
+ \item{Allow -d, -u, -i and -p to be specified as -D, -U, -I and -P for
+ compatibility with most C compilers and preprocessors. This allows
+ Makefile options to be shared between cc and nasm, for example.}
+ \item{Minor cleanups.}
+ \item{Went through the list of Katmai instructions and hopefully fixed the
+ (rather few) mistakes in it.}
+ \item{(Hopefully) fixed a number of disassembler bugs related to ambiguous
+ instructions (disambiguated by -p) and SSE instructions with REP.}
+ \item{Fix for bug reported by Mark Junger: "call dword 0x12345678" should
+ work and may add an OSP (affected CALL, JMP, Jcc).}
+ \item{Fix for environments when "stderr" isn't a compile-time constant.}
+\end{itemize}
+
+\xsubsection{cl-0.98p6}{Version 0.98p6}
+
+\begin{itemize}
+ \item{Took officially over coordination of the 0.98 release; so drop
+ the p3.x notation. Skipped p4 and p5 to avoid confusion with John
+ Fine's J4 and J5 releases.}
+ \item{Update the documentation; however, it still doesn't include
+ documentation for the various new instructions. I somehow wonder if
+ it makes sense to have an instruction set reference in the assembler
+ manual when Intel et al have PDF versions of their manuals online.}
+ \item{Recognize "idt" or "centaur" for the -p option to ndisasm.}
+ \item{Changed error messages back to stderr where they belong, but add an
+ -E option to redirect them elsewhere (the DOS shell cannot redirect
+ stderr.)}
+ \item{-M option to generate Makefile dependencies (based on code from Alex Verstak.)}
+ \item{\code{\%undef} preprocessor directive, and -u option, that undefines a
+ single-line macro.}
+ \item{OS/2 Makefile (Mkfiles/Makefile.os2) for Borland under OS/2; from
+ Chuck Crayne.}
+ \item{Various minor bugfixes (reported by):
+ - Dangling \code{\%s} in preproc.c (Martin Junker)}
+ \item{THERE ARE KNOWN BUGS IN SSE AND THE OTHER KATMAI INSTRUCTIONS. I am
+ on a trip and didn't bring the Katmai instruction reference, so I
+ can't work on them right now.}
+ \item{Updated the License file per agreement with Simon and Jules to
+ include a GPL distribution clause.}
+\end{itemize}
+
+\xsubsection{cl-0.98p3.7}{Version 0.98p3.7}
+
+\begin{itemize}
+ \item{(Hopefully) fixed the canned Makefiles to include the outrdf2 and
+ zoutieee modules.}
+ \item{Renamed changes.asm to changed.asm.}
+\end{itemize}
+
+\xsubsection{cl-0.98p3.6}{Version 0.98p3.6}
+
+\begin{itemize}
+ \item{Fixed a bunch of instructions that were added in 0.98p3.5 which had
+ memory operands, and the address-size prefix was missing from the
+ instruction pattern.}
+\end{itemize}
+
+\xsubsection{cl-0.98p3.5}{Version 0.98p3.5}
+
+\begin{itemize}
+ \item{Merged in changes from John S. Fine's 0.98-J5 release. John's based
+ 0.98-J5 on my 0.98p3.3 release; this merges the changes.}
+ \item{Expanded the instructions flag field to a long so we can fit more
+ flags; mark SSE (KNI) and AMD or Katmai-specific instructions as
+ such.}
+ \item{Fix the "PRIV" flag on a bunch of instructions, and create new
+ "PROT" flag for protected-mode-only instructions (orthogonal to if
+ the instruction is privileged!) and new "SMM" flag for SMM-only
+ instructions.}
+ \item{Added AMD-only SYSCALL and SYSRET instructions.}
+ \item{Make SSE actually work, and add new Katmai MMX instructions.}
+ \item{Added a -p (preferred vendor) option to ndisasm so that it can
+ distinguish e.g. Cyrix opcodes also used in SSE. For example:
+\begin{lstlisting}
+ndisasm -p cyrix aliased.bin
+00000000 670F514310 paddsiw mm0,[ebx+0x10]
+00000005 670F514320 paddsiw mm0,[ebx+0x20]
+ndisasm -p intel aliased.bin
+00000000 670F514310 sqrtps xmm0,[ebx+0x10]
+00000005 670F514320 sqrtps xmm0,[ebx+0x20]
+\end{lstlisting}}
+ \item{Added a bunch of Cyrix-specific instructions.}
+\end{itemize}
+
+\xsubsection{cl-0.98p3.4}{Version 0.98p3.4}
+
+\begin{itemize}
+ \item{Made at least an attempt to modify all the additional Makefiles (in
+ the Mkfiles directory). I can't test it, but this was the best I
+ could do.}
+ \item{DOS DJGPP+"Opus Make" Makefile from John S. Fine.}
+ \item{changes.asm changes from John S. Fine.}
+\end{itemize}
+
+\xsubsection{cl-0.98p3.3}{Version 0.98p3.3}
+
+\begin{itemize}
+ \item{Patch from Conan Brink to allow nesting of \code{\%rep} directives.}
+ \item{If we're going to allow INT01 as an alias for INT1/ICEBP (one of
+ Jules 0.98p3 changes), then we should allow INT03 as an alias for INT3
+ as well.}
+ \item{Updated changes.asm to include the latest changes.}
+ \item{Tried to clean up the <CR>s that had snuck in from a DOS/Windows
+ environment into my Unix environment, and try to make sure than
+ DOS/Windows users get them back.}
+ \item{We would silently generate broken tools if insns.dat wasn't sorted
+ properly. Change insns.pl so that the order doesn't matter.}
+ \item{Fix bug in insns.pl (introduced by me) which would cause conditional
+ instructions to have an extra "cc" in disassembly, e.g. "jnz"
+ disassembled as "jccnz".}
+\end{itemize}
+
+\xsubsection{cl-0.98p3.2}{Version 0.98p3.2}
+
+\begin{itemize}
+ \item{Merged in John S. Fine's changes from his 0.98-J4 prerelease; see
+ http://www.csoft.net/cz/johnfine/}
+ \item{Changed previous "spotless" Makefile target (appropriate for distribution)
+ to "distclean", and added "cleaner" target which is same as "clean"
+ except deletes files generated by Perl scripts; "spotless" is union.}
+ \item{Removed BASIC programs from distribution. Get a Perl interpreter
+ instead (see below.)}
+ \item{Calling this "pre-release 3.2" rather than "p3-hpa2" because of
+ John's contributions.}
+ \item{Actually link in the IEEE output format (zoutieee.c); fix a bunch of
+ compiler warnings in that file. Note I don't know what IEEE output
+ is supposed to look like, so these changes were made "blind".}
+\end{itemize}
+
+\xsubsection{cl-0.98p3-hpa}{Version 0.98p3-hpa}
+
+\begin{itemize}
+ \item{Merged nasm098p3.zip with nasm-0.97.tar.gz to create a fully
+ buildable version for Unix systems (Makefile.in updates, etc.)}
+ \item{Changed insns.pl to create the instruction tables in nasm.h and
+ names.c, so that a new instruction can be added by adding it *only*
+ to insns.dat.}
+ \item{Added the following new instructions: SYSENTER, SYSEXIT, FXSAVE,
+ FXRSTOR, UD1, UD2 (the latter two are two opcodes that Intel
+ guarantee will never be used; one of them is documented as UD2 in
+ Intel documentation, the other one just as "Undefined Opcode" --
+ calling it UD1 seemed to make sense.)}
+ \item{MAX\_SYMBOL was defined to be 9, but LOADALL286 and LOADALL386 are 10
+ characters long. Now MAX\_SYMBOL is derived from insns.dat.}
+ \item{A note on the BASIC programs included: forget them. insns.bas is
+ already out of date. Get yourself a Perl interpreter for your
+ platform of choice at \href{http://www.cpan.org/ports/index.html}
+ {http://www.cpan.org/ports/index.html}.}
+\end{itemize}
+
+\xsubsection{cl-0.98p3}{Version 0.98 pre-release 3}
+
+\begin{itemize}
+ \item{added response file support, improved command line handling,
+ new layout help screen}
+ \item{fixed limit checking bug, 'OUT byte nn, reg' bug, and
+ a couple of rdoff related bugs, updated Wishlist; 0.98 Prerelease 3.}
+\end{itemize}
+
+\xsubsection{cl-0.98p2}{Version 0.98 pre-release 2}
+
+\begin{itemize}
+ \item{fixed bug in outcoff.c to do with truncating section names longer
+ than 8 characters, referencing beyond end of string; 0.98 pre-release 2}
+\end{itemize}
+
+\xsubsection{cl-0.98p1}{Version 0.98 pre-release 1}
+
+\begin{itemize}
+ \item{Fixed a bug whereby STRUC didn't work at all in RDF.}
+ \item{Fixed a problem with group specification in PUBDEFs in OBJ.}
+ \item{Improved ease of adding new output formats. Contribution due to Fox Cutter.}
+ \item{Fixed a bug in relocations in the `bin' format: was showing up when
+ a relocatable reference crossed an 8192-byte boundary in any output
+ section.}
+ \item{Fixed a bug in local labels: local-label lookups were inconsistent
+ between passes one and two if an EQU occurred between the definition
+ of a global label and the subsequent use of a local label local to
+ that global.}
+ \item{Fixed a seg-fault in the preprocessor (again) which happened when
+ you use a blank line as the first line of a multi-line macro
+ definition and then defined a label on the same line as a call to
+ that macro.}
+ \item{Fixed a stale-pointer bug in the handling of the NASM environment
+ variable. Thanks to Thomas McWilliams.}
+ \item{ELF had a hard limit on the number of sections which caused
+ segfaults when transgressed. Fixed.}
+ \item{Added ability for ndisasm to read from stdin by using `-' as the
+ filename.}
+ \item{ndisasm wasn't outputting the TO keyword. Fixed.}
+ \item{Fixed error cascade on bogus expression in \code{\%if} - an error in
+ evaluation was causing the entire \code{\%if} to be discarded, thus creating
+ trouble later when the \code{\%else} or \code{\%endif} was encountered.}
+ \item{Forward reference tracking was instruction-granular not operand-
+ granular, which was causing 286-specific code to be generated
+ needlessly on code of the form `shr word [forwardref],1'. Thanks to
+ Jim Hague for sending a patch.}
+ \item{All messages now appear on stdout, as sending them to stderr serves
+ no useful purpose other than to make redirection difficult.}
+ \item{Fixed the problem with EQUs pointing to an external symbol - this
+ now generates an error message.}
+ \item{Allowed multiple size prefixes to an operand, of which only the first
+ is taken into account.}
+ \item{Incorporated John Fine's changes, including fixes of a large number
+ of preprocessor bugs, some small problems in OBJ, and a reworking of
+ label handling to define labels before their line is assembled, rather
+ than after.}
+ \item{Reformatted a lot of the source code to be more readable. Included
+ 'coding.txt' as a guideline for how to format code for contributors.}
+ \item{Stopped nested \code{\%reps} causing a panic - they now cause a slightly more
+ friendly error message instead.}
+ \item{Fixed floating point constant problems (patch by Pedro Gimeno)}
+ \item{Fixed the return value of insn\_size() not being checked for -1, indicating
+ an error.}
+ \item{Incorporated 3Dnow! instructions.}
+ \item{Fixed the 'mov eax, eax + ebx' bug.}
+ \item{Fixed the GLOBAL EQU bug in ELF. Released developers release 3.}
+ \item{Incorporated John Fine's command line parsing changes}
+ \item{Incorporated David Lindauer's OMF debug support}
+ \item{Made changes for LCC 4.0 support (\code{\_\_NASM\_CDecl\_\_}, removed register size
+ specification warning when sizes agree).}
+\end{itemize}
+
+\xsection{cl-0.9x}{NASM 0.9 Series}
+
+Revisions before 0.98.
+
+\xsubsection{cl-0.97}{Version 0.97 released December 1997}
+
+\begin{itemize}
+ \item{This was entirely a bug-fix release to 0.96, which seems to have got
+ cursed. Silly me.}
+ \item{Fixed stupid mistake in OBJ which caused `MOV EAX,<constant>' to
+ fail. Caused by an error in the `MOV EAX,<segment>' support.}
+ \item{ndisasm hung at EOF when compiled with lcc on Linux because lcc on
+ Linux somehow breaks feof(). ndisasm now does not rely on feof().}
+ \item{A heading in the documentation was missing due to a markup error in
+ the indexing. Fixed.}
+ \item{Fixed failure to update all pointers on realloc() within extended-
+ operand code in parser.c. Was causing wrong behaviour and seg faults
+ on lines such as `dd 0.0,0.0,0.0,0.0,...'}
+ \item{Fixed a subtle preprocessor bug whereby invoking one multi-line
+ macro on the first line of the expansion of another, when the second
+ had been invoked with a label defined before it, didn't expand the
+ inner macro.}
+ \item{Added internal.doc back in to the distribution archives - it was
+ missing in 0.96 *blush*}
+ \item{Fixed bug causing 0.96 to be unable to assemble its own test files,
+ specifically objtest.asm. *blush again*}
+ \item{Fixed seg-faults and bogus error messages caused by mismatching
+ \code{\%rep} and \code{\%endrep} within multi-line macro definitions.}
+ \item{Fixed a problem with buffer overrun in OBJ, which was causing
+ corruption at ends of long PUBDEF records.}
+ \item{Separated DOS archives into main-program and documentation to reduce
+ download size.}
+\end{itemize}
+
+\xsubsection{cl-0.96}{Version 0.96 released November 1997}
+
+\begin{itemize}
+ \item{Fixed a bug whereby, if `nasm sourcefile' would cause a filename
+ collision warning and put output into `nasm.out', then `nasm
+ sourcefile -o outputfile' still gave the warning even though the
+ `-o' was honoured.
+ Fixed name pollution under Digital UNIX: one of its header files
+ defined R\_SP, which broke the enum in nasm.h.}
+ \item{Fixed minor instruction table problems: FUCOM and FUCOMP didn't have
+ two-operand forms; NDISASM didn't recognise the longer register
+ forms of PUSH and POP (eg FF F3 for PUSH BX); TEST mem,imm32 was
+ flagged as undocumented; the 32-bit forms of CMOV had 16-bit operand
+ size prefixes; `AAD imm' and `AAM imm' are no longer flagged as
+ undocumented because the Intel Architecture reference documents
+ them.}
+ \item{Fixed a problem with the local-label mechanism, whereby strange
+ types of symbol (EQUs, auto-defined OBJ segment base symbols)
+ interfered with the `previous global label' value and screwed up
+ local labels.}
+ \item{Fixed a bug whereby the stub preprocessor didn't communicate with
+ the listing file generator, so that the -a and -l options in
+ conjunction would produce a useless listing file.}
+ \item{Merged `os2' object file format back into `obj', after discovering
+ that `obj' \emph{also} shouldn't have a link pass separator in a module
+ containing a non-trivial MODEND. Flat segments are now declared
+ using the FLAT attribute. `os2' is no longer a valid object format
+ name: use `obj'.}
+ \item{Removed the fixed-size temporary storage in the evaluator. Very very
+ long expressions (like `mov ax,1+1+1+1+...' for two hundred 1s or
+ so) should now no longer crash NASM.}
+ \item{Fixed a bug involving segfaults on disassembly of MMX instructions,
+ by changing the meaning of one of the operand-type flags in nasm.h.
+ This may cause other apparently unrelated MMX problems; it needs to
+ be tested thoroughly.}
+ \item{Fixed some buffer overrun problems with large OBJ output files.
+ Thanks to DJ Delorie for the bug report and fix.}
+ \item{Made preprocess-only mode actually listen to the \code{\%line} markers as it
+ prints them, so that it can report errors more sanely.}
+ \item{Re-designed the evaluator to keep more sensible track of expressions
+ involving forward references: can now cope with previously-nightmare
+ situations such as:
+\begin{lstlisting}
+mov ax,foo | bar
+foo equ 1
+bar equ 2
+\end{lstlisting}}
+ \item{Added the ALIGN and ALIGNB standard macros.}
+ \item{Added PIC support in ELF: use of WRT to obtain the four extra
+ relocation types needed.}
+ \item{Added the ability for output file formats to define their own
+ extensions to the GLOBAL, COMMON and EXTERN directives.}
+ \item{Implemented common-variable alignment, and global-symbol type and
+ size declarations, in ELF.}
+ \item{Implemented NEAR and FAR keywords for common variables, plus
+ far-common element size specification, in OBJ.}
+ \item{Added a feature whereby EXTERNs and COMMONs in OBJ can be given a
+ default WRT specification (either a segment or a group).}
+ \item{Transformed the Unix NASM archive into an auto-configuring package.}
+ \item{Added a sanity-check for people applying SEG to things which are
+ already segment bases: this previously went unnoticed by the SEG
+ processing and caused OBJ-driver panics later.}
+ \item{Added the ability, in OBJ format, to deal with `MOV EAX,<segment>'
+ type references: OBJ doesn't directly support dword-size segment
+ base fixups, but as long as the low two bytes of the constant term
+ are zero, a word-size fixup can be generated instead and it will
+ work.}
+ \item{Added the ability to specify sections' alignment requirements in
+ Win32 object files and pure binary files.}
+ \item{Added preprocess-time expression evaluation: the \code{\%assign} (and
+ \code{\%iassign}) directive and the bare \code{\%if} (and \code{\%elif}) conditional.
+ Added relational operators to the evaluator, for use only in \code{\%if}
+ constructs: the standard relationals = < > <= >= <> (and C-like
+ synonyms == and !=) plus low-precedence logical operators \&\&,
+ \textasciicircum \textasciicircum and ||.}
+ \item{Added a preprocessor repeat construct: \code{\%rep}, \code{\%exitrep},
+ \code{\%endrep}.}
+ \item{Added the \_\_FILE\_\_ and \_\_LINE\_\_ standard macros.}
+ \item{Added a sanity check for number constants being greater than
+ 0xFFFFFFFF. The warning can be disabled.}
+ \item{Added the \%0 token whereby a variadic multi-line macro can tell how
+ many parameters it's been given in a specific invocation.}
+ \item{Added \code{\%rotate}, allowing multi-line macro parameters to be cycled.}
+ \item{Added the `*' option for the maximum parameter count on multi-line
+ macros, allowing them to take arbitrarily many parameters.}
+ \item{Added the ability for the user-level forms of EXTERN, GLOBAL and
+ COMMON to take more than one argument.}
+ \item{Added the IMPORT and EXPORT directives in OBJ format, to deal with
+ Windows DLLs.}
+ \item{Added some more preprocessor \code{\%if} constructs: \code{\%ifidn},
+ \code{\%ifidni} (exact textual identity), and \code{\%ifid},
+ \code{\%ifnum}, \code{\%ifstr} (token type testing).}
+ \item{Added the ability to distinguish SHL AX,1 (the 8086 version) from
+ SHL AX,BYTE 1 (the 286-and-upwards version whose constant happens to
+ be 1).}
+ \item{Added NetBSD/FreeBSD/OpenBSD's variant of a.out format, complete
+ with PIC shared library features.}
+ \item{Changed NASM's idiosyncratic handling of FCLEX, FDISI, FENI, FINIT,
+ FSAVE, FSTCW, FSTENV, and FSTSW to bring it into line with the
+ otherwise accepted standard. The previous behaviour, though it was a
+ deliberate feature, was a deliberate feature based on a
+ misunderstanding. Apologies for the inconvenience.}
+ \item{Improved the flexibility of ABSOLUTE: you can now give it an
+ expression rather than being restricted to a constant, and it can
+ take relocatable arguments as well.}
+ \item{Added the ability for a variable to be declared as EXTERN multiple
+ times, and the subsequent definitions are just ignored.}
+ \item{We now allow instruction prefixes (CS, DS, LOCK, REPZ etc) to be
+ alone on a line (without a following instruction).}
+ \item{Improved sanity checks on whether the arguments to EXTERN, GLOBAL
+ and COMMON are valid identifiers.}
+ \item{Added misc/exebin.mac to allow direct generation of .EXE files by
+ hacking up an EXE header using DB and DW; also added test/binexe.asm
+ to demonstrate the use of this. Thanks to Yann Guidon for
+ contributing the EXE header code.}
+ \item{ndisasm forgot to check whether the input file had been successfully
+ opened. Now it does. Doh!}
+ \item{Added the Cyrix extensions to the MMX instruction set.}
+ \item{Added a hinting mechanism to allow [EAX+EBX] and [EBX+EAX] to be
+ assembled differently. This is important since [ESI+EBP] and
+ [EBP+ESI] have different default base segment registers.}
+ \item{Added support for the PharLap OMF extension for 4096-byte segment
+ alignment.}
+\end{itemize}
+
+\xsubsection{cl-0.95}{Version 0.95 released July 1997}
+
+\begin{itemize}
+ \item{Fixed yet another ELF bug. This one manifested if the user relied on
+ the default segment, and attempted to define global symbols without
+ first explicitly declaring the target segment.}
+ \item{Added makefiles (for NASM and the RDF tools) to build Win32 console
+ apps under Symantec C++. Donated by Mark Junker.}
+ \item{Added `macros.bas' and `insns.bas', QBasic versions of the Perl
+ scripts that convert `standard.mac' to `macros.c' and convert
+ `insns.dat' to `insnsa.c' and `insnsd.c'. Also thanks to Mark
+ Junker.}
+ \item{Changed the diassembled forms of the conditional instructions so
+ that JB is now emitted as JC, and other similar changes. Suggested
+ list by Ulrich Doewich.}
+ \item{Added `@' to the list of valid characters to begin an identifier with.}
+ \item{Documentary changes, notably the addition of the `Common Problems'
+ section in nasm.doc.}
+ \item{Fixed a bug relating to 32-bit PC-relative fixups in OBJ.}
+ \item{Fixed a bug in perm\_copy() in labels.c which was causing exceptions
+ in cleanup\_labels() on some systems.}
+ \item{Positivity sanity check in TIMES argument changed from a warning to
+ an error following a further complaint.}
+ \item{Changed the acceptable limits on byte and word operands to allow
+ things like `\textasciitilde 10111001b' to work.}
+ \item{Fixed a major problem in the preprocessor which caused seg-faults if
+ macro definitions contained blank lines or comment-only lines.}
+ \item{Fixed inadequate error checking on the commas separating the
+ arguments to `db', `dw' etc.}
+ \item{Fixed a crippling bug in the handling of macros with operand counts
+ defined with a `+' modifier.}
+ \item{Fixed a bug whereby object file formats which stored the input file
+ name in the output file (such as OBJ and COFF) weren't doing so
+ correctly when the output file name was specified on the command
+ line.}
+ \item{Removed [INC] and [INCLUDE] support for good, since they were
+ obsolete anyway.}
+ \item{Fixed a bug in OBJ which caused all fixups to be output in 16-bit
+ (old-format) FIXUPP records, rather than putting the 32-bit ones in
+ FIXUPP32 (new-format) records.}
+ \item{Added, tentatively, OS/2 object file support (as a minor variant
+ on OBJ).}
+ \item{Updates to Fox Cutter's Borland C makefile, Makefile.bc2.}
+ \item{Removed a spurious second fclose() on the output file.}
+ \item{Added the `-s' command line option to redirect all messages which
+ would go to stderr (errors, help text) to stdout instead.}
+ \item{Added the `-w' command line option to selectively suppress some
+ classes of assembly warning messages.}
+ \item{Added the `-p' pre-include and `-d' pre-define command-line options.}
+ \item{Added an include file search path: the `-i' command line option.}
+ \item{Fixed a silly little preprocessor bug whereby starting a line with a
+ `\%!' environment-variable reference caused an `unknown directive'
+ error.}
+ \item{Added the long-awaited listing file support: the `-l' command line
+ option.}
+ \item{Fixed a problem with OBJ format whereby, in the absence of any
+ explicit segment definition, non-global symbols declared in the
+ implicit default segment generated spurious EXTDEF records in the
+ output.}
+ \item{Added the NASM environment variable.}
+ \item{From this version forward, Win32 console-mode binaries will be
+ included in the DOS distribution in addition to the 16-bit binaries.
+ Added Makefile.vc for this purpose.}
+ \item{Added `return 0;' to test/objlink.c to prevent compiler warnings.}
+ \item{Added the \_\_NASM\_MAJOR\_\_ and \_\_NASM\_MINOR\_\_ standard defines.}
+ \item{Added an alternative memory-reference syntax in which prefixing an
+ operand with `\&' is equivalent to enclosing it in square brackets,
+ at the request of Fox Cutter.}
+ \item{Errors in pass two now cause the program to return a non-zero error
+ code, which they didn't before.}
+ \item{Fixed the single-line macro cycle detection, which didn't work at
+ all on macros with no parameters (caused an infinite loop). Also
+ changed the behaviour of single-line macro cycle detection to work
+ like cpp, so that macros like `extrn' as given in the documentation
+ can be implemented.}
+ \item{Fixed the implementation of WRT, which was too restrictive in that
+ you couldn't do `mov ax,[di+abc wrt dgroup]' because (di+abc) wasn't
+ a relocatable reference.}
+\end{itemize}
+
+\xsubsection{cl-0.94}{Version 0.94 released April 1997}
+
+\begin{itemize}
+ \item{Major item: added the macro processor.}
+ \item{Added undocumented instructions SMI, IBTS, XBTS and LOADALL286. Also
+ reorganised CMPXCHG instruction into early-486 and Pentium forms.
+ Thanks to Thobias Jones for the information.}
+ \item{Fixed two more stupid bugs in ELF, which were causing `ld' to
+ continue to seg-fault in a lot of non-trivial cases.}
+ \item{Fixed a seg-fault in the label manager.}
+ \item{Stopped FBLD and FBSTP from \emph{requiring} the TWORD keyword, which is
+ the only option for BCD loads/stores in any case.}
+ \item{Ensured FLDCW, FSTCW and FSTSW can cope with the WORD keyword, if
+ anyone bothers to provide it. Previously they complained unless no
+ keyword at all was present.}
+ \item{Some forms of FDIV/FDIVR and FSUB/FSUBR were still inverted: a
+ vestige of a bug that I thought had been fixed in 0.92. This was
+ fixed, hopefully for good this time...}
+ \item{Another minor phase error (insofar as a phase error can \emph{ever} be
+ minor) fixed, this one occurring in code of the form
+\begin{lstlisting}
+rol ax,forward_reference
+forward_reference equ 1
+\end{lstlisting}}
+ \item{The number supplied to TIMES is now sanity-checked for positivity,
+ and also may be greater than 64K (which previously didn't work on
+ 16-bit systems).}
+ \item{Added Watcom C makefiles, and misc/pmw.bat, donated by Dominik Behr.}
+ \item{Added the INCBIN pseudo-opcode.}
+ \item{Due to the advent of the preprocessor, the [INCLUDE] and [INC]
+ directives have become obsolete. They are still supported in this
+ version, with a warning, but won't be in the next.}
+ \item{Fixed a bug in OBJ format, which caused incorrect object records to
+ be output when absolute labels were made global.}
+ \item{Updates to RDOFF subdirectory, and changes to outrdf.c.}
+\end{itemize}
+
+\xsubsection{cl-0.93}{Version 0.93 released January 1997}
+
+This release went out in a great hurry after semi-crippling bugs
+were found in 0.92.
+
+\begin{itemize}
+ \item{Really \emph{did} fix the stack overflows this time. *blush*}
+ \item{Had problems with EA instruction sizes changing between passes, when
+ an offset contained a forward reference and so 4 bytes were
+ allocated for the offset in pass one; by pass two the symbol had
+ been defined and happened to be a small absolute value, so only 1
+ byte got allocated, causing instruction size mismatch between passes
+ and hence incorrect address calculations. Fixed.}
+ \item{Stupid bug in the revised ELF section generation fixed (associated
+ string-table section for .symtab was hard-coded as 7, even when this
+ didn't fit with the real section table). Was causing `ld' to
+ seg-fault under Linux.}
+ \item{Included a new Borland C makefile, Makefile.bc2, donated by Fox
+ Cutter <lmb@comtch.iea.com>.}
+\end{itemize}
+
+\xsubsection{cl-0.92}{Version 0.92 released January 1997}
+
+\begin{itemize}
+ \item{The FDIVP/FDIVRP and FSUBP/FSUBRP pairs had been inverted: this was
+ fixed. This also affected the LCC driver.}
+ \item{Fixed a bug regarding 32-bit effective addresses of the form
+ \code{[other\_register+ESP]}.}
+ \item{Documentary changes, notably documentation of the fact that Borland
+ Win32 compilers use `obj' rather than `win32' object format.}
+ \item{Fixed the COMENT record in OBJ files, which was formatted
+ incorrectly.}
+ \item{Fixed a bug causing segfaults in large RDF files.}
+ \item{OBJ format now strips initial periods from segment and group
+ definitions, in order to avoid complications with the local label
+ syntax.}
+ \item{Fixed a bug in disassembling far calls and jumps in NDISASM.}
+ \item{Added support for user-defined sections in COFF and ELF files.}
+ \item{Compiled the DOS binaries with a sensible amount of stack, to
+ prevent stack overflows on any arithmetic expression containing
+ parentheses.}
+ \item{Fixed a bug in handling of files that do not terminate in a newline.}
+\end{itemize}
+
+\xsubsection{cl-0.91}{Version 0.91 released November 1996}
+
+\begin{itemize}
+ \item{Loads of bug fixes.}
+ \item{Support for RDF added.}
+ \item{Support for DBG debugging format added.}
+ \item{Support for 32-bit extensions to Microsoft OBJ format added.}
+ \item{Revised for Borland C: some variable names changed, makefile added.}
+ \item{LCC support revised to actually work.}
+ \item{JMP/CALL NEAR/FAR notation added.}
+ \item{`a16', `o16', `a32' and `o32' prefixes added.}
+ \item{Range checking on short jumps implemented.}
+ \item{MMX instruction support added.}
+ \item{Negative floating point constant support added.}
+ \item{Memory handling improved to bypass 64K barrier under DOS.}
+ \item{\code{\$} prefix to force treatment of reserved words as identifiers added.}
+ \item{Default-size mechanism for object formats added.}
+ \item{Compile-time configurability added.}
+ \item{\code{\#}, \code{\@}, \code{\textasciitilde} and \code{?} are now valid characters in labels.}
+ \item{\code{-e} and \code{-k} options in NDISASM added.}
+\end{itemize}
+
+\xsubsection{cl-0.90} Version 0.90 released October 1996
+
+First release version. First support for object file output. Other
+changes from previous version (0.3x) too numerous to document.
diff --git a/doc/latex/src/contact.tex b/doc/latex/src/contact.tex
new file mode 100644
index 00000000..f90631af
--- /dev/null
+++ b/doc/latex/src/contact.tex
@@ -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}
diff --git a/doc/latex/src/directive.tex b/doc/latex/src/directive.tex
new file mode 100644
index 00000000..964315cd
--- /dev/null
+++ b/doc/latex/src/directive.tex
@@ -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.
diff --git a/doc/latex/src/idxconf.ist b/doc/latex/src/idxconf.ist
new file mode 100644
index 00000000..cb36fe99
--- /dev/null
+++ b/doc/latex/src/idxconf.ist
@@ -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 "
diff --git a/doc/latex/src/inslist.tex b/doc/latex/src/inslist.tex
new file mode 100644
index 00000000..fdd75da8
--- /dev/null
+++ b/doc/latex/src/inslist.tex
@@ -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
diff --git a/doc/latex/src/intro.tex b/doc/latex/src/intro.tex
new file mode 100644
index 00000000..78c0946e
--- /dev/null
+++ b/doc/latex/src/intro.tex
@@ -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.
diff --git a/doc/latex/src/language.tex b/doc/latex/src/language.tex
new file mode 100644
index 00000000..e29b8381
--- /dev/null
+++ b/doc/latex/src/language.tex
@@ -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.
diff --git a/doc/latex/src/macropkg.tex b/doc/latex/src/macropkg.tex
new file mode 100644
index 00000000..c71b548c
--- /dev/null
+++ b/doc/latex/src/macropkg.tex
@@ -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.
diff --git a/doc/latex/src/mixsize.tex b/doc/latex/src/mixsize.tex
new file mode 100644
index 00000000..b8a35ea8
--- /dev/null
+++ b/doc/latex/src/mixsize.tex
@@ -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.)
diff --git a/doc/latex/src/nasm.tex b/doc/latex/src/nasm.tex
new file mode 100644
index 00000000..6ba1920b
--- /dev/null
+++ b/doc/latex/src/nasm.tex
@@ -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}
diff --git a/doc/latex/src/nasmlogo.eps b/doc/latex/src/nasmlogo.eps
new file mode 100644
index 00000000..9ec29194
--- /dev/null
+++ b/doc/latex/src/nasmlogo.eps
@@ -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
diff --git a/doc/latex/src/ndisasm.tex b/doc/latex/src/ndisasm.tex
new file mode 100644
index 00000000..d350a2c9
--- /dev/null
+++ b/doc/latex/src/ndisasm.tex
@@ -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.
diff --git a/doc/latex/src/outfmt.tex b/doc/latex/src/outfmt.tex
new file mode 100644
index 00000000..7f4cb976
--- /dev/null
+++ b/doc/latex/src/outfmt.tex
@@ -0,0 +1,1606 @@
+%
+% vim: ts=4 sw=4 et
+%
+\xchapter{outfmt}{\textindexlc{Output Formats}}
+
+NASM is a portable assembler, designed to be able to compile on any
+ANSI C-supporting platform and produce output to run on a variety of
+Intel x86 operating systems. For this reason, it has a large number
+of available output formats, selected using the \codeindex{-f} option
+on the NASM \textindex{command line}. Each of these formats, along with
+its extensions to the base NASM syntax, is detailed in this chapter.
+
+\xsection{binfmt}{\codeindex{bin}: \textindexlc{Flat-Form Binary}\index{pure binary} Output}
+\index{file extension!bin}
+
+The \code{bin} format does not produce object files: it generates
+nothing in the output file except the code you wrote. Such ``pure
+binary'' files are used by \textindex{MS-DOS}: \codeindex{.COM}
+executables and \codeindex{.SYS} device drivers are pure binary
+files. Pure binary output is also useful for \textindex{operating system}
+and \textindex{boot loader} development.
+
+The \code{bin} format supports \textindex{multiple section names}.
+For details of how NASM handles sections in the \code{bin} format,
+see \nref{multisec}.
+
+Using the \code{bin} format puts NASM by default into 16-bit mode
+(see \nref{bits}). In order to use \code{bin} to write 32-bit
+or 64-bit code, such as an OS kernel, you need to explicitly issue
+the \indexcode{BITS}\code{BITS 32} or \indexcode{BITS}\code{BITS 64}
+directive.
+
+\code{bin} has no default output file name extension: instead, it
+leaves your file name as it is once the original extension has been
+removed. Thus, the default is for NASM to assemble \code{binprog.asm}
+into a binary file called \code{binprog}.
+
+\xsubsection{binorg}{\codeindex{ORG}: Binary File \textindexlc{Program Origin}}
+
+The \code{bin} format provides an additional directive to the list
+given in \nref{directive}: \code{ORG}. The function of the
+\code{ORG} directive is to specify the origin address which NASM
+will assume the program begins at when it is loaded into memory.
+
+For example, the following code will generate the longword
+\code{0x00000104}:
+
+\begin{lstlisting}
+org 0x100
+dd label
+label:
+\end{lstlisting}
+
+Unlike the \code{ORG} directive provided by MASM-compatible assemblers,
+which allows you to jump around in the object file and overwrite
+code you have already generated, NASM's \code{ORG} does exactly what
+the directive says: \emph{origin}. Its sole function is to specify one
+offset which is added to all internal address references within the
+section; it does not permit any of the trickery that MASM's version
+does. See \nref{proborg} for further comments.
+
+\xsubsection{binseg}{\code{bin} Extensions to the \code{SECTION} Directive}
+\index{section!bin extensions to}
+
+The \code{bin} output format extends the \code{SECTION} (or \code{SEGMENT})
+directive to allow you to specify the alignment requirements of segments.
+This is done by appending the \codeindex{ALIGN} qualifier to the end of
+the section-definition line. For example,
+
+\begin{lstlisting}
+section .data align=16
+\end{lstlisting}
+
+switches to the section \code{.data} and also specifies that it must be
+aligned on a 16-byte boundary.
+
+The parameter to \code{ALIGN} specifies how many low bits of the
+section start address must be forced to zero. The alignment value
+given may be any power of two.
+\index{section alignment!in bin}
+\index{segment alignment!in bin}
+\index{alignment!in bin sections}
+
+\xsubsection{multisec}{\textindexlc{Multisection} Support for the \code{bin} Format}
+\index{bin!multisection}
+
+The \code{bin} format allows the use of multiple sections, of arbitrary names,
+besides the ``known'' \code{.text}, \code{.data}, and \code{.bss} names.
+
+\begin{itemize}
+ \item{Sections may be designated \codeindex{progbits} or \codeindex{nobits}.
+ Default is \code{progbits} (except \code{.bss}, which defaults to
+ \code{nobits}, of course).}
+
+ \item{Sections can be aligned at a specified boundary following the previous
+ section with \code{align=}, or at an arbitrary byte-granular position with
+ \codeindex{start=}.}
+
+ \item{Sections can be given a virtual start address, which will be used
+ for the calculation of all memory references within that section
+ with \codeindex{vstart=}.}
+
+ \item{Sections can be ordered using \codeindex{follows=}\code{<section>} or
+ \codeindex{vfollows=}\code{<section>} as an alternative to specifying
+ an explicit start address.}
+
+ \item{Arguments to \code{org}, \code{start}, \code{vstart}, and \code{align=}
+ are critical expressions. See \nref{crit}. E.g.
+ \code{align=(1 << ALIGN\_SHIFT)} - \code{ALIGN\_SHIFT} must be defined
+ before it is used here.}
+
+ \item{Any code which comes before an explicit \code{SECTION} directive
+ is directed by default into the \code{.text} section.}
+
+ \item{If an \code{ORG} statement is not given, \code{ORG 0} is used by default.}
+
+ \item{The \code{.bss} section will be placed after the last \code{progbits}
+ section, unless \code{start=}, \code{vstart=}, \code{follows=}, or
+ \code{vfollows=} has been specified.}
+
+ \item{All sections are aligned on dword boundaries, unless a different
+ alignment has been specified.}
+
+ \item{Sections may not overlap.}
+
+ \item{NASM creates the \code{section.<secname>.start} for each section,
+ which may be used in your code.}
+\end{itemize}
+
+\xsubsection{map}{\textindexlc{Map Files}}
+\index{file extension!map}
+
+Map files can be generated in \code{-f bin} format by means of the \code{[map]}
+option. Map types of \code{all} (default), \code{brief}, \code{sections},
+\code{segments}, or \code{symbols} may be specified. Output may be directed
+to \code{stdout} (default), \code{stderr}, or a specified file. E.g.
+\code{[map symbols myfile.map]}. No ``user form'' exists, the square
+brackets must be used.
+
+\xsection{ithfmt}{\codeindex{ith}: \textindexlc{Intel Hex} Output}
+\index{file extension!ith}
+
+The \code{ith} file format produces Intel hex-format files. Just as the
+\code{bin} format, this is a flat memory image format with no support for
+relocation or linking. It is usually used with ROM programmers and
+similar utilities.
+
+All extensions supported by the \code{bin} file format is also supported by
+the \code{ith} file format.
+
+\code{ith} provides a default output file-name extension of \code{.ith}.
+
+\xsection{srecfmt}{\codeindex{srec}: \textindexlc{Motorola S-Records} Output}
+\index{file extension!srec}
+
+The \code{srec} file format produces Motorola S-records files. Just as the
+\code{bin} format, this is a flat memory image format with no support for
+relocation or linking. It is usually used with ROM programmers and similar
+utilities.
+
+All extensions supported by the \code{bin} file format is also supported by
+the \code{srec} file format.
+
+\code{srec} provides a default output file-name extension of \code{.srec}.
+
+\xsection{objfmt}{\codeindex{obj}: \textindexlc{Microsoft OMF}\index{OMF} Object Files}
+\index{file extension!obj}
+
+The \code{obj} file format (NASM calls it \code{obj} rather than
+\code{omf} for historical reasons) is the one produced by \textindex{MASM}
+and \textindex{TASM}, which is typically fed to 16-bit DOS linkers
+to produce \codeindex{.EXE} files. It is also the format used by
+\textindex{OS/2}.
+
+\code{obj} provides a default output file-name extension of \code{.obj}.
+
+\code{obj} is not exclusively a 16-bit format, though: NASM has full
+support for the 32-bit extensions to the format. In particular,
+32-bit \code{obj} format files are used by \textindex{Borland's Win32
+compilers}, instead of using Microsoft's newer \codeindex{win32} object
+file format.
+
+The \code{obj} format does not define any special segment names: you
+can call your segments anything you like. Typical names for segments
+in \code{obj} format files are \code{CODE}, \code{DATA} and \code{BSS}.
+
+If your source file contains code before specifying an explicit
+\code{SEGMENT} directive, then NASM will invent its own segment called
+\codeindex{\_\_NASMDEFSEG} for you.
+
+When you define a segment in an \code{obj} file, NASM defines the
+segment name as a symbol as well, so that you can access the segment
+address of the segment. So, for example:
+
+\begin{lstlisting}
+segment data
+
+dvar: dw 1234
+
+segment code
+
+function:
+ mov ax,data ; get segment address of data
+ mov ds,ax ; and move it into DS
+ inc word [dvar] ; now this reference will work
+ ret
+\end{lstlisting}
+
+The \code{obj} format also enables the use of the \codeindex{SEG}
+and \codeindex{WRT} operators, so that you can write code which
+does things like
+
+\begin{lstlisting}
+extern foo
+
+ mov ax,seg foo ; get preferred segment of foo
+ mov ds,ax
+ mov ax,data ; a different segment
+ mov es,ax
+ mov ax,[ds:foo] ; this accesses `foo'
+ mov [es:foo wrt data],bx ; so does this
+\end{lstlisting}
+
+\xsubsection{objseg}{\code{obj} Extensions to the \code{SEGMENT} Directive}
+\index{SEGMENT!obj extensions to}
+
+The \code{obj} output format extends the \code{SEGMENT} (or \code{SECTION})
+directive to allow you to specify various properties of the segment
+you are defining. This is done by appending extra qualifiers to the
+end of the segment-definition line. For example,
+
+\begin{lstlisting}
+segment code private align=16
+\end{lstlisting}
+
+defines the segment \code{code}, but also declares it to be a private
+segment, and requires that the portion of it described in this code
+module must be aligned on a 16-byte boundary.
+
+The available qualifiers are:
+
+%\begin{tabular}{ l l }
+%\codeindex{CLASS} &
+%\begin{minipage}[t]{0.8\columnwidth}
+%can be used to specify the segment class; this feature indicates to
+%the linker that segments of the same class should be placed near each
+%other in the output file. The class name can be any word, e.g.
+%\code{CLASS=CODE}.
+%\end{minipage} \\
+%
+%\codeindex{OVERLAY} &
+%\begin{minipage}[t]{0.8\columnwidth}
+%like \code{CLASS}, is specified with an arbitrary word as an argument,
+%and provides overlay information to an overlay-capable linker.
+%\end{minipage}
+%\end{tabular}
+
+\begin{itemize}
+ \item{\codeindex{PRIVATE}, \codeindex{PUBLIC}, \codeindex{COMMON}
+ and \codeindex{STACK} specify the combination characteristics
+ of the segment. \code{PRIVATE} segments do not get combined
+ with any others by the linker; \code{PUBLIC} and \code{STACK}
+ segments get concatenated together at link time; and \code{COMMON}
+ segments all get overlaid on top of each other rather than stuck
+ end-to-end.}
+
+ \item{\codeindex{ALIGN} is used, as shown above, to specify how many
+ low bits of the segment start address must be forced to zero.
+ The alignment value given may be any power of two from 1 to 4096;
+ in reality, the only values supported are 1, 2, 4, 16, 256 and 4096,
+ so if 8 is specified it will be rounded up to 16, and 32, 64 and 128
+ will all be rounded up to 256, and so on. Note that alignment to
+ 4096-byte boundaries is a \textindex{PharLap} extension to the
+ format and may not be supported by all linkers.
+ \index{section alignment!in OBJ}
+ \index{segment alignment!in OBJ}
+ \index{alignment!in OBJ sections}}
+
+ \item{\codeindex{CLASS} can be used to specify the segment class;
+ this feature indicates to the linker that segments of the same
+ class should be placed near each other in the output file.
+ The class name can be any word, e.g. \code{CLASS=CODE}.}
+
+ \item{\codeindex{OVERLAY}, like \code{CLASS}, is specified with
+ an arbitrary word as an argument, and provides overlay information
+ to an overlay-capable linker.}
+
+ \item{Segments can be declared as \codeindex{USE16} or \codeindex{USE32},
+ which has the effect of recording the choice in the object file
+ and also ensuring that NASM's default assembly mode when assembling
+ in that segment is 16-bit or 32-bit respectively.}
+
+ \item{When writing \textindex{OS/2} object files, you should declare
+ 32-bit segments as \codeindex{FLAT}, which causes the default
+ segment base for anything in the segment to be the special group
+ \code{FLAT}, and also defines the group if it is not already defined.}
+
+ \item{The \code{obj} file format also allows segments to be declared as
+ having a pre-defined absolute segment address, although no linkers
+ are currently known to make sensible use of this feature;
+ nevertheless, NASM allows you to declare a segment such as
+ \code{SEGMENT SCREEN ABSOLUTE=0xB800} if you need to. The
+ \codeindex{ABSOLUTE} and \code{ALIGN} keywords are mutually
+ exclusive.}
+\end{itemize}
+
+NASM's default segment attributes are \code{PUBLIC}, \code{ALIGN=1}, no
+class, no overlay, and \code{USE16}.
+
+\xsubsection{group}{\codeindex{GROUP}: Defining Groups of Segments}
+\index{segments!groups of}
+
+The \code{obj} format also allows segments to be grouped, so that a
+single segment register can be used to refer to all the segments in
+a group. NASM therefore supplies the \code{GROUP} directive, whereby
+you can code
+
+\begin{lstlisting}
+segment data
+ ; some data
+segment bss
+ ; some uninitialized data
+group dgroup data bss
+\end{lstlisting}
+
+which will define a group called \code{dgroup} to contain the segments
+\code{data} and \code{bss}. Like \code{SEGMENT}, \code{GROUP} causes
+the group name to be defined as a symbol, so that you can refer to
+a variable \code{var} in the \code{data} segment as \code{var wrt data}
+or as \code{var wrt dgroup}, depending on which segment value is
+currently in your segment register.
+
+If you just refer to \code{var}, however, and \code{var} is declared
+in a segment which is part of a group, then NASM will default to giving
+you the offset of \code{var} from the beginning of the \emph{group},
+not the \emph{segment}. Therefore \code{SEG var}, also, will return
+the group base rather than the segment base.
+
+NASM will allow a segment to be part of more than one group, but
+will generate a warning if you do this. Variables declared in a
+segment which is part of more than one group will default to being
+relative to the first group that was defined to contain the segment.
+
+A group does not have to contain any segments; you can still make
+\code{WRT} references to a group which does not contain the variable
+you are referring to. OS/2, for example, defines the special group
+\code{FLAT} with no segments in it.
+
+\xsubsection{uppercase}{\codeindex{UPPERCASE}: Disabling Case Sensitivity in Output}
+
+Although NASM itself is \textindex{case sensitive}, some OMF linkers are
+not; therefore it can be useful for NASM to output single-case
+object files. The \code{UPPERCASE} format-specific directive causes all
+segment, group and symbol names that are written to the object file
+to be forced to upper case just before being written. Within a
+source file, NASM is still case-sensitive; but the object file can
+be written entirely in upper case if desired.
+
+\code{UPPERCASE} is used alone on a line; it requires no parameters.
+
+\xsubsection{import}{\codeindex{IMPORT}: Importing DLL Symbols}
+\index{DLL symbols!importing}
+\index{symbols!importing from DLLs}
+
+The \code{IMPORT} format-specific directive defines a symbol to be
+imported from a DLL, for use if you are writing a DLL's
+\textindex{import library} in NASM. You still need to declare the
+symbol as \code{EXTERN} as well as using the \code{IMPORT}
+directive.
+
+The \code{IMPORT} directive takes two required parameters, separated
+by white space, which are (respectively) the name of the symbol you
+wish to import and the name of the library you wish to import it
+from. For example:
+
+\begin{lstlisting}
+import WSAStartup wsock32.dll
+\end{lstlisting}
+
+A third optional parameter gives the name by which the symbol is
+known in the library you are importing it from, in case this is not
+the same as the name you wish the symbol to be known by to your code
+once you have imported it. For example:
+
+\begin{lstlisting}
+import asyncsel wsock32.dll WSAAsyncSelect
+\end{lstlisting}
+
+\xsubsection{export}{\codeindex{EXPORT}: Exporting DLL Symbols}
+\index{DLL symbols!exporting}
+\index{symbols!exporting from DLLs}
+
+The \code{EXPORT} format-specific directive defines a global
+symbol to be exported as a DLL symbol, for use if you are
+writing a DLL in NASM. You still need to declare the symbol
+as \code{GLOBAL} as well as using the \code{EXPORT} directive.
+
+\code{EXPORT} takes one required parameter, which is the name of the
+symbol you wish to export, as it was defined in your source file. An
+optional second parameter (separated by white space from the first)
+gives the \emph{external} name of the symbol: the name by which you
+wish the symbol to be known to programs using the DLL. If this name
+is the same as the internal name, you may leave the second parameter
+off.
+
+Further parameters can be given to define attributes of the exported
+symbol. These parameters, like the second, are separated by white
+space. If further parameters are given, the external name must also
+be specified, even if it is the same as the internal name. The
+available attributes are:
+
+\begin{itemize}
+ \item{\code{resident} indicates that the exported name is
+ to be kept resident by the system loader. This is
+ an optimisation for frequently used symbols imported
+ by name.}
+
+ \item{\code{nodata} indicates that the exported symbol
+ is a function which does not make use of any initialized
+ data.}
+
+ \item{\code{parm=NNN}, where \code{NNN} is an integer, sets
+ the number of parameter words for the case in which
+ the symbol is a call gate between 32-bit and 16-bit
+ segments.}
+
+ \item{An attribute which is just a number indicates that
+ the symbol should be exported with an identifying
+ number (ordinal), and gives the desired number.}
+\end{itemize}
+
+For example:
+
+\begin{lstlisting}
+export myfunc
+export myfunc TheRealMoreFormalLookingFunctionName
+export myfunc myfunc 1234 ; export by ordinal
+export myfunc myfunc resident parm=23 nodata
+\end{lstlisting}
+
+\xsubsection{dotdotstart}{\codeindex{..start}: Defining the \textindexlc{Program Entry Point}}
+
+\code{OMF} linkers require exactly one of the object files being linked to
+define the program entry point, where execution will begin when the
+program is run. If the object file that defines the entry point is
+assembled using NASM, you specify the entry point by declaring the
+special symbol \code{..start} at the point where you wish execution to
+begin.
+
+\xsubsection{objextern}{\code{obj} Extensions to the \code{EXTERN} Directive}
+\index{EXTERN!obj extensions to}
+
+If you declare an external symbol with the directive
+
+\begin{lstlisting}
+extern foo
+\end{lstlisting}
+
+then references such as \code{mov ax,foo} will give you the offset of
+\code{foo} from its preferred segment base (as specified in whichever
+module \code{foo} is actually defined in). So to access the contents of
+\code{foo} you will usually need to do something like
+
+\begin{lstlisting}
+mov ax,seg foo ; get preferred segment base
+mov es,ax ; move it into ES
+mov ax,[es:foo] ; and use offset `foo' from it
+\end{lstlisting}
+
+This is a little unwieldy, particularly if you know that an external
+is going to be accessible from a given segment or group, say
+\code{dgroup}. So if \code{DS} already contained \code{dgroup},
+you could simply code
+
+\begin{lstlisting}
+mov ax,[foo wrt dgroup]
+\end{lstlisting}
+
+However, having to type this every time you want to access \code{foo}
+can be a pain; so NASM allows you to declare \code{foo} in the
+alternative form
+
+\begin{lstlisting}
+extern foo:wrt dgroup
+\end{lstlisting}
+
+This form causes NASM to pretend that the preferred segment base of
+\code{foo} is in fact \code{dgroup}; so the expression \code{seg foo}
+will now return \code{dgroup}, and the expression \code{foo} is
+equivalent to \code{foo wrt dgroup}.
+
+This \index{default-WRT mechanism}default-\code{WRT} mechanism can be used
+to make externals appear to be relative to any group or segment in
+your program. It can also be applied to common variables: see
+\nref{objcommon}.
+
+\xsubsection{objcommon}{\code{obj} Extensions to the \code{COMMON} Directive}
+\index{COMMON!obj extensions to}
+
+The \code{obj} format allows common variables to be either near
+\index{common variables!near} or far\index{common variables!far};
+NASM allows you to specify which your variables should be by the
+use of the syntax
+
+\begin{lstlisting}
+common nearvar 2:near ; nearvar is a near common
+common farvar 10:far ; and farvar is far
+\end{lstlisting}
+
+Far common variables may be greater in size than 64Kb, and so the
+OMF specification says that they are declared as a number of
+\emph{elements} of a given size. So a 10-byte far common variable could
+be declared as ten one-byte elements, five two-byte elements, two
+five-byte elements or one ten-byte element.
+
+Some \code{OMF} linkers require the \index{element size!in common
+variables}\index{common variables!element size}element size, as well as
+the variable size, to match when resolving common variables declared
+in more than one module. Therefore NASM must allow you to specify
+the element size on your far common variables. This is done by the
+following syntax:
+
+\begin{lstlisting}
+common c_5by2 10:far 5 ; two five-byte elements
+common c_2by5 10:far 2 ; five two-byte elements
+\end{lstlisting}
+
+If no element size is specified, the default is 1. Also, the \code{FAR}
+keyword is not required when an element size is specified, since
+only far commons may have element sizes at all. So the above
+declarations could equivalently be
+
+\begin{lstlisting}
+common c_5by2 10:5 ; two five-byte elements
+common c_2by5 10:2 ; five two-byte elements
+\end{lstlisting}
+
+In addition to these extensions, the \code{COMMON} directive
+in \code{obj} also supports default-\code{WRT} specification
+like \code{EXTERN} does (explained in \nref{objextern}).
+So you can also declare things like
+
+\begin{lstlisting}
+common foo 10:wrt dgroup
+common bar 16:far 2:wrt data
+common baz 24:wrt data:6
+\end{lstlisting}
+
+\xsubsection{objdepend}{Embedded File Dependency Information}
+
+Since NASM 2.13.02, \code{obj} files contain embedded dependency file
+information. To suppress the generation of dependencies, use
+
+\begin{lstlisting}
+%pragma obj nodepend
+\end{lstlisting}
+
+\xsection{win32fmt}{\codeindex{win32}: Microsoft Win32 Object Files}
+
+The \code{win32} output format generates Microsoft Win32 object files,
+suitable for passing to Microsoft linkers such as \emph{Visual C++}.
+Note that Borland Win32 compilers do not use this format, but use
+\code{obj} instead (see \nref{objfmt}).
+
+\code{win32} provides a default output file-name extension of \code{.obj}.
+
+Note that although Microsoft say that Win32 object files follow the
+COFF (Common Object File Format) standard, the object files produced
+by Microsoft Win32 compilers are not compatible with COFF linkers such
+as DJGPP's, and vice versa. This is due to a difference of opinion over
+the precise semantics of PC-relative relocations. To produce COFF files
+suitable for DJGPP, use NASM's \code{coff} output format; conversely,
+the \code{coff} format does not produce object files that Win32 linkers
+can generate correct output from.
+
+\xsubsection{win32sect}{\code{win32} Extensions to the \code{SECTION} Directive}
+\index{SECTION!win32 extensions to}
+
+Like the \code{obj} format, \code{win32} allows you to specify additional
+information on the \code{SECTION} directive line, to control the type
+and properties of sections you declare. Section types and properties
+are generated automatically by NASM for the \textindex{standard section names}
+\code{.text}, \code{.data} and \code{.bss}, but may still be overridden by
+these qualifiers.
+
+The available qualifiers are:
+
+\begin{itemize}
+ \item{\code{code}, or equivalently \code{text}, defines the section
+ to be a code section. This marks the section as readable and
+ executable, but not writable, and also indicates to the linker
+ that the type of the section is code.}
+
+ \item{\code{data} and \code{bss} define the section to be a data
+ section, analogously to \code{code}. Data sections are marked
+ as readable and writable, but not executable. \code{data}
+ declares an initialized data section, whereas \code{bss} declares
+ an uninitialized data section.}
+
+ \item{\code{rdata} declares an initialized data section that is
+ readable but not writable. Microsoft compilers use this section
+ to place constants in it.}
+
+ \item{\code{info} defines the section to be an \textindex{informational section},
+ which is not included in the executable file by the linker, but may
+ (for example) pass information \emph{to} the linker. For example,
+ declaring an \code{info}-type section called \codeindex{.drectve} causes
+ the linker to interpret the contents of the section as command-line
+ options.}
+
+ \item{\code{align=}, used with a trailing number as in \code{obj}, gives the
+ \index{section alignment!in win32} \index{alignment!in win32 sections}
+ alignment requirements of the section. The maximum you may
+ specify is 64: the Win32 object file format contains no means to
+ request a greater section alignment than this. If alignment is not
+ explicitly specified, the defaults are 16-byte alignment for code
+ sections, 8-byte alignment for rdata sections and 4-byte alignment
+ for data (and BSS) sections.
+ Informational sections get a default alignment of 1 byte (no
+ alignment), though the value does not matter.}
+\end{itemize}
+
+The defaults assumed by NASM if you do not specify the above
+qualifiers are:
+
+\begin{lstlisting}
+section .text code align=16
+section .data data align=4
+section .rdata rdata align=8
+section .bss bss align=4
+\end{lstlisting}
+
+Any other section name is treated by default like \code{.text}.
+
+\xsubsection{win32safeseh}{\code{win32} Safe Structured Exception Handling}
+
+Among other improvements in Windows XP SP2 and Windows Server 2003
+Microsoft has introduced concept of "safe structured exception
+handling." General idea is to collect handlers' entry points in
+designated read-only table and have alleged entry point verified
+against this table prior exception control is passed to the handler. In
+order for an executable module to be equipped with such "safe exception
+handler table," all object modules on linker command line has to comply
+with certain criteria. If one single module among them does not, then
+the table in question is omitted and above mentioned run-time checks
+will not be performed for application in question. Table omission is by
+default silent and therefore can be easily overlooked. One can instruct
+linker to refuse to produce binary without such table by passing
+\code{/safeseh} command line option.
+
+Without regard to this run-time check merits it's natural to expect
+NASM to be capable of generating modules suitable for \code{/safeseh}
+linking. From developer's viewpoint the problem is two-fold:
+
+\begin{itemize}
+ \item{how to adapt modules not deploying exception handlers of their own;}
+ \item{how to adapt/develop modules utilizing custom exception handling.}
+\end{itemize}
+
+Former can be easily achieved with any NASM version by adding following
+line to source code:
+
+\begin{lstlisting}
+$@feat.00 equ 1
+\end{lstlisting}
+
+As of version 2.03 NASM adds this absolute symbol automatically. If
+it's not already present to be precise. I.e. if for whatever reason
+developer would choose to assign another value in source file, it would
+still be perfectly possible.
+
+Registering custom exception handler on the other hand requires certain
+"magic." As of version 2.03 additional directive is implemented,
+\code{safeseh}, which instructs the assembler to produce appropriately
+formatted input data for above mentioned "safe exception handler
+table." Its typical use would be:
+
+\begin{lstlisting}
+section .text
+extern _MessageBoxA@16
+%if __NASM_VERSION_ID__ >= 0x02030000
+safeseh handler ; register handler as "safe handler"
+%endif
+handler:
+ push DWORD 1 ; MB_OKCANCEL
+ push DWORD caption
+ push DWORD text
+ push DWORD 0
+ call _MessageBoxA@16
+ sub eax,1 ; incidentally suits as return value
+ ; for exception handler
+ ret
+global _main
+_main:
+ push DWORD handler
+ push DWORD [fs:0]
+ mov DWORD [fs:0],esp ; engage exception handler
+ xor eax,eax
+ mov eax,DWORD[eax] ; cause exception
+ pop DWORD [fs:0] ; disengage exception handler
+ add esp,4
+ ret
+text: db 'OK to rethrow, CANCEL to generate core dump',0
+caption:db 'SEGV',0
+
+section .drectve info
+ db '/defaultlib:user32.lib /defaultlib:msvcrt.lib '
+\end{lstlisting}
+
+As you might imagine, it's perfectly possible to produce .exe binary
+with "safe exception handler table" and yet engage unregistered
+exception handler. Indeed, handler is engaged by simply manipulating
+\code{[fs:0]} location at run-time, something linker has no power over,
+run-time that is. It should be explicitly mentioned that such failure
+to register handler's entry point with \code{safeseh} directive has
+undesired side effect at run-time. If exception is raised and
+unregistered handler is to be executed, the application is abruptly
+terminated without any notification whatsoever. One can argue that
+system could at least have logged some kind "non-safe exception
+handler in x.exe at address n" message in event log, but no, literally
+no notification is provided and user is left with no clue on what
+caused application failure.
+
+Finally, all mentions of linker in this paragraph refer to Microsoft
+linker version 7.x and later. Presence of \code{@feat.00} symbol and input
+data for "safe exception handler table" causes no backward
+incompatibilities and "safeseh" modules generated by NASM 2.03 and
+later can still be linked by earlier versions or non-Microsoft linkers.
+
+\xsubsection{codeview}{Debugging formats for Windows}
+\index{Windows debugging formats}
+
+The \code{win32} and \code{win64} formats support the Microsoft CodeView
+debugging format. Currently CodeView version 8 format is supported
+(\codeindex{cv8}), but newer versions of the CodeView debugger should be
+able to handle this format as well.
+
+\xsection{win64fmt}{\codeindex{win64}: Microsoft Win64 Object Files}
+
+The \code{win64} output format generates Microsoft Win64 object files,
+which is nearly 100\% identical to the \code{win32} object format
+(\nref{win32fmt}) with the exception that it is meant to target
+64-bit code and the x86-64 platform altogether. This object file is used
+exactly the same as the \code{win32} object format, in NASM, with regard to this exception.
+
+\xsubsection{win64pic}{\code{win64}: Writing Position-Independent Code}
+
+While \code{REL} takes good care of RIP-relative addressing, there is one
+aspect that is easy to overlook for a Win64 programmer: indirect
+references. Consider a switch dispatch table:
+
+\begin{lstlisting}
+ jmp qword [dsptch+rax*8]
+ ...
+dsptch: dq case0
+ dq case1
+ ...
+\end{lstlisting}
+
+Even a novice Win64 assembler programmer will soon realize that the code
+is not 64-bit savvy. Most notably linker will refuse to link it with
+
+\begin{lstlisting}
+'ADDR32' relocation to '.text' invalid without /LARGEADDRESSAWARE:NO
+\end{lstlisting}
+
+So [s]he will have to split jmp instruction as following:
+
+\begin{lstlisting}
+ lea rbx,[rel dsptch]
+ jmp qword [rbx+rax*8]
+\end{lstlisting}
+
+What happens behind the scene is that effective address in \code{lea} is
+encoded relative to instruction pointer, or in perfectly position-independent
+manner. But this is only part of the problem! Trouble is that in .dll context
+\code{caseN} relocations will make their way to the final module and might
+have to be adjusted at .dll load time. To be specific when it can't be loaded
+at preferred address. And when this occurs, pages with such relocations will
+be rendered private to current process, which kind of undermines the idea
+of sharing .dll. But no worry, it's trivial to fix:
+
+\begin{lstlisting}
+ lea rbx,[rel dsptch]
+ add rbx,[rbx+rax*8]
+ jmp rbx
+ ...
+dsptch: dq case0-dsptch
+ dq case1-dsptch
+ ...
+\end{lstlisting}
+
+NASM version 2.03 and later provides another alternative, \code{wrt
+..imagebase} operator, which returns offset from base address of the
+current image, be it .exe or .dll module, therefore the name. For those
+acquainted with PE-COFF format base address denotes start of
+\code{IMAGE\_DOS\_HEADER} structure. Here is how to implement switch with
+these image-relative references:
+
+\begin{lstlisting}
+ lea rbx,[rel dsptch]
+ mov eax,[rbx+rax*4]
+ sub rbx,dsptch wrt ..imagebase
+ add rbx,rax
+ jmp rbx
+ ...
+dsptch: dd case0 wrt ..imagebase
+ dd case1 wrt ..imagebase
+\end{lstlisting}
+
+One can argue that the operator is redundant. Indeed, snippet before
+last works just fine with any NASM version and is not even Windows
+specific... The real reason for implementing \code{wrt ..imagebase} will
+become apparent in next paragraph.
+
+It should be noted that \code{wrt ..imagebase} is defined as 32-bit
+operand only:
+
+\begin{lstlisting}
+dd label wrt ..imagebase ; ok
+dq label wrt ..imagebase ; bad
+mov eax,label wrt ..imagebase ; ok
+mov rax,label wrt ..imagebase ; bad
+\end{lstlisting}
+
+\xsubsection{win64seh}{\code{win64}: Structured Exception Handling}
+
+Structured exception handing in Win64 is completely different matter
+from Win32. Upon exception program counter value is noted, and
+linker-generated table comprising start and end addresses of all the
+functions [in given executable module] is traversed and compared to the
+saved program counter. Thus so called \code{UNWIND\_INFO} structure is
+identified. If it's not found, then offending subroutine is assumed to
+be "leaf" and just mentioned lookup procedure is attempted for its
+caller. In Win64 leaf function is such function that does not call any
+other function \emph{nor} modifies any Win64 non-volatile registers,
+including stack pointer. The latter ensures that it's possible to
+identify leaf function's caller by simply pulling the value from the
+top of the stack.
+
+While majority of subroutines written in assembler are not calling any
+other function, requirement for non-volatile registers' immutability
+leaves developer with not more than 7 registers and no stack frame,
+which is not necessarily what [s]he counted with. Customarily one would
+meet the requirement by saving non-volatile registers on stack and
+restoring them upon return, so what can go wrong? If [and only if] an
+exception is raised at run-time and no \code{UNWIND\_INFO} structure is
+associated with such "leaf" function, the stack unwind procedure will
+expect to find caller's return address on the top of stack immediately
+followed by its frame. Given that developer pushed caller's
+non-volatile registers on stack, would the value on top point at some
+code segment or even addressable space? Well, developer can attempt
+copying caller's return address to the top of stack and this would
+actually work in some very specific circumstances. But unless developer
+can guarantee that these circumstances are always met, it's more
+appropriate to assume worst case scenario, i.e. stack unwind procedure
+going berserk. Relevant question is what happens then? Application is
+abruptly terminated without any notification whatsoever. Just like in
+Win32 case, one can argue that system could at least have logged
+"unwind procedure went berserk in x.exe at address n" in event log, but
+no, no trace of failure is left.
+
+Now, when we understand significance of the \code{UNWIND\_INFO} structure,
+let's discuss what's in it and/or how it's processed. First of all it
+is checked for presence of reference to custom language-specific
+exception handler. If there is one, then it's invoked. Depending on the
+return value, execution flow is resumed (exception is said to be
+"handled"), \emph{or} rest of \code{UNWIND\_INFO} structure is processed as
+following. Beside optional reference to custom handler, it carries
+information about current callee's stack frame and where non-volatile
+registers are saved. Information is detailed enough to be able to
+reconstruct contents of caller's non-volatile registers upon call to
+current callee. And so caller's context is reconstructed, and then
+unwind procedure is repeated, i.e. another \code{UNWIND\_INFO} structure is
+associated, this time, with caller's instruction pointer, which is then
+checked for presence of reference to language-specific handler, etc.
+The procedure is recursively repeated till exception is handled. As
+last resort system "handles" it by generating memory core dump and
+terminating the application.
+
+As for the moment of this writing NASM unfortunately does not
+facilitate generation of above mentioned detailed information about
+stack frame layout. But as of version 2.03 it implements building
+blocks for generating structures involved in stack unwinding. As
+simplest example, here is how to deploy custom exception handler for
+leaf function:
+
+\begin{lstlisting}
+default rel
+section .text
+extern MessageBoxA
+handler:
+ sub rsp,40
+ mov rcx,0
+ lea rdx,[text]
+ lea r8,[caption]
+ mov r9,1 ; MB_OKCANCEL
+ call MessageBoxA
+ sub eax,1 ; incidentally suits as return value
+ ; for exception handler
+ add rsp,40
+ ret
+global main
+main:
+ xor rax,rax
+ mov rax,QWORD[rax] ; cause exception
+ ret
+main_end:
+text: db 'OK to rethrow, CANCEL to generate core dump',0
+caption:db 'SEGV',0
+
+section .pdata rdata align=4
+ dd main wrt ..imagebase
+ dd main_end wrt ..imagebase
+ dd xmain wrt ..imagebase
+section .xdata rdata align=8
+xmain: db 9,0,0,0
+ dd handler wrt ..imagebase
+section .drectve info
+ db '/defaultlib:user32.lib /defaultlib:msvcrt.lib '
+\end{lstlisting}
+
+What you see in \code{.pdata} section is element of the "table comprising
+start and end addresses of function" along with reference to associated
+\code{UNWIND\_INFO} structure. And what you see in \code{.xdata} section is
+\code{UNWIND\_INFO} structure describing function with no frame, but with
+designated exception handler. References are \emph{required} to be
+image-relative (which is the real reason for implementing \code{wrt
+..imagebase} operator). It should be noted that \code{rdata align=n}, as
+well as \code{wrt ..imagebase}, are optional in these two segments'
+contexts, i.e. can be omitted. Latter means that \emph{all} 32-bit
+references, not only above listed required ones, placed into these two
+segments turn out image-relative. Why is it important to understand?
+Developer is allowed to append handler-specific data to \code{UNWIND\_INFO}
+structure, and if [s]he adds a 32-bit reference, then [s]he will have
+to remember to adjust its value to obtain the real pointer.
+
+As already mentioned, in Win64 terms leaf function is one that does not
+call any other function \emph{nor} modifies any non-volatile register,
+including stack pointer. But it's not uncommon that assembler
+programmer plans to utilize every single register and sometimes even
+have variable stack frame. Is there anything one can do with bare
+building blocks? I.e. besides manually composing fully-fledged
+\code{UNWIND\_INFO} structure, which would surely be considered
+error-prone? Yes, there is. Recall that exception handler is called
+first, before stack layout is analyzed. As it turned out, it's
+perfectly possible to manipulate current callee's context in custom
+handler in manner that permits further stack unwinding. General idea is
+that handler would not actually "handle" the exception, but instead
+restore callee's context, as it was at its entry point and thus mimic
+leaf function. In other words, handler would simply undertake part of
+unwinding procedure. Consider following example:
+
+\begin{lstlisting}
+function:
+ mov rax,rsp ; copy rsp to volatile register
+ push r15 ; save non-volatile registers
+ push rbx
+ push rbp
+ mov r11,rsp ; prepare variable stack frame
+ sub r11,rcx
+ and r11,-64
+ mov QWORD[r11],rax ; check for exceptions
+ mov rsp,r11 ; allocate stack frame
+ mov QWORD[rsp],rax ; save original rsp value
+magic_point:
+ ...
+ mov r11,QWORD[rsp] ; pull original rsp value
+ mov rbp,QWORD[r11-24]
+ mov rbx,QWORD[r11-16]
+ mov r15,QWORD[r11-8]
+ mov rsp,r11 ; destroy frame
+ ret
+\end{lstlisting}
+
+The keyword is that up to \code{magic\_point} original \code{rsp} value
+remains in chosen volatile register and no non-volatile register,
+except for \code{rsp}, is modified. While past \code{magic\_point}
+\code{rsp} remains constant till the very end of the \code{function}.
+In this case custom language-specific exception handler would look like this:
+
+\begin{lstlisting}
+EXCEPTION_DISPOSITION
+handler(EXCEPTION_RECORD *rec, ULONG64 frame,
+ CONTEXT *context, DISPATCHER_CONTEXT *disp)
+{
+ ULONG64 *rsp;
+
+ if (context->Rip < (ULONG64)magic_point)
+ rsp = (ULONG64 *)context->Rax;
+ else {
+ rsp = ((ULONG64 **)context->Rsp)[0];
+ context->Rbp = rsp[-3];
+ context->Rbx = rsp[-2];
+ context->R15 = rsp[-1];
+ }
+ context->Rsp = (ULONG64)rsp;
+
+ memcpy(disp->ContextRecord, context, sizeof(CONTEXT));
+ RtlVirtualUnwind(UNW_FLAG_NHANDLER, disp->ImageBase,
+ dips->ControlPc, disp->FunctionEntry,
+ disp->ContextRecord,
+ &disp->HandlerData,
+ &disp->EstablisherFrame,
+ NULL);
+
+ return ExceptionContinueSearch;
+}
+\end{lstlisting}
+
+As custom handler mimics leaf function, corresponding \code{UNWIND\_INFO}
+structure does not have to contain any information about stack frame
+and its layout.
+
+\xsection{cofffmt}{\codeindex{coff}: \textindexlc{Common Object File Format}}
+
+The \code{coff} output type produces \code{COFF} object files suitable for
+linking with the \textindex{DJGPP} linker.
+
+\code{coff} provides a default output file-name extension of \code{.o}.
+
+The \code{coff} format supports the same extensions to the \code{SECTION}
+directive as \code{win32} does, except that the \code{align} qualifier and
+the \code{info} section type are not supported.
+
+\xsection{machofmt}{\codeindex{macho32} and \codeindex{macho64}:
+\textindexlc{Mach Object File Format}}
+\index{Mach-O}
+
+The \code{macho32}, \code{macho64} output formts produces Mach-O
+object files suitable for linking with the \textindex{MacOS X} linker.
+\codeindex{macho} is a synonym for \code{macho32}.
+
+\code{macho} provides a default output file-name extension of \code{.o}.
+
+\xsubsection{machosect}{\code{macho} extensions to the \code{SECTION} Directive}
+\index{SECTION!macho extensions to}
+
+The \code{macho} output format specifies section names in the format
+"\emph{segment}\code{,}\emph{section}". No spaces are allowed around the
+comma. The following flags can also be specified:
+
+\begin{itemize}
+ \item{\code{data} - this section contains initialized data items}
+ \item{\code{code} - this section contains code exclusively}
+ \item{\code{mixed} - this section contains both code and data}
+ \item{\code{bss} - this section is uninitialized and filled with zero}
+ \item{\code{zerofill} - same as \code{bss}}
+ \item{\code{no\_dead\_strip} - inhibit dead code stripping for this section}
+ \item{\code{live\_support} - set the live support flag for this section}
+ \item{\code{strip\_static\_syms} - strip static symbols for this section}
+ \item{\code{debug} - this section contains debugging information}
+ \item{\code{align=}\emph{alignment} - specify section alignment}
+\end{itemize}
+
+The default is \code{data}, unless the section name is \code{\_\_text} or
+\code{\_\_bss} in which case the default is \code{text} or \code{bss},
+respectively.
+
+For compatibility with other Unix platforms, the following standard
+names are also supported:
+
+\begin{lstlisting}
+.text = __TEXT,__text text
+.rodata = __DATA,__const data
+.data = __DATA,__data data
+.bss = __DATA,__bss bss
+\end{lstlisting}
+
+If the \code{.rodata} section contains no relocations, it is instead put
+into the \code{\_\_TEXT,\_\_const} section unless this section has already
+been specified explicitly. However, it is probably better to specify
+\code{\_\_TEXT,\_\_const} and \code{\_\_DATA,\_\_const} explicitly as appropriate.
+
+\xsubsection{machotls}{\textindexlc{Thread Local Storage in Mach-O}\index{TLS}:
+\code{macho} special symbols and \codeindex{WRT}}
+
+Mach-O defines the following special symbols that can be used on the
+right-hand side of the \code{WRT} operator:
+
+\begin{itemize}
+ \item{\code{..tlvp} is used to specify access to thread-local storage.}
+ \item{\code{..gotpcrel} is used to specify references to the Global Offset Table.
+ The GOT is supported in the \code{macho64} format only.}
+\end{itemize}
+
+\xsubsection{macho-ssvs}{\code{macho} specfic directive
+\codeindex{subsections\_via\_symbols}}
+
+The directive \code{subsections\_via\_symbols} sets the
+\code{MH\_SUBSECTIONS\_VIA\_SYMBOLS} flag in the Mach-O header,
+that effectively separates a block (or a subsection) based on a symbol.
+It is often used for eliminating dead codes by a linker.
+
+This directive takes no arguments.
+
+This is a macro implemented as a \code{\%pragma}. It can also be
+specified in its \code{\%pragma} form, in which case it will not affect
+non-Mach-O builds of the same source code:
+
+\begin{lstlisting}
+%pragma macho subsections_via_symbols
+\end{lstlisting}
+
+\xsubsection{macho-snds}{\code{macho} specfic directive \codeindex{no\_dead\_strip}}
+
+The directive \code{no\_dead\_strip} sets the Mach-O \code{SH\_NO\_DEAD\_STRIP}
+section flag on the section containing a a specific symbol. This directive takes
+a list of symbols as its arguments.
+
+This is a macro implemented as a \code{\%pragma}. It can also be
+specified in its \code{\%pragma} form, in which case it will not affect
+non-Mach-O builds of the same source code:
+
+\begin{lstlisting}
+%pragma macho no_dead_strip symbol...
+\end{lstlisting}
+
+\xsubsection{macho-pext}{\code{macho} specific extensions to the
+\code{GLOBAL} Directive: \codeindex{private\_extern}}
+
+The directive extension to \code{GLOBAL} marks the symbol with limited
+global scope. For example, you can specify the global symbol with
+this extension:
+
+\begin{lstlisting}
+global foo:private_extern
+foo:
+ ; codes
+\end{lstlisting}
+
+Using with static linker will clear the private extern attribute.
+But linker option like \code{-keep\_private\_externs} can avoid it.
+
+\xsection{elffmt}{\codeindex{elf32}, \codeindex{elf64}, \codeindex{elfx32}:
+\textindexlc{Executable and Linkable Format} Object Files}
+\index{ELF}\index{linux!elf}
+
+The \code{elf32}, \code{elf64} and \code{elfx32} output formats generate
+\code{ELF32} and \code{ELF64} (Executable and Linkable Format) object files,
+as used by Linux as well as \textindex{Unix System V}, including
+\textindex{Solaris x86}, \textindex{UnixWare} and \textindex{SCO Unix}.
+\code{elf} provides a default output file-name extension of \code{.o}.
+\code{elf} is a synonym for \code{elf32}.
+
+The \code{elfx32} format is used for the \textindex{x32} ABI, which is
+a 32-bit ABI with the CPU in 64-bit mode.
+
+\xsubsection{abisect}{ELF specific directive \codeindex{osabi}}
+
+The ELF header specifies the application binary interface for the
+target operating system (OSABI). This field can be set by using the
+\code{osabi} directive with the numeric value (0-255) of the target
+system. If this directive is not used, the default value will be "UNIX
+System V ABI" (0) which will work on most systems which support ELF.
+
+\xsubsection{elfsect}{\code{elf} extensions to the \code{SECTION} Directive}
+\index{SECTION!elf extensions to}
+
+Like the \code{obj} format, \code{elf} allows you to specify additional
+information on the \code{SECTION} directive line, to control the type
+and properties of sections you declare. Section types and properties
+are generated automatically by NASM for the \textindexlc{standard section
+names}, but may still be overridden by these qualifiers.
+
+The available qualifiers are:
+
+\begin{itemize}
+ \item{\codeindex{alloc} defines the section to be one which is loaded into
+ memory when the program is run. \codeindex{noalloc} defines it to be one
+ which is not, such as an informational or comment section.}
+
+ \item{\codeindex{exec} defines the section to be one which should have execute
+ permission when the program is run. \codeindex{noexec} defines it as one
+ which should not.}
+
+ \item{\codeindex{write} defines the section to be one which should be writable
+ when the program is run. \codeindex{nowrite} defines it as one which should
+ not.}
+
+ \item{\codeindex{progbits} defines the section to be one with explicit contents
+ stored in the object file: an ordinary code or data section, for
+ example, \codeindex{nobits} defines the section to be one with no explicit
+ contents given, such as a BSS section.}
+
+ \item{\code{align=}, used with a trailing number as in \code{obj}, gives the
+ \index{section alignment!in elf}\index{alignment!in elf sections}alignment
+ requirements of the section.}
+
+ \item{\codeindex{tls} defines the section to be one which contains
+ thread local variables.}
+\end{itemize}
+
+The defaults assumed by NASM if you do not specify the above
+qualifiers are:
+\indexcode{.text} \indexcode{.rodata} \indexcode{.lrodata}
+\indexcode{.data} \indexcode{.ldata} \indexcode{.bss}
+\indexcode{.lbss} \indexcode{.tdata} \indexcode{.tbss}
+\indexcode{.comment}
+
+\begin{lstlisting}
+section .text progbits alloc exec nowrite align=16
+section .rodata progbits alloc noexec nowrite align=4
+section .lrodata progbits alloc noexec nowrite align=4
+section .data progbits alloc noexec write align=4
+section .ldata progbits alloc noexec write align=4
+section .bss nobits alloc noexec write align=4
+section .lbss nobits alloc noexec write align=4
+section .tdata progbits alloc noexec write align=4 tls
+section .tbss nobits alloc noexec write align=4 tls
+section .comment progbits noalloc noexec nowrite align=1
+section other progbits alloc noexec nowrite align=1
+\end{lstlisting}
+
+(Any section name other than those in the above table is treated by
+default like \code{other} in the above. Please note that section
+names are case sensitive.)
+
+\xsubsection{elfwrt}{\textindexlc{Position-Independent Code}: \code{elf}
+Special Symbols and \codeindex{WRT}}
+\index{PIC}
+
+Since \code{ELF} does not support segment-base references, the \code{WRT}
+operator is not used for its normal purpose; therefore NASM's \code{elf}
+output format makes use of \code{WRT} for a different purpose, namely the
+PIC-specific \index{relocations!PIC-specific}relocation types.
+
+\code{elf} defines five special symbols which you can use as the
+right-hand side of the \code{WRT} operator to obtain PIC relocation
+types. They are \codeindex{..gotpc}, \codeindex{..gotoff}, \codeindex{..got},
+\codeindex{..plt} and \codeindex{..sym}. Their functions are summarized here:
+
+\begin{itemize}
+ \item{Referring to the symbol marking the global offset table base
+ using \code{wrt ..gotpc} will end up giving the distance from the
+ beginning of the current section to the global offset table.
+ (\codeindex{\_GLOBAL\_OFFSET\_TABLE\_} is the standard symbol name
+ used to refer to the \textindex{GOT}.) So you would then need to add
+ \codeindex{\$\$} to the result to get the real address of the GOT.}
+
+ \item{Referring to a location in one of your own sections using
+ \code{wrt ..gotoff} will give the distance from the beginning of
+ the GOT to the specified location, so that adding on the address
+ of the GOT would give the real address of the location you wanted.}
+
+ \item{Referring to an external or global symbol using \code{wrt ..got}
+ causes the linker to build an entry \emph{in} the GOT containing the
+ address of the symbol, and the reference gives the distance from the
+ beginning of the GOT to the entry; so you can add on the address of
+ the GOT, load from the resulting address, and end up with the
+ address of the symbol.}
+
+ \item{Referring to a procedure name using \code{wrt ..plt} causes the
+ linker to build a \textindex{procedure linkage table} entry for the symbol,
+ and the reference gives the address of the \textindex{PLT} entry. You can
+ only use this in contexts which would generate a PC-relative
+ relocation normally (i.e. as the destination for \code{CALL} or
+ \code{JMP}), since ELF contains no relocation type to refer to PLT
+ entries absolutely.}
+
+ \item{Referring to a symbol name using \code{wrt ..sym} causes NASM to
+ write an ordinary relocation, but instead of making the relocation
+ relative to the start of the section and then adding on the offset
+ to the symbol, it will write a relocation record aimed directly at
+ the symbol in question. The distinction is a necessary one due to a
+ peculiarity of the dynamic linker.}
+\end{itemize}
+
+A fuller explanation of how to use these relocation types to write
+shared libraries entirely in NASM is given in \nref{picdll}.
+
+\xsubsection{elftls}{\textindexlc{Thread Local Storage in ELF}:
+\code{elf} Special Symbols and \codeindex{WRT}}
+\index{TLS}
+
+In ELF32 mode, referring to an external or global symbol using
+\code{wrt ..tlsie}\indexcode{..tlsie} causes the linker to build
+an entry \emph{in} the GOT containing the
+offset of the symbol within the TLS block, so you can access the value
+of the symbol with code such as:
+
+\begin{lstlisting}
+mov eax,[tid wrt ..tlsie]
+mov [gs:eax],ebx
+\end{lstlisting}
+
+In ELF64 or ELFx32 mode, referring to an external or global symbol using
+\code{wrt ..gottpoff}\indexcode{..gottpoff} causes the linker to build an
+entry \emph{in} the GOT containing the offset of the symbol within the TLS
+block, so you can access the value of the symbol with code such as:
+
+\begin{lstlisting}
+mov rax,[rel tid wrt ..gottpoff]
+mov rcx,[fs:rax]
+\end{lstlisting}
+
+\xsubsection{elfglob}{\code{elf} Extensions to the \code{GLOBAL} Directive}
+\index{GLOBAL!elf extensions to}
+
+\code{ELF} object files can contain more information about a global symbol
+than just its address: they can contain the \index{symbol sizes!specifying}
+\index{size!of symbols}size of the symbol and its \index{symbol types!specifying}
+\index{type!of symbols}type as well. These are not merely debugger conveniences,
+but are actually necessary when the program being written is a
+\textindexlc{shared library}. NASM therefore supports some extensions to the
+\code{GLOBAL} directive, allowing you to specify these features.
+
+You can specify whether a global variable is a function or a data
+object by suffixing the name with a colon and the word
+\codeindex{function} or \codeindex{data}. (\codeindex{object} is
+a synonym for \code{data}.) For example:
+
+\begin{lstlisting}
+global hashlookup:function, hashtable:data
+\end{lstlisting}
+
+exports the global symbol \code{hashlookup} as a function and
+\code{hashtable} as a data object.
+
+Optionally, you can control the ELF visibility of the symbol. Just
+add one of the visibility keywords: \codeindex{default},
+\codeindex{internal}, \codeindex{hidden}, or \codeindex{protected}.
+The default is \code{default} of course. For example, to make
+\code{hashlookup} hidden:
+
+\begin{lstlisting}
+global hashlookup:function hidden
+\end{lstlisting}
+
+You can also specify the size of the data associated with the
+symbol, as a numeric expression (which may involve labels, and even
+forward references) after the type specifier. Like this:
+
+\begin{lstlisting}
+global hashtable:data (hashtable.end - hashtable)
+
+hashtable:
+ db this,that,theother ; some data here
+.end:
+\end{lstlisting}
+
+This makes NASM automatically calculate the length of the table and
+place that information into the \code{ELF} symbol table.
+
+Declaring the type and size of global symbols is necessary when
+writing shared library code. For more information, see
+\nref{picglobal}.
+
+\xsubsection{elfcomm}{\code{elf} Extensions to the \code{COMMON} Directive}
+\index{COMMON!elf extensions to}
+
+\code{ELF} also allows you to specify alignment requirements
+\index{common variables!alignment in elf}
+\index{alignment!of elf common variables} on common variables.
+This is done by putting a number (which must be a power of two)
+after the name and size of the common variable, separated (as usual)
+by a colon. For example, an array of doublewords would benefit from
+4-byte alignment:
+
+\begin{lstlisting}
+common dwordarray 128:4
+\end{lstlisting}
+
+This declares the total size of the array to be 128 bytes, and
+requires that it be aligned on a 4-byte boundary.
+
+\xsubsection{elf16}{16-bit code and ELF}
+\index{ELF!16-bit code and}
+
+The \code{ELF32} specification doesn't provide relocations for 8- and
+16-bit values, but the GNU \code{ld} linker adds these as an extension.
+NASM can generate GNU-compatible relocations, to allow 16-bit code to
+be linked as ELF using GNU \code{ld}. If NASM is used with the
+\code{-w+gnu-elf-extensions} option, a warning is issued when one of
+these relocations is generated.
+
+\xsubsection{elfdbg}{Debug formats and ELF}
+\index{ELF!Debug formats}
+
+ELF provides debug information in \code{STABS} and \code{DWARF} formats.
+Line number information is generated for all executable sections, but please
+note that only the ".text" section is executable by default.
+
+\xsection{aoutfmt}{\codeindex{aout}: Linux \code{a.out} Object Files}
+\index{a.out!Linux version}
+\index{linux!a.out}
+
+The \code{aout} format generates \code{a.out} object files, in the
+form used by early Linux systems (current Linux systems use ELF, see
+\nref{elffmt}.) These differ from other \code{a.out} object
+files in that the magic number in the first four bytes of the file is
+different; also, some implementations of \code{a.out}, for example
+NetBSD's, support position-independent code, which Linux's
+implementation does not.
+
+\code{a.out} provides a default output file-name extension of \code{.o}.
+
+\code{a.out} is a very simple object format. It supports no special
+directives, no special symbols, no use of \code{SEG} or \code{WRT}, and no
+extensions to any standard directives. It supports only the three
+\textindexlc{standard section names} \codeindex{.text}, \codeindex{.data}
+and \codeindex{.bss}.
+
+\xsection{aoutbfmt}{\codeindex{aoutb}: \textindex{NetBSD}/\textindex{FreeBSD}/\textindex{OpenBSD}
+\code{a.out} Object Files}
+\index{a.out!BSD version}
+
+The \code{aoutb} format generates \code{a.out} object files, in the form
+used by the various free \code{BSD Unix} clones, \code{NetBSD}, \code{FreeBSD}
+and \code{OpenBSD}. For simple object files, this object format is exactly
+the same as \code{aout} except for the magic number in the first four bytes
+of the file. However, the \code{aoutb} format supports
+\index{PIC}\textindexlc{position-independent code} in the same way as the
+\code{elf} format, so you can use it to write \code{BSD}
+\textindexlc{shared libraries}.
+
+\code{aoutb} provides a default output file-name extension of \code{.o}.
+
+\code{aoutb} supports no special directives, no special symbols, and
+only the three \textindexlc{standard section names} \codeindex{.text},
+\codeindex{.data} and \codeindex{.bss}. However, it also supports the same
+use of \codeindex{WRT} as \code{elf} does, to provide position-independent
+code relocation types. See \nref{elfwrt} for full documentation
+of this feature.
+
+\code{aoutb} also supports the same extensions to the \code{GLOBAL}
+directive as \code{elf} does: see \nref{elfglob} for
+documentation of this.
+
+\xsection{as86fmt}{\code{as86}: \textindex{Minix}/Linux \codeindex{as86} Object Files}
+\index{linux!as86}
+
+The Minix/Linux 16-bit assembler \code{as86} has its own non-standard
+object file format. Although its companion linker \codeindex{ld86}
+produces something close to ordinary \code{a.out} binaries as output,
+the object file format used to communicate between \code{as86} and
+\code{ld86} is not itself \code{a.out}.
+
+NASM supports this format, just in case it is useful, as \code{as86}.
+\code{as86} provides a default output file-name extension of \code{.o}.
+
+\code{as86} is a very simple object format (from the NASM user's point
+of view). It supports no special directives, no use of \code{SEG} or
+\code{WRT}, and no extensions to any standard directives. It supports
+only the three \textindexlc{standard section names} \codeindex{.text},
+\codeindex{.data} and \codeindex{.bss}. The only special symbol supported
+is \code{..start}.
+
+\xsection{rdffmt}{\index{RDOFF}\codeindex{rdf}: \textindexlc{Relocatable Dynamic
+Object File Format}}
+
+The \code{rdf} output format produces \code{RDOFF} object files.
+\code{RDOFF} (Relocatable Dynamic Object File Format) is a home-grown
+object-file format, designed alongside NASM itself and reflecting in
+its file format the internal structure of the assembler.
+
+\code{RDOFF} is not used by any well-known operating systems. Those
+writing their own systems, however, may well wish to use \code{RDOFF}
+as their object format, on the grounds that it is designed primarily
+for simplicity and contains very little file-header bureaucracy.
+
+The Unix NASM archive, and the DOS archive which includes sources,
+both contain an \index{rdoff subdirectory}\code{rdoff} subdirectory
+holding a set of RDOFF utilities: an RDF linker, an \code{RDF}
+static-library manager, an RDF file dump utility, and a program
+which will load and execute an RDF executable under Linux.
+
+\code{rdf} supports only the \index{standard section names}
+\codeindex{.text}, \codeindex{.data} and \codeindex{.bss}.
+
+\xsubsection{rdflib}{Requiring a Library: The \codeindex{LIBRARY} Directive}
+
+\code{RDOFF} contains a mechanism for an object file to demand a given
+library to be linked to the module, either at load time or run time.
+This is done by the \code{LIBRARY} directive, which takes one argument
+which is the name of the module:
+
+\begin{lstlisting}
+library mylib.rdl
+\end{lstlisting}
+
+\xsubsection{rdfmod}{Specifying a Module Name: The \codeindex{MODULE} Directive}
+
+Special \code{RDOFF} header record is used to store the name of the module.
+It can be used, for example, by run-time loader to perform dynamic
+linking. \code{MODULE} directive takes one argument which is the name
+of current module:
+
+\begin{lstlisting}
+module mymodname
+\end{lstlisting}
+
+Note that when you statically link modules and tell linker to strip
+the symbols from output file, all module names will be stripped too.
+To avoid it, you should start module names with \index{\$!prefix}\code{\$},
+like:
+
+\begin{lstlisting}
+module $kernel.core
+\end{lstlisting}
+
+\xsubsection{rdfglob}{\code{rdf} Extensions to the \code{GLOBAL} Directive}
+\index{GLOBAL!rdf extensions to}
+
+\code{RDOFF} global symbols can contain additional information needed by
+the static linker. You can mark a global symbol as exported, thus
+telling the linker do not strip it from target executable or library
+file. Like in \code{ELF}, you can also specify whether an exported symbol
+is a procedure (function) or data object.
+
+Suffixing the name with a colon and the word \codeindex{export} you make the
+symbol exported:
+
+\begin{lstlisting}
+global sys_open:export
+\end{lstlisting}
+
+To specify that exported symbol is a procedure (function), you add the
+word \codeindex{proc} or \codeindex{function} after declaration:
+
+\begin{lstlisting}
+global sys_open:export proc
+\end{lstlisting}
+
+Similarly, to specify exported data object, add the word \codeindex{data}
+or \codeindex{object} to the directive:
+
+\begin{lstlisting}
+global kernel_ticks:export data
+\end{lstlisting}
+
+\xsubsection{rdfimpt}{\code{rdf} Extensions to the \code{EXTERN} Directive}
+\index{EXTERN!rdf extensions to}
+
+By default the \code{EXTERN} directive in \code{RDOFF} declares a "pure external"
+symbol (i.e. the static linker will complain if such a symbol is not resolved).
+To declare an "imported" symbol, which must be resolved later during a dynamic
+linking phase, \code{RDOFF} offers an additional \code{import} modifier. As in
+\code{GLOBAL}, you can also specify whether an imported symbol is a procedure
+(function) or data object. For example:
+
+\begin{lstlisting}
+library $libc
+extern _open:import
+extern _printf:import proc
+extern _errno:import data
+\end{lstlisting}
+
+Here the directive \code{LIBRARY} is also included, which gives the dynamic linker
+a hint as to where to find requested symbols.
+
+\xsection{dbgfmt}{\codeindex{dbg}: Debugging Format}
+
+The \code{dbg} format does not output an object file as such; instead,
+it outputs a text file which contains a complete list of all the
+transactions between the main body of NASM and the output-format
+back end module. It is primarily intended to aid people who want to
+write their own output drivers, so that they can get a clearer idea
+of the various requests the main program makes of the output driver,
+and in what order they happen.
+
+For simple files, one can easily use the \code{dbg} format like this:
+
+\begin{lstlisting}
+nasm -f dbg filename.asm
+\end{lstlisting}
+
+which will generate a diagnostic file called \code{filename.dbg}.
+However, this will not work well on files which were designed for a
+different object format, because each object format defines its own
+macros (usually user-level forms of directives), and those macros
+will not be defined in the \code{dbg} format. Therefore it can be
+useful to run NASM twice, in order to do the preprocessing with the
+native object format selected:
+
+\begin{lstlisting}
+nasm -e -f rdf -o rdfprog.i rdfprog.asm
+nasm -a -f dbg rdfprog.i
+\end{lstlisting}
+
+This preprocesses \code{rdfprog.asm} into \code{rdfprog.i}, keeping the
+\code{rdf} object format selected in order to make sure RDF special
+directives are converted into primitive form correctly. Then the
+preprocessed source is fed through the \code{dbg} format to generate
+the final diagnostic output.
+
+This workaround will still typically not work for programs intended
+for \code{obj} format, because the \code{obj}- \code{SEGMENT} and \code{GROUP}
+directives have side effects of defining the segment and group names
+as symbols; \code{dbg} will not do this, so the program will not
+assemble. You will have to work around that by defining the symbols
+yourself (using \code{EXTERN}, for example) if you really need to get a
+\code{dbg} trace of an \code{obj}-specific source file.
+
+\code{dbg} accepts any section name and any directives at all, and logs
+them all to its output file.
+
+\code{dbg} accepts and logs any \code{\%pragma}, but the specific \code{\%pragma}:
+
+\begin{lstlisting}
+%pragma dbg maxdump <size>
+\end{lstlisting}
+
+where \code{<size>} is either a number or \code{unlimited}, can be
+used to control the maximum size for dumping the full contents of a
+\code{rawdata} output object.
diff --git a/doc/latex/src/preproc.tex b/doc/latex/src/preproc.tex
new file mode 100644
index 00000000..17468602
--- /dev/null
+++ b/doc/latex/src/preproc.tex
@@ -0,0 +1,2400 @@
+%
+% vim: ts=4 sw=4 et
+%
+\xchapter{preproc}{The NASM \textindexlc{Preprocessor}}
+
+NASM contains a powerful \textindex{macro processor}, which supports
+conditional assembly, multi-level file inclusion, two forms of macro
+(single-line and multi-line), and a ``context stack'' mechanism for
+extra macro power. Preprocessor directives all begin with a \code{\%}
+sign.
+
+The preprocessor collapses all lines which end with a backslash
+\code{\textbackslash} character into a single line.
+Thus:
+
+\begin{lstlisting}
+%define THIS_VERY_LONG_MACRO_NAME_IS_DEFINED_TO \
+ THIS_VALUE
+\end{lstlisting}
+
+will work like a single-line macro without the backslash-newline
+sequence.
+
+\xsection{slmacro}{\textindexlc{Single-Line Macros}}
+
+\xsubsection{define}{The Normal Way: \indexcode{\%idefine}\codeindex{\%define}}
+
+Single-line macros are defined using the \code{\%define} preprocessor
+directive. The definitions work in a similar way to C; so you can do
+things like
+
+\begin{lstlisting}
+%define ctrl 0x1F &
+%define param(a,b) ((a)+(a)*(b))
+
+ mov byte [param(2,ebx)], ctrl 'D'
+\end{lstlisting}
+
+which will expand to
+
+\begin{lstlisting}
+ mov byte [(2)+(2)*(ebx)], 0x1F & 'D'
+\end{lstlisting}
+
+When the expansion of a single-line macro contains tokens which
+invoke another macro, the expansion is performed at invocation time,
+not at definition time. Thus the code
+
+\begin{lstlisting}
+%define a(x) 1+b(x)
+%define b(x) 2*x
+
+ mov ax,a(8)
+\end{lstlisting}
+
+will evaluate in the expected way to \code{mov ax,1+2*8}, even though
+the macro \code{b} wasn't defined at the time of definition of \code{a}.
+
+Macros defined with \code{\%define} are \textindex{case sensitive}: after
+\code{\%define foo bar}, only \code{foo} will expand to \code{bar}:
+\code{Foo} or \code{FOO} will not. By using \code{\%idefine} instead of
+\code{\%define} (the ``i'' stands for ``insensitive'') you can define
+all the case variants of a macro at once, so that \code{\%idefine foo bar}
+would cause \code{foo}, \code{Foo}, \code{FOO}, \code{fOO} and so on
+all to expand to \code{bar}.
+
+There is a mechanism which detects when a macro call has occurred as
+a result of a previous expansion of the same macro, to guard against
+\textindex{circular references} and infinite loops. If this happens,
+the preprocessor will only expand the first occurrence of the macro.
+Hence, if you code
+
+\begin{lstlisting}
+%define a(x) 1+a(x)
+
+ mov ax,a(3)
+\end{lstlisting}
+
+the macro \code{a(3)} will expand once, becoming \code{1+a(3)}, and will
+then expand no further. This behaviour can be useful: see \nref{32c}
+for an example of its use.
+
+You can \index{overloading!single-line macros}overload single-line
+macros: if you write
+
+\begin{lstlisting}
+%define foo(x) 1+x
+%define foo(x,y) 1+x*y
+\end{lstlisting}
+
+the preprocessor will be able to handle both types of macro call,
+by counting the parameters you pass; so \code{foo(3)} will become
+\code{1+3} whereas \code{foo(ebx,2)} will become \code{1+ebx*2}.
+However, if you define
+
+\begin{lstlisting}
+%define foo bar
+\end{lstlisting}
+
+then no other definition of \code{foo} will be accepted: a macro with
+no parameters prohibits the definition of the same name as a macro
+\emph{with} parameters, and vice versa.
+
+This doesn't prevent single-line macros being \emph{redefined}:
+you can perfectly well define a macro with
+
+\begin{lstlisting}
+%define foo bar
+\end{lstlisting}
+
+and then re-define it later in the same source file with
+
+\begin{lstlisting}
+%define foo baz
+\end{lstlisting}
+
+Then everywhere the macro \code{foo} is invoked, it will be expanded
+according to the most recent definition. This is particularly useful
+when defining single-line macros with \code{\%assign}
+(see \nref{assign}).
+
+You can \textindex{pre-define} single-line macros using the \code{-d}
+option on the NASM command line: see \nref{opt-d}.
+
+\xsubsection{xdefine}{Resolving \code{\%define}: \indexcode{\%ixdefine}\codeindex{\%xdefine}}
+
+To have a reference to an embedded single-line macro resolved at the
+time that the embedding macro is \emph{defined}, as opposed to when the
+embedding macro is \emph{expanded}, you need a different mechanism to the
+one offered by \code{\%define}. The solution is to use \code{\%xdefine}, or
+it's \index{case sensitive}case-insensitive counterpart \code{\%ixdefine}.
+
+Suppose you have the following code:
+
+\begin{lstlisting}
+%define isTrue 1
+%define isFalse isTrue
+%define isTrue 0
+
+val1: db isFalse
+
+%define isTrue 1
+
+val2: db isFalse
+\end{lstlisting}
+
+In this case, \code{val1} is equal to 0, and \code{val2} is equal to 1.
+This is because, when a single-line macro is defined using \code{\%define},
+it is expanded only when it is called. As \code{isFalse} expands to \code{isTrue},
+the expansion will be the current value of \code{isTrue}. The first time it is called
+that is 0, and the second time it is 1.
+
+If you wanted \code{isFalse} to expand to the value assigned to the
+embedded macro \code{isTrue} at the time that \code{isFalse} was defined,
+you need to change the above code to use \code{\%xdefine}.
+
+\begin{lstlisting}
+%xdefine isTrue 1
+%xdefine isFalse isTrue
+%xdefine isTrue 0
+
+val1: db isFalse
+
+%xdefine isTrue 1
+
+val2: db isFalse
+\end{lstlisting}
+
+Now, each time that \code{isFalse} is called, it expands to 1,
+as that is what the embedded macro \code{isTrue} expanded to at
+the time that \code{isFalse} was defined.
+
+% FIXME the keys
+\xsubsection{indmacro}{\textindexlc{Macro Indirection}: \indexcode{\%[}\code{\%[...]}}
+
+The \code{\%[...]} construct can be used to expand macros in contexts
+where macro expansion would otherwise not occur, including in the
+names other macros. For example, if you have a set of macros named
+\code{Foo16}, \code{Foo32} and \code{Foo64}, you could write:
+
+\begin{lstlisting}
+mov ax,Foo%[__BITS__] ; The Foo value
+\end{lstlisting}
+
+to use the builtin macro \code{\_\_BITS\_\_} (see \nref{bitsm})
+to automatically select between them. Similarly, the two statements:
+
+\begin{lstlisting}
+%xdefine Bar Quux ; Expands due to %xdefine
+%define Bar %[Quux] ; Expands due to %[...]
+\end{lstlisting}
+
+have, in fact, exactly the same effect.
+
+\code{\%[...]} concatenates to adjacent tokens in the same way that
+multi-line macro parameters do, see \nref{concat} for details.
+
+% FIXME concatmacro key
+\xsubsection{concatmacro}{Concatenating Single Line Macro Tokens: \codeindex{\%+}}
+
+Individual tokens in single line macros can be concatenated, to produce
+longer tokens for later processing. This can be useful if there are
+several similar macros that perform similar functions.
+
+Please note that a space is required after \code{\%+}, in order to
+disambiguate it from the syntax \code{\%+1} used in multiline macros.
+
+As an example, consider the following:
+
+\begin{lstlisting}
+%define BDASTART 400h ; Start of BIOS data area
+
+struc tBIOSDA ; its structure
+ .COM1addr RESW 1
+ .COM2addr RESW 1
+ ; ..and so on
+endstruc
+\end{lstlisting}
+
+Now, if we need to access the elements of tBIOSDA in different places,
+we can end up with:
+
+\begin{lstlisting}
+mov ax,BDASTART + tBIOSDA.COM1addr
+mov bx,BDASTART + tBIOSDA.COM2addr
+\end{lstlisting}
+
+This will become pretty ugly (and tedious) if used in many places, and
+can be reduced in size significantly by using the following macro:
+
+\begin{lstlisting}
+; Macro to access BIOS variables by their names (from tBDA):
+
+%define BDA(x) BDASTART + tBIOSDA. %+ x
+\end{lstlisting}
+
+Now the above code can be written as:
+
+\begin{lstlisting}
+mov ax,BDA(COM1addr)
+mov bx,BDA(COM2addr)
+\end{lstlisting}
+
+Using this feature, we can simplify references to a lot of macros
+(and, in turn, reduce typing errors).
+
+% FIXME they key
+\xsubsection{selfref}{The Macro Name Itself: \codeindex{\%?} and \codeindex{\%??}}
+
+The special symbols \code{\%?} and \code{\%??} can be used to
+reference the macro name itself inside a macro expansion,
+this is supported for both single-and multi-line macros.
+\code{\%?} refers to the macro name as \emph{invoked}, whereas
+\code{\%??} refers to the macro name as \emph{declared}.
+The two are always the same for case-sensitive macros, but
+for case-insensitive macros, they can differ.
+
+For example:
+
+\begin{lstlisting}
+%idefine Foo mov %?,%??
+
+ foo
+ FOO
+\end{lstlisting}
+
+will expand to:
+
+\begin{lstlisting}
+ mov foo,Foo
+ mov FOO,Foo
+\end{lstlisting}
+
+The sequence:
+
+\begin{lstlisting}
+%idefine keyword $%?
+\end{lstlisting}
+
+can be used to make a keyword ``disappear'', for example in case a new
+instruction has been used as a label in older code. For example:
+
+\begin{lstlisting}
+%idefine pause $%? ; Hide the PAUSE instruction
+\end{lstlisting}
+
+\xsubsection{undef}{Undefining Single-Line Macros: \codeindex{\%undef}}
+
+Single-line macros can be removed with the \code{\%undef} directive.
+For example, the following sequence:
+
+\begin{lstlisting}
+%define foo bar
+%undef foo
+
+ mov eax, foo
+\end{lstlisting}
+
+will expand to the instruction \code{mov eax, foo}, since after
+\code{\%undef} the macro \code{foo} is no longer defined.
+
+Macros that would otherwise be pre-defined can be undefined on the
+command-line using the \code{-u} option on the NASM command line:
+see \nref{opt-u}.
+
+\xsubsection{assign}{\textindex{Preprocessor Variables}: \codeindex{\%assign}}
+
+An alternative way to define single-line macros is by means of the
+\code{\%assign} command (and its \index{case sensitive}case-insensitive
+counterpart \codeindex{\%iassign}, which differs from \code{\%assign} in
+exactly the same way that \code{\%idefine} differs from \code{\%define}).
+
+\code{\%assign} is used to define single-line macros which take no
+parameters and have a numeric value. This value can be specified in
+the form of an expression, and it will be evaluated once, when the
+\code{\%assign} directive is processed.
+
+Like \code{\%define}, macros defined using \code{\%assign} can be
+re-defined later, so you can do things like
+
+\begin{lstlisting}
+%assign i i+1
+\end{lstlisting}
+
+to increment the numeric value of a macro.
+
+\code{\%assign} is useful for controlling the termination of \code{\%rep}
+preprocessor loops: see \nref{rep} for an example of this. Another
+use for \code{\%assign} is given in \nref{16c} and \nref{32c}.
+
+The expression passed to \code{\%assign} is a \textindex{critical expression}
+(see \nref{crit}), and must also evaluate to a pure number
+(rather than a relocatable reference such as a code or data address,
+or anything involving a register).
+
+\xsubsection{defstr}{Defining Strings: \indexcode{\%idefstr}\codeindex{\%defstr}}
+
+\code{\%defstr}, and its case-insensitive counterpart \code{\%idefstr},
+define or redefine a single-line macro without parameters but converts
+the entire right-hand side, after macro expansion, to a quoted string
+before definition.
+
+For example:
+
+\begin{lstlisting}
+%defstr test TEST
+\end{lstlisting}
+
+is equivalent to
+
+\begin{lstlisting}
+%define test 'TEST'
+\end{lstlisting}
+
+This can be used, for example, with the \code{\%!} construct
+(see \nref{getenv}):
+
+\begin{lstlisting}
+%defstr PATH %!PATH ; The operating system PATH variable
+\end{lstlisting}
+
+\xsubsection{deftok}{Defining Tokens: \indexcode{\%ideftok}\codeindex{\%deftok}}
+
+\code{\%deftok}, and its case-insensitive counterpart \code{\%ideftok},
+define or redefine a single-line macro without parameters but converts
+the second parameter, after string conversion, to a sequence of tokens.
+
+For example:
+
+\begin{lstlisting}
+%deftok test 'TEST'
+\end{lstlisting}
+
+is equivalent to
+
+\begin{lstlisting}
+%define test TEST
+\end{lstlisting}
+
+\xsection{strmanip}{\textindexlc{String Manipulation in Macros}}
+
+It's often useful to be able to handle strings in macros. NASM
+supports a few simple string handling macro operators from which
+more complex operations can be constructed.
+
+All the string operators define or redefine a value (either a string
+or a numeric value) to a single-line macro. When producing a string
+value, it may change the style of quoting of the input string or
+strings, and possibly use \code{\textbackslash}-escapes inside
+\code{`}-quoted strings.
+
+\xsubsection{strcat}{\textindexlc{Concatenating Strings}: \codeindex{\%strcat}}
+
+The \code{\%strcat} operator concatenates quoted strings and assign
+them to a single-line macro.
+
+For example:
+
+\begin{lstlisting}
+%strcat alpha "Alpha: ", '12" screen'
+\end{lstlisting}
+
+would assign the value \code{'Alpha: 12" screen'} to \code{alpha}.
+Similarly:
+
+\begin{lstlisting}
+%strcat beta '"foo"\', "'bar'"
+\end{lstlisting}
+
+would assign the value \code{`"foo" \textbackslash \textbackslash 'bar'`}
+to \code{beta}.
+
+The use of commas to separate strings is permitted but optional.
+
+\xsubsection{strlen}{\textindexlc{String Length}: \codeindex{\%strlen}}
+
+The \code{\%strlen} operator assigns the length of a string to a macro.
+For example:
+
+\begin{lstlisting}
+%strlen charcnt 'my string'
+\end{lstlisting}
+
+In this example, \code{charcnt} would receive the value 9, just as
+if an \code{\%assign} had been used. In this example, \code{'my string'}
+was a literal string but it could also have been a single-line
+macro that expands to a string, as in the following example:
+
+\begin{lstlisting}
+%define sometext 'my string'
+%strlen charcnt sometext
+\end{lstlisting}
+
+As in the first case, this would result in \code{charcnt} being
+assigned the value of 9.
+
+\xsubsection{substr}{\textindexlc{Extracting Substrings}: \codeindex{\%substr}}
+
+Individual letters or substrings in strings can be extracted using the
+\code{\%substr} operator. An example of its use is probably more useful
+than the description:
+
+\begin{lstlisting}
+%substr mychar 'xyzw' 1 ; equivalent to %define mychar 'x'
+%substr mychar 'xyzw' 2 ; equivalent to %define mychar 'y'
+%substr mychar 'xyzw' 3 ; equivalent to %define mychar 'z'
+%substr mychar 'xyzw' 2,2 ; equivalent to %define mychar 'yz'
+%substr mychar 'xyzw' 2,-1 ; equivalent to %define mychar 'yzw'
+%substr mychar 'xyzw' 2,-2 ; equivalent to %define mychar 'yz'
+\end{lstlisting}
+
+As with \code{\%strlen} (see \nref{strlen}), the first
+parameter is the single-line macro to be created and the second
+is the string. The third parameter specifies the first character
+to be selected, and the optional fourth parameter (preceeded by comma)
+is the length. Note that the first index is 1, not 0 and the last
+index is equal to the value that \code{\%strlen} would assign given
+the same string. Index values out of range result in an empty string.
+A negative length means ``until N-1 characters before the end of string'',
+i.e. \code{-1} means until end of string, \code{-2} until one character
+before, etc.
+
+\xsection{mlmacro}{\textindexlc{Multi-Line Macros}: \indexcode{\%imacro}\codeindex{\%macro}}
+
+Multi-line macros are much more like the type of macro seen in MASM
+and TASM: a multi-line macro definition in NASM looks something like
+this.
+
+\begin{lstlisting}
+%macro prologue 1
+
+ push ebp
+ mov ebp,esp
+ sub esp,%1
+
+%endmacro
+\end{lstlisting}
+
+This defines a C-like function prologue as a macro: so you would
+invoke the macro with a call such as
+
+\begin{minipage}{\linewidth}
+\begin{lstlisting}
+myfunc: prologue 12
+\end{lstlisting}
+\end{minipage}
+
+which would expand to the three lines of code
+
+\begin{lstlisting}
+myfunc: push ebp
+ mov ebp,esp
+ sub esp,12
+\end{lstlisting}
+
+The number \code{1} after the macro name in the \code{\%macro} line
+defines the number of parameters the macro \code{prologue} expects
+to receive. The use of \code{\%1} inside the macro definition refers
+to the first parameter to the macro call. With a macro taking more
+than one parameter, subsequent parameters would be referred to as
+\code{\%2}, \code{\%3} and so on.
+
+Multi-line macros, like single-line macros, are \textindex{case-sensitive},
+unless you define them using the alternative directive \code{\%imacro}.
+
+If you need to pass a comma as \emph{part} of a parameter to a
+multi-line macro, you can do that by enclosing the entire parameter
+in \index{braces!around macro parameters}braces. So you could code
+things like
+
+\begin{lstlisting}
+%macro silly 2
+
+ %2: db %1
+
+%endmacro
+
+ silly 'a', letter_a ; letter_a: db 'a'
+ silly 'ab', string_ab ; string_ab: db 'ab'
+ silly {13,10}, crlf ; crlf: db 13,10
+\end{lstlisting}
+
+\xsubsection{mlmacover}{Overloading Multi-Line Macros}
+\index{overloading!multi-line macros}
+
+As with single-line macros, multi-line macros can be overloaded by
+defining the same macro name several times with different numbers of
+parameters. This time, no exception is made for macros with no
+parameters at all. So you could define
+
+\begin{lstlisting}
+%macro prologue 0
+
+ push ebp
+ mov ebp,esp
+
+%endmacro
+\end{lstlisting}
+
+to define an alternative form of the function prologue which
+allocates no local stack space.
+
+Sometimes, however, you might want to ``overload'' a machine
+instruction; for example, you might want to define
+
+\begin{lstlisting}
+%macro push 2
+
+ push %1
+ push %2
+
+%endmacro
+\end{lstlisting}
+
+so that you could code
+
+\begin{lstlisting}
+ push ebx ; this line is not a macro call
+ push eax,ecx ; but this one is
+\end{lstlisting}
+
+Ordinarily, NASM will give a warning for the first of the above two
+lines, since \code{push} is now defined to be a macro, and is being
+invoked with a number of parameters for which no definition has been
+given. The correct code will still be generated, but the assembler
+will give a warning. This warning can be disabled by the use of the
+\code{-w-macro-params} command-line option (see \nref{opt-w}).
+
+\xsubsection{maclocal}{\textindexlc{Macro-Local Labels}}
+
+NASM allows you to define labels within a multi-line macro definition
+in such a way as to make them local to the macro call: so calling
+the same macro multiple times will use a different label each time.
+You do this by prefixing \codeindex{\%\%} to the label name.
+So you can invent an instruction which executes a \code{RET} if the
+\code{Z} flag is set by doing this:
+
+\begin{lstlisting}
+%macro retz 0
+
+ jnz %%skip
+ ret
+ %%skip:
+
+%endmacro
+\end{lstlisting}
+
+You can call this macro as many times as you want, and every time
+you call it NASM will make up a different ``real'' name to substitute
+for the label \code{\%\%skip}. The names NASM invents are of the form
+\code{..@2345.skip}, where the number 2345 changes with every macro
+call. The \codeindex{..@} prefix prevents macro-local labels from
+interfering with the local label mechanism, as described in
+\nref{locallab}. You should avoid defining your own labels
+in this form (the \code{..@} prefix, then a number, then another period)
+in case they interfere with macro-local labels.
+
+\xsubsection{mlmacgre}{\textindexlc{Greedy Macro Parameters}}
+
+Occasionally it is useful to define a macro which lumps its entire
+command line into one parameter definition, possibly after
+extracting one or two smaller parameters from the front. An example
+might be a macro to write a text string to a file in MS-DOS, where
+you might want to be able to write
+
+\begin{lstlisting}
+writefile [filehandle],"hello, world",13,10
+\end{lstlisting}
+
+NASM allows you to define the last parameter of a macro to be
+\emph{greedy}, meaning that if you invoke the macro with more
+parameters than it expects, all the spare parameters get lumped into
+the last defined one along with the separating commas. So if you
+code:
+
+\begin{lstlisting}
+%macro writefile 2+
+
+ jmp %%endstr
+ %%str: db %2
+ %%endstr:
+ mov dx,%%str
+ mov cx,%%endstr-%%str
+ mov bx,%1
+ mov ah,0x40
+ int 0x21
+
+%endmacro
+\end{lstlisting}
+
+then the example call to \code{writefile} above will work as expected:
+the text before the first comma, \code{[filehandle]}, is used as the
+first macro parameter and expanded when \code{\%1} is referred to, and
+all the subsequent text is lumped into \code{\%2} and placed after the
+\code{db}.
+
+The greedy nature of the macro is indicated to NASM by the use of
+the \index{modifier!+}\code{+} sign after the parameter count on the
+\code{\%macro} line.
+
+If you define a greedy macro, you are effectively telling NASM how
+it should expand the macro given \emph{any} number of parameters from
+the actual number specified up to infinity; in this case, for
+example, NASM now knows what to do when it sees a call to
+\code{writefile} with 2, 3, 4 or more parameters. NASM will take this
+into account when overloading macros, and will not allow you to
+define another form of \code{writefile} taking 4 parameters (for
+example).
+
+Of course, the above macro could have been implemented as a
+non-greedy macro, in which case the call to it would have had to
+look like
+
+\begin{lstlisting}
+writefile [filehandle], {"hello, world",13,10}
+\end{lstlisting}
+
+NASM provides both mechanisms for putting \textindex{commas in macro
+parameters}, and you choose which one you prefer for each macro
+definition.
+
+See \nref{sectmac} for a better way to write the above macro.
+
+\xsubsection{mlmacrange}{\textindexlc{Macro Parameters Range}}
+
+NASM allows you to expand parameters via special construction \code{\%\{x:y\}}
+where \code{x} is the first parameter index and \code{y} is the last.
+Any index can be either negative or positive but must never be zero.
+
+For example
+
+\begin{lstlisting}
+%macro mpar 1-*
+ db %{3:5}
+%endmacro
+
+mpar 1,2,3,4,5,6
+\end{lstlisting}
+
+expands to \code{3,4,5} range.
+
+Even more, the parameters can be reversed so that
+
+\begin{lstlisting}
+%macro mpar 1-*
+ db %{5:3}
+%endmacro
+
+mpar 1,2,3,4,5,6
+\end{lstlisting}
+
+expands to \code{5,4,3} range.
+
+But even this is not the last. The parameters can be addressed via negative
+indices so NASM will count them reversed. The ones who know Python may see
+the analogue here.
+
+\begin{lstlisting}
+%macro mpar 1-*
+ db %{-1:-3}
+%endmacro
+
+mpar 1,2,3,4,5,6
+\end{lstlisting}
+
+expands to \code{6,5,4} range.
+
+Note that NASM uses \textindex{comma} to separate parameters being expanded.
+
+By the way, here is a trick - you might use the index \code{\%{-1:-1}}
+which gives you the \textindex{last} argument passed to a macro.
+
+\xsubsection{mlmacdef}{\textindexlc{Default Macro Parameters}}
+
+NASM also allows you to define a multi-line macro with a \emph{range}
+of allowable parameter counts. If you do this, you can specify
+defaults for \textindex{omitted parameters}. So, for example:
+
+\begin{lstlisting}
+%macro die 0-1 "Painful program death has occurred."
+
+ writefile 2,%1
+ mov ax,0x4c01
+ int 0x21
+
+%endmacro
+\end{lstlisting}
+
+This macro (which makes use of the \code{writefile} macro defined in
+\nref{mlmacgre}) can be called with an explicit error message,
+which it will display on the error output stream before exiting, or it can be
+called with no parameters, in which case it will use the default
+error message supplied in the macro definition.
+
+In general, you supply a minimum and maximum number of parameters
+for a macro of this type; the minimum number of parameters are then
+required in the macro call, and then you provide defaults for the
+optional ones. So if a macro definition began with the line
+
+\begin{lstlisting}
+%macro foobar 1-3 eax,[ebx+2]
+\end{lstlisting}
+
+then it could be called with between one and three parameters, and
+\code{\%1} would always be taken from the macro call. \code{\%2}, if not
+specified by the macro call, would default to \code{eax}, and \code{\%3}
+if not specified would default to \code{[ebx+2]}.
+
+You can provide extra information to a macro by providing
+too many default parameters:
+
+\begin{lstlisting}
+%macro quux 1 something
+\end{lstlisting}
+
+This will trigger a warning by default; see \nref{opt-w} for
+more information.
+When \code{quux} is invoked, it receives not one but two parameters.
+\code{something} can be referred to as \code{\%2}. The difference
+between passing \code{something} this way and writing \code{something}
+in the macro body is that with this way \code{something} is evaluated
+when the macro is defined, not when it is expanded.
+
+You may omit parameter defaults from the macro definition, in which
+case the parameter default is taken to be blank. This can be useful
+for macros which can take a variable number of parameters, since the
+\codeindex{\%0} token (see \nref{percent0}) allows you to
+determine how many parameters were really passed to the macro call.
+
+This defaulting mechanism can be combined with the greedy-parameter
+mechanism; so the \code{die} macro above could be made more powerful,
+and more useful, by changing the first line of the definition to
+
+\begin{lstlisting}
+%macro die 0-1+ "Painful program death has occurred.",13,10
+\end{lstlisting}
+
+The maximum parameter count can be infinite, denoted by \code{*}. In
+this case, of course, it is impossible to provide a \emph{full} set of
+default parameters. Examples of this usage are shown in
+\nref{rotate}.
+
+\xsubsection{percent0}{\codeindex{\%0}: \index{counting macro parameters}Macro Parameter Counter}
+
+The parameter reference \code{\%0} will return a numeric constant giving the
+number of parameters received, that is, if \code{\%0} is n then \code{\%}n
+is the last parameter. \code{\%0} is mostly useful for macros that can take a variable
+number of parameters. It can be used as an argument to \code{\%rep}
+(see \nref{rep}) in order to iterate through all the parameters
+of a macro. Examples are given in \nref{rotate}.
+
+\xsubsection{percent00}{\codeindex{\%00}: \index{label preceeding macro}Label Preceeding Macro}
+
+\code{\%00} will return the label preceeding the macro invocation, if any. The
+label must be on the same line as the macro invocation, may be a local label
+(see \nref{locallab}), and need not end in a colon.
+
+\xsubsection{rotate}{\codeindex{\%rotate}: \textindexlc{Rotating Macro Parameters}}
+
+Unix shell programmers will be familiar with the \index{shift
+command}\code{shift} shell command, which allows the arguments passed
+to a shell script (referenced as \code{\$1}, \code{\$2} and so on) to be
+moved left by one place, so that the argument previously referenced
+as \code{\$2} becomes available as \code{\$1}, and the argument previously
+referenced as \code{\$1} is no longer available at all.
+
+NASM provides a similar mechanism, in the form of \code{\%rotate}. As
+its name suggests, it differs from the Unix \code{shift} in that no
+parameters are lost: parameters rotated off the left end of the
+argument list reappear on the right, and vice versa.
+
+\code{\%rotate} is invoked with a single numeric argument (which may be
+an expression). The macro parameters are rotated to the left by that
+many places. If the argument to \code{\%rotate} is negative, the macro
+parameters are rotated to the right.
+
+\index{iterating over macro parameters}So a pair of macros to save and
+restore a set of registers might work as follows:
+
+\begin{lstlisting}
+%macro multipush 1-*
+
+ %rep %0
+ push %1
+ %rotate 1
+ %endrep
+
+%endmacro
+\end{lstlisting}
+
+This macro invokes the \code{PUSH} instruction on each of its arguments
+in turn, from left to right. It begins by pushing its first
+argument, \code{\%1}, then invokes \code{\%rotate} to move all the arguments
+one place to the left, so that the original second argument is now
+available as \code{\%1}. Repeating this procedure as many times as there
+were arguments (achieved by supplying \code{\%0} as the argument to
+\code{\%rep}) causes each argument in turn to be pushed.
+
+Note also the use of \code{*} as the maximum parameter count,
+indicating that there is no upper limit on the number of parameters
+you may supply to the \codeindex{multipush} macro.
+
+It would be convenient, when using this macro, to have a \code{POP}
+equivalent, which \emph{didn't} require the arguments to be given in
+reverse order. Ideally, you would write the \code{multipush} macro
+call, then cut-and-paste the line to where the pop needed to be
+done, and change the name of the called macro to \code{multipop}, and
+the macro would take care of popping the registers in the opposite
+order from the one in which they were pushed.
+
+This can be done by the following definition:
+
+\begin{lstlisting}
+%macro multipop 1-*
+
+ %rep %0
+ %rotate -1
+ pop %1
+ %endrep
+
+%endmacro
+\end{lstlisting}
+
+This macro begins by rotating its arguments one place to the
+\emph{right}, so that the original \emph{last} argument appears
+as \code{\%1}. This is then popped, and the arguments are rotated
+right again, socthe second-to-last argument becomes \code{\%1}.
+Thus the arguments are iterated through in reverse order.
+
+\xsubsection{concat}{\textindexlc{Concatenating Macro Parameters}}
+
+NASM can concatenate macro parameters and macro indirection constructs
+on to other text surrounding them. This allows you to declare a family
+of symbols, for example, in a macro definition. If, for example, you
+wanted to generate a table of key codes along with offsets into the
+table, you could code something like
+
+\begin{lstlisting}
+%macro keytab_entry 2
+
+ keypos%1 equ $-keytab
+ db %2
+
+%endmacro
+
+keytab:
+ keytab_entry F1,128+1
+ keytab_entry F2,128+2
+ keytab_entry Return,13
+\end{lstlisting}
+
+which would expand to
+
+\begin{lstlisting}
+keytab:
+keyposF1 equ $-keytab
+ db 128+1
+keyposF2 equ $-keytab
+ db 128+2
+keyposReturn equ $-keytab
+ db 13
+\end{lstlisting}
+
+You can just as easily concatenate text on to the other end of a
+macro parameter, by writing \code{\%1foo}.
+
+If you need to append a \emph{digit} to a macro parameter, for example
+defining labels \code{foo1} and \code{foo2} when passed the parameter
+\code{foo}, you can't code \code{\%11} because that would be taken as the
+eleventh macro parameter. Instead, you must code
+\index{braces!after \% sign}\code{\%\{1\}1}, which will separate the first
+\code{1} (giving the number of the macro parameter) from the second
+(literal text to be concatenated to the parameter).
+
+This concatenation can also be applied to other preprocessor in-line
+objects, such as macro-local labels (\nref{maclocal})
+and context-local labels (\nref{ctxlocal}).
+In all cases, ambiguities in syntax can be resolved by enclosing
+everything after the \code{\%} sign and before the literal text
+in braces: so \code{\%\{\%foo\}bar} concatenates the text \code{bar}
+to the end of the real name of the macro-local label \code{\%\%foo}.
+(This is unnecessary, since the form NASM uses for the real names of
+macro-local labels means that the two usages \code{\%\{\%foo\}bar}
+and \code{\%\%foobar} would both expand to the same
+thing anyway; nevertheless, the capability is there.)
+
+The single-line macro indirection construct, \code{\%[...]}
+(\nref{indmacro}), behaves the same way as macro
+parameters for the purpose of concatenation.
+
+See also the \code{\%+} operator, \nref{concatmacro}.
+
+\xsubsection{mlmaccc}{\textindexlc{Condition Codes as Macro Parameters}}
+
+NASM can give special treatment to a macro parameter which contains
+a condition code. For a start, you can refer to the macro parameter
+\code{\%1} by means of the alternative syntax \codeindex{\%+1},
+which informs NASM that this macro parameter is supposed to contain
+a condition code, and will cause the preprocessor to report an
+error message if the macro is called with a parameter which is
+\emph{not} a valid condition code.
+
+Far more usefully, though, you can refer to the macro parameter by
+means of \codeindex{\%-1}, which NASM will expand as the \emph{inverse}
+condition code. So the \code{retz} macro defined in \nref{maclocal}
+can be replaced by a general \textindexlc{conditional-return macro} like this:
+
+\begin{lstlisting}
+%macro retc 1
+
+ j%-1 %%skip
+ ret
+ %%skip:
+
+%endmacro
+\end{lstlisting}
+
+This macro can now be invoked using calls like \code{retc ne}, which
+will cause the conditional-jump instruction in the macro expansion
+to come out as \code{JE}, or \code{retc po} which will make the jump a
+\code{JPE}.
+
+The \code{\%+1} macro-parameter reference is quite happy to interpret
+the arguments \code{CXZ} and \code{ECXZ} as valid condition codes;
+however, \code{\%-1} will report an error if passed either of these,
+because no inverse condition code exists.
+
+\xsubsection{nolist}{\textindexlc{Disabling Listing Expansion}\indexcode{.nolist}}
+
+When NASM is generating a listing file from your program, it will
+generally expand multi-line macros by means of writing the macro
+call and then listing each line of the expansion. This allows you to
+see which instructions in the macro expansion are generating what
+code; however, for some macros this clutters the listing up
+unnecessarily.
+
+NASM therefore provides the \code{.nolist} qualifier, which you can
+include in a macro definition to inhibit the expansion of the macro
+in the listing file. The \code{.nolist} qualifier comes directly after
+the number of parameters, like this:
+
+\begin{lstlisting}
+%macro foo 1.nolist
+\end{lstlisting}
+
+Or like this:
+
+\begin{lstlisting}
+%macro bar 1-5+.nolist a,b,c,d,e,f,g,h
+\end{lstlisting}
+
+\xsubsection{unmacro}{Undefining Multi-Line Macros: \codeindex{\%unmacro}}
+
+Multi-line macros can be removed with the \code{\%unmacro} directive.
+Unlike the \code{\%undef} directive, however, \code{\%unmacro} takes an
+argument specification, and will only remove \textindex{exact matches} with
+that argument specification.
+
+For example:
+
+\begin{lstlisting}
+%macro foo 1-3
+ ; Do something
+%endmacro
+%unmacro foo 1-3
+\end{lstlisting}
+
+removes the previously defined macro \code{foo}, but
+
+\begin{lstlisting}
+%macro bar 1-3
+ ; Do something
+%endmacro
+%unmacro bar 1
+\end{lstlisting}
+
+does \emph{not} remove the macro \code{bar}, since the argument
+specification does not match exactly.
+
+\xsection{condasm}{\textindexlc{Conditional Assembly}\indexcode{\%if}}
+
+Similarly to the C preprocessor, NASM allows sections of a source
+file to be assembled only if certain conditions are met. The general
+syntax of this feature looks like this:
+
+\begin{lstlisting}
+%if<condition>
+ ; some code which only appears if <condition> is met
+%elif<condition2>
+ ; only appears if <condition> is not met but <condition2> is
+%else
+ ; this appears if neither <condition> nor <condition2> was met
+%endif
+\end{lstlisting}
+
+The inverse forms \codeindex{\%ifn} and \codeindex{\%elifn} are also supported.
+
+The \codeindex{\%else} clause is optional, as is the \codeindex{\%elif} clause.
+You can have more than one \code{\%elif} clause as well.
+
+There are a number of variants of the \code{\%if} directive. Each has its
+corresponding \code{\%elif}, \code{\%ifn}, and \code{\%elifn} directives; for
+example, the equivalents to the \code{\%ifdef} directive are \code{\%elifdef},
+\code{\%ifndef}, and \code{\%elifndef}.
+
+\xsubsection{ifdef}{\codeindex{\%ifdef}: Testing Single-Line Macro Existence
+\index{testing, single-line macro existence}}
+
+Beginning a conditional-assembly block with the line \code{\%ifdef MACRO}
+will assemble the subsequent code if, and only if, a single-line macro called
+\code{MACRO} is defined. If not, then the \code{\%elif} and \code{\%else}
+blocks (if any) will be processed instead.
+
+For example, when debugging a program, you might want to write code
+such as
+
+\begin{lstlisting}
+ ; perform some function
+%ifdef DEBUG
+ writefile 2,"Function performed successfully",13,10
+%endif
+ ; go and do something else
+\end{lstlisting}
+
+Then you could use the command-line option \code{-dDEBUG} to create a
+version of the program which produced debugging messages, and remove
+the option to generate the final release version of the program.
+
+You can test for a macro \emph{not} being defined by using
+\codeindex{\%ifndef} instead of \code{\%ifdef}. You can also test
+for macro definitions in \code{\%elif} blocks by using
+\codeindex{\%elifdef} and \codeindex{\%elifndef}.
+
+\xsubsection{ifmacro}{\codeindex{\%ifmacro}: Testing Multi-Line Macro Existence
+\index{testing!multi-line macro existence}}
+
+The \code{\%ifmacro} directive operates in the same way as the \code{\%ifdef}
+directive, except that it checks for the existence of a multi-line macro.
+
+For example, you may be working with a large project and not have control
+over the macros in a library. You may want to create a macro with one
+name if it doesn't already exist, and another name if one with that name
+does exist.
+
+The \code{\%ifmacro} is considered true if defining a macro with the given name
+and number of arguments would cause a definitions conflict. For example:
+
+\begin{lstlisting}
+%ifmacro MyMacro 1-3
+
+ %error "MyMacro 1-3" causes a conflict with an existing macro.
+
+%else
+
+ %macro MyMacro 1-3
+
+ ; insert code to define the macro
+
+ %endmacro
+
+%endif
+\end{lstlisting}
+
+This will create the macro ``\code{MyMacro 1-3}'' if no macro already exists which
+would conflict with it, and emits a warning if there would be a definition
+conflict.
+
+You can test for the macro not existing by using the \codeindex{\%ifnmacro}
+instead of \code{\%ifmacro}. Additional tests can be performed in
+\code{\%elif} blocks by using \codeindex{\%elifmacro} and
+\codeindex{\%elifnmacro}.
+
+\xsubsection{ifctx}{\codeindex{\%ifctx}: Testing the Context Stack
+\index{testing!context stack}}
+
+The conditional-assembly construct \code{\%ifctx} will cause the
+subsequent code to be assembled if and only if the top context on
+the preprocessor's context stack has the same name as one of the arguments.
+As with \code{\%ifdef}, the inverse and \code{\%elif} forms \codeindex{\%ifnctx},
+\codeindex{\%elifctx} and \codeindex{\%elifnctx} are also supported.
+
+For more details of the context stack, see \nref{ctxstack}.
+For a sample use of \code{\%ifctx}, see \nref{blockif}.
+
+\xsubsection{if}{\codeindex{\%if}: Testing Arbitrary Numeric Expressions}
+\index{testing!arbitrary numeric expressions}
+
+The conditional-assembly construct \code{\%if expr} will cause the
+subsequent code to be assembled if and only if the value of the
+numeric expression \code{expr} is non-zero. An example of the use of
+this feature is in deciding when to break out of a \code{\%rep}
+preprocessor loop: see \nref{rep} for a detailed example.
+
+The expression given to \code{\%if}, and its counterpart
+\codeindex{\%elif}, is a critical expression (see \nref{crit}).
+
+\code{\%if} extends the normal NASM expression syntax, by providing a
+set of \textindexlc{relational operators} which are not normally available in
+expressions. The operators \codeindex{=}, \codeindex{\textless},
+\codeindex{\textgreater}, \codeindex{\textless=}, \codeindex{\textgreater=}
+and \codeindex{\textless\textgreater} test equality,
+less-than, greater-than, less-or-equal, greater-or-equal and not-equal
+respectively. The C-like forms \codeindex{==} and \codeindex{!=} are
+supported as alternative forms of \code{=} and \code{\textless\textgreater}.
+In addition, low-priority logical operators \codeindex{\&\&},
+\codeindex{\^{}\^{}} and \codeindex{||} are provided, supplying
+\textindex{logical!ND}, \textindex{logical!XOR} and \textindex{logical!OR}.
+These work like the C logical operators (although C has no logical XOR),
+in that they always return either 0 or 1, and treat any non-zero input as 1
+(so that \code{\^{}\^{}}, for example, returns 1 if exactly one of its inputs
+is zero, and 0 otherwise). The relational operators also return 1
+for true and 0 for false.
+
+Like other \code{\%if} constructs, \code{\%if} has a counterpart
+\codeindex{\%elif}, and negative forms \codeindex{\%ifn} and \codeindex{\%elifn}.
+
+\xsubsection{ifidn}{\codeindex{\%ifidn} and \codeindex{\%ifidni}: Testing Exact Text Identity}
+\index{testing!exact text identity}
+
+The construct \code{\%ifidn text1,text2} will cause the subsequent code
+to be assembled if and only if \code{text1} and \code{text2}, after
+expanding single-line macros, are identical pieces of text.
+Differences in white space are not counted.
+
+\code{\%ifidni} is similar to \code{\%ifidn}, but is \textindex{case-insensitive}.
+
+For example, the following macro pushes a register or number on the
+stack, and allows you to treat \code{IP} as a real register:
+
+\begin{lstlisting}
+%macro pushparam 1
+
+ %ifidni %1,ip
+ call %%label
+ %%label:
+ %else
+ push %1
+ %endif
+
+%endmacro
+\end{lstlisting}
+
+Like other \code{\%if} constructs, \code{\%ifidn} has a counterpart
+\codeindex{\%elifidn}, and negative forms \codeindex{\%ifnidn} and
+\codeindex{\%elifnidn}. Similarly, \code{\%ifidni} has counterparts
+\codeindex{\%elifidni}, \codeindex{\%ifnidni} and \codeindex{\%elifnidni}.
+
+\xsubsection{iftyp}{\codeindex{\%ifid}, \codeindex{\%ifnum}, \codeindex{\%ifstr}: Testing Token Types}
+\index{testing!token types}
+
+Some macros will want to perform different tasks depending on
+whether they are passed a number, a string, or an identifier. For
+example, a string output macro might want to be able to cope with
+being passed either a string constant or a pointer to an existing
+string.
+
+The conditional assembly construct \code{\%ifid}, taking one parameter
+(which may be blank), assembles the subsequent code if and only if
+the first token in the parameter exists and is an identifier.
+\code{\%ifnum} works similarly, but tests for the token being a numeric
+constant; \code{\%ifstr} tests for it being a string.
+
+For example, the \code{writefile} macro defined in \nref{mlmacgre}
+can be extended to take advantage of \code{\%ifstr} in the following fashion:
+
+\begin{lstlisting}
+%macro writefile 2-3+
+
+ %ifstr %2
+ jmp %%endstr
+ %if %0 = 3
+ %%str: db %2,%3
+ %else
+ %%str: db %2
+ %endif
+ %%endstr: mov dx,%%str
+ mov cx,%%endstr-%%str
+ %else
+ mov dx,%2
+ mov cx,%3
+ %endif
+ mov bx,%1
+ mov ah,0x40
+ int 0x21
+
+%endmacro
+\end{lstlisting}
+
+Then the \code{writefile} macro can cope with being called in either of
+the following two ways:
+
+\begin{lstlisting}
+writefile [file], strpointer, length
+writefile [file], "hello", 13, 10
+\end{lstlisting}
+
+In the first, \code{strpointer} is used as the address of an
+already-declared string, and \code{length} is used as its length; in
+the second, a string is given to the macro, which therefore declares
+it itself and works out the address and length for itself.
+
+Note the use of \code{\%if} inside the \code{\%ifstr}: this is to detect
+whether the macro was passed two arguments (so the string would be a
+single string constant, and \code{db \%2} would be adequate) or more (in
+which case, all but the first two would be lumped together into
+\code{\%3}, and \code{db \%2,\%3} would be required).
+
+The usual \indexcode{\%elifid}\indexcode{\%elifnum}\indexcode{\%elifstr}\code{\%elif}...,
+\indexcode{\%ifnid}\indexcode{\%ifnnum}\indexcode{\%ifnstr}\code{\%ifn}..., and
+\indexcode{\%elifnid}\indexcode{\%elifnnum}\indexcode{\%elifnstr}\code{\%elifn}...
+versions exist for each of \code{\%ifid}, \code{\%ifnum} and \code{\%ifstr}.
+
+\xsubsection{iftoken}{\codeindex{\%iftoken}: Test for a Single Token}
+
+Some macros will want to do different things depending on if it is
+passed a single token (e.g. paste it to something else using \code{\%+})
+versus a multi-token sequence.
+
+The conditional assembly construct \code{\%iftoken} assembles the
+subsequent code if and only if the expanded parameters consist of
+exactly one token, possibly surrounded by whitespace.
+
+For example:
+
+\begin{lstlisting}
+%iftoken 1
+\end{lstlisting}
+
+will assemble the subsequent code, but
+
+\begin{lstlisting}
+%iftoken -1
+\end{lstlisting}
+
+will not, since \code{-1} contains two tokens: the unary minus operator
+\code{-}, and the number \code{1}.
+
+The usual \codeindex{\%eliftoken}, \codeindex{\%ifntoken}, and
+\codeindex{\%elifntoken} variants are also provided.
+
+\xsubsection{ifempty}{\codeindex{\%ifempty}: Test for Empty Expansion}
+
+The conditional assembly construct \code{\%ifempty} assembles the
+subsequent code if and only if the expanded parameters do not contain
+any tokens at all, whitespace excepted.
+
+The usual \codeindex{\%elifempty}, \codeindex{\%ifnempty}, and
+\codeindex{\%elifnempty} variants are also provided.
+
+\xsubsection{ifenv}{\codeindex{\%ifenv}: Test If Environment Variable Exists}
+
+The conditional assembly construct \code{\%ifenv} assembles the
+subsequent code if and only if the environment variable referenced by
+the \code{\%^^21}\emph{variable} directive exists.
+
+The usual \codeindex{\%elifenv}, \codeindex{\%ifnenv}, and \codeindex{\%elifnenv}
+variants are also provided.
+
+Just as for \code{\%^^21}\emph{variable} the argument should be written as a
+string if it contains characters that would not be legal in an
+identifier. See \nref{getenv}.
+
+\xsection{rep}{\textindexlc{Preprocessor Loops}\index{repeating code}: \codeindex{\%rep}}
+
+NASM's \code{TIMES} prefix, though useful, cannot be used to invoke a
+multi-line macro multiple times, because it is processed by NASM
+after macros have already been expanded. Therefore NASM provides
+another form of loop, this time at the preprocessor level: \code{\%rep}.
+
+The directives \code{\%rep} and \codeindex{\%endrep} (\code{\%rep}
+takes a numeric argument, which can be an expression; \code{\%endrep}
+takes no arguments) can be used to enclose a chunk of code, which is then
+replicated as many times as specified by the preprocessor:
+
+\begin{lstlisting}
+%assign i 0
+%rep 64
+ inc word [table+2*i]
+%assign i i+1
+%endrep
+\end{lstlisting}
+
+This will generate a sequence of 64 \code{INC} instructions,
+incrementing every word of memory from \code{[table]} to
+\code{[table+126]}.
+
+For more complex termination conditions, or to break out of a repeat
+loop part way along, you can use the \codeindex{\%exitrep} directive to
+terminate the loop, like this:
+
+\begin{lstlisting}
+fibonacci:
+%assign i 0
+%assign j 1
+%rep 100
+%if j > 65535
+ %exitrep
+%endif
+ dw j
+%assign k j+i
+%assign i j
+%assign j k
+%endrep
+
+fib_number equ ($-fibonacci)/2
+\end{lstlisting}
+
+This produces a list of all the Fibonacci numbers that will fit in
+16 bits. Note that a maximum repeat count must still be given to
+\code{\%rep}. This is to prevent the possibility of NASM getting into an
+infinite loop in the preprocessor, which (on multitasking or
+multi-user systems) would typically cause all the system memory to
+be gradually used up and other applications to start crashing.
+
+Note a maximum repeat count is limited by 62 bit number, though it
+is hardly possible that you ever need anything bigger.
+
+\xsection{files}{Source Files and Dependencies}
+
+These commands allow you to split your sources into multiple files.
+
+\xsubsection{include}{\codeindex{\%include}: \textindexlc{Including Other Files}}
+
+Using, once again, a very similar syntax to the C preprocessor,
+NASM's preprocessor lets you include other source files into your
+code. This is done by the use of the \codeindex{\%include} directive:
+
+\begin{lstlisting}
+%include "macros.mac"
+\end{lstlisting}
+
+will include the contents of the file \code{macros.mac} into the source
+file containing the \code{\%include} directive.
+
+Include files are \index{searching for include files}searched for in the
+current directory (the directory you're in when you run NASM, as
+opposed to the location of the NASM executable or the location of
+the source file), plus any directories specified on the NASM command
+line using the \code{-i} option.
+
+The standard C idiom for preventing a file being included more than
+once is just as applicable in NASM: if the file \code{macros.mac} has
+the form
+
+\begin{lstlisting}
+%ifndef MACROS_MAC
+ %define MACROS_MAC
+ ; now define some macros
+%endif
+\end{lstlisting}
+
+then including the file more than once will not cause errors,
+because the second time the file is included nothing will happen
+because the macro \code{MACROS\_MAC} will already be defined.
+
+You can force a file to be included even if there is no \code{\%include}
+directive that explicitly includes it, by using the \codeindex{-p} option
+on the NASM command line (see \nref{opt-p}).
+
+\xsubsection{pathsearch}{\codeindex{\%pathsearch}: Search the Include Path}
+
+The \code{\%pathsearch} directive takes a single-line macro name and a
+filename, and declare or redefines the specified single-line macro to
+be the \emph{include-path-resolved} version of the filename, if the file
+exists (otherwise, it is passed unchanged).
+
+For example,
+
+\begin{lstlisting}
+%pathsearch MyFoo "foo.bin"
+\end{lstlisting}
+
+... with \code{-Ibins/} in the include path may end up defining the macro
+\code{MyFoo} to be \code{"bins/foo.bin"}.
+
+\xsubsection{depend}{\codeindex{\%depend}: Add Dependent Files}
+
+The \code{\%depend} directive takes a filename and adds it to the list of
+files to be emitted as dependency generation when the \code{-M} options
+and its relatives (see \nref{opt-M}) are used. It produces
+no output.
+
+This is generally used in conjunction with \code{\%pathsearch}. For
+example, a simplified version of the standard macro wrapper for the
+\code{INCBIN} directive looks like:
+
+\begin{lstlisting}
+%imacro incbin 1-2+ 0
+%pathsearch dep %1
+%depend dep
+ incbin dep,%2
+%endmacro
+\end{lstlisting}
+
+This first resolves the location of the file into the macro \code{dep},
+then adds it to the dependency lists, and finally issues the
+assembler-level \code{INCBIN} directive.
+
+\xsubsection{use}{\codeindex{\%use}: Include Standard Macro Package}
+
+The \code{\%use} directive is similar to \code{\%include}, but rather than
+including the contents of a file, it includes a named standard macro
+package. The standard macro packages are part of NASM, and are
+described in \nref{macropkg}.
+
+Unlike the \code{\%include} directive, package names for the \code{\%use}
+directive do not require quotes, but quotes are permitted. In NASM
+2.04 and 2.05 the unquoted form would be macro-expanded; this is no
+longer true. Thus, the following lines are equivalent:
+
+\begin{lstlisting}
+%use altreg
+%use 'altreg'
+\end{lstlisting}
+
+Standard macro packages are protected from multiple inclusion. When a
+standard macro package is used, a testable single-line macro of the
+form \code{\_\_USE\_\emph{package}\_\_} is also defined,
+see \nref{usedef}.
+
+\xsection{ctxstack}{The \textindexlc{Context Stack}}
+
+Having labels that are local to a macro definition is sometimes not
+quite powerful enough: sometimes you want to be able to share labels
+between several macro calls. An example might be a \code{REPEAT} ...
+\code{UNTIL} loop, in which the expansion of the \code{REPEAT} macro
+would need to be able to refer to a label which the \code{UNTIL} macro
+had defined. However, for such a macro you would also want to be
+able to nest these loops.
+
+NASM provides this level of power by means of a \emph{context stack}.
+The preprocessor maintains a stack of \emph{contexts}, each of which is
+characterized by a name. You add a new context to the stack using
+the \codeindex{\%push} directive, and remove one using \codeindex{\%pop}.
+You can define labels that are local to a particular context on the stack.
+
+\xsubsection{pushpop}{\codeindex{\%push} and \codeindex{\%pop}: Creating and Removing Contexts}
+\index{context!create}
+\index{context!remove }
+
+The \code{\%push} directive is used to create a new context and place it
+on the top of the context stack. \code{\%push} takes an optional argument,
+which is the name of the context. For example:
+
+\begin{lstlisting}
+%push foobar
+\end{lstlisting}
+
+This pushes a new context called \code{foobar} on the stack. You can have
+several contexts on the stack with the same name: they can still be
+distinguished. If no name is given, the context is unnamed (this is
+normally used when both the \code{\%push} and the \code{\%pop} are inside a
+single macro definition.)
+
+The directive \code{\%pop}, taking one optional argument, removes the top
+context from the context stack and destroys it, along with any
+labels associated with it. If an argument is given, it must match the
+name of the current context, otherwise it will issue an error.
+
+\xsubsection{ctxlocal}{\textindexlc{Context-Local Labels}}
+
+Just as the usage \code{\%\%foo} defines a label which is local to the
+particular macro call in which it is used, the usage \indexcode{\%\$}\code{\%\$foo}
+is used to define a label which is local to the context on the top
+of the context stack. So the \code{REPEAT} and \code{UNTIL} example given
+above could be implemented by means of:
+
+\begin{lstlisting}
+%macro repeat 0
+
+ %push repeat
+ %$begin:
+
+%endmacro
+
+%macro until 1
+
+ j%-1 %$begin
+ %pop
+
+%endmacro
+\end{lstlisting}
+
+and invoked by means of, for example,
+
+\begin{lstlisting}
+mov cx,string
+repeat
+add cx,3
+scasb
+until e
+\end{lstlisting}
+
+which would scan every fourth byte of a string in search of the byte
+in \code{AL}.
+
+If you need to define, or access, labels local to the context
+\emph{below} the top one on the stack, you can use
+\indexcode{\%\$\$}\code{\%\$\$foo}, or \code{\%\$\$\$foo} for
+the context below that, and so on.
+
+\xsubsection{ctxdefine}{\textindexlc{Context-Local Single-Line Macros}}
+
+NASM also allows you to define single-line macros which are local to
+a particular context, in just the same way:
+
+\begin{lstlisting}
+%define %$localmac 3
+\end{lstlisting}
+
+will define the single-line macro \code{\%\$localmac} to be local to the
+top context on the stack. Of course, after a subsequent \code{\%push},
+it can then still be accessed by the name \code{\%\$\$localmac}.
+
+\xsubsection{ctxfallthrough}{\textindexlc{Context Fall-Through Lookup} \emph{(deprecated)}}
+
+Context fall-through lookup (automatic searching of outer contexts)
+is a feature that was added in NASM version 0.98.03. Unfortunately,
+this feature is unintuitive and can result in buggy code that would
+have otherwise been prevented by NASM's error reporting. As a result,
+this feature has been \emph{deprecated}. NASM version 2.09 will issue a
+warning when usage of this \emph{deprecated} feature is detected. Starting
+with NASM version 2.10, usage of this \emph{deprecated} feature will simply
+result in an \emph{expression syntax error}.
+
+An example usage of this \emph{deprecated} feature follows:
+
+\begin{lstlisting}
+%macro ctxthru 0
+%push ctx1
+ %assign %$external 1
+ %push ctx2
+ %assign %$internal 1
+ mov eax, %$external
+ mov eax, %$internal
+ %pop
+%pop
+%endmacro
+\end{lstlisting}
+
+As demonstrated, \code{\%\$external} is being defined in the \code{ctx1}
+context and referenced within the \code{ctx2} context. With context
+fall-through lookup, referencing an undefined context-local macro
+like this implicitly searches through all outer contexts until a match
+is made or isn't found in any context. As a result, \code{\%\$external}
+referenced within the \code{ctx2} context would implicitly use \code{\%\$external}
+as defined in \code{ctx1}. Most people would expect NASM to issue an error in
+this situation because \code{\%\$external} was never defined within \code{ctx2}
+and also isn't qualified with the proper context depth, \code{\%\$\$external}.
+
+Here is a revision of the above example with proper context depth:
+
+\begin{lstlisting}
+%macro ctxthru 0
+%push ctx1
+ %assign %$external 1
+ %push ctx2
+ %assign %$internal 1
+ mov eax, %$$external
+ mov eax, %$internal
+ %pop
+%pop
+%endmacro
+\end{lstlisting}
+
+As demonstrated, \code{\%\$external} is still being defined in the \code{ctx1}
+context and referenced within the \code{ctx2} context. However, the
+reference to \code{\%\$external} within \code{ctx2} has been fully qualified with
+the proper context depth, \code{\%\$\$external}, and thus is no longer ambiguous,
+unintuitive or erroneous.
+
+\xsubsection{ctxrepl}{\codeindex{\%repl}: Renaming a Context}
+\index{context!rename}
+
+If you need to change the name of the top context on the stack (in
+order, for example, to have it respond differently to \code{\%ifctx}),
+you can execute a \code{\%pop} followed by a \code{\%push}; but this will
+have the side effect of destroying all context-local labels and
+macros associated with the context that was just popped.
+
+NASM provides the directive \code{\%repl}, which \emph{replaces} a context
+with a different name, without touching the associated macros and
+labels. So you could replace the destructive code
+
+\begin{lstlisting}
+%pop
+%push newname
+\end{lstlisting}
+
+with the non-destructive version \code{\%repl newname}.
+
+\xsubsection{blockif}{Example Use of the \textindexlc{Context Stack}:
+\textindexlc{Block IFs}}
+
+This example makes use of almost all the context-stack features,
+including the conditional-assembly construct \codeindex{\%ifctx}, to
+implement a block IF statement as a set of macros.
+
+\begin{lstlisting}
+%macro if 1
+
+ %push if
+ j%-1 %$ifnot
+
+%endmacro
+
+%macro else 0
+
+ %ifctx if
+ %repl else
+ jmp %$ifend
+ %$ifnot:
+ %else
+ %error "expected `if' before `else'"
+ %endif
+
+%endmacro
+
+%macro endif 0
+
+ %ifctx if
+ %$ifnot:
+ %pop
+ %elifctx else
+ %$ifend:
+ %pop
+ %else
+ %error "expected `if' or `else' before `endif'"
+ %endif
+
+%endmacro
+\end{lstlisting}
+
+This code is more robust than the \code{REPEAT} and \code{UNTIL} macros
+given in \nref{ctxlocal}, because it uses conditional assembly to check
+that the macros are issued in the right order (for example, not calling \code{endif}
+before \code{if}) and issues a \code{\%error} if they're not.
+
+In addition, the \code{endif} macro has to be able to cope with the two
+distinct cases of either directly following an \code{if}, or following
+an \code{else}. It achieves this, again, by using conditional assembly
+to do different things depending on whether the context on top of
+the stack is \code{if} or \code{else}.
+
+The \code{else} macro has to preserve the context on the stack, in
+order to have the \code{\%\$ifnot} referred to by the \code{if} macro be the
+same as the one defined by the \code{endif} macro, but has to change
+the context's name so that \code{endif} will know there was an
+intervening \code{else}. It does this by the use of \code{\%repl}.
+
+A sample usage of these macros might look like:
+
+\begin{lstlisting}
+cmp ax,bx
+
+if ae
+ cmp bx,cx
+
+ if ae
+ mov ax,cx
+ else
+ mov ax,bx
+ endif
+
+else
+ cmp ax,cx
+
+ if ae
+ mov ax,cx
+ endif
+
+endif
+\end{lstlisting}
+
+The block-\code{IF} macros handle nesting quite happily, by means of
+pushing another context, describing the inner \code{if}, on top of the
+one describing the outer \code{if}; thus \code{else} and \code{endif}
+always refer to the last unmatched \code{if} or \code{else}.
+
+\xsection{stackrel}{\textindexlc{Stack Relative Preprocessor Directives}}
+
+The following preprocessor directives provide a way to use
+labels to refer to local variables allocated on the stack:
+
+\begin{itemize}
+ \item{\code{\%arg} (see \nref{arg});}
+ \item{\code{\%stacksize} (see \nref{stacksize});}
+ \item{\code{\%local} (see \nref{local}).}
+\end{itemize}
+
+\xsubsection{arg}{\codeindex{\%arg} Directive}
+
+The \code{\%arg} directive is used to simplify the handling of
+parameters passed on the stack. Stack based parameter passing
+is used by many high level languages, including C, C++ and Pascal.
+
+While NASM has macros which attempt to duplicate this functionality
+(see \nref{16cmacro}), the syntax is not particularly convenient
+to use and is not TASM compatible. Here is an example which shows the use
+of \code{\%arg} without any external macros:
+
+\begin{lstlisting}
+some_function:
+
+ %push mycontext ; save the current context
+ %stacksize large ; tell NASM to use bp
+ %arg i:word, j_ptr:word
+
+ mov ax,[i]
+ mov bx,[j_ptr]
+ add ax,[bx]
+ ret
+
+ %pop ; restore original context
+\end{lstlisting}
+
+This is similar to the procedure defined in \nref{16cmacro}
+and adds the value in i to the value pointed to by j\_ptr and returns
+the sum in the ax register. See \nref{pushpop} for an
+explanation of \code{push} and \code{pop} and the use of context stacks.
+
+\xsubsection{stacksize}{\codeindex{\%stacksize} Directive}
+
+The \code{\%stacksize} directive is used in conjunction with the
+\code{\%arg} (see \nref{arg}) and the \code{\%local}
+(see \nref{local}) directives. It tells NASM the default
+size to use for subsequent \code{\%arg} and \code{\%local} directives.
+The \code{\%stacksize} directive takes one required argument
+which is one of \code{flat}, \code{flat64}, \code{large} or \code{small}.
+
+\begin{lstlisting}
+%stacksize flat
+\end{lstlisting}
+
+This form causes NASM to use stack-based parameter addressing
+relative to \code{ebp} and it assumes that a near form of call
+was used to get to this label (i.e. that \code{eip} is on the stack).
+
+\begin{lstlisting}
+%stacksize flat64
+\end{lstlisting}
+
+This form causes NASM to use stack-based parameter addressing
+relative to \code{rbp} and it assumes that a near form of call was used
+to get to this label (i.e. that \code{rip} is on the stack).
+
+\begin{lstlisting}
+%stacksize large
+\end{lstlisting}
+
+This form uses \code{bp} to do stack-based parameter addressing and
+assumes that a far form of call was used to get to this address
+(i.e. that \code{ip} and \code{cs} are on the stack).
+
+\begin{lstlisting}
+%stacksize small
+\end{lstlisting}
+
+This form also uses \code{bp} to address stack parameters, but it is
+different from \code{large} because it also assumes that the old value
+of bp is pushed onto the stack (i.e. it expects an \code{ENTER}
+instruction). In other words, it expects that \code{bp}, \code{ip} and
+\code{cs} are on the top of the stack, underneath any local space which
+may have been allocated by \code{ENTER}. This form is probably most
+useful when used in combination with the \code{\%local} directive
+(see \nref{local}).
+
+\xsubsection{local}{\codeindex{\%local} Directive}
+
+The \code{\%local} directive is used to simplify the use of local
+temporary stack variables allocated in a stack frame. Automatic
+local variables in C are an example of this kind of variable. The
+\code{\%local} directive is most useful when used with the \code{\%stacksize}
+(see \nref{stacksize} and is also compatible with the \code{\%arg} directive
+(see \nref{arg}). It allows simplified reference to variables on the
+stack which have been allocated typically by using the \code{ENTER}
+instruction.
+% (see \nref{insENTER} for a description of that instruction).
+An example of its use is the following:
+
+\begin{lstlisting}
+silly_swap:
+
+ %push mycontext ; save the current context
+ %stacksize small ; tell NASM to use bp
+ %assign %$localsize 0 ; see text for explanation
+ %local old_ax:word, old_dx:word
+
+ enter %$localsize,0 ; see text for explanation
+ mov [old_ax],ax ; swap ax & bx
+ mov [old_dx],dx ; and swap dx & cx
+ mov ax,bx
+ mov dx,cx
+ mov bx,[old_ax]
+ mov cx,[old_dx]
+ leave ; restore old bp
+ ret ;
+
+ %pop ; restore original context
+\end{lstlisting}
+
+The \code{\%\$localsize} variable is used internally by the
+\code{\%local} directive and \emph{must} be defined within the
+current context before the \code{\%local} directive may be used.
+Failure to do so will result in one expression syntax error for
+each \code{\%local} variable declared. It then may be used in
+the construction of an appropriately sized ENTER instruction
+as shown in the example.
+
+\xsection{pperror}{Reporting \textindexlc{User-Defined Errors}:
+\codeindex{\%error}, \codeindex{\%warning}, \codeindex{\%fatal}}
+
+The preprocessor directive \code{\%error} will cause NASM to report an
+error if it occurs in assembled code. So if other users are going to
+try to assemble your source files, you can ensure that they define the
+right macros by means of code like this:
+
+\begin{lstlisting}
+%ifdef F1
+ ; do some setup
+%elifdef F2
+ ; do some different setup
+%else
+ %error "Neither F1 nor F2 was defined."
+%endif
+\end{lstlisting}
+
+Then any user who fails to understand the way your code is supposed
+to be assembled will be quickly warned of their mistake, rather than
+having to wait until the program crashes on being run and then not
+knowing what went wrong.
+
+Similarly, \code{\%warning} issues a warning, but allows assembly to continue:
+
+\begin{lstlisting}
+%ifdef F1
+ ; do some setup
+%elifdef F2
+ ; do some different setup
+%else
+ %warning "Neither F1 nor F2 was defined, assuming F1."
+ %define F1
+%endif
+\end{lstlisting}
+
+\code{\%error} and \code{\%warning} are issued only on the final assembly
+pass. This makes them safe to use in conjunction with tests that
+depend on symbol values.
+
+\code{\%fatal} terminates assembly immediately, regardless of pass. This
+is useful when there is no point in continuing the assembly further,
+and doing so is likely just going to cause a spew of confusing error
+messages.
+
+It is optional for the message string after \code{\%error}, \code{\%warning}
+or \code{\%fatal} to be quoted. If it is \emph{not}, then single-line macros
+are expanded in it, which can be used to display more information to
+the user. For example:
+
+\begin{lstlisting}
+%if foo > 64
+ %assign foo_over foo-64
+ %error foo is foo_over bytes too large
+%endif
+\end{lstlisting}
+
+\xsection{otherpreproc}{\textindexlc{Other Preprocessor Directives}}
+
+\xsubsection{line}{\codeindex{\%line} Directive}
+
+The \code{\%line} directive is used to notify NASM that the input line
+corresponds to a specific line number in another file. Typically
+this other file would be an original source file, with the current
+NASM input being the output of a pre-processor. The \code{\%line}
+directive allows NASM to output messages which indicate the line
+number of the original source file, instead of the file that is being
+read by NASM.
+
+This preprocessor directive is not generally used directly by
+programmers, but may be of interest to preprocessor authors. The
+usage of the \code{\%line} preprocessor directive is as follows:
+
+\begin{lstlisting}
+%line nnn[+mmm] [filename]
+\end{lstlisting}
+
+In this directive, \code{nnn} identifies the line of the original source
+file which this line corresponds to. \code{mmm} is an optional parameter
+which specifies a line increment value; each line of the input file
+read in is considered to correspond to \code{mmm} lines of the original
+source file. Finally, \code{filename} is an optional parameter which
+specifies the file name of the original source file.
+
+After reading a \code{\%line} preprocessor directive, NASM will report
+all file name and line numbers relative to the values specified
+therein.
+
+If the command line option \codeindex{--no-line} is given, all \code{\%line}
+directives are ignored. This may be useful for debugging preprocessed
+code. See \nref{opt-no-line}.
+
+\xsubsection{getenv}{\codeindex{\%^^21\emph{variable}}: Read an Environment Variable}
+
+The \code{\%^^21\emph{variable}} directive makes it possible to read the
+value of an environment variable at assembly time. This could, for example,
+be used to store the contents of an environment variable into a string, which
+could be used at some other point in your code.
+
+For example, suppose that you have an environment variable \code{FOO},
+and you want the contents of \code{FOO} to be embedded in your program as
+a quoted string. You could do that as follows:
+
+\begin{lstlisting}
+%defstr FOO %!FOO
+\end{lstlisting}
+
+See \nref{defstr} for notes on the \code{\%defstr} directive.
+
+If the name of the environment variable contains non-identifier
+characters, you can use string quotes to surround the name of the
+variable, for example:
+
+\begin{lstlisting}
+%defstr C_colon %!'C:'
+\end{lstlisting}
+
+\xsection{stdmac}{\textindexlc{Standard Macros}}
+
+NASM defines a set of standard macros, which are already defined
+when it starts to process any source file. If you really need a
+program to be assembled with no pre-defined macros, you can use the
+\codeindex{\%clear} directive to empty the preprocessor of everything
+but context-local preprocessor variables and single-line macros.
+
+Most \textindex{user-level assembler directives} are implemented as macros
+which invoke primitive directives; these are described in \nref{directive}.
+The rest of the standard macro set is described here.
+
+\xsubsection{stdmacver}{\textindexlc{NASM Version} Macros}
+
+The single-line macros \codeindex{\_\_NASM\_MAJOR\_\_}, \codeindex{\_\_NASM\_MINOR\_\_},
+\codeindex{\_\_NASM\_SUBMINOR\_\_} and \codeindex{\_\_NASM\_PATCHLEVEL\_\_} expand to
+the major, minor, subminor and patch level parts of the \textindexlc{version number of NASM}
+being used. So, under NASM 0.98.32p1 for example, \code{\_\_NASM\_MAJOR\_\_}
+would be defined to be 0, \code{\_\_NASM\_MINOR\_\_} would be defined as 98,
+\code{\_\_NASM\_SUBMINOR\_\_} would be defined to 32, and \code{\_\_NASM\_PATCHLEVEL\_\_}
+would be defined as 1.
+
+Additionally, the macro \codeindex{\_\_NASM\_SNAPSHOT\_\_} is defined for
+automatically generated snapshot releases \emph{only}.
+
+\xsubsection{stdmacverid}{\codeindex{\_\_NASM\_VERSION\_ID\_\_}:
+\textindexlc{NASM Version ID}}
+
+The single-line macro \code{\_\_NASM\_VERSION\_ID\_\_} expands to a dword integer
+representing the full version number of the version of nasm being used.
+The value is the equivalent to \code{\_\_NASM\_MAJOR\_\_}, \code{\_\_NASM\_MINOR\_\_},
+\code{\_\_NASM\_SUBMINOR\_\_} and \code{\_\_NASM\_PATCHLEVEL\_\_} concatenated to
+produce a single doubleword. Hence, for 0.98.32p1, the returned number
+would be equivalent to:
+
+\begin{lstlisting}
+dd 0x00622001
+\end{lstlisting}
+
+or
+
+\begin{lstlisting}
+db 1,32,98,0
+\end{lstlisting}
+
+Note that the above lines are generate exactly the same code, the second
+line is used just to give an indication of the order that the separate
+values will be present in memory.
+
+
+\xsubsection{stdmacverstr}{\codeindex{\_\_NASM\_VER\_\_}:
+\textindexlc{NASM Version string}}
+
+The single-line macro \code{\_\_NASM\_VER\_\_} expands to a string which defines
+the version number of nasm being used. So, under NASM 0.98.32 for example,
+
+\begin{lstlisting}
+db __NASM_VER__
+\end{lstlisting}
+
+would expand to
+
+\begin{lstlisting}
+db "0.98.32"
+\end{lstlisting}
+
+\xsubsection{fileline}{\codeindex{\_\_FILE\_\_} and \codeindex{\_\_LINE\_\_}:
+File Name and Line Number}
+
+Like the C preprocessor, NASM allows the user to find out the file
+name and line number containing the current instruction. The macro
+\code{\_\_FILE\_\_} expands to a string constant giving the name of the
+current input file (which may change through the course of assembly
+if \code{\%include} directives are used), and \code{\_\_LINE\_\_} expands
+to a numeric constant giving the current line number in the input file.
+
+These macros could be used, for example, to communicate debugging
+information to a macro, since invoking \code{\_\_LINE\_\_} inside a macro
+definition (either single-line or multi-line) will return the line
+number of the macro \emph{call}, rather than \emph{definition}. So to
+determine where in a piece of code a crash is occurring, for example,
+one could write a routine \code{stillhere}, which is passed a line number
+in \code{EAX} and outputs something like "line 155: still here".
+You could then write a macro
+
+\begin{lstlisting}
+%macro notdeadyet 0
+ push eax
+ mov eax,__LINE__
+ call stillhere
+ pop eax
+%endmacro
+\end{lstlisting}
+
+and then pepper your code with calls to \c{notdeadyet} until you
+find the crash point.
+
+\xsubsection{bitsm}{\codeindex{\_\_BITS\_\_}: Current BITS Mode}
+
+The \code{\_\_BITS\_\_} standard macro is updated every time that the BITS
+mode is set using the \code{BITS XX} or \code{[BITS XX]} directive,
+where XX is a valid mode number of 16, 32 or 64. \code{\_\_BITS\_\_} receives
+the specified mode number and makes it globally available. This can be very
+useful for those who utilize mode-dependent macros.
+
+\xsubsection{ofmtm}{\codeindex{\_\_OUTPUT\_FORMAT\_\_}: Current Output Format}
+
+The \code{\_\_OUTPUT\_FORMAT\_\_} standard macro holds the current output
+format name, as given by the \code{-f} option or NASM's default. Type
+\code{nasm -hf} for a list.
+
+\begin{lstlisting}
+%ifidn __OUTPUT_FORMAT__, win32
+ %define NEWLINE 13, 10
+%elifidn __OUTPUT_FORMAT__, elf32
+ %define NEWLINE 10
+%endif
+\end{lstlisting}
+
+\xsubsection{dfmtm}{\codeindex{\_\_DEBUG\_FORMAT\_\_}:
+Current Debug Format}
+
+If debugging information generation is enabled, The
+\code{\_\_DEBUG\_FORMAT\_\_} standard macro holds the current
+debug format name as specified by the \code{-F} or \code{-g} option
+or the output format default. Type \code{nasm -f} \emph{output}
+\code{y} for a list.
+
+\code{\_\_DEBUG\_FORMAT\_\_} is not defined if debugging is not
+enabled, or if the debug format specified is \code{null}.
+
+\xsubsection{datetime}{Assembly Date and Time Macros}
+
+NASM provides a variety of macros that represent the timestamp of the
+assembly session.
+
+\begin{itemize}
+ \item{The \codeindex{\_\_DATE\_\_} and \codeindex{\_\_TIME\_\_}
+ macros give the assembly date and time as strings, in ISO 8601
+ format (\code{"YYYY-MM-DD"} and \code{"HH:MM:SS"}, respectively).}
+
+ \item{The \codeindex{\_\_DATE\_NUM\_\_} and \codeindex{\_\_TIME\_NUM\_\_}
+ macros give the assembly date and time in numeric form; in the format
+ \code{YYYYMMDD} and \code{HHMMSS} respectively.}
+
+ \item{The \codeindex{\_\_UTC\_DATE\_\_} and \codeindex{\_\_UTC\_TIME\_\_}
+ macros give the assembly date and time in universal time (UTC) as strings,
+ in ISO 8601 format (\code{"YYYY-MM-DD"} and \code{"HH:MM:SS"}, respectively).
+ If the host platform doesn't provide UTC time, these macros are undefined.}
+
+ \item{The \codeindex{\_\_UTC\_DATE\_NUM\_\_} and \codeindex{\_\_UTC\_TIME\_NUM\_\_}
+ macros give the assembly date and time universal time (UTC) in numeric form;
+ in the format \code{YYYYMMDD} and \code{HHMMSS} respectively. If the
+ host platform doesn't provide UTC time, these macros are undefined.}
+
+ \item{The \code{\_\_POSIX\_TIME\_\_} macro is defined as a number containing
+ the number of seconds since the POSIX epoch, 1 January 1970 00:00:00 UTC;
+ excluding any leap seconds. This is computed using UTC time if
+ available on the host platform, otherwise it is computed using the
+ local time as if it was UTC.}
+\end{itemize}
+
+All instances of time and date macros in the same assembly session
+produce consistent output. For example, in an assembly session
+started at 42 seconds after midnight on January 1, 2010 in Moscow
+(timezone UTC+3) these macros would have the following values,
+assuming, of course, a properly configured environment with a correct
+clock:
+
+\begin{lstlisting}
+__DATE__ "2010-01-01"
+__TIME__ "00:00:42"
+__DATE_NUM__ 20100101
+__TIME_NUM__ 000042
+__UTC_DATE__ "2009-12-31"
+__UTC_TIME__ "21:00:42"
+__UTC_DATE_NUM__ 20091231
+__UTC_TIME_NUM__ 210042
+__POSIX_TIME__ 1262293242
+\end{lstlisting}
+
+\xsubsection{usedef}{\indexcode{\_\_USE\_*\_\_}\code{\_\_USE\_}
+\emph{package}\code{\_\_}: Package Include Test}
+
+When a standard macro package (see \nref{macropkg}) is included with the
+\code{\%use} directive (see \nref{use}), a single-line macro of
+the form \code{\_\_USE\_}\emph{package}\code{\_\_} is automatically defined.
+This allows testing if a particular package is invoked or not.
+
+For example, if the \code{altreg} package is included (see \nref{pkgaltreg}),
+then the macro \code{\_\_USE\_ALTREG\_\_} is defined.
+
+\xsubsection{passdef}{\codeindex{\_\_PASS\_\_}: Assembly Pass}
+
+The macro \code{\_\_PASS\_\_} is defined to be \code{1} on preparatory passes,
+and \code{2} on the final pass. In preprocess-only mode, it is set to
+\code{3}, and when running only to generate dependencies (due to the
+\code{-M} or \code{-MG} option, see \nref{opt-M}) it is set to \code{0}.
+
+\emph{Avoid using this macro if at all possible. It is tremendously easy
+to generate very strange errors by misusing it, and the semantics may
+change in future versions of NASM.}
+
+\xsubsection{struc}{\codeindex{STRUC} and \codeindex{ENDSTRUC}:
+\textindexlc{Declaring Structure} Data Types}
+
+The core of NASM contains no intrinsic means of defining data
+structures; instead, the preprocessor is sufficiently powerful that
+data structures can be implemented as a set of macros. The macros
+\code{STRUC} and \code{ENDSTRUC} are used to define a structure
+data type.
+
+\code{STRUC} takes one or two parameters. The first parameter is the name
+of the data type. The second, optional parameter is the base offset of
+the structure. The name of the data type is defined as a symbol with
+the value of the base offset, and the name of the data type with the
+suffix \code{\_size} appended to it is defined as an \code{EQU} giving
+the size of the structure. Once \code{STRUC} has been issued, you are
+defining the structure, and should define fields using the \code{RESB}
+family of pseudo-instructions, and then invoke \code{ENDSTRUC} to finish
+the definition.
+
+For example, to define a structure called \code{mytype} containing a
+longword, a word, a byte and a string of bytes, you might code
+
+\begin{lstlisting}
+struc mytype
+ mt_long: resd 1
+ mt_word: resw 1
+ mt_byte: resb 1
+ mt_str: resb 32
+endstruc
+\end{lstlisting}
+
+The above code defines six symbols: \code{mt\_long} as 0 (the offset
+from the beginning of a \code{mytype} structure to the longword field),
+\code{mt\_word} as 4, \code{mt\_byte} as 6, \code{mt\_str} as 7,
+\code{mytype\_size} as 39, and \code{mytype} itself as zero.
+
+The reason why the structure type name is defined at zero by default
+is a side effect of allowing structures to work with the local label
+mechanism: if your structure members tend to have the same names in
+more than one structure, you can define the above structure like this:
+
+\begin{lstlisting}
+struc mytype
+ .long: resd 1
+ .word: resw 1
+ .byte: resb 1
+ .str: resb 32
+endstruc
+\end{lstlisting}
+
+This defines the offsets to the structure fields as \code{mytype.long},
+\code{mytype.word}, \code{mytype.byte} and \code{mytype.str}.
+
+NASM, since it has no \emph{intrinsic} structure support, does not
+support any form of period notation to refer to the elements of a
+structure once you have one (except the above local-label notation),
+so code such as \code{mov ax,[mystruc.mt\_word]} is not valid.
+\code{mt\_word} is a constant just like any other constant, so the
+correct syntax is \code{mov ax,[mystruc+mt\_word]} or
+\code{mov ax,[mystruc+mytype.word]}.
+
+Sometimes you only have the address of the structure displaced by an
+offset. For example, consider this standard stack frame setup:
+
+\begin{lstlisting}
+push ebp
+mov ebp, esp
+sub esp, 40
+\end{lstlisting}
+
+In this case, you could access an element by subtracting the offset:
+
+\begin{lstlisting}
+mov [ebp - 40 + mytype.word], ax
+\end{lstlisting}
+
+However, if you do not want to repeat this offset, you can use -40 as
+a base offset:
+
+\begin{lstlisting}
+struc mytype, -40
+\end{lstlisting}
+
+And access an element this way:
+
+\begin{lstlisting}
+mov [ebp + mytype.word], ax
+\end{lstlisting}
+
+\xsubsection{istruc}{\codeindex{ISTRUC}, \codeindex{AT} and
+\codeindex{IEND}: Declaring}
+\textindexlc{Instances of Structures}
+
+Having defined a structure type, the next thing you typically want
+to do is to declare instances of that structure in your data
+segment. NASM provides an easy way to do this in the \code{ISTRUC}
+mechanism. To declare a structure of type \code{mytype} in a program,
+you code something like this:
+
+\begin{lstlisting}
+mystruc:
+ istruc mytype
+ at mt_long, dd 123456
+ at mt_word, dw 1024
+ at mt_byte, db 'x'
+ at mt_str, db 'hello, world', 13, 10, 0
+ iend
+\end{lstlisting}
+
+The function of the \code{AT} macro is to make use of the \code{TIMES}
+prefix to advance the assembly position to the correct point for the
+specified structure field, and then to declare the specified data.
+Therefore the structure fields must be declared in the same order as
+they were specified in the structure definition.
+
+If the data to go in a structure field requires more than one source
+line to specify, the remaining source lines can easily come after
+the \code{AT} line. For example:
+
+\begin{lstlisting}
+at mt_str, db 123,134,145,156,167,178,189
+ db 190,100,0
+\end{lstlisting}
+
+Depending on personal taste, you can also omit the code part of the
+\code{AT} line completely, and start the structure field on the next
+line:
+
+\begin{lstlisting}
+at mt_str
+ db 'hello, world'
+ db 13,10,0
+\end{lstlisting}
+
+\xsubsection{align}{\codeindex{ALIGN} and \codeindex{ALIGNB}: Data Alignment}
+
+The \code{ALIGN} and \code{ALIGNB} macros provides a convenient way to
+align code or data on a word, longword, paragraph or other boundary.
+Some assemblers call this directive \codeindex{EVEN}. The syntax of the
+\code{ALIGN} and \code{ALIGNB} macros is
+
+\begin{lstlisting}
+align 4 ; align on 4-byte boundary
+align 16 ; align on 16-byte boundary
+align 8,db 0 ; pad with 0s rather than NOPs
+align 4,resb 1 ; align to 4 in the BSS
+alignb 4 ; equivalent to previous line
+\end{lstlisting}
+
+Both macros require their first argument to be a power of two; they
+both compute the number of additional bytes required to bring the
+length of the current section up to a multiple of that power of two,
+and then apply the \code{TIMES} prefix to their second argument to
+perform the alignment.
+
+If the second argument is not specified, the default for \code{ALIGN}
+is \code{NOP}, and the default for \code{ALIGNB} is \code{RESB 1}.
+So if the second argument is specified, the two macros are equivalent.
+Normally, you can just use \code{ALIGN} in code and data sections and
+\code{ALIGNB} in BSS sections, and never need the second argument
+except for special purposes.
+
+\code{ALIGN} and \code{ALIGNB}, being simple macros, perform no error
+checking: they cannot warn you if their first argument fails to be a
+power of two, or if their second argument generates more than one
+byte of code. In each of these cases they will silently do the wrong
+thing.
+
+\code{ALIGNB} (or \code{ALIGN} with a second argument of \code{RESB 1})
+can be used within structure definitions:
+
+\begin{lstlisting}
+struc mytype2
+ mt_byte:
+ resb 1
+ alignb 2
+ mt_word:
+ resw 1
+ alignb 4
+ mt_long:
+ resd 1
+ mt_str:
+ resb 32
+endstruc
+\end{lstlisting}
+
+This will ensure that the structure members are sensibly aligned
+relative to the base of the structure.
+
+A final caveat: \code{ALIGN} and \code{ALIGNB} work relative to the
+beginning of the \emph{section}, not the beginning of the address space
+in the final executable. Aligning to a 16-byte boundary when the
+section you're in is only guaranteed to be aligned to a 4-byte
+boundary, for example, is a waste of effort. Again, NASM does not
+check that the section's alignment characteristics are sensible for
+the use of \code{ALIGN} or \code{ALIGNB}.
+
+Both \code{ALIGN} and \code{ALIGNB} do call \code{SECTALIGN} macro implicitly.
+See \nref{sectalign} for details.
+
+See also the \code{smartalign} standard macro package, \nref{pkgsmartalign}.
+
+\xsubsection{sectalign}{\codeindex{SECTALIGN}: Section Alignment}
+
+The \code{SECTALIGN} macros provides a way to modify alignment attribute
+of output file section. Unlike the \code{align=} attribute (which is allowed
+at section definition only) the \code{SECTALIGN} macro may be used at any time.
+
+For example the directive
+
+\begin{lstlisting}
+SECTALIGN 16
+\end{lstlisting}
+
+sets the section alignment requirements to 16 bytes. Once increased it can
+not be decreased, the magnitude may grow only.
+
+Note that \code{ALIGN} (see \nref{align}) calls the \code{SECTALIGN}
+macro implicitly so the active section alignment requirements may be updated.
+This is by default behaviour, if for some reason you want the \code{ALIGN}
+do not call \code{SECTALIGN} at all use the directive
+
+\begin{lstlisting}
+SECTALIGN OFF
+\end{lstlisting}
+
+It is still possible to turn in on again by
+
+\begin{lstlisting}
+SECTALIGN ON
+\end{lstlisting}
diff --git a/doc/latex/src/running.tex b/doc/latex/src/running.tex
new file mode 100644
index 00000000..9cd0d363
--- /dev/null
+++ b/doc/latex/src/running.tex
@@ -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.
diff --git a/doc/latex/src/source.tex b/doc/latex/src/source.tex
new file mode 100644
index 00000000..32323f76
--- /dev/null
+++ b/doc/latex/src/source.tex
@@ -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.
diff --git a/doc/latex/src/trouble.tex b/doc/latex/src/trouble.tex
new file mode 100644
index 00000000..b129780f
--- /dev/null
+++ b/doc/latex/src/trouble.tex
@@ -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.
diff --git a/doc/latex/src/version.tex b/doc/latex/src/version.tex
new file mode 100644
index 00000000..607821ae
--- /dev/null
+++ b/doc/latex/src/version.tex
@@ -0,0 +1,4 @@
+%
+% vim: ts=4 sw=4 et
+%
+\newcommand{\version}{2.14.01-272-gb3f7c8eb}