NASM

https://www.nasm.us/docs/3.01/
Admin
This documentation provides a comprehensive guide to the NASM (Netwide Assembler) language, its...
Tokens:170,762
Snippets:1,509
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### NASM %map() Expansion Example

Source: https://www.nasm.us/docs/3.01/nasm05.html

Shows the expanded output of the %map() function examples.

```nasm
      db 'foo','bar','baz','quux' 
      db bar dup ('foo'),quux dup ('baz') 
      db bar dup ('foo',"!"),quux dup ('baz',"!")
```

--------------------------------

### NASM %map() Function Examples

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates the usage of the %map() function with different parameter groupings and fixed parameters.

```nasm
%define alpha(&x)     x 
%define alpha(&x,y)   y dup (x) 
%define alpha(s,&x,y) y dup (x,s) 
; 0 fixed + 1 grouped parameters per call, calls alpha(&x) 
      db %map(alpha,foo,bar,baz,quux) 
; 0 fixed + 2 grouped parameters per call, calls alpha(&x,y) 
      db %map(alpha::2,foo,bar,baz,quux) 
; 1 fixed + 2 grouped parameters per call, calls alpha(s,&x,y) 
      db %map(alpha:("!")::2,foo,bar,baz,quux)
```

--------------------------------

### Build Windows Installer

Source: https://www.nasm.us/docs/3.01/nasmad.html

Command to build the installer package for the Windows platform using NSIS.

```shell
make nsis
```

--------------------------------

### Assembling a .COM File with NASM

Source: https://www.nasm.us/docs/3.01/nasm10.html

Command-line example for assembling a NASM source file into a .COM executable using the 'bin' format.

```Shell
nasm myprog.asm -fbin -o myprog.com
```

--------------------------------

### NASM %realpath() and %pathsearch() Example

Source: https://www.nasm.us/docs/3.01/nasm05.html

Shows how to use %realpath() in conjunction with %pathsearch() to resolve file paths.

```nasm
%define SOMEREALPATH %realpath(%pathsearch("somefile.asm"))
```

--------------------------------

### NASM Basic Memory Address Examples

Source: https://www.nasm.us/docs/3.01/nasm03.html

Demonstrates basic effective address syntax in NASM using variables and register offsets. These examples show how to reference memory locations with direct variable names, offsets from variables, and combinations of segment registers and base registers.

```assembly
wordvar dw      123 
        mov     ax,[wordvar] 
        mov     ax,[wordvar+1] 
        mov     ax,[es:wordvar+bx]
```

--------------------------------

### Re-use Setup Code as Data Storage with ABSOLUTE

Source: https://www.nasm.us/docs/3.01/nasm08.html

Employ ABSOLUTE with an expression to allow a TSR's setup code space to be re-used as runtime data storage after execution.

```assembly
        org     100h               ; it's a .COM program 

        jmp     setup              ; setup code comes last 

        ; the resident part of the TSR goes here 
setup:
        ; now write the code that installs the TSR here 

absolute setup 

runtimevar1     resw    1 
runtimevar2     resd    20 

tsr_end:

```

--------------------------------

### Assemble to Raw Binary File

Source: https://www.nasm.us/docs/3.01/nasm02.html

Example of assembling a file into a raw binary file. The output file is explicitly named 'myfile.com' using the -o option.

```bash
nasm -f bin myfile.asm -o myfile.com
```

--------------------------------

### Assemble to 32-bit ELF Object File

Source: https://www.nasm.us/docs/3.01/nasm02.html

Example of assembling a file into a 32-bit ELF object file. The output will be named 'myfile.o'.

```bash
nasm -f elf myfile.asm
```

--------------------------------

### NASM %map() String Concatenation Expansion

Source: https://www.nasm.us/docs/3.01/nasm05.html

Displays the result of the %map() string concatenation example.

```nasm
      db '' 
      db 'a' 
      db 'a:b' 
      db 'a:b:c' 
      db 'a:b:c:d'
```

--------------------------------

### Macro Definition and Expansion Example

Source: https://www.nasm.us/docs/3.01/nasmac.html

Demonstrates the behavior of %define within macros and how %$name macros are expanded, ensuring correct expansion of macro arguments.

```Assembly
%macro  abc     1 
             %define %1 hello 
     %endm 

     abc     %$here 
     %$here
```

--------------------------------

### NASM %sel() Function Example

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates the %sel() function for conditional expansion based on an expression's value.

```nasm
%define b 2 
%xdefine bstr %sel(b,"one","two","three") ; %define bstr "two"
```

--------------------------------

### NASM: Boot Sector ORG Directive Example

Source: https://www.nasm.us/docs/3.01/nasm14.html

Demonstrates the correct usage of the ORG directive for boot sector programs in NASM, contrasting it with the MASM approach.

```assembly
        ORG 0 

        ; some boot sector code 

        ORG 510 
        DW 0xAA55
```

--------------------------------

### Forward Reference Example with TIMES

Source: https://www.nasm.us/docs/3.01/nasmac.html

Demonstrates the use of the TIMES directive with a forward reference, showing how the assembler handles it and the sanity check for positivity and size limits.

```assembly
rol ax,forward_reference 
forward_reference equ 1

```

--------------------------------

### Split EA Addressing Syntax Example

Source: https://www.nasm.us/docs/3.01/nasm04.html

Demonstrates the split effective addressing syntax for memory operands, showing base, index, scale, and displacement.

```assembly
mov eax,[ebx+8,ecx*4]   ; ebx=base, ecx=index, 4=scale, 8=disp
```

--------------------------------

### Equivalent C code for printf example

Source: https://www.nasm.us/docs/3.01/nasm11.html

Shows the equivalent C code for the NASM assembly snippet that calls printf.

```c
    int myint = 1234;
    printf("This number -> %d <- should be 1234\n", myint);

```

--------------------------------

### Multi-Line Macro Expansion Example

Source: https://www.nasm.us/docs/3.01/nasm05.html

