The Extendable Assembler Library

libxas, a Bell-style, open-source, fast, Rust-based assembler

TODO: Links, table-of-contents

The Extendable Assembler Library, or libxas, is a power tool for assembly programmers, toolchain writers, virtualization/emulation enthusiasts, and more. Using its powerful, efficient, and easy-to-integrate Rust stack, libxas allows anyone to easily write assembly for a wide span of different platforms, quickly assemble it into many different output formats, and write extensions which expand the library's capabilities. It is:

• Fast. libxas focuses on speed. Zero-cost abstractions are used to provide a robust, extendable platform without compromising on speed.
• Safe. Being built in Rust, libxas has high safety and a low potential for vulnerabilities. This is especially critical in environments where using opcode functionalities for foreign data transformation requires a fully secure, inescapable environment.
• Extendable. The libxas stack can easily be built upon for writing assemblers, build toolchains, and integrating new architectures and output formats.

The Stack

(TODO: Stack diagram)

The libxas stack is designed to be as extendable and modular as possible. Individual output formats and input architectures, as well as various features, are easy to disable and compile out.

BBU

BBU - "Better Binutils" - is the heart of libxas. It holds the various ISA backends with opcode translation and optimization, as well as any architecture-specific information which is passed during output. It also contains outs, a modular output file system which allows for easily implementing new architectures across a variety of object file formats.

EAF

Most usecases of libxas involve simply using the already existing toolchains to assemble lines from various sources. EAF - the "Easy Assembler Frontend" - simplifies this process significantly. With a robust API for Rust programs to link to, EAF abstracts away all the gritty internal details of libxas and presents a clean frontend for development. Everything is automatically processed between input and output buffers using Platform, the format information system used throughout libxas.

XASP

The Extendable Assembler Syntax Processor is comprised of two in-house modules: the Parser, which handles macro recognition and instruction formatting, and the Lexer, which helps transforms macros and instructions into structures from BBU modules. These have extreme flexibility through powerful leverage of Rust generics, allowing complex architectures to seamlessly integrate.

Philosophy

There are absolutely times when toolchains should be built for people "in-the-know". The LLVM and GCC toolchains do their job very well, and are designed to be fully integrated at all stages of compiler creation. Tools like LLVM IR provide powerful abstraction and optimization. For a cutting-edge compiler, those types of tightly-woven toolchains and libraries are critical. However, not every use case is the next GCC. Often, people just want something simple and easy to develop with. When dealing with assembly, this is especially important; assembly development time is extremely high, so time working with toolchains should be minimized.

To ensure that anyone can quickly and painlessly work with libxas, we are committed to simple, highly documented interfaces. Anyone with a new idea for an output format or ISA should not have to worry about initial time developing either a proof-of-concept or a stable production toolchain.

Licensing and Libraries

libxas is licensed under the GNU General Public License, version 2 (or, at your option, any later version). This was chosen to ensure user freedom while also guaranteeing derivations are available to the entire community.

We also use the following libraries, which have their own respective licenses:

• log: v0.4.17, MIT and/or Apache-2.0
• num_traits: v0.2.15, MIT and/or Apache-2.0

Usage

If you're looking to use individual parts of the stack, check their (TBD) documentation. Otherwise, you're probably looking for how to use EAF.

1. Make your Cargo project and add libxas as a dependency.
2. Store your assembly in a String. If you're working with files, use std::fs::read_to_string or something similar.
3. Create a platform::Platform instance using one of the creation functions.
4. Call eaf::assemble_full_source with your assembly and Platform.
5. Read/store the resulting Vec<u8> as your output.

Contributions

Contributions are always welcome, and very much appreciated. You can:

• Report bugs and suggest new features in Issues
• Resolve TODOs/FIXMEs/NOTEs or make other contributions (please submit a Pull Request)
• Help document libxas (instructions TBA)

Compatibility

libxas requires Rust stable >= v1.56.1 or a fairly recent nightly. This is because we use Rust Edition 2021. You could attempt to change the Rust version to 2018 and run on a lower version, but this is NOT SUPPORTED.

Architecture Support