🗡️ stackaroo

Nice, long knife to stab yourself in the eye

stackaroo is a highly unsafe library, letting you swap out the OS-provided thread stack with your own custom stack (e.g. heap-backed).

What is this madness?

This library was created as part of research into Linux kernel internals. It provides platform-specific assembly implementations (x86_64 and AArch64) to perform direct stack pointer manipulation, allowing you to:

• Execute functions on arbitrarily large custom stacks (4GB? Why not!)
• Perform deep recursion that would normally cause stack overflow
• Test stack-intensive algorithms without OS stack limitations
• Experience the pure terror of manual memory management

Quick Example

use stackaroo::swap_to_heap;

struct Args {
    n: u64,
    result: u64,
}

fn fibonacci(args: &mut Args) {
    fn fib(n: u64) -> u64 {
        let huge_array = [0u8; 1024 * 1024]; // 1MB per frame
        std::hint::black_box(&huge_array);   // Don't let it be compiled-out
        if n <= 1 { return n; }
        fib(n - 1) + fib(n - 2)
    }
    args.result = fib(args.n);
}

fn main() {
    unsafe {
        const STACK_SIZE: usize = 1 << 30; // 1GB
        let mut args = Args { n: 32, result: 0 };
        swap_to_heap(fibonacci, Some(&mut args), STACK_SIZE).unwrap();
        println!("Fibonacci({}) = {}", args.n, args.result);
    }
}

Project Structure

This is a Cargo workspace containing two crates:

• stackaroo - Core Rust library for stack swapping
• stackaroo-ffi - C FFI bindings (staticlib/cdylib) for use from C/C++

Features

Core Library (stackaroo)

• Supports x86_64 and AArch64 architectures
• no_std compatible
• One swap per thread (with std/tls) or one swap globally (no-std)
• Does not support recursive/nested stack swaps

Available features:

• std (default): Enables standard library support (implies alloc)
• tls (default): Enables thread-local storage for thread-safe stack swapping (requires std)
• alloc: Enables heap allocation support (required for swap_to_heap)

FFI Library (stackaroo-ffi)

• Provides C-compatible API for use from C, C++, and other languages
• Generates C header file (stackaroo.h) automatically via cbindgen
• Available as both static and dynamic libraries

Available features:

• std (default): Enables standard library support
• alloc: Enables heap allocation support

Using from C/C++

To use stackaroo from C or C++, build the stackaroo-ffi crate:

cd stackaroo-ffi
cargo build --release

This will generate:

• target/release/libstackaroo.a (static library)
• target/release/stackaroo.dll / .so / .dylib (dynamic library)
• stackaroo.h (C header file in the stackaroo-ffi directory)

Example C usage:

#include "stackaroo.h"
#include <stdio.h>
#include <stdlib.h>

void my_function(void* arg) {
    int* value = (int*)arg;
    *value *= 2;
    printf("Value doubled: %d\n", *value);
}

int main() {
    // Allocate 1MB stack
    size_t stack_size = 1024 * 1024;
    void* stack = aligned_alloc(16, stack_size);
    void* stack_top = (char*)stack + stack_size;
    
    int value = 42;
    StackarooError err = stackaroo_swap_to(my_function, &value, stack_top);
    
    if (err == STACKAROOERROR_OK) {
        printf("Success! Value is now: %d\n", value);
    }
    
    free(stack);
    return 0;
}

Link with: -lstackaroo (and ensure the library path is in your linker search path)

Warning

This library is extremely unsafe and should only be used by people who understand the implications of manual stack management. It's primarily intended for research, kernel development, and testing scenarios where you need to bypass OS stack limitations.

License

This project is licensed under the Apache License 2.0.