Flat Assembler

https://flatassembler.net/docs.php
Admin
Flat Assembler is an assembly language compiler that supports multiple CPU architectures and...
Tokens:67,202
Snippets:607
Trust Score:9.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Assembly: Bound Instruction Examples

Source: https://flatassembler.net/docs.php/index_article=manual

Demonstrates the usage of the 'bound' instruction to verify if a signed value within a register falls within specified limits. It shows examples for both word and double word sizes.

```assembly
bound ax,[bx]    ; check word for bounds
bound eax,[esi]  ; check double word for bounds
```

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

### Assembly: Input (IN) Instruction Examples

Source: https://flatassembler.net/docs.php/index_article=manual

Illustrates the 'in' instruction for transferring data from I/O ports to CPU registers. Examples cover reading a byte and a word, using both immediate port addressing and indirect addressing via the DX register.

```assembly
in al,20h        ; input byte from port 20h
in ax,dx         ; input word from port addressed by dx
```

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

### Preprocessor Handling of Labels and Directives

Source: https://flatassembler.net/docs.php/index_article=manual

Illustrates how the preprocessor handles lines starting with a label, allowing preprocessor directives and macroinstructions to follow labels.

```assembly
    start: include 'start.inc'
```

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

### Macroinstruction and Equ Directive Example

Source: https://flatassembler.net/docs.php/index_article=manual

Illustrates the processing order where macroinstructions like 'foo' are recognized before directives like 'equ' when they appear as the first symbol on a line.

```assembly
    foo equ
    foo bar

```

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

### Repeat Block with Custom Start Index Parameter

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

Demonstrates how to use additional arguments with the 'repeat' instruction to specify named parameters and their starting values. This allows for more flexible control over the repetition range.

```asm
        repeat 16, i:0
                f#i = 1 shl i
        end repeat

```

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

### POP Instruction Examples in Assembly

Source: https://flatassembler.net/docs.php/index_article=manual

Provides examples for the 'pop' instruction, which retrieves a value from the top of the stack into a destination operand. 'popw' and 'popd' are variants for word and double word sizes. Chained pops are also supported.

```assembly
pop bx          ; restore general register
pop ds          ; restore segment register
popw [si]       ; restore memory
```

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

### Self-Establishing Block Example (Flat Assembler)

Source: https://flatassembler.net/docs.php/index_article=manual

Shows a modification to the previous example using an anonymous label ('@@') to create a self-establishing block. This resolves the antinomy by ensuring the block can always be defined, even if 'alpha' is not defined elsewhere.

```assembly
    if ~ defined alpha | defined @f
        alpha:
        @@:
    end if

```

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

### Macro with Context-less Argument Example

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

This snippet demonstrates the definition and usage of a macroinstruction ('both') that accepts a regular argument ('a') and a context-less argument ('&b'). The context-less argument is prefixed with '&' to ensure its text is reinterpreted in the new context during macro evaluation, as shown in the example output.

```assembly
char = 'A'
other.char = 'W'

macro both a, &b
        namespace other
                db a, b
        end namespace
end macro

both char+1, char+1 ; db 'B', 'X'
```

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

### Assembly: Output (OUT) Instruction Examples

Source: https://flatassembler.net/docs.php/index_article=manual

Shows the 'out' instruction for transferring data from CPU registers to I/O ports. Examples include outputting a word and a byte, using both immediate port addressing and indirect addressing via the DX register.

```assembly
out 20h,ax       ; output word to port 20h
out dx,al        ; output byte to port addressed by dx
```

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

### PUSH Instruction Examples in Assembly

Source: https://flatassembler.net/docs.php/index_article=manual

Shows examples of the 'push' instruction, which stores a value (memory, general register, segment register, or immediate value) onto the stack. 'pushw' and 'pushd' are variants for word and double word sizes respectively. Chained pushes are also supported.

```assembly
push ax         ; store general register
push es         ; store segment register
pushw [bx]      ; store memory
push 1000h      ; store immediate value
```

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

### Assembly: Symbol character example

Source: https://flatassembler.net/docs.php/index_article=manual

Demonstrates the use of symbol characters, which are treated as individual items even without spaces. Here, '+' is used.

```assembly
mov eax, 5+3
```

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

### Symbol Recognition Based on Position (Example)

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

Demonstrates how the same identifier can have different meanings based on its position within a source line, illustrating the concept of symbol classes.

```assembly
        ?restore = 1
        restore restore ; remove the value of the expression-class symbol

```

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

### Enter Stack Frame Creation

Source: https://flatassembler.net/docs.php/index_article=manual

The 'enter' instruction creates a stack frame for implementing block-structured languages. This example allocates 2048 bytes on the stack and sets the lexical nesting level to 0.

```assembly
    enter 2048,0     ; enter and allocate 2048 bytes on stack

```

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

### List Appending Macro

Source: https://flatassembler.net/docs.php/index_article=manual

A practical example of a macro 'append' that uses 'match' directives to add items to a symbolic constant 'list', handling both empty and non-empty list states.

```assembly
    list equ

    macro append item
     {
       match any, list { list equ list,item }
       match , list { list equ item }
     }

```

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

### Set Output File Format and Extension

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

