hypothalamus 0.5.0

//! Game Boy Advance ROM image builder.

use crate::driver::{CompilerConfig, DriverError};
use crate::target::RuntimeAbi;
use crate::tool;
use std::env;
use std::fs;
use std::path::{Path, PathBuf};
use std::process::Command;
use std::time::{SystemTime, UNIX_EPOCH};

/// Size of the GBA cartridge header.
pub const HEADER_SIZE: usize = 0xC0;

/// Default GBA ROM title written into the header.
pub const ROM_TITLE: &[u8; 12] = b"HYPOTHALAM  ";

/// Default GBA game code written into the header.
pub const GAME_CODE: &[u8; 4] = b"HYBF";

/// Default GBA maker code written into the header.
pub const MAKER_CODE: &[u8; 2] = b"00";

const DEVKITARM_BIN: &str = "/opt/devkitpro/devkitARM/bin";
const GBA_TOOL_HINT: &str = "Install devkitARM or pass --gba-gcc /path/to/arm-none-eabi-gcc and --gba-objcopy /path/to/arm-none-eabi-objcopy.";
const STARTUP_ASM: &str = include_str!("gba/startup.S");
const LINKER_SCRIPT: &str = include_str!("gba/gba.ld");
const RUNTIME_C: &str = include_str!("gba/runtime.c");

const NINTENDO_LOGO: [u8; 156] = [
    0x24, 0xFF, 0xAE, 0x51, 0x69, 0x9A, 0xA2, 0x21, 0x3D, 0x84, 0x82, 0x0A, 0x84, 0xE4, 0x09, 0xAD,
    0x11, 0x24, 0x8B, 0x98, 0xC0, 0x81, 0x7F, 0x21, 0xA3, 0x52, 0xBE, 0x19, 0x93, 0x09, 0xCE, 0x20,
    0x10, 0x46, 0x4A, 0x4A, 0xF8, 0x27, 0x31, 0xEC, 0x58, 0xC7, 0xE8, 0x33, 0x82, 0xE3, 0xCE, 0xBF,
    0x85, 0xF4, 0xDF, 0x94, 0xCE, 0x4B, 0x09, 0xC1, 0x94, 0x56, 0x8A, 0xC0, 0x13, 0x72, 0xA7, 0xFC,
    0x9F, 0x84, 0x4D, 0x73, 0xA3, 0xCA, 0x9A, 0x61, 0x58, 0x97, 0xA3, 0x27, 0xFC, 0x03, 0x98, 0x76,
    0x23, 0x1D, 0xC7, 0x61, 0x03, 0x04, 0xAE, 0x56, 0xBF, 0x38, 0x84, 0x00, 0x40, 0xA7, 0x0E, 0xFD,
    0xFF, 0x52, 0xFE, 0x03, 0x6F, 0x95, 0x30, 0xF1, 0x97, 0xFB, 0xC0, 0x85, 0x60, 0xD6, 0x80, 0x25,
    0xA9, 0x63, 0xBE, 0x03, 0x01, 0x4E, 0x38, 0xE2, 0xF9, 0xA2, 0x34, 0xFF, 0xBB, 0x3E, 0x03, 0x44,
    0x78, 0x00, 0x90, 0xCB, 0x88, 0x11, 0x3A, 0x94, 0x65, 0xC0, 0x7C, 0x63, 0x87, 0xF0, 0x3C, 0xAF,
    0xD6, 0x25, 0xE4, 0x8B, 0x38, 0x0A, 0xAC, 0x72, 0x21, 0xD4, 0xF8, 0x07,
];

/// Build a complete `.gba` ROM image from generated LLVM IR.
pub fn build_image(
    config: &CompilerConfig,
    module: &str,
    output: &Path,
) -> Result<(), DriverError> {
    let temp_dir = temporary_dir();
    fs::create_dir_all(&temp_dir).map_err(|source| DriverError::WriteFile {
        path: temp_dir.clone(),
        source,
    })?;

    let result = build_image_in_dir(config, module, output, &temp_dir);
    let _ = fs::remove_dir_all(&temp_dir);
    result
}

/// Patch the 192-byte GBA ROM header at the start of `rom`.
pub fn patch_header(rom: &mut Vec<u8>) {
    if rom.len() < HEADER_SIZE {
        rom.resize(HEADER_SIZE, 0);
    }

    rom[..HEADER_SIZE].fill(0);
    rom[0..4].copy_from_slice(&0xEA00002E_u32.to_le_bytes());
    rom[0x04..0xA0].copy_from_slice(&NINTENDO_LOGO);
    rom[0xA0..0xAC].copy_from_slice(ROM_TITLE);
    rom[0xAC..0xB0].copy_from_slice(GAME_CODE);
    rom[0xB0..0xB2].copy_from_slice(MAKER_CODE);
    rom[0xB2] = 0x96;
    rom[0xBD] = header_checksum(rom);
}