Shows the expanded code after invoking the 'prologue' macro with the argument 12. This illustrates how macros generate assembly instructions.

```Assembly
myfunc: push    ebp 
        mov     ebp,esp 
        sub     esp,12

```

--------------------------------

### NASM Continuation Line Collapsing Example

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates how NASM collapses lines ending with a backslash into a single line for macro definitions.

```assembly
%define THIS_VERY_LONG_MACRO_NAME_IS_DEFINED_TO \
        THIS_VALUE

```

--------------------------------

### Setting Output Prefix with %pragma

Source: https://www.nasm.us/docs/3.01/nasm05.html

Example of using the %pragma directive to control assembler output, specifically to prepend an underscore to global symbols.

```nasm
%pragma output gprefix _

```

--------------------------------

### NASM Packed BCD Constant Examples

Source: https://www.nasm.us/docs/3.01/nasm03.html

Provides examples of declaring packed BCD constants using the DT directive, showcasing positive, negative, and zero values with and without underscores.

```assembly
      dt 12_345_678_901_245_678p 
      dt -12_345_678_901_245_678p 
      dt +0p33 
      dt 33p
```

--------------------------------

### Assembly Date and Time Macros Example

Source: https://www.nasm.us/docs/3.01/nasm06.html

Demonstrates the output of various date and time macros during an assembly session. These macros provide consistent values within a single assembly run.

```Assembly
      __?DATE?__             "2010-01-01" 
      __?TIME?__             "00:00:42" 
      __?DATE_NUM?__         20100101 
      __?TIME_NUM?__         000042 
      __?UTC_DATE?__         "2009-12-31" 
      __?UTC_TIME?__         "21:00:42" 
      __?UTC_DATE_NUM?__     20091231 
      __?UTC_TIME_NUM?__     210042 
      __?POSIX_TIME?__       1262293242
```

--------------------------------

### NASM: EVEX instruction with displacement and k-register

Source: https://www.nasm.us/docs/3.01/nasmac.html

Example of a VMOVNTPS instruction with a displacement and a k-register, demonstrating correct handling of EVEX flags.

```assembly
      vmovdqu32 [0xabcd]{k1}, zmm0

```

--------------------------------

### NASM Numeric Constant Examples

Source: https://www.nasm.us/docs/3.01/nasm03.html

Demonstrates various ways to specify numeric constants in NASM, including decimal, hexadecimal, octal, and binary bases, with and without prefixes and suffixes. Underscores are shown for readability.

```assembly
mov     ax,200          ; decimal 
mov     ax,0200         ; still decimal 
mov     ax,0200d        ; explicitly decimal 
mov     ax,0d200        ; also decimal 
mov     ax,0c8h         ; hex 
mov     ax,0xc8         ; hex yet again 
mov     ax,0hc8         ; still hex 
mov     ax,310q         ; octal 
mov     ax,310o         ; octal again 
mov     ax,0o310        ; octal yet again 
mov     ax,0q310        ; octal yet again 
mov     ax,11001000b    ; binary 
mov     ax,1100_1000b   ; same binary constant 
mov     ax,1100_1000y   ; same binary constant once more 
mov     ax,0b1100_1000  ; same binary constant yet again 
mov     ax,0y1100_1000  ; same binary constant yet again 

; Deprecated syntax: 
mov     ax,$0c8         ; hex again: the 0 is required
```

--------------------------------

### Repeat Code Block 64 Times with %rep

Source: https://www.nasm.us/docs/3.01/nasm05.html

Use the %rep directive to replicate a block of code a specified number of times. This example generates 64 INC instructions.

```nasm
%assign i 0 
%rep    64 
        inc     word [table+2*i] 
%assign i i+1 
%endrep

```

--------------------------------

### Token Pasting Macro Example

Source: https://www.nasm.us/docs/3.01/nasmac.html

Demonstrates token pasting in NASM macros, where a macro definition can result in a different numerical value.

```assembly
   %define N 1e%++%+ 5 
           dd N, 1e+5

```

--------------------------------

### NASM Undefine Macro Example

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates removing a multi-line macro using %unmacro with an exact argument specification match.

```nasm
%macro foo 1-3 
        ; Do something 
%endmacro 
%unmacro foo 1-3
```

--------------------------------

### NASM Object File Segment Example

Source: https://www.nasm.us/docs/3.01/nasm09.html

Demonstrates defining and referencing segments in NASM's obj format. This is useful for organizing code and data in 16-bit DOS executables.

```assembly
segment data 

dvar:	dw	1234 

segment code 

function:
		mov	ax,data 		; get segment address of data
		mov	ds,ax 			; and move it into DS
		inc	word [dvar] 		; now this reference will work
		ret

```

--------------------------------

### Conditional Assembly with %iftoken

Source: https://www.nasm.us/docs/3.01/nasm05.html

Illustrates the use of %iftoken to check if a parameter consists of exactly one token. It shows an example that will assemble and one that will not.

```nasm
%iftoken 1

```

```nasm
%iftoken -1

```

--------------------------------

### Handling Forward References in Expressions

Source: https://www.nasm.us/docs/3.01/nasmac.html

This example demonstrates how NASM now handles expressions involving forward references, allowing for more complex calculations where symbols are defined after their use.

```assembly
mov ax,foo | bar 
foo equ 1 
bar equ 2

```

--------------------------------

### Defining Program Entry Point in NASM

Source: https://www.nasm.us/docs/3.01/nasm09.html

To specify the program entry point for OMF linkers, declare the special symbol `..start` at the desired beginning of execution.

```nasm
..start:
```

--------------------------------

### NASM Floating-Point Constant Examples

Source: https://www.nasm.us/docs/3.01/nasm03.html

Demonstrates various ways to declare floating-point constants using DB, DW, DD, DQ, DT, and DO directives, including traditional decimal, hexadecimal, and underscore separators.

