ZASM Language Reference

Documentation home · Complete examples · Include files

This reference covers the current Windows x86 assembler. An instruction name appearing in a source-code constant or an older design document does not establish support; the operand forms below describe the implemented encodings.

Source Files and Statements

• .zasm is the main assembly source file. .zh is the convention for shared headers.
• Write one instruction, data directive, label, or include statement per line.
• Indentation uses spaces or tabs. Separate operands with commas.
• Use Intel-style destination-first order: add eax, 5 adds 5 to EAX.
• Mnemonics, register names, labels, and the using keyword are case-insensitive.
• Keep DLL export names in their documented spelling, such as MessageBoxA.
• Start comments with ;. // and block comments are not implemented for ZASM.
• A semicolon outside quotes comments out the remainder of the line; it does not separate instructions.

  mov eax, 7       ; EAX now contains 7.
  add eax, 5       ; EAX now contains 12.

The entry point is the first emitted byte, even if it belongs to a data directive. Neither start: nor main: automatically selects an entry point. Place code first or use jmp start before inline data. Import/include declarations themselves emit no CPU instructions, though included files can contain instructions or data.

Operands

Decimal and hexadecimal integer literals are supported. Hexadecimal can use a 0x prefix or an h suffix. Binary literals, floating-point literals, and general expressions such as 2 * 4 or message + 1 are Coming Soon. Signed decimal immediates are not consistently accepted across instructions; use a 32-bit hexadecimal bit pattern, such as 0xFFFFFFFF, when needed. Data directives parse integer operands directly and can accept signed decimal values.

Square brackets mean memory access when used with MOV or indirect CALL. With LEA, brackets describe an address to calculate without reading its contents:

value: dd 42
; Instruction examples; place data behind a jump in a complete program.
mov eax, value       ; Address of value.
mov eax, [value]     ; The 32-bit value 42 stored at that address.
lea edx, [value]     ; Address of value, without loading the stored number.

Memory Addressing

MOV r32, [mem] and LEA r32, [mem] accept these forms:

The displacement can also be a resolvable address symbol. Scaled indexes, multiple register bases, and subtraction syntax such as [ebp - 4] are not implemented. Examples using [esp + 4] assume the stack contains valid data there. Indirect CALL has a narrower form: use an absolute address or import/data symbol, such as call [puts]. Register-indirect calls and [reg + offset] calls are not supported.

Registers

The current backend emits 32-bit instructions using these general-purpose registers. The roles are conventions; instructions determine how a register is used.

Use these 32-bit names. Register constants such as AX, AL, RAX, and XMM0 exist in the project, but their corresponding instruction widths are not implemented. Their presence is not a guarantee that they encode correctly.

Instruction Reference

imm32/address means a number or an address symbol. Arithmetic and bitwise instructions below operate on 32-bit registers; memory operands are limited to the explicitly listed forms.

Short jumps must be within -128 through +127 bytes of the end of the instruction. Use JZ or JNZ when the short form is out of range. JE and JNE aliases are not currently implemented. RET accepts a cleanup count from 0 to 65535 bytes; use it only when returning to a caller that expects that calling convention.

INT is not a portable console-output or system-call interface for a Windows application. Use imported Windows/C runtime functions for the examples here.

Compare and Branch

  mov eax, 7
  add eax, 5
  cmp eax, 12
  jz equal
  mov eax, 1
  jmp done
equal:
  mov eax, 0
done:
  nop

This is a fragment: add program termination in a complete application. ZASM has no high-level if statement or loop statement yet; use labels and branches. See the arithmetic example for a complete program.

Assembler Directives

A directive controls assembly rather than describing a CPU instruction. Data directives emit bytes; imports describe DLL dependencies. using loads additional source before assembly.

DW and DD accept integer literals, not quoted strings, symbol initializers, or floating-point values. DB integer operands emit their low 8 bits; DW emits the low 16 bits. Values do not imply range-checked variable types. DQ, repetition directives such as TIMES/DUP, alignment, constants, and separate data/code sections are Coming Soon.

Strings and Named Data

message db 'Hello, World!', 0x0A, 0
quote: db 'It''s Zero', 0
path: db "C:\Zero\samples", 0

Both single-quoted and double-quoted strings emit UTF-8. Double the matching quote to put it inside a string. Backslashes are literal: use numeric 10 or 0x0A for a newline rather than \n. A trailing zero is not added automatically. Semicolons, commas, and colons inside quotes are ordinary text. Whether a library displays UTF-8 correctly depends on that API and the console configuration.