/// Return true when `rom` has the header fields Hypothalamus writes.
pub fn has_valid_header(rom: &[u8]) -> bool {
    rom.len() >= HEADER_SIZE
        && rom[0..4] == 0xEA00002E_u32.to_le_bytes()
        && rom[0x04..0xA0] == NINTENDO_LOGO
        && rom[0xA0..0xAC] == ROM_TITLE[..]
        && rom[0xAC..0xB0] == GAME_CODE[..]
        && rom[0xB0..0xB2] == MAKER_CODE[..]
        && rom[0xB2] == 0x96
        && rom[0xBD] == header_checksum(rom)
}

/// Compute the GBA header complement checksum byte.
pub fn header_checksum(rom: &[u8]) -> u8 {
    let sum = rom[0xA0..=0xBC]
        .iter()
        .fold(0_u8, |sum, byte| sum.wrapping_add(*byte));
    0_u8.wrapping_sub(sum).wrapping_sub(0x19)
}

/// Locate a GBA tool using an explicit override, `PATH`, then devkitPro.
pub fn find_gba_tool(override_path: Option<&Path>, name: &'static str) -> Option<PathBuf> {
    tool::find_tool(override_path, name, Some(Path::new(DEVKITARM_BIN)))
}

fn build_image_in_dir(
    config: &CompilerConfig,
    module: &str,
    output: &Path,
    temp_dir: &Path,
) -> Result<(), DriverError> {
    let gcc = find_gba_tool(config.gba_gcc.as_deref(), "arm-none-eabi-gcc").ok_or(
        DriverError::ToolNotFound {
            tool: "arm-none-eabi-gcc",
            hint: GBA_TOOL_HINT,
        },
    )?;
    let objcopy = find_gba_tool(config.gba_objcopy.as_deref(), "arm-none-eabi-objcopy").ok_or(
        DriverError::ToolNotFound {
            tool: "arm-none-eabi-objcopy",
            hint: GBA_TOOL_HINT,
        },
    )?;

    let ll_path = if config.keep_ll {
        output.with_extension("ll")
    } else {
        temp_dir.join("program.ll")
    };
    write_file(&ll_path, module.as_bytes())?;

    let bf_object = temp_dir.join("program.o");
    compile_bf_object(config, &ll_path, &bf_object)?;

    let startup_source = temp_dir.join("gba_startup.S");
    let runtime_source = temp_dir.join("gba_runtime.c");
    let linker_script = temp_dir.join("gba.ld");
    write_file(&startup_source, STARTUP_ASM.as_bytes())?;
    write_file(&runtime_source, runtime_c_source(config).as_bytes())?;
    write_file(&linker_script, LINKER_SCRIPT.as_bytes())?;

    let startup_object = temp_dir.join("gba_startup.o");
    let runtime_object = temp_dir.join("gba_runtime.o");
    let elf_path = temp_dir.join("program.elf");
    let raw_path = temp_dir.join("program.gba.raw");

    compile_startup(&gcc, &startup_source, &startup_object)?;
    compile_runtime(&gcc, &runtime_source, &runtime_object)?;
    link_elf(
        &gcc,
        &linker_script,
        &startup_object,
        &runtime_object,
        &bf_object,
        &elf_path,
    )?;
    objcopy_rom(&objcopy, &elf_path, &raw_path)?;

    let mut rom = fs::read(&raw_path).map_err(|source| DriverError::ReadSource {
        path: raw_path,
        source,
    })?;
    patch_header(&mut rom);
    write_file(output, &rom)
}

fn compile_bf_object(
    config: &CompilerConfig,
    ll_path: &Path,
    output: &Path,
) -> Result<(), DriverError> {
    let mut command = Command::new(&config.clang);
    command.arg("-Wno-override-module");
    command.arg(config.opt_level.clang_arg());
    command.arg("-ffreestanding");
    command.arg("-fno-builtin");
    command.arg("-fno-unwind-tables");
    command.arg("-fno-asynchronous-unwind-tables");
    if let Some(target_triple) = config.target.llvm_triple() {
        command.arg(format!("--target={target_triple}"));
    }
    command.args(config.target.clang_args());
    command.arg("-c");
    command.arg(ll_path);
    command.arg("-o");
    command.arg(output);
    run_command(command, &config.clang)
}

fn compile_startup(gcc: &Path, source: &Path, output: &Path) -> Result<(), DriverError> {
    let mut command = Command::new(gcc);
    command.args([
        "-mcpu=arm7tdmi",
        "-marm",
        "-mthumb-interwork",
        "-x",
        "assembler-with-cpp",
        "-c",
    ]);
    command.arg(source);
    command.arg("-o");
    command.arg(output);
    run_command(command, &gcc.display().to_string())
}

