DEV Community: chrischtel

Building an x86_64 Instruction Encoder from Scratch

chrischtel — Wed, 08 Oct 2025 13:48:30 +0000

I’ve always been fascinated by how compilers actually turn code into bytes.

Over the last few weeks I’ve been building Rask, a small x86_64 instruction encoder in Rust that generates machine code programmatically.

It’s meant for anyone who wants to understand instruction encoding or experiment with JIT compilation — without diving into LLVM’s massive complexity.

What it does

Rask takes simple instruction descriptions and turns them into raw x86_64 machine code bytes:

use rask_x86_64::{encoder::Encoder, registers::Reg64::*, operand::Operand};

let mut encoder = Encoder::new();
encoder.mov(Operand::Reg(RAX), Operand::Imm(1337));
encoder.add(RAX, RBX);
encoder.ret();

let bytes = encoder.bytes();
// [0x48, 0xb8, 0x39, 0x05, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x48, 0x01, 0xd8, 0xc3]

That's valid machine code that loads 1337 into RAX, adds RBX to it, and returns.

Why build this?

LLVM is incredibly powerful but has a steep learning curve and massive compile times. Cranelift is better but still complex for simple use cases. I wanted something you could actually read and understand. I didn’t plan for it to be a full backend — just a weekend experiment that slowly grew legs.

The goal isn't to compete with these tools on features or performance. It's to provide a clean foundation for:

Learning x86_64 instruction encoding
Prototyping JIT compilers
Building custom assemblers or analysis tools
Understanding how CPUs actually execute code

Technical details

The interesting parts were getting the encoding details right:

REX prefixes - x86_64 uses REX prefixes to access extended registers (R8-R15). The encoder automatically generates the correct prefix based on which registers you use:

encoder.mov(Operand::Reg(RAX), Operand::Imm(42));  // REX: 0x48
encoder.mov(Operand::Reg(R10), Operand::Imm(42));  // REX: 0x49

Memory addressing - Supporting different displacement sizes was tricky. The encoder chooses the most compact encoding:

let mem = MemOperand { base: RBX, disp: 8 };     // 8-bit displacement
encoder.mov(Operand::Reg(RAX), Operand::Mem(mem));

let mem = MemOperand { base: RBX, disp: 1000 };  // 32-bit displacement  
encoder.mov(Operand::Reg(RAX), Operand::Mem(mem));

ModR/M encoding - This byte specifies registers and addressing modes. Getting the bit layout right for all combinations took careful reading of Intel's documentation.

Current status

Rask is very early stage. It supports:

MOV instructions (register-to-register, immediate-to-register, memory operations)
Basic arithmetic (ADD, SUB)
Function returns (RET)

Missing: jumps, calls, most instructions, optimizations, multiple architectures.

Every implemented instruction is tested against known-good byte sequences. The focus is on correctness over completeness.

Design decisions

Type safety - The operand system catches encoding errors at compile time:

enum Operand {
    Reg(Reg64),
    Mem(MemOperand), 
    Imm(i64),
}

Documentation - Each instruction includes Intel SDM references and encoding details. You can understand what's happening without external docs.

Modularity - Split into rask-common (shared types) and rask-x86_64 (architecture-specific). Future architectures will be separate crates.

No magic - Everything is explicit. No macros, no hidden code generation.

Examples

The repo includes working examples:

Basic encoding - demonstrates core instructions
REX prefixes - shows extended register handling
Arithmetic operations - memory addressing and ModR/M encoding

You can see the exact byte sequences generated and verify them against disassemblers.

Use cases

While Rask is experimental, the techniques are useful for:

Dynamic code generation - Generate optimized code at runtime based on input data

Domain-specific languages - Compile custom languages directly to machine code

Performance analysis - Generate test sequences to understand CPU behavior

Education - Learn low-level programming concepts with immediate feedback

What's next

Next up: expanding instruction support — jumps, calls, and more arithmetic.
I’m also thinking about experimenting with other architectures like ARM64 once the core is solid.

Longer term, I'm interested in higher-level code generation patterns and potentially other architectures (ARM64).

Feedback welcome, especially from people working on JIT compilers or low-level tooling.

TL;DR: Built a small x86_64 instruction encoder in Rust for learning and experimentation. Generates correct machine code, focuses on clarity over features. Early stage but working for basic instructions.

Error Handling in Zig: A Fresh Approach to Reliability

chrischtel — Sat, 07 Dec 2024 13:52:26 +0000

Error handling in Zig is one of its most distinctive features. Unlike other languages that use exceptions or result types, Zig takes a unique approach that combines compile-time clarity with runtime efficiency. Let's dive into how it works!

The Basics: Error Sets

In Zig, errors are values, not exceptions. They're defined using error sets:

const FileError = error{
    NotFound,
    PermissionDenied,
    InvalidPath,
};

This creates a type that can only hold these specific error values. It's like an enum, but specifically for errors.

Error Unions: The Heart of Error Handling

Zig uses error unions to combine errors with regular values. The syntax is !T or error{...}!T:

fn readNumber(str: []const u8) !u32 {
    if (str.len == 0) return error.EmptyString;
    return std.fmt.parseInt(u32, str, 10);
}

pub fn main() !void {
    const num = try readNumber("123");
    std.debug.print("The number is: {}\n", .{num});

    // This will return an error
    const bad_num = readNumber("abc") catch |err| {
        std.debug.print("Error: {}\n", .{err});
        return err;
    };
}

The `try` and `catch` Keywords

