aboutsummaryrefslogtreecommitdiffstats
path: root/doc/latex/src/macropkg.tex
diff options
context:
space:
mode:
Diffstat (limited to 'doc/latex/src/macropkg.tex')
-rw-r--r--doc/latex/src/macropkg.tex127
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.