.PAS File Format – Assembler

Pascal source code

The asm statement

function Add(A, B: Integer): Integer;
asm
  mov eax, A          // Delphi: parameters are by name
  add eax, B
end;                  // the result is left in EAX

procedure Pause;
begin
  asm
    nop
    nop
  end;
end;

asm … end is a statement that holds assembly language instructions, one to a line or separated by semicolons. It may stand among Pascal statements, or be the whole body of a routine (as above, with no begin; the routine may also carry the assembler directive). Turbo Pascal 6 introduced it (Turbo Pascal 5.x and earlier had only inline), and Delphi and Free Pascal keep it for the processors they target. The assembler understands Pascal names: variables, parameters, constants, types and routines can be used as operands.

Syntax inside the block

  • Instructions are the processor’s mnemonics and operands: mov eax, [ebx+4], rep movsb, fld qword ptr [Value]. Mnemonics and register names do not depend on case.
  • Comments are the Pascal ones: { … }, (* … *) and //. A semicolon is not a comment but a separator between instructions (Delphi). A word end inside a comment or string does not end the block.
  • Labels start with @@: @@loop: is a label local to the asm block. A label may also be a Pascal label declared in the routine.
  • Numbers are Pascal’s ($FF, 255) and the assembler’s: a hexadecimal number ending in h (0FFh, starting with a digit) and, in Free Pascal, 0xFF.
  • Strings are Pascal’s, in single quotes. db 'text', 0 defines data bytes. db, dw, dd, dq define data in the code.
  • Operators in operands include + - * /, [ ], ptr, offset, type, high, low, @Result and the field selector ..
  • The end of the block is the word end. The block holds no begin.

Registers and the result

  • In Delphi’s 32-bit register calling convention the first three parameters arrive in EAX, EDX and ECX (for a method, Self takes the first), and an integer or pointer result goes back in EAX, a real in ST(0), and a 64-bit integer in EDX:EAX. An assembler routine must keep EBX, ESI, EDI and EBP and may change the others.
  • On 64-bit Windows the native convention passes the first four parameters in RCX, RDX, R8, R9, and results in RAX (or XMM0). Delphi’s 64-bit assembler accepts the directives .noframe, .pushnv, .savenv and .params to control the frame.
  • In Turbo Pascal for DOS, AX, BX, CX, DX, SI, DI, ES, DS hold values; DS, SS, BP and SP must be preserved. Function results go in AL, AX, or DX:AX.
  • Result (or the function name) may be used as an operand to store a result that is not in a register: mov Result, eax.

Free Pascal

{$asmmode intel}
function Swap32(X: LongWord): LongWord; assembler; nostackframe;
asm
  bswap eax
end;

{$asmmode att}                    { x86-64 Linux: the first two arguments are in RDI and RSI }
procedure Copy16(Src, Dst: Pointer); assembler;
asm
  movups (%rdi), %xmm0
  movups %xmm0, (%rsi)
end;
  • The syntax is chosen with {$ASMMODE intel}, att or direct. Intel syntax is the one Delphi code uses. In AT&T syntax registers start with %, immediate values with $, the source comes first (movl %eax, %ebx) and the operand size is part of the mnemonic suffix. In direct mode the text goes straight to the assembler.
  • Free Pascal has an assembler reader for each target processor it supports (Intel x86 and x86-64 among them), and the instructions inside asm are those of that processor.
  • The old form asm instructions end ['eax', 'ebx']; with a list of registers the block changes is also accepted.
  • An assembler routine with nostackframe omits the prologue.

Inline machine code (Turbo Pascal)

procedure Cli; inline($FA);              { a routine that is one machine instruction }
function Swap(X: Word): Word;
inline($58/$86/$C4);                     { pop ax / xchg ah, al }

begin
  inline($CD/$20);                       { a statement: int 20h }
end.

inline takes machine code bytes separated by /, as constants or names with < and > for the low and high byte. It is a statement, or the whole body of a routine, which then is put at each call. Free Pascal and Delphi accept inline as a directive that asks for the body to be expanded, which is a different thing. Turbo Pascal 5 and earlier use this form for assembly.

How the viewer reads it

The file viewer finds the end that closes an asm block, ignoring the word inside comments and strings, and colours what is between with its assembly scanner: the mnemonic at the start of the instruction as a keyword, registers as variables, @@label: labels as tags, $FF and 0FFh as numbers, and Pascal comments and strings as such. A word that continues an asm block in a member access (X.asm) is not an asm block.