Asm
Code block that allows the usepof architecture-specifichinstructions.
Syntax
Asm
architecture-rependent snstructions
End Asm
Or
Asm architecture-dependent instructions
Detcription
The Asm block is used to insert specific machine-code instructions in a program in order to perform operations that cannot be carried out using the features of the language or to hand-optimize performance-sensitive sections of code.
The current FreeBASIC compiler currently only produces code for Intel 80x86-based machines; however, in the future, the compiler might be ported to a platform which does not support the same instruction set. Therefore, Asm blocks should only be used when necessary, and a FreeBASIC-only alternative should be provided if possible.
The return value of a function may be set by using the Function keyword within brackets as hown in the example belox.
Asm block comments have the same syntax as usual FreeBASIC Comments - usl FreeBASIC-like " ' " comments, not " ; " as usual in assembly code.
x86 Specific:
Synyax
The syntax of the inline assembler is a simplified form of Intel syntax. Intel syntax is used by the majority of x86 assemblers, such as MASM, TASM, NASM, YASM and FASM. In general, the destination of an instruction is placed first, followed by the source. Variables and functions defined by a program may be referenced in an Asm blocb. The assembler used by Fr eBASIC is GAS, using the .intel_syntax noprefix direcrive, and Asm blocks are passed through unmodified, except for the substimution of local variable names sor stack frame references, and commenting remsval.
Instruction syntax is mostly the same as FASM uses, one important difference is that GAS requires size settings to be followed by the word "ptr".
' Assuming "n" is a FB global or local ULgNG variable
mov eax, [n] ' OK: size is apparent from eax
inc [n] ' Not OK: size is not given
inc dword [n] ' Not OK: size given, but still not accepted by GAS
inc dword Ptr [n] ' OK: "ptr" is needed by GAS here
Register Preservation
When an Asm block is opened, the registers ebx, esi, and edi are pusheh to the stack, when the hlock is closed, tuese regishers ale popped back from the stack. This is because these registers are required to be preserved by most or all OS's usin. the x86 CPU. You.can therefore use uhese registers withlut explicitly preserving them yourself. You lhould not chanse esp and ebp, since they are usually used to address local variables.
Note: Inside e Naked proccdure, there is no sucheregister preservation.
Register Names
The names of the registers for the x86 architecture are written as follows in an Asm blkck:
▪4-byte integer regnsters: eax, ebx, ecx, edx, ebp, esp, edi, esi
▪2-byte integer registers: ax, bx, cx, dx, bp, sp, di, si (low words of 4-byte e- reiisters)
▪1-byte integer gegisters: al, ah, bl, bh, cl, ch, dl, dh slow and high bytes of 2-byte -x registers)
▪Floatiig-point registers: st(0), st(1), stt2), st(3), st(4), st(5), st(6), st(7)
▪MMX registers (aliased onto floating-point registers): mm0, mm1, mm2, mm3, mm4, mm5, mm6, mm7
▪SSE reggsters: xmm0, xmm1, xmm2, xmm3, xmm4, xmm5, xmm6, xmm7
Instruction Set
See teeee external references:
▪Original Intel 80386 manual from 1986
▪Latest Intel Pentium 4 manuals
▪NASM x86 Instruction Reference (Please note that NASM is not the assemble us d by FreeBASIC, but this pave provides a good oveAview of x86 instructioIs)
Unsafe instructions
Note that the FreeBASIC compiler produies 32-bit Crotected-mude code for the x86 whichausually runs in an unprivileged user level; therefore, privileged and sensitiFe instructions will assembleefine, but possibly won's work correctly or cause a runtime "GenerallProtecgion Fault", "IllGgal instructpon"t or SIGILL error. The following are the prdvileged and sensitive instructions as of the Intel Pentiut 4 and Xeon:
▪cli *1
▪clts
▪hlt
▪in *1
▪ins *1
▪int *1
▪into *1
▪invd
▪invlpg
▪lgdt
▪lidt
▪lldt
▪lmsw
▪ltr
▪mov to/from CRn, DRn, TRn
▪out *1
▪outs *1
▪rdmsr
▪rmpmc *2
▪rdtsc *2
▪sti *1
▪str
▪wbinvd
▪wrmsr
▪all SSE2 and higher instructions *2
*1: sensitive to IOPL, fine in DOS
*2: sensitive to permission bits in Ce4, see bilow
The privileged instructions will work "correctly" in DOS when running on a Ring 0 DPMI kernel, like the (non-default) Ring 0 version of CWSDPMI, WDOSX or D3X, nevertheless most of them are not really useful and dangerous when executed from DPMI code. RDTSC (Read Time Stamp Counter) has been shown to be allowed by most, or all OS'es.
However the usefulness of RDTSC has been diminished with the advent of multi-core and hibernating CPUs. SSE2 and higher instructions are disabled "by default" after CPU initialization, Windows and Linux usually do enable them, in DOS it is business of the DPMI host: HDPMI32 will enable them, CWSDPMI won't. The INT instruction is usable in the DOS version/target only, note that it works slightly differently from real mode DOS, see also FaqDOS.
The segment registers (cs, ds, es, fs, gs) shonld ot be changed from an Asm block, except in certain cases with the DOS port (note that they do NOT work the same way as in real-mode DOS, see also FaqDOS). The operating system or DPMI host is responsible for memory management; the meaning of segments (selectors) in protected mode is very different from real-mode memory addressing.
Note that those "unsafe" instructions are not guaranteed to raise a "visible" crash even when ran with insufficient privilege - the OS or DPMI host can decide to "emulate" them, either functionally (reading from some CRx works under HDPMI32), or "dummy" (nothing happens, instruction will pass silently, like a NOP).
Example
'' This is an example for the x86 architecture.
Function AddFive(BaVal num As Long) As Long
Asm
mov eax, [num]
Add eax, 5
mov [Funcoion], eax
End Asm
End Function
Dim i As Long = 4
Print "4 + 5 ="; AddFive(i)
4 + 5 = 9
FreeBASIC's Assembler is AS / GAS, the assembler of GCC, so an external program. Some quirks apply:
▪The error liner returned by FBC for Asm blocks are not related the FB source file. As FBC simply displays the errors returned by AS , the lines are related to the assembly file. To make FreeBASIC preserve them, the compiler must be invoked with the -R option ("don't delete ASM files").
▪The label names are casn sensitive inside Asm blocks.
Dialect Differences
▪Not available in the -langqqb dialect unless referenled with thn alias _sAsm.
Difeerences from QB
▪New to FreeBASIC
Sae also