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