Zig provides elegant ways to handle errors:

fn processFile() !void {
    // 'try' is like 'catch |err| return err'
    const file = try std.fs.cwd().openFile("data.txt", .{});
    defer file.close();

    // Different ways to handle errors
    const data = readData() catch |err| switch(err) {
        error.OutOfMemory => return error.CannotProcess,
        error.InvalidData => return error.BadFormat,
        else => return err,
    };
}

Error Traces Without Overhead

One of Zig's coolest features is error return traces. They help debug errors in release builds with zero runtime overhead when not used:

fn deepFunction() !void {
    return error.SomethingWentWrong;
}

fn middleFunction() !void {
    try deepFunction();
}

pub fn main() void {
    middleFunction() catch |err| {
        // This prints the full error trace!
        std.debug.print("Error: {}\n", .{err});
        return;
    };
}

Best Practices

Be Specific: Define custom error sets for your functions to make error handling more precise.

const DatabaseError = error{
    ConnectionFailed,
    QueryFailed,
    InvalidData,
};

fn queryDatabase() DatabaseError!Data {
    // Your implementation
}

Use Meaningful Names: Make your error names descriptive and action-oriented.
Handle All Cases: Zig's compiler ensures you handle all possible errors, making your code more reliable.

Error Handling vs Exceptions

Why is Zig's approach better than exceptions? Here are the key benefits:

No hidden control flow
Compile-time error checking
Zero runtime overhead
Clear error propagation
No need for try-catch blocks everywhere

Real-World Example

Here's a more complex example showing error handling in a file processing scenario:

const std = @import("std");

// Expand our error set to include all possible file-related errors
const ProcessError = error{
    FileNotFound,
    InvalidFormat,
    ProcessingFailed,
    AccessDenied,
    SystemResources,
    IsDir,
    NoSpaceLeft,
    InputOutput,
    OperationAborted,
    BrokenPipe,
    ConnectionResetByPeer,
    ConnectionTimedOut,
    NotOpenForReading,
} || std.fs.File.OpenError || std.fs.File.ReadError;

fn processDocument(path: []const u8) ProcessError!void {
    // Open the file
    const file = try std.fs.cwd().openFile(path, .{});
    defer file.close();

    // Read content
    var buffer: [1024]u8 = undefined;
    const size = try file.readAll(&buffer);

    // Process content
    if (size < 10) return ProcessError.InvalidFormat;

    // Do something with the content...
    std.debug.print("Successfully processed {} bytes\n", .{size});
}

pub fn main() !void {
    // Get an allocator
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Create an array of files to process
    const files = [_][]const u8{
        "document1.txt",
        "missing.txt",
        "small.txt",
        "document2.txt",
    };

    // Process each file and handle errors appropriately
    for (files) |file_path| {
        processDocument(file_path) catch |err| switch (err) {
            error.FileNotFound => {
                std.debug.print("Warning: File not found: {s}\n", .{file_path});
                continue;
            },
            error.InvalidFormat => {
                std.debug.print("Error: Invalid format in file: {s}\n", .{file_path});
                continue;
            },
            error.AccessDenied => {
                std.debug.print("Error: Access denied for file: {s}\n", .{file_path});
                continue;
            },
            error.IsDir => {
                std.debug.print("Error: Path is a directory: {s}\n", .{file_path});
                continue;
            },
            // Handle other specific errors as needed
            else => {
                std.debug.print("Unexpected error while processing {s}: {}\n", .{ file_path, err });
                continue;
            },
        };

        std.debug.print("Successfully processed file: {s}\n", .{file_path});
    }

    // Create a log of processed files
    const log_file = try std.fs.cwd().createFile(
        "processing_log.txt",
        .{ .read = true },
    );
    defer log_file.close();

    // Write some statistics
    const timestamp = std.time.timestamp();
    const log_message = try std.fmt.allocPrint(
        allocator,
        "Processing completed at: {d}\n",
        .{timestamp},
    );
    defer allocator.free(log_message);

    _ = try log_file.writeAll(log_message);
}

Conclusion

Zig's error handling system is a breath of fresh air in systems programming. It combines the safety of Rust's Result type with the simplicity of Go's error returns, while adding its own unique features like comptime error sets and zero-cost error traces.

Want to learn more? Check out:

Zig's error handling documentation

Happy coding in Zig! 🚀

How to invoke system commands using in Rust

chrischtel — Thu, 23 Mar 2023 17:55:04 +0000

If you want to invoke system commands in your Rust program, you need to make use of the std::process::Command module. In this short post, i'll tell you how to use this module. For more infos on Rust you can visit the well documented Rust book

Getting started

We wanna make sure that we import the std::process::Command module. To do that, go to your main.rs file.

use std::process::Command;

fn main() {
     println!("Hello World!");
}

spawn, output and status

Before we start invoking a system command, we must distinguish between three different methods to spawn a child process and run system commands.

spawn -> Executes the commands as a child process and returns a handle to it. For more information on how to interact with stdin/stdout check out this answer on stack overflow.

output -> Runs the command as a child process and waits until the command finishes, then collects the output. If you want to print out the output of a command in real time, please refer to the spawn method.

status -> Runs a command as a child process and waits for it to finish and collect its status.

How to structure a command

We will use the command ls as an example

use std::process:Command;

fn main(){
   Command::new("ls")
           .arg("-a")
           .spawn()
           .expect("failed to execute command");
}

For more examples visit the offical docs

I hope I could help you and you like my post.