The 'format' directive specifies output options. 'format binary' or 'format executable' have minor effects, while 'as' defines the output file extension. This example sets the extension to 'com'.

```assembly
format binary as 'com'
```

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

### ADD Instruction Examples

Source: https://flatassembler.net/docs.php/index_article=manual

Demonstrates the usage of the ADD instruction for various operand combinations. ADD replaces the destination with the sum of source and destination, setting CF on overflow. Operands can be bytes, words, or double words.

```assembly
add ax,bx       ; add register to register
    add ax,[si]     ; add memory to register
    add [di],al     ; add register to memory
    add al,48       ; add immediate value to register
    add [char],48   ; add immediate value to memory
```

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

### Flat Assembler MATCH Directive Examples

Source: https://flatassembler.net/docs.php/index_article=ufasm

Demonstrates various ways to use the MATCH directive in Flat Assembler for pattern matching, including matching special characters, quoted strings, prefixed tokens, and sequences.

```assembly
match +,+
{
  display "special character is matched as-is",13,10
}

match 'a','a'
{
  display "the same with quoted string",13,10
}

match =a,a
{
  display "the name token must be preceded with =",13,10
}

match =a=+='a' , a+'a'
{
  display "and = may be actually used with any token",13,10
}
```

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

### Comparison Operations with SSE Instructions (Assembly)

Source: https://flatassembler.net/docs.php/index_article=manual

Provides examples of SSE comparison instructions for packed (cmpps) and scalar (cmpss) single-precision floating-point values. Includes comparisons with immediate operands and conditional mnemonics.

```Assembly
cmpps xmm2,xmm4,0  ; compare packed single precision values
cmpltss xmm0,[ebx] ; compare single precision values
```

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

### Define Dialog Item - Button Example

Source: https://flatassembler.net/docs.php/index_article=win32

Defines a standard dialog item, specifically a 'BUTTON' type with the text 'OK'. It includes its identifier, position, dimensions, and style flags like WS_VISIBLE and WS_TABSTOP.

```assembly
  dialogitem 'BUTTON','OK',IDOK,10,10,45,15,WS_VISIBLE+WS_TABSTOP
```

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

### Fix Directive Example

Source: https://flatassembler.net/docs.php/index_article=manual

Demonstrates how the 'fix' directive is processed first, allowing for the definition of empty macros before other preprocessing steps.

```assembly
    V fix {
      macro empty
       V
    V fix }
       V

```

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

### Namespace Usage with Case-Insensitive and Labeled Symbols (Example)

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

Illustrates how to use symbols within namespaces, including built-in case-insensitive symbols and labeled symbols. It shows how symbol case and definition scope affect resolution.

```assembly
        xor?.mask? := 10101010b
        a = XOR.MASK    ; symbol in the namespace of built-in case-insensitive "XOR"

        label?.test? := 0
        a = LABEL.TEST  ; undefined unless "label?" is defined

```

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

### Define Dialog Box with All Parameters

Source: https://flatassembler.net/docs.php/index_article=win32

Defines a dialog box resource with all available parameters, including position, dimensions, styles, extended styles, menu, and font information. The example omits the menu parameter but specifies a custom font.

```assembly
  dialog about,'About',50,50,200,100,WS_CAPTION+WS_SYSMENU,\
               WS_EX_TOPMOST, ,'Times New Roman',10
```

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

### vptest and vtestpd Testing Operations (Assembly)

Source: https://flatassembler.net/docs.php/index_article=manual

Illustrates assembly examples for vptest (testing 256-bit values) and vtestpd (testing sign bits of 64-bit floats). Both instructions set ZF and CF flags based on the test results.

```assembly
    vptest ymm0,yword [ebx]  ; test 256-bit values
    vtestpd xmm0,xmm1        ; test sign bits of 64-bit floats
```

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

### FASM Macro Redefinition Example

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

Demonstrates how macroinstructions can be redefined and use their previous values in the new definition. This allows for more flexible and dynamic macro behavior.

```assembly
macro zero
        db 0
end macro

macro zero name
        label name:byte
        zero
end macro

zero x
```

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

### IMUL Instruction Examples

Source: https://flatassembler.net/docs.php/index_article=manual

Illustrates the three forms of the IMUL (signed multiplication) instruction. IMUL calculates the product and updates flags, with variations for accumulator by register/memory, register by register/memory, and register by immediate value.

```assembly
imul bl         ; accumulator by register
    imul word [si]  ; accumulator by memory
    imul bx,cx      ; register by register
    imul bx,[si]    ; register by memory
```

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

### Define Output Area Start with ORG

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

The 'org' instruction begins a new output area. Addresses within this area are relative to the value provided to 'org'. The area closes automatically when a new one starts or the source ends.

```assembly
org 100h
start:                  ; start = 100h
```

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

### Define Accelerator Keys for Main Actions

Source: https://flatassembler.net/docs.php/index_article=win32

Defines accelerator keys for common actions. This example sets up hotkeys for F1 and F10, associating them with specific command identifiers (901 and 109 respectively). It uses FVIRTKEY for virtual key codes and FNOINVERT for normal key behavior.