```assembly
      db    -0.2                    ; "Quarter precision" 
      dw    -0.5                    ; IEEE 754r/SSE5 half precision 
      dd    1.2                     ; an easy one 
      dd    1.222_222_222           ; underscores are permitted 
      dd    0x1p+2                  ; 1.0x2^2 = 4.0 
      dq    0x1p+32                 ; 1.0x2^32 = 4 294 967 296.0 
      dq    1.e10                   ; 10 000 000 000.0 
      dq    1.e+10                  ; synonymous with 1.e10 
      dq    1.e-10                  ; 0.000 000 000 1 
      dt    3.141592653589793238462 ; pi 
      do    1.e+4000                ; IEEE 754r quad precision
```

--------------------------------

### NASM Local Labels Example

Source: https://www.nasm.us/docs/3.01/nasm03.html

Demonstrates the use of local labels in NASM. Local labels prefixed with a single period are associated with the preceding non-local label, allowing for distinct scopes.

```assembly
label1  ; some code 

.loop 
        ; some more code 

        jne     .loop 
        ret 

label2  ; some code 

.loop 
        ; some more code 

        jne     .loop 
        ret

```

--------------------------------

### NASM 64-bit Absolute Displacement Examples

Source: https://www.nasm.us/docs/3.01/nasm13.html

Demonstrates the use of 64-bit absolute displacements with MOV instructions, including explicit size declarations. Shows differences between 32-bit and 64-bit displacements and their sign/zero extension behavior.

```nasm
     default abs 

     mov eax,[foo]           ; 32-bit absolute disp, sign-extended 
     mov eax,[a32 foo]       ; 32-bit absolute disp, zero-extended 
     mov eax,[qword foo]     ; 64-bit absolute disp 

     default rel 

     mov eax,[foo]           ; 32-bit relative disp 
     mov eax,[a32 foo]       ; d:o, address truncated to 32 bits(!)
     mov eax,[qword foo]     ; error 
     mov eax,[abs qword foo] ; 64-bit absolute disp
```

--------------------------------

### New Data Destination (NDD) Syntax Example

Source: https://www.nasm.us/docs/3.01/nasm04.html

Illustrates the syntax for the New Data Destination feature in APX instructions, showing a non-destructive ADD operation.

```assembly
add rax, rbx, rcx
```

--------------------------------

### Data segment for C function call example

Source: https://www.nasm.us/docs/3.01/nasm11.html

Defines data variables used in the example of calling a C function from NASM.

```assembly
segment _DATA 

myint       dd   1234 
mystring    db   'This number -> %d <- should be 1234',10,0

```

--------------------------------

### Get Segment Base of a Symbol

Source: https://www.nasm.us/docs/3.01/nasm03.html

Uses the SEG operator to get the preferred segment base of a symbol for creating a valid pointer.

```assembly
mov     ax,seg symbol 
        mov     es,ax 
        mov     bx,symbol

```

--------------------------------

### NASM Conditional Comma Operator Example

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates the use of the conditional comma operator `%,` in NASM macros to handle optional arguments gracefully, especially with greedy single-line macros.

```nasm
%define greedy(a,b,c+) a + 66 %, b * 3 %, c 

       db greedy(1,2)          ; db 1 + 66, 2 * 3 
       db greedy(1,2,3)        ; db 1 + 66, 2 * 3, 3 
       db greedy(1,2,3,4)      ; db 1 + 66, 2 * 3, 3, 4 
       db greedy(1,2,3,4,5)    ; db 1 + 66, 2 * 3, 3, 4, 5

```

--------------------------------

### Instructions from ISE Doc 319433-040

Source: https://www.nasm.us/docs/3.01/nasmaf.html

Reference for instructions from Intel Software Environments (ISE) document 319433-040, including ENQCMD, ENQCMDS, PCONFIG, XRESLDTRK, and XSUSLDTRK. These cover command queuing and transactional synchronization.

```assembly
ENQCMD           reg16,mem512             AR0-1,SZ,NOREX,NOAPX,NOLONG,FL,ENQCMD 
ENQCMD           reg32,mem512             ND,AR0-1,SZ,NOREX,NOAPX,NOLONG,FL,ENQCMD 
ENQCMD           reg32,mem512             AR0-1,SZ,FL,ENQCMD 
ENQCMD           reg64,mem512             AR0-1,SZ,LONG,FL,PROT,ENQCMD,X86_64 
ENQCMD           reg64,mem512             AR0-1,SZ,LONG,FL,PRIV,PROT,ENQCMD,APX,X86_64 
ENQCMDS          reg16,mem512             AR0-1,SZ,NOREX,NOAPX,NOLONG,FL,PRIV,ENQCMD 
ENQCMDS          reg32,mem512             ND,AR0-1,SZ,NOREX,NOAPX,NOLONG,FL,PRIV,ENQCMD 
ENQCMDS          reg32,mem512             AR0-1,SZ,FL,PRIV,ENQCMD 
ENQCMDS          reg64,mem512             AR0-1,SZ,LONG,FL,PRIV,PROT,ENQCMD,X86_64 
ENQCMDS          reg64,mem512             AR0-1,SZ,LONG,FL,PRIV,PROT,ENQCMD,APX,X86_64 
PCONFIG                                   FL,PRIV,PCONFIG 
XRESLDTRK                                 TSXLDTRK 
XSUSLDTRK                                 TSXLDTRK
```

--------------------------------

### NASM .COM File Structure

Source: https://www.nasm.us/docs/3.01/nasm10.html

This is a basic template for creating a .COM file using NASM's 'bin' output format. .COM files are loaded at offset 100h, and execution begins there.

```Assembly
org 100h 

section .text 

start:
    ; put your code here

section .data

    ; put data items here

section .bss

    ; put uninitialized data here
```

--------------------------------

### NASM .EXE Generation with exebin.mac Macros

Source: https://www.nasm.us/docs/3.01/nasm10.html

This snippet demonstrates the basic structure for generating a .EXE file using NASM's 'bin' format and the exebin.mac macro package. It includes the necessary macro calls to generate the file header and structure.

