What is FASM, a brief introduction to the Flat Assembler (FASM), FASM Vs MASM, tools for the trade.

Author: shoorick

Disclaimer: This topic is only a short general introduction to FASM and addresses those who never used it, or even never heard of it.

Introduction

FASM is a 32-bit, open-source, cross-platform assembler, targeting the IA-32 and x86-64 architectures (in addition, FASMARM - in unofficial port of FASM, targets the ARM architecture). There are builds for different platforms, including DOS, Windows and Linux.
Each build differs only on the platform under which the compiler is expected to operate, but all builds share common characteristics, like for instance, the capability of developing applications for the Windows platforms on a Linux machine, and vice versa.
Although FASM is made by one person (Tomasz Grysztar, aka Privalov), it is a very powerful tool, capable for managing complex, real-life projects.

What do we need in order to try FASM?

The least we have to do, is to download from the FASM board the package that corresponds to our system - for Windows, the archive we have to download is "fasmw.zip".
The aforementioned archive contains the following:

● fasm.exe (Win32 console assembler).
● fasmw.exe (GUI IDE with built-in assembler).
● fasm.pdf (Manual).
● INCLUDE (Folder with includes to build win32 applications).
● EXAMPLES (Examples of building win32 applications with fasm).
● SOURCES (Sources of fasm and fasmw).

So, if we have the full FASM package, we can run "fasmw.exe" (the official FASM IDE), and immediately start developing an assembler application.
Alternatively, we can use any other IDE; in that case all we need is the FASM assembler ("fasm.exe"). Of course, if we plan to develop an application targetting win32, we also need the INCLUDE files (headers).
The size of the aforementioned binaries (fasmw.exe, fasm.exe), is extremely lean: 120 and 80 kb respectively.

Let's create the simplest 16-bit application possible...

Run fasmw (the FASM IDE), and type: ret
Save the file as ".asm" and compile it, using the shortcut: "Ctr+F9".
Now, just rename the resulting binary extension from ".bin" to ".com". Congratulations, you have just created a valid DOS application, which executes and just returns. Sure, the binary we just created executes, but it is not yet a proper .com file, as the start offset is 0.
To make a proper .com application, we must add some lines at the start of the assembly listing:

use16
org 100h
ret

Now the output binary will also have a ".com" extension, as designated. use16 in this case is optional, but was required for old version of fasm, which have produced 32-bit code by default.

An example of a 16-bit "Hello, World!" application, coded with FASM, is the "COMDEMO" example, included in the fasm.zip package:

;fasm example of writing 16-bit COM program

org 100h; code starts at offset 100h
use16; use 16-bit code

display_text = 9

mov ah,display_text
mov dx,hello
int 21h

int 20h

hello db 'Hello world!',24h

What are the differences between FASM and MASM?

The main difference between FASM and MASM, is the addressing syntax:

Loading an address:

● Equivalent syntax in MASM: mov eax,offset memvar
● Equivalent syntax in FASM: mov eax,memvar

Loading a value:

● Equivalent syntax in MASM: mov eax,memvar
● Equivalent syntax in FASM: mov eax,[memvar]

Can we create a Win32 application with FASM?

Writing a Win32 application, is in most cases similar to writing it in MASM, but there are some differences; the most prominent is the use of invoke, and the high-level syntax.

invoke in FASM is implemented as an external macro; as such, it cannot determine if the function being invoked is being called via import or directly, or if it's stdcall or c type (the PROTO directive is not used in FASM).
In other words, the invoke keyword in MASM, must be replaced in FASM with the appropriate macro:

● invoke (For stdcall function via import).
● cinvoke (For c function via import).
● stdcall (For direct call stdcall function).
● ccall (For direct call c function).

This is just my personal opinion, but I can not say that this is unhandy, as the assembler programmer must know exactly what he is doing.

