FASMLIB

FASMLIB is a portable general-purpose library for the x86 series of processors written in 32 bit assembly language. It supports FASM, MASM and NASM/YASM, on Windows and Linux.

Development

FASMLIB was developed by Martin Mocko (aka. "vid") in autumn 2006, after the "FASM technical discussion" event in Kraków.

Major additions:
* Versions 0.1 and 0.2 were mostly complete rewrites and redesigns.
* Version 0.3 introduced conversions and text-processing.
* Version 0.4 introduced support for other assemblers.
* Since 0.5.0, versioning style 'major.minor.revision' has been used. This version introduced the heap manager.
* Version 0.6.0 was the first to include the library in library format (instead of as a single object).
* Version 0.7.0 included a rewrite of stream interface, and had full documentation (in CHM format).
* Version 0.8.0 added support for qword (64-bit) numbers and documentation in HTML format.

FASMLIB is still considered to be very incomplete. Further plans for development include Unicode support and command-line processing.

Design

Originally, FASMLIB was planned to be a source-code library for FASM only. Later, it turned out that it could be easily used in other assemblers, and support for them was added. FASMLIB can be used in FASM directly by including its source, or by linking it in. In other assemblers it must be linked in.

FASMLIB is designed to be usable with pure assembly code without any macros. Because of this, all functions have same calling standard: arguments are passed on the stack and the called procedure cleans the arguments from stack. This is true even for procedures with a variable number of arguments.

Every FASMLIB procedure returns its error state in the carry flag (CF). When CF is 1, an error has occurred and the EAX register contains the error code. The library provides set of standard error codes and allows the definition of custom error codes. This design allows macros that provide try-throw-catch-like error handling.

Code utilizing FASMLIB is portable between FASMLIB's supported platforms (Windows and Linux) without modification.

A remarkable feature is that many procedures are provided in two versions. One version is simple to use and provides the most commonly used functionality. The other version provides more functionality, and thus it is harder to use, requiring more arguments.

Why not libc

The use of standard C library (libc) is common in assembly. Unfortunately, there are some problems with using it in assembly, and that inspired the creation of FASMLIB.

The biggest problem is that libc doesn't have a defined ABI. This means that the C library is not truly "standard" for assembly language, and its implementations are used differently. This includes:
* Some implementations may use the cdecl and others the stdcall calling standards. The "cdecl" calling standard is harder to use in assembly, because the coder must count the total size of arguments and clean them from the stack.
* Different registers may be preserved over calls.
* Library variables are often implemented as function calls ("err", "stdin", ...).
* The width of types is not defined. On some implementations the "long" type may have 64bit width, on others it can be 32 bits wide.
* The standard library doesn't contain some useful code (for example, Unicode support). Using various extensions that address this (such as GNU libc) causes portability problems.
* Various implementations use different name decoration.

Because of these reasons, there is always at least some wrapper needed to make libc standard for assembly code too.

Secondly, libc is designed for C and some things do not fit well into assembly programming. For example type names in format strings do not make much sense when used in assembly (for 64bit decimal number you use "%lld").

Contents

FASMLIB currently (version 0.8.0) provides the following features:
* Heap memory management
* ASCII string library
* Conversions between numeric types (byte, word, dword, qword) and ASCII strings (decimal, hexadecimal)
* Stream interface
* File I/O
* Standard I/O streams, File stream, Static memory stream
* ASCII textual processing on streams

Documentation

FASMLIB comes with complete documentation.

Early FASMLIB versions contained documentation in plain text format. Later it was rewritten in DocBook format, which supports conversion to many formats. Currently, documentation is provided in CHM and HTML format.

Part of the documentation is extracted from sources in a doxygen-like manner, using the custom utility AsmDoc.

See also

* C Standard Library
* HLA Standard Library

External links

* [http://fasmlib.x86asm.net Official FASMLIB site]
* [http://board.flatassembler.net/topic.php?t=4696 FASMLIB thread on FASM message board]