```Assembly
section .text
    org 100h

    ; EXE_begin macro generates the 32-byte header
    EXE_begin

    ; Your .EXE code starts here
    ; ... your code ...

    ; EXE_end macro marks section sizes and completes the header
    EXE_end

section .data
    ; Your initialized data here

section .bss
    ; Your uninitialized data here
```

--------------------------------

### Boolean AND Operator

Source: https://www.nasm.us/docs/3.01/nasm03.html

Example of the boolean AND operator (&&) in NASM expressions.

```Assembly
&&
```

--------------------------------

### Configure and Make in POSIX Environment

Source: https://www.nasm.us/docs/3.01/nasmad.html

Standard build process for NASM in a POSIX-compliant environment. Ensure 'configure' script is executable and 'make' is available.

```shell
sh configure 
make
```

--------------------------------

### Build All Components

Source: https://www.nasm.us/docs/3.01/nasmad.html

Command to build all available components of NASM for the current platform.

```shell
make everything
```

--------------------------------

### Boolean OR Operator

Source: https://www.nasm.us/docs/3.01/nasm03.html

Example of the boolean OR operator (||) in NASM expressions.

```Assembly
||
```

--------------------------------

### C Structure Organization Example

Source: https://www.nasm.us/docs/3.01/nasm11.html

Illustrates a C structure definition. Note that C compilers may align structure members to specific boundaries, potentially increasing the total size.

```c
struct { 
    char c; 
    int i;
} foo;
```

--------------------------------

### Boolean XOR Operator

Source: https://www.nasm.us/docs/3.01/nasm03.html

Example of the boolean XOR operator (^^) in NASM expressions.

```Assembly
^^
```

--------------------------------

### Initialize Segments and Stack for .EXE

Source: https://www.nasm.us/docs/3.01/nasm10.html

Sets up DS to point to the data segment and initializes SS and SP to point to the top of the stack. This code is intended to be the entry point of an .EXE file.

```Assembly
segment code 

..start:
        mov     ax,data
        mov     ds,ax
        mov     ax,stack
        mov     ss,ax
        mov     sp,stacktop

```

--------------------------------

### Build Documentation

Source: https://www.nasm.us/docs/3.01/nasmad.html

Command to build the documentation for NASM. This process may not function correctly in non-POSIX environments.

```shell
make doc
```

--------------------------------

### NASM Object File SEG and WRT Operators Example

Source: https://www.nasm.us/docs/3.01/nasm09.html

Illustrates the use of SEG and WRT operators in NASM's obj format for accessing segment addresses and performing memory writes. This is relevant for advanced memory manipulation and inter-segment references.

```assembly
extern	foo 

      mov	ax,seg foo 		; get preferred segment of foo
      mov	ds,ax
      mov	ax,data 			; a different segment
      mov	es,ax
      mov	ax,[ds:foo] 		; this accesses `foo'
      mov	[es:foo wrt data],bx 	; so does this

```

--------------------------------

### NASM Comment Removal Example

Source: https://www.nasm.us/docs/3.01/nasm05.html

Illustrates comment removal in NASM, noting that it occurs after continuation lines are collapsed.

```assembly
      add al,'\'     ; Add the ASCII code for \ 
      mov [ecx],al   ; Save the character

```

--------------------------------

### VMX/SVM Instructions

Source: https://www.nasm.us/docs/3.01/nasmaf.html

List of VMX (Virtual Machine Extensions) and SVM (Secure Virtual Machine) instructions for virtualization support.

```assembly
CLGI                                      VMX,AMD 
STGI                                      VMX,AMD 
VMCALL                                    VMX 
VMCLEAR          mem                      VMX 
VMFUNC                                    VMX 
VMLAUNCH                                  VMX 
VMLOAD                                    VMX,AMD 
VMMCALL                                   VMX,AMD 
VMPTRLD          mem                      VMX 
VMPTRST          mem                      VMX 
VMREAD           rm32,reg32               AR0-1,SD,NOREX,NOAPX,NOLONG,VMX 
VMREAD           rm64,reg64               AR0-1,LONG,PROT,VMX,X86_64 
VMRESUME                                  VMX 
VMRUN                                     VMX,AMD 
VMSAVE                                    VMX,AMD 
VMWRITE          reg32,rm32               AR0-1,SD,NOREX,NOAPX,NOLONG,VMX 
VMWRITE          reg64,rm64               AR0-1,LONG,PROT,VMX,X86_64 
VMXOFF                                    VMX 
VMXON            mem                      VMX
```

--------------------------------

### Critical Expression Example (Invalid)

Source: https://www.nasm.us/docs/3.01/nasm03.html

Illustrates an invalid use of a critical expression with the TIMES directive, where the symbol is defined after the expression.

```assembly
times (label-$) db 0 
label:  db      'Where am I?'

```

--------------------------------

### Configuring NASMENV Environment Variable

Source: https://www.nasm.us/docs/3.01/nasm02.html

Demonstrates how to use the NASMENV environment variable to specify custom options, including using a non-standard separator for options containing spaces.

```bash
export NASMENV="!-s!-ic:\nasmlib\"
```

--------------------------------

### Calling a Pascal Function from Assembly

Source: https://www.nasm.us/docs/3.01/nasm10.html

Demonstrates how to call a Pascal function from assembly code, including pushing parameters onto the stack in the correct order and using a far CALL instruction.

```assembly
extern  SomeFunc 

       ; and then, further down... 

       push   word seg mystring   ; Now push the segment, and... 
       push   word mystring       ; ... offset of "mystring" 
       push   word [myint]        ; one of my variables 
       call   far SomeFunc

```

--------------------------------

### Define Floating-Point Constants with fp

Source: https://www.nasm.us/docs/3.01/nasm07.html

Shows how to define floating-point constants like Infinity and NaN using the `fp` macro package.

```nasm
%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)

```

--------------------------------

### Creating macro aliases with %defalias

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates the creation and management of macro aliases using `%defalias`, `%undefalias`, and `%clear defalias` to maintain legacy names or rename macros.

```nasm
%defalias OLD NEW 
   ; OLD and NEW both undefined 
