Scarlet is an operating system kernel written in Rust that implements native ABI support for executing binaries across different operating systems and architectures. The kernel provides a universal container runtime environment with strong isolation capabilities, comprehensive filesystem support, dynamic linking, and modern graphics capabilities.

# Get started with Docker (recommended)
docker build -t scarlet-dev .
docker run -it --rm -v $(pwd):/workspaces/Scarlet scarlet-dev bash -c "cargo make run-riscv64"

# Once Scarlet boots, you'll see:
Login successful for user: root
Scarlet Shell (Interactive Mode)
# 

# Try Scarlet native binaries:
# hello
Hello, world!
PID  = 5
PPID = 3
# Enter xv6 environment (experimental ABI):
# xv6
xv6 container
Preparing to execute xv6 init...
init: starting sh
$ 

# Try xv6 binaries:
$ echo hello from xv6!
hello from xv6!

# Cross-ABI execution - xv6 calling Scarlet binary with pipe!
$ /scarlet/system/scarlet/bin/hello | cat
Hello, world!
PID  = 10
PPID = 9

See Linux ABI Demo instructions for detailed instructions on building and running the Linux userspace demo.

# Quick summary (inside scarlet-dev container):
# For RISC-V (default)
bash tools/linux/build_buildroot.sh
bash tools/linux/build_user_programs.sh
bash tools/linux/deploy_rootfs.sh
cargo make run-riscv64

These commands rebuild the Buildroot-based Linux rootfs (providing standard utilities via BusyBox) and optional demo binaries, showcasing the initial Linux ABI support alongside Scarlet and xv6.

Scarlet allows binaries from different operating systems to coexist and communicate via standard Unix pipes. This is not virtualization—it is a unified kernel handling multiple ABIs natively.

# ✅ Working Now: xv6 shell executing a Scarlet native binary
# The output from 'hello' (Scarlet ABI) is piped to 'cat' (xv6 ABI)
(xv6)$ /scarlet/system/scarlet/bin/hello | cat
Hello, world!
PID  = 10
PPID = 9

# 🚧 In Progress: Linux ABI Integration
# We are expanding this capability to include Linux binaries (via BusyBox):
(scarlet)$ scarlet_cat /etc/passwd | /system/linux-riscv64/bin/busybox grep "root" | xv6_wc -l

This interoperability is possible because all ABIs share the same underlying kernel objects (VFS, pipes, task structures). The goal is a seamless environment where you can use the best tool for the job, regardless of which OS it was originally written for.

Current Status:

• ✅ Scarlet Native ABI: Fully implemented with interactive shell
• 🧪 xv6 RISC-V 64-bit ABI: Working with Cross-ABI execution capabilities!
• 🧩 Linux RISC-V 64-bit ABI (partial): Buildroot-based userland demo available; syscall coverage expanding
• ✅ Cross-ABI Pipes: Already functional between xv6 and Scarlet environments

• Multi-ABI Support: Transparent execution of binaries from different operating systems
• Runtime Delegation: Execute binaries via userland runtimes (Wasm, emulators, etc.) - Details
• Service Management: Stem daemon (stemd) provides systemd-like service management with dependency resolution - Details
• Container Runtime: Complete filesystem isolation with namespace support
• Dynamic Linking: Native dynamic linker support for shared libraries and position-independent executables
• Advanced VFS: Modern virtual filesystem with ext2, FAT32, overlay, bind mount, and device file support
• Graphics Support: Framebuffer device support with graphics hardware abstraction
• Windowing / UI (in progress): SWS protocol + client libraries - Protocol, sws-client, scarlet-ui
• System Integration: TTY devices, interrupt handling, and comprehensive device management
• Task Management: Full task lifecycle with environment variables and IPC pipes
• Event System: Advanced IPC with event-driven communication and synchronization
• Memory Safety: Built with Rust's safety guarantees for reliable system operation
• RISC-V Ready: Native support for RISC-V 64-bit architecture

Scarlet's Multi-ABI support is built around a modular ABI implementation system:

