NASM - The Netwide Assembler

Chapter 6: Standard Macro Packages

The %use directive (see section 4.8.4) includes one of the standard macro packages included with the NASM distribution and compiled into the NASM binary. It operates like the %include directive (see section 4.8.1), but the included contents is provided by NASM itself.

The names of standard macro packages are case insensitive and can be quoted or not.

As of version 2.15, NASM has %ifusable and %ifusing directives to help the user understand whether an individual package available in this version of NASM (%ifusable) or a particular package already loaded (%ifusing).

6.1 `altreg`: Alternate Register Names

The altreg standard macro package provides alternate register names. It provides numeric register names for all registers (not just R8–R15), the Intel-defined aliases R8L–R15L for the low bytes of register (as opposed to the NASM/AMD standard names R8B–R15B), and the names R0H–R3H (by analogy with R0L–R3L) for AH, CH, DH, and BH.

Example use:

%use altreg 

proc: 
      mov r0l,r3h                    ; mov al,bh 
      ret

6.2 `smartalign`: Smart `ALIGN` Macro

The smartalign standard macro package provides for an ALIGN macro which is more powerful than the default (and backwards-compatible) one (see section 5.10.1). When the smartalign package is enabled, when ALIGN is used without a second argument, NASM will generate a sequence of instructions more efficient than a series of 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 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 nojmp). The following modes are possible:

generic: Works on all x86 CPUs and should have reasonable performance. The default jump threshold is 8. This is the default.
nop: Pad out with NOP instructions. The only difference compared to the standard ALIGN macro is that NASM can still jump over a large padding area. The default jump threshold is 16.
k7: Optimize for the AMD K7 (Athlon/Althon XP). These instructions should still work on all x86 CPUs. The default jump threshold is 16.
k8: Optimize for the AMD K8 (Opteron/Althon 64). These instructions should still work on all x86 CPUs. The default jump threshold is 16.
p6: Optimize for Intel CPUs. This uses the long 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.

The macro __?ALIGNMODE?__ is defined to contain the current alignment mode. A number of other macros beginning with __?ALIGN_ are used internally by this macro package.

6.3 `fp`: Floating-point macros

This packages contains the following floating-point convenience macros:

%define Inf             __?Infinity?__ 
%define NaN             __?QNaN?__ 
%define QNaN            __?QNaN?__ 
%define SNaN            __?SNaN?__ 

%define float8(x)       __?float8?__(x) 
%define float16(x)      __?float16?__(x) 
%define bfloat16(x)     __?bfloat16?__(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)

It also defines the a multi-line macro bf16 that can be used in a similar way to the Dx directives for the other floating-point numbers:

     bf16 -3.1415, NaN, 2000.0, +Inf

6.4 `ifunc`: 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.

The macros provided are:

6.4.1 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 ilog2e() (alias ilog2()) generates an error if the argument is not a power of two.

The function ilog2f() rounds the argument down to the nearest power of two; if the argument is zero it returns zero.

The function ilog2c() rounds the argument up to the nearest power of two.

The functions ilog2fw() (alias ilog2w()) and ilog2cw() generate a warning if the argument is not a power of two, but otherwise behaves like ilog2f() and ilog2c(), respectively.

6.5 `masm`: MASM compatibility

Since version 2.15, NASM has a MASM compatibility package with minimal functionality, as intended to be used primarily with machine-generated code. It does not include any "programmer-friendly" shortcuts, nor does it in any way support ASSUME, symbol typing, or MASM-style structures.

To enable the package, use the directive:

%use masm

Currently, the MASM compatibility package emulates:

The FLAT and OFFSET keywords are recognized and ignored.

The PTR keyword signifies a memory reference, as if the argument had been put in square brackets:

     mov eax,[foo]               ; memory reference 
     mov eax,dword ptr foo       ; memory reference 
     mov eax,dowrd ptr flat:foo  ; memory reference 
     mov eax,offset foo          ; address 
     mov eax,foo                 ; address (ambiguous syntax in MASM)

The SEGMENT ... ENDS syntax:

   segname SEGMENT 
       ... 
   segname ENDS

The PROC ... ENDP syntax:
```
   procname PROC [FAR] 
        ... 
   procname ENDP
```
PROC will also define RET as a macro expanding to either RETF if FAR is specified and RETN otherwise. Any keyword after PROC other than FAR is ignored.
The TBYTE keyword as an alias for TWORD (see section 2.2.7).
The END directive is ignored.
In 64-bit mode relative addressing is the default (DEFAULT REL, see section 7.2.1).

In addition, NASM now natively supports, regardless of whether this package is used or not:

? and DUP syntax for the DB etc data declaration directives (see section 3.2.1).
displacement[base+index] syntax for memory operations, instead of [base+index+displacement].
seg:[addr] instead of [seg:addr] syntax.

A pure offset can be given to LEA without square brackets:

     lea rax,[foo]               ; standard syntax 
     lea rax,foo                 ; also accepted

NASM - The Netwide Assembler

Chapter 6: Standard Macro Packages

6.1 altreg: Alternate Register Names

6.2 smartalign: Smart ALIGN Macro

6.3 fp: Floating-point macros