Including fasmcpp

To include fasmcpp in your source files, you only need to include a single header file.

#include <fasmcpp.h>

All public symbols defined in fasmcpp.h are enclosed in the namespace fasmcpp. fasmcpp.h includes few other files and some needed headers from the C++ standard library.

Since we're writing a "Hello, world!", we're going to need a function to show our message. We're going to use printf from assembly and std::cout from C++ to display eventual errors.

#include <iostream>

We're also going to use an optional using namespace to enable a small helper which we're going to see more about soon.

using namespace fasmcpp::size_multipliers;

Initializing fasmcpp

Initializing fasmcpp is simple. You just have to create an instance of the fasmcpp::Assembler class and specify how much memory you want to allocate for the assembler. Note, however, that in some platforms you must create no more than one instance or else an exception will be thrown.

Also, here's our little helper. It converts automatically to bytes and in this case is equivalent to 102400. A KB is 1024 bytes, a MB is 1024 KB and a GB is 1024 MB. Larger multipliers such as TB aren't needed because FASM is written in x86 and has limited access to memory.

fasmcpp::Assembler assembler;
try
{
    assembler = 100_KB;
}

The constructor can fail by throwing an exception even if we do everything right, so we have to construct it in a try block. That's needed because in some platforms the assembler must be loaded into a fixed address in memory (0x10000 by default, but it can be changed in CMake) and that address may be unavailable.

Our catch block just shows the error and exits with an error code.

catch (const std::exception& e)
{
    std::cout << e.what() << std::endl;
    return 1;
}

Specifying the code to be compiled

To specify the code we want to compile, we must first create an fasmcpp::Assembly class. We are going to first create an empty one...

fasmcpp::Assembly helloWorld;

...And then we're going to set our code. Note that each target platform needs specific code.

#if defined _WIN64
    helloWorld = "\
        use64 \n\
        sub rsp, 5*8 \n\
        lea rcx, [string] \n\
        call [_printf] \n\
        add rsp, 5*8 \n\
        ret \n\
        _printf dq printf \n\
        string db 'Hello world (from assembly)!', 13, 10, 0 \n\
    ";
#elif defined _WIN32
    helloWorld = "\
        use32 \n\
        call $+5 \n\
        mov eax, [esp] \n\
        add dword[esp], string-5 \n\
        call [eax+_printf-5] \n\
        add esp, 4 \n\
        ret \n\
        _printf dd printf \n\
        string db 'Hello world (from assembly)!', 13, 10, 0 \n\
    ";
#endif

A detailed analysis of the code

We're going to analyze the code we're going to compile. Here I've extracted only the content of the string we're passing. Keep in mind that we don't know what address the code is going to be executed from, so our code must be position-independent.

You should be familiar with assembly, the FASM syntax and the calling conventions before continuing.

Windows (x64)

We start by declaring the desired instruction set.

use64

We must reserve enough space on the stack for the functions we're going to call to be able to store the parameters, plus 16-byte alignment.

sub rsp, 5*8

We pass the first and only argument through the RCX register. Note that we must use lea instead of mov to pass pointers because lea uses a relative address to calculate an absolute one, while mov just copies the relative address into the destination.

lea rcx, [string]

Then we call printf, leave the stack pointer as we found it and return.

call [_printf]
add rsp, 5*8
ret

We define the variable _printf which is initialized with a pointer to the printf function that we're going to supply later.

_printf dq printf

And then we define our "Hello, world!" string.

string db "Hello world (from assembly)!", 13, 10, 0

Windows (x86)

We start by declaring the desired instruction set.

use32

Now we need to know EIP so we can do relative addressing, but we can't do mov eax, eip. So we call the next instruction and the CPU will push EIP to the stack.

call $+5

[ESP] is the location our code was loaded to, plus five. So we set our string on the stack and call printf.

mov eax, [esp]
add dword[esp], string-5
call [eax+_printf-5]

printf is __cdecl which means we have to clean up the stack for the arguments we pass.

add esp, 4

ret

We define the variable _printf which is initialized with a pointer to the printf function that we're going to supply later.

_printf dq printf

And then we define our "Hello, world!" string.

string db "Hello world (from assembly)!", 13, 10, 0

Assembling

Before we assemble, we need to first set our Assembler so Assembly knows where to store data during the assembling process.

helloWorld.setAssembler(&assembler);

Also, we have to tell the FASM preprocessor to replace the printf symbol with the pointer to the actual function.

helloWorld.addPredefinition("printf", printf);

Now we're ready to assemble. To do so, just call:

bool success = helloWorld.assemble();

Instead of throwing exceptions when it finds errors in the code, assemble returns false.

Running

If the compilation was successful we can run it. Note however that the run method receives a bool parameter. If true, run saves all non-volatile registers in the stack, depending on the platform and calling convention. If false, run just runs our code. It's recommended for you to be aware of the non-volatile registers, back them up manually and call run with a false argument.

if (success)
{
    helloWorld.run(false);
}

Getting errors

If the compilation wasn't successful we have to see what's wrong. To do so we call the getErrors method which returns a string describing the error. Our code, however, is correct and should succeed.

else
{
    std::cout << helloWorld.getErrors() << std::endl;
}

If you wish to test this bit of code, you can modify the assembly code and make an intentional typo, or even just comment out helloWorld.addPredefinition("printf", printf);.

The entire code

Here is everything put together, plus some time measurements. You can find this in example.cpp.

#include <chrono>
#include <iostream>
#include "fasmcpp.h"
using namespace std::chrono;
using namespace fasmcpp::size_multipliers;
int main()
{
    fasmcpp::Assembler assembler;
    try
    {
        assembler = 100_KB;
    }
    catch (const std::exception& e)
    {
        std::cout << e.what() << std::endl;
        std::cin.get();
        return 1;
    }
    fasmcpp::Assembly helloWorld;
#if defined _WIN64
    helloWorld = "\
        use64 \n\
        sub rsp, 5*8 \n\
        lea rcx, [string] \n\
        call [_printf] \n\
        add rsp, 5*8 \n\
        ret \n\
        _printf dq printf \n\
        string db 'Hello world (from assembly)!', 13, 10, 0 \n\
    ";
#elif defined _WIN32
    helloWorld = "\
        use32 \n\
        call $+5 \n\
        mov eax, [esp] \n\
        add dword[esp], string-5 \n\
        call [eax+_printf-5] \n\
        add esp, 4 \n\
        ret \n\
        _printf dd printf \n\
        string db 'Hello world (from assembly)!', 13, 10, 0 \n\
    ";
#endif
    helloWorld.setAssembler(&assembler);
    helloWorld.addPredefinition("printf", printf);
    high_resolution_clock::time_point before = high_resolution_clock::now();
    bool success = helloWorld.assemble();
    high_resolution_clock::time_point after = high_resolution_clock::now();
    if (success)
    {
        std::cout << helloWorld.getMessages();
        std::cout << "Successfully built code in " <<
            duration_cast<duration<double, std::micro>>(after - before).count() <<
            " microseconds.\n";
        helloWorld.run(false);
    }
    else
    {
        std::cout << helloWorld.getErrors() << std::endl;
    }
    std::cin.get();
}

I hope this helped you get started with fasmcpp. You can take a look at other guides or at the reference.

Table of Contents