Also, in MASM, the number of parameters to a function must match to the function prototype, while in FASM, this is not necessary.
Sometimes this could be very handy. For instance, when you have value in a register and you need to push it as a parameter to a function call, you may save it temporarily onto the stack, perform some other actions, retrieve it from the stack, push it and then invoke the function that will use it with less parameters in the invoke line. If you understand what are you doing, this may give you a real advantage.

But if you wish to enable parameter checking, in order to avoid errors, it is also possible. Read on...

There are 3 kinds of headers in the INCLUDE folder:

● win32a - This is a basic header
● win32ax - This header is extended; it has macros to emulate High Level MASM syntax
● win32axp - This header is extended; it has macros to emulate High Level MASM syntax, and also performs parameter checking.

What about Win32 headers and libraries?

Most Win32 structures and constants are present in FASM headers.
You will have to add missing ones manually (but as always, it's better to do it in a separate include file).
Import libraries not needed in order for FASM to build an imports section.
There is an "import" macro, used to build import section which needs only names of dlls and names of functions to import. INCLUDE section contain imports for most used dlls, missing ones can be created manually, or using tools like "External function scanner" by Vortex, which builds exact import for source automatically.

What about resources?

There are two ways to include resources into application: resource section can be built from existing res-file, made by external rc-compiler, or using own fasm macros for creating resources.
Using these macros is not more complex then manually editing a rc-file, but there is a slight difficulty observed when building dialog boxes; these are easier to build in visual mode...
As a work-around, I wrote a converter, which extracts dialogs from a rc-file, and builds analogous includes in fasm format. So, this must not be a problem any more...

What about UNICODE support?

FASM is UNICODE-ready : just include "win32w*" instead "win32a*".
Use "du" to define UNICODE strings:

du "This string is encoded as wide-char.",0

You can use non-english characters in UNICODE strings by including the corresponding file from the ENCODE folder, the one matching to the codepage of the language used.

What linker do I need for FASM?

FASM builds directly applications of many formats, without linker. If you wish to use a linker to combine with other libraries or objects, you may use MS COFF object output format with later linking using MASM linker, POLINK or other compatible. This also may be useful for debugging complex projects, as FASM does not produce symbolic information for the debugger.

Is there something unique about FASM, that other assemblers can not do?

FASM can include external binary files directly into source using the "file" directive. You can specify an offset in the included file, and how many bytes to include.
Except source building, this allows you to make trans-coding macros for chars, provide splitting, splicing, patching external files directly with fasm etc.
The sourcecode in such cases becomes a kind of "task script"

You may set any starting offset, or not set it at all (equivalent to 0) and start to code - you will get binary file with your code immediately, without additional tools like exe2bin: very handy for OS developers who wish to load code in known address from binary file without headers.

Does FASM support macros?

FASM has a great macro support. Macros in FASM are capable of complex code/data generation with cycling, repetitions etc.
The only disadvantage of FASM macros, is that they do not return a value, but when this is necessary, it is possible to emulate the operation.

What is the licensing policy of FASM?

Currently, the license of FASM allows you not only to use FASM for free, but also build commercial applications. For more information, please advice the LICENSE.TXT file, included in the FASM package.

Is it possible to use FASM in conjunction with WinAsm Studio?

Yes. The FASM Add-In adds full support to build applications with fasm, including scanning for import and converting dialogs into fasm format. FASM add-in is written in fasm.

Where to get everything needed to start with FASM?

● FASM itself, can be downloaded from the download section, at the Flat Assembler Homepage.
● All necessary utilities in order to use FASM in conjunction with WinAsm Studio, can be downloaded from the Support for other Assemblers section, here, at winasm.org.
● Import scanner can be download from Vortex's homepage or the MASM Tools section here, at winasm.org.

Further References

● Flat Assembler entry in Wikipedia
● FASMLIB, a portable library for 32bit x86 assembly language.

You can download the "Quick start with FASM from WinAsm Studio" help file and give or read Comments for the What is FASM article.