```assembly
  accelerator main_keys,
              FVIRTKEY+FNOINVERT,VK_F1,901,
              FVIRTKEY+FNOINVERT,VK_F10,109
```

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

### Anonymous Label Example (Flat Assembler)

Source: https://flatassembler.net/docs.php/index_article=manual

Illustrates the usage of an anonymous label ('@@') which is referenced by '@f'. This construct is used to create self-contained, self-establishing code blocks.

```assembly
    if defined @f
        @@:
    end if

```

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

### Custom Syntax for Labeled Macroinstructions

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

Shows how to define custom syntaxes for 'struc' using 'macro' and 'esc'. This example creates 'struct?' and 'ends?!' macros to simplify the definition and usage of labeled structures.

```assembly
        macro struct? definition&
                esc struc definition
                        label . : .%top - .
                        namespace .
        end macro

        macro ends?! 
                                %top:
                        end namespace
                esc end struc
        end macro

        struct POINT vx:?,vy:?
                x dd vx
                y dd vy
        ends

        my POINT 10,20

```

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

### Convert to String with 'compute', 'arrange', and 'stringify'

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

The 'stringify' command converts a variable's text into a string and writes it back to the same variable. This example uses 'compute' to evaluate an expression, 'arrange' to format it as a decimal token, and then 'stringify' to convert it to a string.

```assembly
calminstruction (var) strcalc? val
                compute val, val        ; compute expression
                arrange val, val        ; convert result to a decimal token
                stringify val           ; convert decimal token to string
                publish var, val
        end calminstruction
                     
        p strcalc 1 shl 1000
        display p

```

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

### Macro Definition and Expansion (Example 1)

Source: https://flatassembler.net/docs.php/index_article=ufasm

Demonstrates a simple macro definition 'Def' and its expansion. The preprocessor replaces the macro invocation with its defined content, which in this case defines a constant using the EQU directive.

```assembly
Def A

```

```assembly
A equ 1

```

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

### Define Dialog Item - Static Bitmap Example

Source: https://flatassembler.net/docs.php/index_article=win32

Defines a 'STATIC' type dialog item intended to display a bitmap. It references a bitmap resource with identifier 7 and specifies its position, dimensions, and the SS_BITMAP style.

```assembly
  dialogitem 'STATIC',7,0,10,50,50,20,WS_VISIBLE+SS_BITMAP
```

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

### vbroadcastss Broadcasting Operation (Assembly)

Source: https://flatassembler.net/docs.php/index_article=manual

Shows an assembly example of vbroadcastss, which broadcasts a 32-bit memory value into all elements of an AVX register. This is a new instruction for broadcasting data.

```assembly
    vbroadcastss ymm0,dword [eax]  ; get eight copies of value
```

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

### Integer to Float Conversion (Assembly)

Source: https://flatassembler.net/docs.php/index_article=manual

Provides assembly examples for vcvtsi2sd (32-bit integer to 64-bit float) and vcvtsi2ss (64-bit integer to 32-bit float) instructions, which use a three-operand syntax for conversions.

```assembly
    vcvtsi2sd xmm4,xmm4,ecx  ; 32-bit integer to 64-bit float
    vcvtsi2ss xmm0,xmm0,rax  ; 64-bit integer to 32-bit float
```

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

### Virtual Machine Control Block (VMCB) Instructions

Source: https://flatassembler.net/docs.php/index_article=manual

Documentation for instructions related to managing virtual machines via VMCB.

```APIDOC
## Virtual Machine Control Block (VMCB) Instructions

### Description
Instructions for starting, saving, loading, and calling the Virtual Machine Monitor (VMM) using VMCB.

### Method
Various (refer to individual instructions)

### Endpoint
N/A (assembly instructions)

#### Instruction Details:

- **`vmrun`**
  - **Description**: Starts a guest virtual machine. The only operand should be an accumulator register (AX, EAX, or RAX in long mode) providing the physical address of the VMCB.
  - **Operands**: 1 (Physical address of VMCB in accumulator register)

- **`vmsave`**
  - **Description**: Stores a subset of processor state into a specified VMCB. Operand rules are the same as for `vmrun`.
  - **Operands**: 1 (VMCB specification in accumulator register)

- **`vmload`**
  - **Description**: Loads a subset of processor state from a specified VMCB. Operand rules are the same as for `vmrun`.
  - **Operands**: 1 (VMCB specification in accumulator register)

- **`vmmcall`**
  - **Description**: Allows guest software to call the VMM. Takes no operands.
  - **Operands**: 0

### Request Example
```assembly
vmrun RAX  ; RAX contains physical address of VMCB
vmsave RBX ; RBX contains VMCB specification
vmload RCX ; RCX contains VMCB specification
vmmcall
```

### Response
N/A (assembly instructions modify processor state)

```

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

### Retain Comments in Assembly

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

The 'retaincomments' directive prevents the assembler from stripping comments (starting with ';'). This allows semicolons to be used in contexts like 'MATCH' patterns. The example defines a macro that processes instructions and comments separately.

```assembly
retaincomments
macro ? line&
        match instruction ; comment , line
                virtual
                        comment
                end virtual
                instruction
        else
                line
        end match
end macro

var dd ?  ; bvar db ?
```

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

### Nested Macro Context Preservation in Flat Assembler

