Programming in Assembler for x64

In this section, we will show some examples of programs written purely in assembler or in connection with other programming languages, including C++ and C#. We assume that the reader is familiar with the coursebook, instructions and directives used to write the assembler programs. We will describe the use of the integrated development environment (Visual Studio) and methods to assemble programs with the command line only.We will also show how to create the static and dynamic library written in assembler for use in assembler or in other compilers.

In the following chapter, we explain how to write, assemble, link, and execute assembly-language programs for x64 processors. We assume that the reader is familiar with the most important processor instructions and MASM directives.

To write a program in assembler, it is convenient to use a Visual Studio IDE: either commercial or free (Community Edition). The following section presents the installation of Visual Studio Community Edition on Windows.

Installation requires the following simple steps:

1. Download installer executable from: https://visualstudio.microsoft.com/free-developer-offers/ - Mind to choose Community Edition (purple), not Code (blue)! as in figure 1.
2. Run the installer, let it download and install.
3. Configure components - a minimal set of development platforms for our laboratory exercises requires:
   1. full install of C++ development platform in native code for Windows (remember to click additional components as in the figure 2),
   2. default install of the C# development platform in managed code for Windows.

This scenario concerns the implementation of a command-line Windows x64 application written in pure Assembler. Assembling, debugging, disassembly window, register view, memory view - data section,

[piotr] TO BE DONE

In this section, we'll go through the process of creating a solution with a C++ main file and a static assembler library.

1. Create the solution. You can create a simple “Hello world” example written in C++ for execution in a console window.

At this stage, you can test the application. It should print “Hello World” in a console window.

2. Add assembler module with library functions.

This time, choose the Empty Project option.

We need to enable MASM in build customisations.

Add an assembly file to the MASM project. You can add a new item of a type of plain text, and name it with an asm extension. For example “library1.asm”.

3. Set the output file type for the assembler project.
The project build generates the exe file by default. We need to change the configuration type to static library (*.lib file).

4. Set references and dependencies between solution modules.
The C++ program relies on an assembler library, so the references and dependencies should be properly set. First, add the reference to a library.

Next, check if dependencies between both modules are properly set.

5. Write the software.
It's time for coding. Let's start with the code of a library function. Let's write a simple function adding two arguments. According to Windows ABI, the first two arguments are passed by rcx and rdx registers. The return value should be stored in rax. We will use the int C++ data type, which is stored using 32 bits. We should make calculations with 32-bit registers ecx, edx, and eax. The assembler file can look like the following code.

.CODE
func_add PROC
  mov eax, ecx
  add eax, edx
  ret
func_add ENDP
END

We will expand the default “Hello world” C++ file with our assembler function call.

#include <iostream>
#include "Assembler1.h"
int main()
{
    std::cout << "Hello World!\n";
    std::cout << func_add(123, 456);
}

Calling a library function requires a prototype. We will declare it in the header file, which we need to add to the C++ project. It can be named “Assembler1.h”.

#pragma once
extern "C" int func_add(int a, int b);

After finishing all the steps, we should be able to properly compile the solution and observe results in a console window.

It is possible to use command-line MASM tools to assemble, link, and create libraries written in assembly language. You can use any editor to create the assembler source code and translate it into machine code. The tools required are integral elements of the Visual Studio Community installation, installed with the option “Desktop development with C++”. For the default VS installation, you can find them in the following folder (it can change due to different version numbers).

C:\Program Files\Microsoft Visual Studio\18\Community\VS\Tools\MSVC\14.50.35717\bin\Hostx64\x64

To use statically included Windows libraries, you need lib files. The essential library is kernel32.lib, but for other Windows functions, you will also need some additional libraries. All are available in the following folder (it can change due to different version numbers).

C:\Program FIles (x86)\Windows Kits\10\Lib\10.0.26100.0\um\x64

For assembling the source file, the ML64.exe program is used. This program has many options, which you can see executing:

ML64.exe /?

After assembling, ML64 can call the linker automatically. An exemplary MASM execution command to assemble and link the file named source.asm can look like this:

ml64 /Fl /Zi /Zd source.asm /link /entry:main

The options used explanation:

• /Fl - generate listing file. MASM will output the source.lst file with the report on the assembling process.
• /Zi - add symbolic debug info. MASM will add to the object file names of symbols defined in the program. It will allow debuggers to name user-defined symbols during debugging.
• /Zd - add line number debug info. MASM will add to the object file source code line numbers.
• /link - MASM will call the linker.
• /entry:main - option for the linker, which informs about the entry point of the program.