Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

6. Performance & Portability

6.1 Design for no_std

x-nes is built without the Rust standard library. This means it can run on any platform with a Rust compiler, from 8-bit microcontrollers to 64-bit desktops.

#![allow(unused)]
#![cfg_attr(not(test), no_std)]
fn main() {
}

The cfg_attr allows std during testing for convenience while keeping the release build minimal.

6.1.1 No Heap Allocation

The emulator never allocates memory. ROM data is borrowed from the caller as &[u8], and all internal state is fixed-size arrays:

StateSizeType
CPU registers7 bytes[u8; 7]
CPU RAM2KB[u8; 2048]
PPU VRAM4KB[u8; 0x1000]
PPU pattern tables8KB[u8; 0x2000]
PPU palette32 bytes[u8; 0x20]
PPU OAM256 bytes[u8; 0x100]
PPU frame buffer61KB[u8; 256 * 240]
Total~75KB

6.1.2 Custom Panic Handler

Without std, there’s no default panic handler. x-nes provides its own:

#![allow(unused)]
fn main() {
#[cfg(not(test))]
#[panic_handler]
fn panic(_info: &core::panic::PanicInfo) -> ! {
    loop {}
}
}

On panic, the CPU loops forever. A debugger can breakpoint on this function to inspect state.

6.2 Cross-Platform Configuration

6.2.1 Cargo Configuration (.cargo/config.toml)

[target.'cfg(any(target_arch = "x86_64", target_arch = "aarch64"))']
rustflags = ["-C", "target-cpu=native"]

[target.thumbv7em-none-eabihf]
rustflags = ["-C", "opt-level=s"]

Desktop builds use target-cpu=native to let LLVM use every instruction your CPU supports. MCU builds optimize for size.

6.2.2 Rust Toolchain (rust-toolchain.toml)

[toolchain]
channel = "stable"
targets = [
    "x86_64-pc-windows-msvc",
    "thumbv7em-none-eabihf",
]

6.2.3 Cargo.toml

[lib]
name = "nes"
crate-type = ["cdylib", "staticlib"]

cdylib produces a shared library (.dll/.so/.dylib) for desktop use. staticlib produces a static archive (.a) for embedded use.

6.3 Crate Type: cdylib vs staticlib

cdylib (Dynamic Library)

Used when x-nes is loaded by another program at runtime:

Desktop app (C, Python, etc.)
          │
          │  FFI call
          ▼
    x-nes.dll / x-nes.so  ← built as cdylib

The host program calls tick(), reset(), etc. through a C-compatible interface.

staticlib (Static Library)

Used when x-nes is linked directly into another program:

Firmware binary
    ├── game code
    ├── x-nes code  ← built as staticlib
    └── board support

Everything is linked into one binary — no runtime loading needed.

6.4 Release Profile

[profile.release]
opt-level      = 3
lto            = true
codegen-units  = 1
strip          = "symbols"
panic          = "abort"
SettingEffect
opt-level = 3Maximum optimization — prioritizes speed
lto = trueLink-time optimization across all dependency boundaries
codegen-units = 1Compiler sees entire crate at once for better inlining
strip = "symbols"Removes debug symbols from output
panic = "abort"No unwind tables (required for no_std + cdylib)

6.5 Build Targets

Building for Desktop

cargo build --release

Output: target/release/nes.dll (Windows), target/release/libnes.so (Linux), or target/release/libnes.dylib (macOS)

Building for Microcontroller (ARM Cortex-M)

rustup target add thumbv7em-none-eabihf
cargo build --release --target thumbv7em-none-eabihf

Output: target/thumbv7em-none-eabihf/release/libnes.a

6.6 Performance Design Decisions

6.6.1 7-Byte CPU Struct

The CPU state is exactly 7 bytes — it fits in a single 64-bit register on x86_64. Register accessors inline to 1-2 mov instructions.

6.6.2 Branchless Flag Operations

set_flag(flag, true):    sr = (sr & !flag) | (1 * flag) = sr | flag
set_flag(flag, false):   sr = (sr & !flag) | (0 * flag) = sr & !flag

The multiply by 0 or 1 replaces a branch. No branch mispredictions.

6.6.3 Jump Table Dispatch

TABLE[opcode as usize](cpu, bus) — a single indexed indirect call. No binary search, no match tree, no bounds check.

6.6.4 Bus Dispatch

Shifting the address right by 12 extracts the top nibble (0-15), which selects the memory region. A match on a small integer compiles to a compact jump table.

6.6.5 Page-Cross Penalty

(base ^ addr) >> 8 is 0 if same page, 1 if different. Added directly to the cycle count — no branch needed.

Summary

  • x-nes is no_std — runs anywhere Rust runs
  • No heap allocation — all state is fixed-size arrays
  • Builds as both dynamic and static library
  • Release profile strips everything unnecessary
  • Same code compiles for desktop and microcontroller targets
  • Binary sizes range from 4KB (MCU) to 9KB (desktop)