alien-assembly ( args... return parameters abi quot -- return... )
Factor handbook » C library interface » Calling arbitrary assembly code

Vocabulary
alien

Inputs

args...	zero or more objects passed to the C function
return	a C return type
parameters	a sequence of C parameter types
abi	one of cdecl or stdcall
quot	a quotation

Outputs

return...

the return value of the function, if not void

Word description
Invokes arbitrary machine code, generated at compile-time by the quotation. Input parameters are taken from the data stack, and the return value is pushed on the data stack after the function returns. A return type of void indicates that no value is to be expected.

The quotation passed to this word must preserve the ds-reg and rs-reg registers. Note that this is not a call in the assembly sense, so there is no return address on the stack.

It's important to mind the ABI. For instance, on x86.32, parameters are passed on the stack in ESP, while on x86.64 arguments are passed in RDI, RSI, RDX, and RCX, and then on the stack. On Windows 64, integers and pointers are passed in RCX, RDX, R8, and R9.

There are Factor words for the input parameters, such as param-reg-0 and param-reg-1.

For output parameters, use return-reg.

Notes
C type names are documented in C type specifiers.

Errors
Throws an callsite-not-compiled if the word calling alien-assembly is not compiled.

See also
alien-invoke, alien-indirect, alien-callback

Definition

IN: alien

: alien-assembly
    ( args... return parameters abi quot -- return... )
    \ alien-assembly callsite-not-compiled ;