message db ... and message: db ... both work. Use the colon form for DW and DD. Names describe addresses, not writable high-level variables. Current data declarations are stored in the read-only .text section. For writable scratch space, existing samples reserve stack space and pass its address to a DLL.

Labels

A label names the current position and can appear before an instruction on the same line. Forward references are supported.

  jmp start
message db 'Hello', 0
start: push message

Label rules:

• Start with a letter, underscore, or period; continue with letters, digits, underscores, or periods.
• Use unique names throughout the expanded source, including headers.
• Names are case-insensitive. start and START identify the same symbol.
• A leading period does not create a local scope; .loop is still a global label.
• Register names cannot be labels. Labels must not collide with imported symbols.
• Use bare labels for direct branches/calls; use address symbols for data operands.

Procedures are labels followed by instructions and usually RET; no PROC or ENDP directive is required or implemented. The top-level program should call exit or ExitProcess rather than depend on RET to terminate it.

Imports and Calling Conventions

#import kernel32.dll, ExitProcess
#IMPORT msvcrt.dll, puts, exit

#import and #IMPORT are the same directive. DLL names without an extension get .dll appended. Declare the actual exported function spelling; for example, use MessageBoxA for the ANSI API. Import declarations do not describe parameter types or perform argument checking. Push arguments in reverse order yourself.

The IAT_ prefix is optional for unambiguous function names. Plain aliases are unavailable when multiple imported DLLs export the same requested name.

For x86 C runtime functions such as puts and printf, the caller removes the arguments after the call. Each argument in these examples occupies 4 bytes:

  push message
  call [puts]
  add esp, 4

For x86 Win32 APIs such as MessageBoxA, the callee removes its arguments:

  push 0           ; uType
  push caption     ; lpCaption
  push message     ; lpText
  push 0           ; hWnd
  call [MessageBoxA]

These snippets require the referenced labels and imports. See the complete examples. Library calls can overwrite EAX, ECX, and EDX. Preserve any values you need across calls, and preserve EBX, ESI, EDI, and EBP when implementing a procedure or callback whose ABI requires it.

Shared Headers

using "windows/console.zh"
using "subfolder/helpers.zh" ; A trailing comment is allowed.

Search order is:

1. The process’s current working directory.
2. Directories supplied by repeated -I or --include, in order.
3. include beside the compiler executable.

The entire relative filename is appended to each directory. Nested includes use the same roots, not the directory containing the current header. Absolute paths are checked directly. Resolved, normalized paths are included once per compilation; active cycles report an error with the chain. Missing-file errors list the requesting source location and searched paths.

DLL-specific headers also cover Kernel32, User32, GDI32, ComCtl32, ComDlg32, Shell32, Winsock, registry/security, COM, Automation, path helpers, multimedia, HTTP, and file versions. See Windows API headers for the catalog, architecture naming, string encodings, and initialization requirements.

The repository keeps these files in root include; publishing copies them to publish/include. Read the include guide for more details. Use the windows/ prefix for working Windows headers. Separate Linux drafts under linux/ prepare future ELF interfaces; they are not runnable with the current backend.

Command Line and Errors

zero <source> [output.exe] [-I <directory>]...
zero run <source> [output.exe] [-I <directory>]...

zcc accepts the same arguments. Options can appear before or after the positional filenames, after run if present. -I and --include each take a separate directory argument. -h and --help display help. The output defaults to the source path with an .exe extension. run inherits the terminal and working directory, waits for completion, and returns the generated program’s exit code.

After successful compilation, run returns the application’s code, which can overlap these compiler error values. The preceding diagnostics distinguish the cases. No application is launched after a compilation failure.

Source errors include a filename and line number, even when the error originates in an included header. Check for an unsupported mnemonic/form, a misspelled symbol, an invalid include path, or a short jump out of range.

Current Limitations

The following require future implementation:

• Register-to-register MOV, memory stores, arithmetic on memory operands, and register-indirect calls.
• MUL, division, ADC, SBB, NOT, string instructions, flag-stack instructions, and additional branch conditions.
• Real 8-bit, 16-bit, 64-bit, or SIMD instruction forms.
• Macros, constants/equates, conditional assembly, general expressions, and typed structures.
• Writable data sections, alignment/reservation directives, and entry-point/subsystem selection.
• #zero, #entry, #define, #importlib, PROC, ENDP, END, and MASM-style section/model directives.
• Object files, linker inputs, exports, and .zprj project files.
• Higher-level Zero compilation, ELF output, and ARM/ARM64 or native x64 code generation.

Coming Soon: expand this reference as each feature gains working syntax and examples. The ZASM feature roadmap tracks implemented features and outstanding work. The documentation roadmap collects broader topics to fill in.