%define NEW 123 
   ; OLD and NEW both 123 
%undef OLD 
   ; OLD and NEW both undefined 
%define OLD 456 
   ; OLD and NEW both 456 
%undefalias OLD 
   ; OLD undefined, NEW defined to 456

```

--------------------------------

### Conditional Assembly with %ifdirective

Source: https://www.nasm.us/docs/3.01/nasm05.html

Shows how to use %ifdirective to check for the support of NASM directives. It includes examples of checking for %ifndef with and without quotes.

```nasm
     %ifdirective %ifndef 
     %ifdirective "%ifndef"

```

--------------------------------

### AMD Lightweight Profiling (LWP) Instructions

Source: https://www.nasm.us/docs/3.01/nasmaf.html

Details instructions for AMD's Lightweight Profiling extension, used for performance monitoring and analysis. Supports both 32-bit and 64-bit modes.

```assembly
LLWPCB           reg32                    386,AMD 
LLWPCB           reg64                    LONG,PROT,X86_64,AMD 
SLWPCB           reg32                    386,AMD 
SLWPCB           reg64                    LONG,PROT,X86_64,AMD 
LWPVAL           reg32,rm32,imm32         386,AMD 
LWPVAL           reg64,rm32,imm32         LONG,PROT,X86_64,AMD 
LWPINS           reg32,rm32,imm32         386,AMD 
LWPINS           reg64,rm32,imm32         LONG,PROT,X86_64,AMD
```

--------------------------------

### Control Listing Output with %pragma

Source: https://www.nasm.us/docs/3.01/nasm02.html

Shows how to dynamically control NASM's listing output options using the %pragma directive within the source code.

```nasm
%pragma list options [+|-]flags...
```

```nasm
%pragma list options +dm -s
```

--------------------------------

### NASM CPU Directive Example

Source: https://www.nasm.us/docs/3.01/nasm08.html

This directive restricts assembly to instructions available on the specified CPU. It can also be used with flags to modify instruction selections.

```assembly
cpu -foo,bar

```

```assembly
cpu nofoo,bar

```

--------------------------------

### Display NASM Usage Information

Source: https://www.nasm.us/docs/3.01/nasm02.html

Displays comprehensive usage instructions and available options for the NASM assembler.

```bash
nasm -h
```

--------------------------------

### Setting Pragma via Command Line

Source: https://www.nasm.us/docs/3.01/nasm02.html

Applies a preprocessor pragma directly from the command line. This is equivalent to placing the pragma at the beginning of the source file.

```bash
nasm -f macho --pragma "macho gprefix _"
```

--------------------------------

### VIA Security Instructions (PENT, CYRIX)

Source: https://www.nasm.us/docs/3.01/nasmaf.html

Includes instructions for various cryptographic operations and secure data handling, specific to PENT and CYRIX processors.

```assembly
XSTORE                                    PENT,CYRIX 
XCRYPTECB                                 PENT,CYRIX 
XCRYPTCBC                                 PENT,CYRIX 
XCRYPTCTR                                 PENT,CYRIX 
XCRYPTCFB                                 PENT,CYRIX 
XCRYPTOFB                                 PENT,CYRIX 
MONTMUL                                   PENT,CYRIX 
XSHA1                                     PENT,CYRIX 
XSHA256                                   PENT,CYRIX
```

--------------------------------

### Conditional Assembly for NASM Version 3.00+ (Backwards Compatibility)

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates how to conditionally assemble code for NASM 3.00 or later, testing for the existence of the %iffile directive using %ifdef and %ifdirective.

```nasm
%ifdef __?NASM_HAS_IFDIRECTIVE?__        ; NASM 3.00 or later 
  %ifdirective %iffile                   ; Test for directive 
    %iffile MYFILE 
       incbin MYFILE 
    %endif 
  %endif 
%endif

```

--------------------------------

### Deprecated Context Fall-Through Lookup Example

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates the deprecated context fall-through lookup feature where an undefined macro in an inner context implicitly searches outer contexts.

```nasm
%macro ctxthru 0 
%push ctx1 
    %assign %$external 1 
        %push ctx2 
            %assign %$internal 1 
            mov eax, %$external 
            mov eax, %$internal 
        %pop 
%pop 
%endmacro
```

--------------------------------

### NASM Substring Extraction with %substr

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates extracting characters or substrings from a string using the `%substr` operator in NASM, including examples with positive and negative indices and lengths.

```nasm
%substr mychar 'xyzw' 1       ; equivalent to %define mychar 'x' 
%substr mychar 'xyzw' 2       ; equivalent to %define mychar 'y' 
%substr mychar 'xyzw' 3       ; equivalent to %define mychar 'z' 
%substr mychar 'xyzw' 2,2     ; equivalent to %define mychar 'yz' 
%substr mychar 'xyzw' 2,-1    ; equivalent to %define mychar 'yzw' 
%substr mychar 'xyzw' 2,-2    ; equivalent to %define mychar 'yz'

```

--------------------------------

### Multi-line Initialization for Structure Field

Source: https://www.nasm.us/docs/3.01/nasm06.html

Demonstrates how to initialize a structure field that spans multiple lines. The 'AT' macro is used for the first line, and subsequent 'db' directives continue the initialization.

```assembly
        at mt_str,  db      123,134,145,156,167,178,189 
                    db      190,100,0

```

--------------------------------

### Exporting a DLL Symbol by Ordinal

Source: https://www.nasm.us/docs/3.01/nasm09.html

Symbols can be exported with an identifying number (ordinal) by providing the ordinal as a parameter to the `EXPORT` directive. This example exports `myfunc` with ordinal `1234`.

```nasm
export  myfunc myfunc 1234
```

--------------------------------

### Defining token macros with %deftok

Source: https://www.nasm.us/docs/3.01/nasm05.html

Illustrates `%deftok` which converts its second parameter to a sequence of tokens after string conversion, equivalent to `%define` for token sequences.

```nasm
%deftok test 'TEST'