Source: https://flatassembler.net/docs.php/index_article=fasmg

Demonstrates how text within an inner macro preserves the context coloring from the outer macro. This example improves the 'state' and 'switch' macros by nesting them within a 'setup' macro.

```assembly
macro setup variable

        variable = 0

        macro state
                db variable
        end macro

        macro switch value
                variable = variable xor (value)
        end macro

end macro

setup GLOBAL_STATE

namespace Program

        switch 8

        GLOBAL_STATE = 0

        state

end namespace

```

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

### Executing Compiler from Command Line

Source: https://flatassembler.net/docs.php/index_article=manual

Explains how to execute the flat assembler from the command line, including available options and parameters.

```APIDOC
## Executing Compiler from Command Line

To execute flat assembler from the command line you need to provide two parameters - first should be name of source file, second should be name of destination file. If no second parameter is given, the name for output file will be guessed automatically. After displaying short information about the program name and version, compiler will read the data from source file and compile it. When the compilation is successful, compiler will write the generated code to the destination file and display the summary of compilation process; otherwise it will display the information about error that occurred.

In the command line you can also include `-m` option followed by a number, which specifies how many kilobytes of memory flat assembler should maximally use. In case of DOS version this options limits only the usage of extended memory. The `-p` option followed by a number can be used to specify the limit for number of passes the assembler performs. If code cannot be generated within specified amount of passes, the assembly will be terminated with an error message. The maximum value of this setting is 65536, while the default limit, used when no such option is included in command line, is 100.

The source file should be a text file, and can be created in any text editor. Line breaks are accepted in both DOS and Unix standards, tabulators are treated as spaces.

There are no command line options that would affect the output of compiler, flat assembler requires only the source code to include the information it really needs. For example, to specify output format you specify it by using the `format` directive at the beginning of source.
```

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

### Define Macroinstruction - FASM

Source: https://flatassembler.net/docs.php/index_article=fasmg

Defines a simple macroinstruction named 'octet' that takes one argument 'value' and generates a 'db value' line. This is a basic example of text replacement before assembly.

```assembly
        macro octet value*
                db value
        end macro

```

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

### Secure Virtual Machine (SVM)

Source: https://flatassembler.net/docs.php/index_article=manual

Documentation for the `skinit` instruction used in AMD's Secure Virtual Machine (SVM).

```APIDOC
## Secure Virtual Machine (SVM)

### Description
Provides a secure way to reinitialize the processor for trusted software startup using the `skinit` instruction.

### Method
`skinit`

### Endpoint
N/A (assembly instruction)

### Parameters
#### Instruction Details:

- **`skinit`**
  - **Description**: Securely reinitializes the processor, allowing for the startup of trusted software like a VM monitor. Requires a single operand, which must be EAX, providing the physical address of the secure loader block (SLB).
  - **Operands**: 1 (Physical address of SLB in EAX)

### Request Example
```assembly
mov EAX, PHYSICAL_ADDRESS_OF_SLB
skinit
```

### Response
N/A (assembly instruction modifies processor state)

```

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

### Intercepting Non-Instruction Lines with 'struc ?'

Source: https://flatassembler.net/docs.php/index_article=fasmg

This example uses 'struc ?' to intercept lines that do not start with a known instruction, treating the initial symbol as a label. It specifically checks for '.CODE' and then either processes it with 'CODE tail' or passes the original 'head tail' through. This approach is generally more efficient for handling unknown commands as it only triggers when a standard instruction isn't found.

```assembly
struc (head) ? tail&
        match .=CODE?, head
                CODE tail
        else
                head tail
        end match
end struc

```

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

### Generate Relocatable Byte Instructions

Source: https://flatassembler.net/docs.php/index_article=fasmg

Shows an example of how to generate relocatable code using the 'BYTE?' macro with 'HIGH' and 'LOW' modifiers. This approach allows individual parts of an address to be relocated separately.

```assembly
BYTE HIGH address
BYTE LOW address
```

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

### Arithmetic Operations with SSE Instructions (Assembly)

Source: https://flatassembler.net/docs.php/index_article=manual

Shows examples of SSE arithmetic instructions for both packed (ps) and scalar (ss) single-precision floating-point values. Operations include addition, subtraction, multiplication, division, reciprocal, square root, max, and min.

```Assembly
mulss xmm0,[ebx]   ; multiply single precision values
addps xmm3,xmm7    ; add packed single precision values
```

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

### Virtual-Machine Extensions (VMX)

Source: https://flatassembler.net/docs.php/index_article=manual

Documentation for VMX instructions used for virtual machine management.

