1 files changed, 127 insertions, 0 deletions
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.