```

--------------------------------

### AMX Tile Management Instructions

Source: https://www.nasm.us/docs/3.01/nasmaf.html

Instructions for managing AMX tiles, including releasing and zeroing tiles. TILERELEASE frees a tile, and TILEZERO initializes a tile to zeros.

```assembly
TILERELEASE                               LONG,PROT,AMXTILE,X86_64 
TILEZERO         tmmreg                   LONG,PROT,AMXTILE,X86_64
```

--------------------------------

### Define Structure with Base Offset

Source: https://www.nasm.us/docs/3.01/nasm06.html

Defines a structure 'mytype' with a base offset of -40. This is useful when the structure's memory location is already displaced, for example, on the stack.

```assembly
struc   mytype, -40

```

--------------------------------

### Generate Listing File with COFF Format

Source: https://www.nasm.us/docs/3.01/nasm02.html

Assembles a file using the COFF format and generates a listing file named 'myfile.lst'. The listing file includes addresses and generated code.

```bash
nasm -f coff myfile.asm -l myfile.lst
```

--------------------------------

### AMX Tile Configuration Instructions

Source: https://www.nasm.us/docs/3.01/nasmaf.html

Instructions for configuring and managing AMX tiles. Use LDTILECFG to load tile configuration and STTILECFG to store it.

```assembly
LDTILECFG        mem512                   AR0,SZ,LONG,PROT,AMXTILE,X86_64 
STTILECFG        mem512                   AR0,SZ,LONG,PROT,AMXTILE,X86_64
```

--------------------------------

### Importing a DLL Symbol in NASM

Source: https://www.nasm.us/docs/3.01/nasm09.html

Use the `IMPORT` directive to declare a symbol that will be imported from a DLL. The symbol must also be declared `EXTERN`. This example imports `WSAStartup` from `wsock32.dll`.

```nasm
import  WSAStartup wsock32.dll
```

--------------------------------

### Hiding instructions with %*?

Source: https://www.nasm.us/docs/3.01/nasm05.html

Shows how `%*?` can be used to effectively hide a keyword or instruction, useful for maintaining compatibility with older codebases.

```nasm
%idefine pause $%*?                 ; Hide the PAUSE instruction

```

--------------------------------

### Conditional Output Prefix with %pragma

Source: https://www.nasm.us/docs/3.01/nasm05.html

Shows how to conditionally apply a %pragma directive based on the output format, in this case, prepending an underscore to global symbols only for win32 or win64 output.

```nasm
%pragma win gprefix _

```

--------------------------------

### Conditional Operator Example

Source: https://www.nasm.us/docs/3.01/nasm03.html

Illustrates the NASM conditional operator, similar to C's ternary operator. Spaces around '?' and ':' are recommended due to potential symbol name conflicts.

```Assembly
boolean ? trueval : falseval
```

--------------------------------

### AMX Tile Load and Store Instructions

Source: https://www.nasm.us/docs/3.01/nasmaf.html

Instructions for loading data into and storing data from AMX tiles. Use TILELOADD, TILELOADDT1 for loading and TILESTORED for storing.

```assembly
TILELOADD        tmmreg,mem               AR1,ANYSIZE,SIB,LONG,MIB,PROT,AMXTILE,APX,X86_64 
TILELOADDT1      tmmreg,mem               AR1,ANYSIZE,SIB,LONG,MIB,PROT,AMXTILE,APX,X86_64 
TILESTORED       mem,tmmreg               AR0,ANYSIZE,SIB,LONG,MIB,PROT,AMXTILE,APX,X86_64
```

--------------------------------

### NASM Special Floating-Point Operator Example

Source: https://www.nasm.us/docs/3.01/nasm03.html

Shows how to use the __?float64?__ special operator to generate the binary representation of a 64-bit floating-point number and assign it to a register.

```assembly
      mov    rax,__?float64?__(3.141592653589793238462)
```

--------------------------------

### Create and Remove Contexts with %push and %pop

Source: https://www.nasm.us/docs/3.01/nasm05.html

Manages a stack of contexts for label scoping. %push creates a new context, and %pop removes the top context from the stack.

```nasm
%push    foobar

```

```nasm
%pop

```

--------------------------------

### Section Alignment in Binary Output

Source: https://www.nasm.us/docs/3.01/nasm09.html

Defines section alignment requirements for binary output formats. Ensures segments start at addresses with a specified number of trailing zero bits.

```assembly
section .data   align=16

```

--------------------------------

### Pre-Define a Macro with -d

Source: https://www.nasm.us/docs/3.01/nasm02.html

Use the -d option to pre-define a macro, equivalent to using a %define directive at the start of the source file. It can also be specified as -D for Makefile compatibility.

```bash
nasm myfile.asm -dFOO=100

```

--------------------------------

### Pascal Function Definition in Assembly

Source: https://www.nasm.us/docs/3.01/nasm10.html

Defines a function in assembly following the Pascal calling convention, including stack frame setup, parameter access, local variable allocation, and return.

```assembly
global  myfunc 

myfunc: push    bp 
        mov     bp,sp 
        sub     sp,0x40         ; 64 bytes of local stack space 
        mov     bx,[bp+8]       ; first parameter to function 
        mov     bx,[bp+6]       ; second parameter to function 

        ; some more code 

        mov     sp,bp           ; undo "sub sp,0x40" above 
        pop     bp 
        retf    4               ; total size of params is 4

```

--------------------------------

### Test File Existence with %iffile and %pathsearch

Source: https://www.nasm.us/docs/3.01/nasm05.html

Use %iffile to conditionally assemble code if a file is available. Search the include path using %pathsearch() in conjunction with %iffile.

```nasm
%define MYFILE "file.asm" 
%iffile %pathsearch(MYFILE) 
     ; ... 
%endif