```APIDOC
## VMX Instructions

### Description
Provides instructions for managing virtual machines using Virtual-Machine Extensions (VMX).

### Method
Various (refer to individual instructions)

### Endpoint
N/A (assembly instructions)

#### Instruction Details:

- **`vmxon`**
  - **Description**: Enters VMX operation. Requires a single 64-bit memory operand pointing to the VMXON region.
  - **Operands**: 1 (64-bit memory)

- **`vmxoff`**
  - **Description**: Leaves VMX operation. Takes no operands.
  - **Operands**: 0

- **`vmlaunch`**
  - **Description**: Launches a virtual machine. Takes no operands.
  - **Operands**: 0

- **`vmresume`**
  - **Description**: Resumes a virtual machine. Takes no operands.
  - **Operands**: 0

- **`vmcall`**
  - **Description**: Allows guest software to call the VM monitor. Takes no operands.
  - **Operands**: 0

- **`vmptrld`**
  - **Description**: Loads the physical address of the current Virtual Machine Control Structure (VMCS). Requires a single 64-bit memory operand.
  - **Operands**: 1 (64-bit memory)

- **`vmptrst`**
  - **Description**: Stores the pointer to the current VMCS into memory. Requires a single 64-bit memory operand.
  - **Operands**: 1 (64-bit memory)

- **`vmclear`**
  - **Description**: Sets the launch state of a VMCS to clear. Requires a single 64-bit memory operand.
  - **Operands**: 1 (64-bit memory)

- **`vmread`**
  - **Description**: Reads a field from VMCS into a register or memory. Source operand is a general-purpose register, destination can be register or memory. Operand size is 64-bit in long mode, 32-bit otherwise.
  - **Operands**: 2 (Source: register, Destination: register/memory)

- **`vmwrite`**
  - **Description**: Writes a value to a VMCS field. Source can be register or memory, destination must be a register. Operand size is 64-bit in long mode, 32-bit otherwise.
  - **Operands**: 2 (Source: register/memory, Destination: register)

### Request Example
```assembly
vmxon [physical_address_of_vmxon_region]
vmxoff
vmlaunch
vmresume
vmcall
vmptrld [memory_operand]
vmptrst [memory_operand]
vmclear [memory_operand]
vmread REX.W R10, VMCS_FIELD_ENCODING
vmwrite VMCS_FIELD_ENCODING, R11
```

### Response
N/A (assembly instructions modify processor state)

```

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

### Intercepting Lines with Custom Prefixes using 'macro ?'

Source: https://flatassembler.net/docs.php/index_article=fasmg

This example demonstrates how to use the 'macro ?' directive to intercept lines starting with special characters like '.' (e.g., '.CODE', '.DATA'). It allows processing these custom commands by invoking corresponding global macroinstructions or passing other lines through unmodified. This method is effective for handling syntax that conflicts with standard assembler interpretations.

```assembly
macro ? line&
        match .=CODE?, line
                CODE
        else match .=DATA?, line
                DATA
        else
                line
        end match
end macro  

```

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

### Macro with Include Directive (Example 2)

Source: https://flatassembler.net/docs.php/index_article=ufasm

Shows a macro 'Inc' that uses the 'include' directive. The macro takes a parameter 'f', quotes it, and appends '.inc'. This generated line is then processed by the preprocessor to include the specified file.

```assembly
macro Inc f
{
    include `f#'.inc'
}

Inc win32a

```

```assembly
    include 'win32a.inc'

```

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

### AMD 3DNow! Instructions

Source: https://flatassembler.net/docs.php/index_article=manual

This section covers AMD 3DNow! instructions, which extend MMX capabilities to operate on packed single-precision floating-point values.

```APIDOC
## AMD 3DNow! Instructions

### Description
The 3DNow! extension adds new MMX instructions and introduces operations on 64-bit packed floating-point values, each consisting of two single-precision floating-point values. These instructions follow the same rules as general MMX operations: the destination operand should be an MMX register, and the source operand can be an MMX register or a 64-bit memory location.

### Instructions:
- **pavgusb**: Computes the rounded averages of packed unsigned bytes.
- **pmulhrw**: Performs a signed multiplication of packed words, rounds the high word of each double word result, and stores them in the destination operand.
- **pi2fd**: Converts packed double word integers into packed floating-point values.
- **pf2id**: Converts packed floating-point values into packed double word integers using truncation.
- **pi2fw**: Converts packed word integers into packed floating-point values; only the low words of each double word in the source operand are used.
- **pf2iw**: Converts packed floating-point values to packed word integers; results are extended to double words using sign extension.
- **pfadd**: Adds packed floating-point values.
- **pfsub**: Subtracts packed floating-point values (destination - source).
- **pfsubr**: Subtracts packed floating-point values (source - destination).
- **pfmul**: Multiplies packed floating-point values.
- **pfacc**: Adds the low and high floating-point values of the destination operand, storing the result in the low double word of destination. It then adds the low and high floating-point values of the source operand, storing the result in the high double word of destination.
- **pfnacc**: Subtracts the high floating-point value of the destination operand from the low, storing the result in the low double word of destination. It then subtracts the high floating-point value of the source operand from the low, storing the result in the high double word of destination.
- **pfpnacc**: Subtracts the high floating-point value of the destination operand from the low, storing the result in the low double word of destination. It then adds the low and high floating-point values of the source operand, storing the result in the high double word of destination.
- **pfmax**: Computes the maximum of floating-point values.
- **pfmin**: Computes the minimum of floating-point values.
- **pswapd**: Reverses the high and low double words of the source operand.
- **pfrcp**: Returns estimates of the reciprocals of floating-point values from the source operand.
- **pfrsqrt**: Returns estimates of the reciprocal square roots of floating-point values from the source operand.
- **pfrcpit1**: Performs the first step in the Newton-Raphson iteration to refine the reciprocal approximation produced by the `pfrcp` instruction.
- **pfrsqit1**: Performs the first step in the Newton-Raphson iteration to refine the reciprocal square root approximation produced by the `pfrsqrt` instruction.
- **pfrcpit2**: Performs the second final step in the Newton-Raphson iteration to refine the reciprocal approximation or the reciprocal square root approximation.
- **pfcmpeq**: Compares packed floating-point values for equality and sets all bits or zeroes all bits of the corresponding data element in the destination operand according to the result.
- **pfcmpge**: Compares packed floating-point values and checks if the destination value is greater than or equal to the source value, setting bits accordingly.
- **pfcmpgt**: Compares packed floating-point values and checks if the destination value is greater than the source value, setting bits accordingly.

