aboutsummaryrefslogtreecommitdiffstats
path: root/doc/latex/src/macropkg.tex
diff options
context:
space:
mode:
authorCyrill Gorcunov <gorcunov@gmail.com>2019-03-31 19:33:08 +0300
committerCyrill Gorcunov <gorcunov@gmail.com>2019-03-31 19:34:50 +0300
commita384068a04a5cf92a4564fa39b061b7539cb94f9 (patch)
tree711eb1fdc3892eb6f966b5418d3f2a4917aa078b /doc/latex/src/macropkg.tex
parent982186a1a3139763f2aa2710b32236009f64270d (diff)
downloadnasm-a384068a04a5cf92a4564fa39b061b7539cb94f9.tar.gz
nasm-a384068a04a5cf92a4564fa39b061b7539cb94f9.tar.xz
nasm-a384068a04a5cf92a4564fa39b061b7539cb94f9.zip
doc: latex -- Initial importlatex
It is an initial import for conversion of our documentation to latex format. Note that latex additional packages needs to be preinstalled, xelatex is used for pdf generation. While I've been very carefull while converting the docs there is a big probability that some indices might be screwed so we need to review everything once again. Then we need to create a converter for html backend, I started working on it but didn't successed yet and I fear won't have enough spare time in near future. Also we need to autogenerate instruction table and warnings from insns.dat and probably from scanning nasm sources. To build nasm.pdf just run make -C doc/latex/ it doesn't require configuration and rather a standalone builder out of our traditional build engine. Signed-off-by: Cyrill Gorcunov <gorcunov@gmail.com>
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.