```

--------------------------------

### Exporting a DLL Symbol with a Specific External Name

Source: https://www.nasm.us/docs/3.01/nasm09.html

The `EXPORT` directive can take a second parameter to specify the external name of the symbol. This example exports `myfunc` and makes it known externally as `TheRealMoreFormalLookingFunctionName`.

```nasm
export  myfunc TheRealMoreFormalLookingFunctionName
```

--------------------------------

### NASM Broadcasting Decorator with Opsize

Source: https://www.nasm.us/docs/3.01/nasm03.html

Demonstrates the use of broadcasting decorators with the opsize keyword for specific instructions like VDIVPS. This ensures that the opsize keyword matches the element size when using broadcasting for operations on packed data.

```assembly
VDIVPS zmm4, zmm5, dword [rbx]{1to16}   ; single-precision float 
     VDIVPS zmm4, zmm5, zword [rbx]          ; packed 512 bit memory
```

--------------------------------

### Incorrect Mixed-Size Jump (16-bit to 32-bit)

Source: https://www.nasm.us/docs/3.01/nasm12.html

This example shows an incorrect way to perform a jump from a 16-bit segment to a 32-bit segment. The offset is truncated, resulting in an ordinary 16-bit far jump.

```assembly
        jmp     0x1234:0x56789ABC       ; wrong!
```

--------------------------------

### Intel Instruction Set Extensions - General

Source: https://www.nasm.us/docs/3.01/nasmaf.html

Details various instructions including CLDEMOTE, MOVDIRI, MOVDIR64B, and PCONFIG, specifying their operand types and supported features like APX and PCONFIG.

```assembly
CLDEMOTE         mem                      CLDEMOTE 
MOVDIRI          mem32,reg32              MOVDIRI 
MOVDIRI          mem64,reg64              LONG,PROT,MOVDIRI,X86_64 
MOVDIRI          mem32,reg32              LONG,PROT,APX,MOVDIRI,X86_64 
MOVDIRI          mem64,reg64              LONG,PROT,APX,MOVDIRI,X86_64 
MOVDIR64B        reg16,mem512             NOLONG,MOVDIR64B 
MOVDIR64B        reg32,mem512             MOVDIR64B 
MOVDIR64B        reg64,mem512             LONG,PROT,MOVDIR64B,X86_64 
MOVDIR64B        reg64,mem512             LONG,PROT,APX,MOVDIR64B,X86_64 
PCONFIG                                   FL,PCONFIG
```

--------------------------------

### Intel SMX GETSEC Instruction

Source: https://www.nasm.us/docs/3.01/nasmaf.html

The GETSEC instruction is part of the Intel Trusted Execution Technology (TXT) and is used for secure system setup. It is available on processors supporting the SMX feature set.

```assembly
GETSEC                                    NOAPX,FL,KATMAI
```

--------------------------------

### Macro Calls for writefile

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates two ways to call the writefile macro: one with a string pointer and length, and another with a string literal.

```nasm
        writefile [file], strpointer, length 
        writefile [file], "hello", 13, 10

```

--------------------------------

### Single-line macro expansion with %*?

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates how `%*?` expands differently from `%?` within single-line macros, affecting macro definition and usage.

```nasm
%imacro Foo 0 
      %idefine Bar _%? 
      mov BAR,bAr 
%endmacro 

      foo 
      mov eax,bar

```

```nasm
      mov _foo,_foo 
      mov eax,_foo

```

```nasm
%imacro Foo 0 
      %idefine Bar _%*? 
      mov BAR,bAr 
%endmacro 

      foo 
      mov eax,bar

```

```nasm
      mov _BAR,_bAr 
      mov eax,_bar

```

--------------------------------

### Accessing External Symbol with Segment Base

Source: https://www.nasm.us/docs/3.01/nasm09.html

When accessing an external symbol like `foo`, you often need to first get its segment base and move it into a segment register (e.g., `ES`) before using the offset.

```nasm
mov     ax,seg foo
        mov     es,ax
        mov     ax,[es:foo]
```

--------------------------------

### NASM: Boot Sector with TIMES Directive

Source: https://www.nasm.us/docs/3.01/nasm14.html

Shows the correct method to pad a boot sector to a specific size using the TIMES directive in NASM, ensuring the assembly point reaches 510 before the signature word.

```assembly
        ORG 0 

        ; some boot sector code 

        TIMES 510-($-$$) DB 0 
        DW 0xAA55
```

--------------------------------

### Exporting a Simple DLL Symbol in NASM

Source: https://www.nasm.us/docs/3.01/nasm09.html

Use the `EXPORT` directive to define a global symbol to be exported as a DLL symbol. The symbol must also be declared `GLOBAL`. This example exports a symbol named `myfunc`.

```nasm
export  myfunc
```

--------------------------------

### Generate Configure Script from Git Repository

Source: https://www.nasm.us/docs/3.01/nasmad.html

Command to generate the 'configure' script when building NASM from the git repository in a POSIX environment. Requires autotools like m4, autoconf, and autoheader.

```shell
sh autogen.sh
```

--------------------------------

### NASM Version String Macro

Source: https://www.nasm.us/docs/3.01/nasm06.html

Expands to a string defining the NASM version number. Used for displaying or logging the version.

```assembly
        db      __?NASM_VER?__
```

```assembly
        db      "0.98.32"
```

--------------------------------

### Access Local Data Item using GOT Offset

Source: https://www.nasm.us/docs/3.01/nasm11.html

Use `..gotoff` to get the offset of a local variable from the GOT base. This is useful for accessing variables declared within your library's sections.

```nasm
lea     eax,[ebx+myvar wrt ..gotoff]
```

--------------------------------

### ELF Common Variable with Alignment

Source: https://www.nasm.us/docs/3.01/nasm09.html

Specify alignment requirements for common variables in ELF object files by appending a power-of-two number after the size, separated by a colon. This example declares a 128-byte array aligned on a 4-byte boundary.

```nasm
common  dwordarray 128:4
```

--------------------------------

### Exporting a DLL Symbol with Attributes

Source: https://www.nasm.us/docs/3.01/nasm09.html

The `EXPORT` directive supports attributes like `resident`, `nodata`, and `parm=NNN` to define properties of the exported symbol. This example exports `myfunc` with the `resident` and `nodata` attributes, and sets `parm` to 23.

```nasm
export  myfunc myfunc resident parm=23 nodata
```

--------------------------------

### NASM Complex Register-Based Effective Addresses

Source: https://www.nasm.us/docs/3.01/nasm03.html

Illustrates more complex effective addresses involving multiple registers and arithmetic operations. These examples show how NASM handles combinations of registers, multiplication, and constant offsets within memory references.

```assembly
mov     eax,[ebx*2+ecx+offset] 
        mov     ax,[bp+di+8]