• Binary Detection: Automatic identification of binary format and target ABI
• Native Implementation: Each ABI module implements its own syscall interface using shared kernel APIs
• Shared Kernel Resources: All ABIs operate on common kernel objects (VFS, memory, devices, etc.)

• Scarlet Native: ✅ Complete - Direct kernel interface with optimal performance
• xv6 RISC-V 64-bit: 🧪 Experimental - Largely implemented with core functionality available
• Linux RISC-V 64-bit (partial): 🧩 Early userland demo via Buildroot rootfs; syscall surface expanding toward full POSIX support

This architecture enables true containerization where applications from different operating systems can coexist and communicate without modification.

The xv6 ABI implementation is currently available as an experimental feature:

• Testing Ready: Core functionality is stable and ready for testing
• Binary Compatibility: Included xv6 binaries (cat, grep, wc, sh, etc.) work correctly
• Cross-ABI Communication: Pipes and IPC work seamlessly with other ABI implementations
• Production Note: While functional, this is an experimental implementation subject to changes

The Linux ABI implementation is currently in active development:

• Userspace Support: Runs simple static binaries and Buildroot/BusyBox environments.
• Syscall Coverage: Basic file I/O, process management, and memory operations are implemented.
• Limitations: Many advanced syscalls (networking, complex signals) are stubbed or missing. See docs/abi/linux/status.md for the compatibility matrix.

Scarlet supports multiple CPU architectures with a unified codebase:

• RISC-V 64-bit - Primary development platform, fully supported
• AArch64 (ARM 64-bit) - Experimental supported

The kernel includes hardware abstraction layers for interrupt handling, memory management, graphics/framebuffer support, and device drivers that work across both architectures.

# RISC-V (default)
cargo make build
cargo make run-riscv64

# AArch64
ARCH=aarch64 cargo make build
cargo make run-aarch64

See Multi-Architecture Support documentation for detailed information on cross-architecture development.

Scarlet implements a modern Virtual File System (VFS v2) with support for multiple filesystem types and container isolation:

• TmpFS: Memory-based temporary filesystem
• CpioFS: Read-only CPIO archive filesystem for initramfs
• ext2: Full ext2 filesystem implementation for persistent storage
• FAT32: Complete FAT32 filesystem support
• OverlayFS: Union filesystem combining multiple layers
• DevFS: Device file system for hardware access

• Mount Namespace Isolation: Per-task filesystem namespaces
• Bind Mount Operations: Directory mounting across namespaces
• Overlay Support: Layered filesystems with copy-on-write semantics

# Build and run development container
docker build -t scarlet-dev .
docker run -it --rm -v $(pwd):/workspaces/Scarlet scarlet-dev

# Common commands:
cargo make run-riscv64                        # Build (release) and run (RISC-V)
cargo make test-riscv64               # Run tests (RISC-V)
cargo make debug-riscv64              # Debug with GDB

Requirements: Rust nightly, cargo-make, qemu, RISC-V toolchain

# Full build (RISC-V, debug)
cargo make build-riscv64

# Individual components
cargo make build-kernel-debug-riscv64     # Kernel only
cargo make build-userlib-debug-riscv64    # User space library
cargo make build-userbin-debug-riscv64    # User programs
cargo make build-initramfs-debug-riscv64  # Initial RAM filesystem
cargo make build-rootfs-riscv64           # Root filesystem image

# Clean build artifacts
cargo make clean-riscv64

# Run all tests
cargo make test-riscv64

# Debug kernel with GDB
cargo make debug-riscv64
# Then in another terminal: gdb and connect to :1234

Contributions are welcome! Please feel free to submit a Pull Request.

For more detailed information about the Scarlet kernel, visit our documentation:

• Scarlet Documentation
• Linux ABI Demo
• Linux userspace artifacts (Buildroot + optional binaries)
• Linux rootfs deployment guide
• Linux ABI support status and roadmap

To generate the documentation, run:

# Generate documentation
cargo make doc-riscv64      # Generate docs for all components (RISC-V)
cargo make doc-kernel      # Generate kernel docs only
cargo make doc-userlib     # Generate user library docs only

This project is licensed under the MIT License - see the LICENSE file for details.