### Method
AMD 3DNow! Instructions

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **destination** (MMX register) - Description
- **source** (MMX register or 64-bit memory) - Description

### Request Example
```assembly
pavgusb mm0, [mem]
```

### Response
#### Success Response (N/A)
- **destination** (MMX register) - Contains the result of the operation.

#### Response Example
N/A
```

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

### Compiler Overview

Source: https://flatassembler.net/docs.php/index_article=manual

Provides an overview of the flat assembler, its purpose, and system requirements.

```APIDOC
## Compiler Overview

Flat assembler is a fast assembly language compiler for the x86 architecture processors, which does multiple passes to optimize the size of generated machine code. It is self-compilable and versions for different operating systems are provided. All the versions are designed to be used from the system command line and they should not differ in behavior.

### System Requirements

All versions require the x86 architecture 32-bit processor (at least 80386), although they can produce programs for the x86 architecture 16-bit processors, too. DOS version requires an OS compatible with MS DOS 2.0 and either true real mode environment or DPMI. Windows version requires a Win32 console compatible with 3.1 version.
```

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

### Include Predefined Import Tables (Flat Assembler)

Source: https://flatassembler.net/docs.php/index_article=win32

Flat Assembler allows including pre-made import tables for standard libraries. This example includes the ASCII variant of KERNEL32.DLL imports and the WideChar variant of USER32.DLL imports, assuming the INCLUDE environment variable is set correctly.

```assembly
  library kernel32,'KERNEL32.DLL',\
          user32,'USER32.DLL'

  include 'apia\kernel32.inc'
  include 'apiw\user32.inc'
```

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

### XSAVE Set of Instructions

Source: https://flatassembler.net/docs.php/index_article=manual

Documentation for instructions used to save and restore processor state components.

```APIDOC
## XSAVE Set of Instructions

### Description
Provides instructions for saving and restoring processor state components using XSAVE.

### Method
Various (refer to individual instructions)

### Endpoint
N/A (assembly instructions)

#### Instruction Details:

- **`xsave`**
  - **Description**: Stores processor state components defined by a bit mask in EDX:EAX into a memory area. Takes a memory operand.
  - **Operands**: 1 (Memory area for state)

- **`xsaveopt`**
  - **Description**: Optimized version of `xsave`. Stores processor state components defined by a bit mask in EDX:EAX into a memory area. Takes a memory operand.
  - **Operands**: 1 (Memory area for state)

- **`xrstor`**
  - **Description**: Restores processor state components from a memory area, defined by a mask in EDX:EAX.
  - **Operands**: 1 (Memory area for state)

- **`xsave64`**
  - **Description**: 64-bit version of `xsave`, allowed only in long mode.
  - **Operands**: 1 (Memory area for state)

- **`xsaveopt64`**
  - **Description**: 64-bit optimized version of `xsaveopt`, allowed only in long mode.
  - **Operands**: 1 (Memory area for state)

- **`xrstor64`**
  - **Description**: 64-bit version of `xrstor`, allowed only in long mode.
  - **Operands**: 1 (Memory area for state)

- **`xgetbv`**
  - **Description**: Reads the contents of a 64-bit XCR specified by ECX into EDX:EAX. Takes no operands.
  - **Operands**: 0 (Reads XCR specified by ECX)

- **`xsetbv`**
  - **Description**: Writes the contents of EDX:EAX into the 64-bit XCR specified by ECX. Takes no operands.
  - **Operands**: 0 (Writes to XCR specified by ECX)

### Request Example
```assembly
xsave [memory_area]
xrstor [memory_area]
xsave64 [memory_area]
xrstor64 [memory_area]
mov ECX, XCR_NUMBER
xgetbv
xsetbv
```

### Response
N/A (assembly instructions modify processor state)

```

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

### INC Instruction Examples

Source: https://flatassembler.net/docs.php/index_article=manual

Shows examples of the INC instruction, which increments an operand by one without affecting the Carry Flag (CF). Operands can be general registers or memory locations, and can be byte, word, or double word.

```assembly
inc ax          ; increment register by one
    inc byte [bx]   ; increment memory by one
```

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

### Intercept Any Line Start with Label (Assembly)

Source: https://flatassembler.net/docs.php/index_article=fasmg

This snippet defines a macroinstruction that intercepts any line starting with an identifier not recognized as a known instruction. It handles labels followed by ':', '=', or other text, allowing a label to begin any source line.

```assembly
struc ? tail&
                match :, tail 
                        .: 
                else match : instruction, tail
                        .: instruction
                else match == value, tail
                        . = value
                else 
                        .: tail
                end match 
        end struc