```

--------------------------------

### Sample Usage of Block IF Macros

Source: https://www.nasm.us/docs/3.01/nasm05.html

Demonstrates nested usage of the custom IF, ELSE, and ENDIF macros for conditional logic within NASM assembly.

```nasm
cmp     ax,bx 

if ae 
       cmp     bx,cx 

       if ae 
               mov     ax,cx 
       else 
               mov     ax,bx 
       endif 

else 
       cmp     ax,cx 

       if ae 
               mov     ax,cx 
       endif 

endif
```

--------------------------------

### Configuring Symbol Prefixes and Suffixes for Different ABIs

Source: https://www.nasm.us/docs/3.01/nasm08.html

Configures global and local symbol prefixes and suffixes using pragmas to adhere to various ABI conventions, including specific settings for ELF.

```nasm
; The most common conventions 
%pragma output gprefix _ 
%pragma output lprefix L_ 
; ELF uses a different convention 
%pragma elf    gprefix                       ; empty 
%pragma elf    lprefix .L

```

--------------------------------

### Importing a DLL Symbol with a Different External Name

Source: https://www.nasm.us/docs/3.01/nasm09.html

The `IMPORT` directive can take a third optional parameter to specify the external name of the symbol if it differs from the name used internally. This example imports `WSAAsyncSelect` from `wsock32.dll` and makes it available as `asyncsel`.

```nasm
import  asyncsel wsock32.dll WSAAsyncSelect
```

--------------------------------

### Custom Win64 Exception Handler

Source: https://www.nasm.us/docs/3.01/nasm09.html

This C-style code defines a custom exception handler that can manipulate the CONTEXT record to manage stack unwinding. It's designed to work with the assembly example provided, allowing the function to mimic a Win64 leaf function.

```c
EXCEPTION_DISPOSITION handler (EXCEPTION_RECORD *rec,ULONG64 frame, 
        CONTEXT *context,DISPATCHER_CONTEXT *disp) 
{   ULONG64 *rsp; 
    if (context->Rip<(ULONG64)magic_point) 
        rsp = (ULONG64 *)context->Rax; 
    else 
    {   rsp = ((ULONG64 **)context->Rsp)[0]; 
        context->Rbp = rsp[-3]; 
        context->Rbx = rsp[-2]; 
        context->R15 = rsp[-1]; 
    } 
    context->Rsp = (ULONG64)rsp; 

    memcpy (disp->ContextRecord,context,sizeof(CONTEXT)); 
    RtlVirtualUnwind(UNW_FLAG_NHANDLER,disp->ImageBase, 
        dips->ControlPc,disp->FunctionEntry,disp->ContextRecord, 
        &disp->HandlerData,&disp->EstablisherFrame,NULL); 
    return ExceptionContinueSearch; 
}

```

--------------------------------

### Basic NASM Source Line Structure

Source: https://www.nasm.us/docs/3.01/nasm03.html

Illustrates the general layout of a NASM source line, showing the optional fields for label, instruction, operands, and comments.

```assembly
label:    instruction operands        ; comment

```

--------------------------------

### Replacing a Context with %repl Directive

Source: https://www.nasm.us/docs/3.01/nasm05.html

Illustrates the use of the %repl directive to change a context's name without losing associated macros and labels, contrasting it with the destructive pop/push method.

```nasm
%pop 
%push   newname
```

```nasm
%repl newname
```

--------------------------------

### Intel PBNDKB and PREFETCHRST2 Instructions

Source: https://www.nasm.us/docs/3.01/nasmaf.html

Lists mnemonics for PBNDKB and PREFETCHRST2 instructions, indicating their operand types and associated features like MOVRS.

```assembly
PBNDKB                                    PBNDKB 
PREFETCHRST2     mem8                     MOVRS
```

--------------------------------

### NASM Unicode to UTF-8 Conversion

Source: https://www.nasm.us/docs/3.01/nasm03.html

Shows equivalent ways to represent a Unicode character (smiley face) in NASM strings, demonstrating conversion to UTF-8 encoding. Includes examples using backquoted strings with Unicode escapes and direct byte representation.

```assembly
db `\u263a`            ; UTF-8 smiley face 
db `\xe2\x98\xba`      ; UTF-8 smiley face 
db 0E2h, 098h, 0BAh    ; UTF-8 smiley face
```

--------------------------------

### Context-Local Labels with REPEAT and UNTIL Macros

Source: https://www.nasm.us/docs/3.01/nasm05.html

Implements REPEAT and UNTIL macros using context-local labels ('%$') for scoped label definition and jumping.

```nasm
%macro repeat 0 

    %push   repeat 
    %$begin: 

%endmacro 

%macro until 1 

        j%-1    %$begin 
    %pop 

%endmacro
```

```nasm
        mov     di,string 
        repeat 
        add     di,3 
        scasb 
        until   e
```

--------------------------------

### Disassemble with Synchronization Point

Source: https://www.nasm.us/docs/3.01/nasmab.html

Use synchronization points with the -s option to ensure NDISASM correctly disassembles code that follows data. Sync points are measured from the program origin. This example synchronizes after 32 bytes (0x20) in a file originating at 0x100.

```bash
ndisasm -o100h -s120h file.com
```

--------------------------------

### Build Unix Man Pages

Source: https://www.nasm.us/docs/3.01/nasmad.html

Command to generate the Unix man pages for NASM.

```shell
make manpages
```
Tokens:
Raw