fn compile_runtime(gcc: &Path, source: &Path, output: &Path) -> Result<(), DriverError> {
    let mut command = Command::new(gcc);
    command.args([
        "-mcpu=arm7tdmi",
        "-mthumb",
        "-mthumb-interwork",
        "-ffreestanding",
        "-fno-builtin",
        "-fno-common",
        "-fno-jump-tables",
        "-fno-unwind-tables",
        "-fno-asynchronous-unwind-tables",
        "-Os",
        "-std=c99",
        "-c",
    ]);
    command.arg(source);
    command.arg("-o");
    command.arg(output);
    run_command(command, &gcc.display().to_string())
}

fn link_elf(
    gcc: &Path,
    linker_script: &Path,
    startup_object: &Path,
    runtime_object: &Path,
    bf_object: &Path,
    output: &Path,
) -> Result<(), DriverError> {
    let mut command = Command::new(gcc);
    command.args([
        "-mcpu=arm7tdmi",
        "-mthumb",
        "-mthumb-interwork",
        "-nostdlib",
        "-Wl,--gc-sections",
        "-Wl,--no-warn-execstack",
    ]);
    command.arg(format!("-Wl,-T,{}", linker_script.display()));
    command.arg(startup_object);
    command.arg(runtime_object);
    command.arg(bf_object);
    command.arg("-o");
    command.arg(output);
    run_command(command, &gcc.display().to_string())
}

fn objcopy_rom(objcopy: &Path, elf_path: &Path, output: &Path) -> Result<(), DriverError> {
    let mut command = Command::new(objcopy);
    command.arg("-O");
    command.arg("binary");
    command.arg(elf_path);
    command.arg(output);
    run_command(command, &objcopy.display().to_string())
}

fn run_command(command: Command, tool_name: &str) -> Result<(), DriverError> {
    if let Some(failure) = tool::run_captured(command).map_err(|source| DriverError::RunTool {
        tool: tool_name.to_string(),
        source,
    })? {
        return Err(DriverError::tool_failed(tool_name, failure));
    }

    Ok(())
}

fn write_file(path: &Path, bytes: &[u8]) -> Result<(), DriverError> {
    fs::write(path, bytes).map_err(|source| DriverError::WriteFile {
        path: path.to_path_buf(),
        source,
    })
}

fn temporary_dir() -> PathBuf {
    let timestamp = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|duration| duration.as_nanos())
        .unwrap_or_default();
    env::temp_dir().join(format!(
        "hypothalamus-gba-{}-{timestamp}",
        std::process::id()
    ))
}

fn runtime_c_source(config: &CompilerConfig) -> String {
    let (entry_symbol, putchar_symbol, getchar_symbol) = runtime_symbols(config);

    RUNTIME_C
        .replace(
            "__HYPOTHALAMUS_ENTRY_SYMBOL__",
            &escape_c_string(entry_symbol),
        )
        .replace(
            "__HYPOTHALAMUS_PUTCHAR_SYMBOL__",
            &escape_c_string(putchar_symbol),
        )
        .replace(
            "__HYPOTHALAMUS_GETCHAR_SYMBOL__",
            &escape_c_string(getchar_symbol),
        )
}

fn runtime_symbols(config: &CompilerConfig) -> (&str, &str, &str) {
    match config.target.runtime_abi() {
        RuntimeAbi::Freestanding(options) => (
            &options.entry_symbol,
            &options.putchar_symbol,
            &options.getchar_symbol,
        ),
        RuntimeAbi::Hosted => ("bf_main", "bf_putchar", "bf_getchar"),
    }
}

fn escape_c_string(value: &str) -> String {
    value.replace('\\', "\\\\").replace('"', "\\\"")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn patches_valid_gba_header() {
        let mut rom = vec![0xAA; 512];

        patch_header(&mut rom);

        assert!(has_valid_header(&rom));
        assert_eq!(&rom[0xA0..0xAC], ROM_TITLE);
        assert_eq!(&rom[0xAC..0xB0], GAME_CODE);
        assert_eq!(&rom[0xB0..0xB2], MAKER_CODE);
        assert_eq!(rom[0xB2], 0x96);
    }

    #[test]
    fn patch_extends_short_roms() {
        let mut rom = Vec::new();

        patch_header(&mut rom);

        assert_eq!(rom.len(), HEADER_SIZE);
        assert!(has_valid_header(&rom));
    }

    #[test]
    fn runtime_c_uses_configured_freestanding_symbols() {
        let target = crate::target::TargetProfile::resolve("gba").with_runtime_abi(
            RuntimeAbi::Freestanding(crate::llvm::FreestandingOptions {
                entry_symbol: "custom_entry".to_string(),
                putchar_symbol: "custom_putchar".to_string(),
                getchar_symbol: "custom_getchar".to_string(),
            }),
        );
        let config = CompilerConfig::for_target("examples/hello.bf", target);

        let runtime = runtime_c_source(&config);

        assert!(runtime.contains("__asm__(\"custom_entry\")"));
        assert!(runtime.contains("__asm__(\"custom_putchar\")"));
        assert!(runtime.contains("__asm__(\"custom_getchar\")"));
        assert!(runtime.contains("hypothalamus_bf_entry();"));
        assert!(!runtime.contains("bf_main();"));
    }
}