```

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

### Manage Output Areas with ORG and SECTION

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

Demonstrates the behavior of 'org' and 'section' in handling initialized and uninitialized data. 'section' can trim preceding reserved data, while 'org' simply starts a new area. Uninitialized data at the end of the file is not written.

```assembly
data1 dw 1
buffer1 rb 10h          ; zeroed and present in the output

org 400h
data dw 2
buffer2 rb 20h          ; not in the output

section 1000h
data3 dw 3
buffer3 rb 30h          ; not in the output
```

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

### CALM Instruction with Label Publishing - FASM

Source: https://flatassembler.net/docs.php/index_article=fasmg

Demonstrates using the 'compute' and 'publish' commands in CALM to replicate label definition. 'compute' gets the current address ($), and 'publish' assigns this address to a generated symbol, similar to defining a label.

```assembly
        global_uid = 0

        calminstruction pointer
                compute global_uid, global_uid + 1
                local symbol, command
                arrange symbol, =next#global_uid
                arrange command, =db symbol
                assemble command
                local address
                compute address, $ 
                publish symbol:, address
        end calminstruction 

```

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

### Define CALM Instructions as Symbols with 'publish'

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

This example demonstrates defining a custom CALM instruction ('initsym') that uses the 'publish' directive to assign a value to a variable. This allows initializing symbols directly within the CALM instruction context.

```assembly
calminstruction calminstruction?.initsym? variable*,value&
                publish variable, value
        end calminstruction

```

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

### Define Custom CALM Instructions with 'macro'

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

Macros allow defining custom commands within the 'calminstruction' namespace. This example defines 'asmarranged' which arranges a variable and then assembles it. It's then used to create a 'writeln' command.

```assembly
macro calminstruction?.asmarranged? variable*, pattern&
                arrange variable, pattern
                assemble variable
        end macro

        calminstruction writeln? text&
                asmarranged text, =display text,10
        end calminstruction

        writeln 'Next!'

```

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

### Creating a Macro Wrapper with outscope in Flat Assembler

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

Illustrates how to create a macroinstruction wrapper for the 'irpv' directive using the 'outscope' directive. This example defines a macro 'irpv?!' that, when executed, displays a message and then calls 'irpv' with the 'outscope' directive. 'outscope' ensures that any parameters defined by the called 'irpv' are created in the context of the source text calling the macro, not within the macro itself.

```assembly
        macro irpv?! statement&
                display 'IRPV wrapper'
                esc outscope irpv statement
        end macro

```

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

### FASM FIX Directive Example: Replacing ENDM with }

Source: https://flatassembler.net/docs.php/index_article=ufasm

Illustrates the usage of the FIX directive, which performs token replacements at the source reader level before general preprocessing. The example shows how to redefine ENDM to be interpreted as a closing brace, primarily for syntax adjustment.

```assembly
FIX ENDM }

macro mymacro arg
  ; ... macro definition ...
ENDM ; This will now be treated as }

```

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

### x86 Long Mode: Type Conversion Instructions

Source: https://flatassembler.net/docs.php/index_article=manual

Provides examples of new type conversion instructions available in x86 long mode: 'cdqe' for sign-extending EAX to RAX, 'cqo' for sign-extending RAX to RDX, and 'movsxd' for sign-extending a 32-bit operand to a 64-bit register.

```assembly
    cdqe             ; sign extends EAX into RAX
    cqo              ; sign extends RAX into RDX:RAX
    movsxd rbx, eax  ; sign extends EAX into RBX
```

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

### Conditional Inclusion Based on Symbol Match

Source: https://flatassembler.net/docs.php/index_article=manual

This snippet demonstrates the basic usage of the `match` directive to conditionally include files based on a simple symbol match. The first example includes 'first.inc' because '+' in the pattern matches the '+' symbol in the input, while the second example does not include 'second.inc' due to a non-match.

```assembler
match +,+ { include 'first.inc' }
match +,- { include 'second.inc' }
```

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

### Assembler Code Example: Interpreted Layer and Label Resolution

Source: https://flatassembler.net/docs.php/index_article=ufasm

This snippet illustrates the coexistence of the interpreted layer and label resolution in Flat Assembler. It shows a variable 'A' being calculated using arithmetic operations and then used to define the address of a label 'gamma', demonstrating how the assembler integrates interpreted values with label definitions.

```assembly
        mov     eax,gamma
A = 1
repeat 5
    A = A*%
end repeat
label gamma at $+A-7


```

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

### Define Structure with Array Field in Flat Assembler

Source: https://flatassembler.net/docs.php/index_article=win32

Defines a 'FOO' structure with a byte array 'data' of 256 elements. The example shows initializing the first few bytes of the array and the rest are left undefined.

```assembly
struct FOO
  data db 256 dup (?)
ends

some FOO <"ABC",0>
```

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

### Flat Assembler: Virtual Addressing Space with File Extension

Source: https://flatassembler.net/docs.php/index_article=manual

Shows how to use the 'virtual' directive with both 'at' and 'as' keywords. The 'as' keyword specifies an additional file extension where the initialized content of the virtual addressing space will be stored upon successful assembly.

```assembly
    virtual at 0 as 'asc'
        times 256 db %-1
    end virtual

```

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

### Define Menu Item with State and Type Flags

Source: https://flatassembler.net/docs.php/index_article=win32

Defines a menu item with specific state and type flags. This example shows how to set an item as checked ('MFS_CHECKED') and configure it as a radio button ('MFT_RADIOCHECK').

```assembly
  menuitem 'Selection',102, ,MFS_CHECKED,MFT_RADIOCHECK
```

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

### Include External File Data with file

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

The 'file' instruction reads data from an external file and writes it to the output. It takes the file path as a string. Optional arguments include an offset within the file and the number of bytes to copy. 'file 'data.bin'' inserts the entire file. 'excerpt file 'data.bin':10h,4' inserts 4 bytes starting from offset 10h.

```assembly
file 'data.bin'                 ; insert entire file
```

```assembly
excerpt file 'data.bin':10h,4   ; insert selected four bytes
```

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

### Manage Virtual and Real Address Spaces (Assembly)

Source: https://flatassembler.net/docs.php/index_article=fasmg

This snippet demonstrates managing distinct address spaces for data and code using 'element', 'org', and 'virtual'. It defines macros to switch between these spaces and uses 'postpone' to ensure proper closing of virtual blocks.

```assembly
element DATA
        DATA_OFFSET = 2000h
        element CODE
        CODE_OFFSET = 1000h

        macro DATA?
                _END
                virtual at DATA + DATA_OFFSET
        end macro

        macro CODE?
                _END
                org CODE + CODE_OFFSET
        end macro

        macro _END?
                if $ relativeto DATA
                        DATA_OFFSET = $ - DATA
                        end virtual
                else if $ relativeto CODE
                        CODE_OFFSET = $ - CODE
                end if 
        end macro

        postpone
                _END
        end postpone

        CODE

```

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

### AVX 256-bit Data Store Operation

Source: https://flatassembler.net/docs.php/index_article=manual

Example of storing unaligned 256-bit data to memory using the VMOVUPS instruction with AVX registers.

```assembly
vmovups [edi],ymm6        ; store unaligned 256-bit data
```

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

### Assembly: Comment and line continuation

Source: https://flatassembler.net/docs.php/index_article=manual

Illustrates how comments are handled (text after ';') and how to continue a long instruction onto the next line using the '\' character.

```assembly
mov eax, 1 ; This is a comment\
  mov ebx, 2
```

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

### Assembly: Quoted string example

Source: https://flatassembler.net/docs.php/index_article=manual

Shows the syntax for using quoted strings, which can contain any characters including special ones. Double quotes are used here.

```assembly
mov eax, "Hello, World!"
```

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

### Match for Single Iteration with Variable Conversion

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

This snippet rewrites a previous example using 'irpv' to use 'match' for single iteration on the last value of a symbolic variable. It demonstrates how 'match' can replace 'irpv' for converting a symbolic variable's value.

```assembly
x = 1
var equ x
match symbol, var
        symbol = 2
end match
assert x = 2
```

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

### Defining Labels with Size

Source: https://flatassembler.net/docs.php/index_article=fasmg_manual

Demonstrates defining labels using the 'label' keyword, optionally specifying their size in bytes. This is equivalent to using ':' but occupies a full line and allows for size specification.

```assembly
        label character:byte
        label char:1

```

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

### FASM Tokenization Example: mov ax, 2+1

Source: https://flatassembler.net/docs.php/index_article=ufasm

Illustrates how FASM's preprocessor parses a line of assembly code into individual tokens. It shows the separation of name tokens, symbol characters, and numeric literals based on whitespace and special characters.

```assembly
mov     ax,2+1
```

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

### vpinsrd Insertion Operation (Assembly)

Source: https://flatassembler.net/docs.php/index_article=manual

Shows an assembly example of the vpinsrd instruction, which inserts a double word into an SSE register. This instruction uses a four-operand syntax.

```assembly
    vpinsrd xmm0,xmm0,eax,3  ; insert double word
```

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

### Safer Mode Extensions (SMX)

Source: https://flatassembler.net/docs.php/index_article=manual

Documentation for the `getsec` instruction used in Safer Mode Extensions (SMX).

```APIDOC
## Safer Mode Extensions (SMX)

### Description
Provides security functionalities through the `getsec` instruction.

### Method
`getsec`

### Endpoint
N/A (assembly instruction)

### Parameters
#### Instruction Details:

- **`getsec`**
  - **Description**: Executes a function determined by the contents of the EAX register. Takes no operands.
  - **Operands**: 0

### Request Example
```assembly
mov EAX, FUNCTION_CODE
getsec
```

### Response
N/A (assembly instruction modifies processor state)

```

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

### Compiler Error: Source File Not Found

Source: https://flatassembler.net/docs.php/index_article=manual

An example of an error message displayed when the compiler cannot locate the input source file. This indicates a file path issue.

```text
flat assembler  version 1.73 (16384 kilobytes memory)
error: source file not found.


```
Tokens:
Raw