Make Doom For Mips

2. Determine Endianness and ABI

Verify the target architecture details by examining the VM source:

• Endianness (little-endian vs big-endian MIPS)
• Floating-point support (hardware vs soft-float)
• Word size (32-bit vs 64-bit)
• ABI variant (o32, n32, n64)

3. Understand Memory Layout

From the VM source, extract:

• Expected entry point address
• Stack location and size
• Heap boundaries
• Text/data segment placement
• Any memory-mapped I/O regions

4. Identify Supported Instructions

Check for instruction limitations:

• Floating-point instruction support
• Privileged instructions
• Branch delay slot handling
• Any unimplemented instructions that will cause VM termination

Systematic Approach to Freestanding Compilation

Phase 1: Comprehensive Header Analysis

Before compiling, scan all source files to identify required headers:

# Find all included headers
grep -rh '#include' src/ | sort -u

Create stub headers for ALL identified system headers upfront rather than reactively fixing one error at a time. Common headers needed for complex C programs:

• <stdio.h>, <stdlib.h>, <string.h>, <stdint.h>
• <limits.h>, <stddef.h>, <stdarg.h>
• <ctype.h>, <math.h>, <time.h>
• <errno.h>, <assert.h>, <fcntl.h>
• <unistd.h>, <sys/types.h>, <sys/stat.h>

Phase 2: Standard Library Implementation

Create a comprehensive stdlib replacement with COMPLETE implementations:

Critical functions that must work correctly (not return 0 or stub):

• printf, fprintf, sprintf, snprintf - Used for debug output and parsing
• sscanf, fscanf - Used for configuration parsing
• malloc, free, realloc - Memory management
• memcpy, memset, memmove, strlen, strcmp, strcpy - String/memory operations
• atoi, atol, strtol - Number parsing
• fopen, fread, fwrite, fclose, fseek, ftell - File I/O

Warning signs of incomplete implementations:

• Functions returning 0 unconditionally
• Empty function bodies
• "TODO" or stub comments
• Missing format specifier handling in printf-family functions

Phase 3: Linker Script Configuration

Create a linker script that matches the VM's expectations:

• Entry point symbol must match what the VM looks for
• Section addresses must align with VM memory layout
• Stack initialization must be included in startup code
• Verify .text, .data, .bss, .rodata placement

Verification Strategies

1. Syscall Verification

After implementing syscalls, verify each one works:

// Test write syscall
const char *msg = "Syscall test\n";
write(1, msg, strlen(msg));

// Test read syscall
char buf[100];
int n = read(0, buf, sizeof(buf));

// Test file operations
int fd = open("/path/to/file", O_RDONLY);
// etc.

2. Entry Point Verification

Confirm the entry point matches:

# Check the ELF entry point
mips-*-readelf -h output.elf | grep Entry

# Verify symbol is at expected address
mips-*-nm output.elf | grep __start

3. Map File Analysis for Debugging

Generate and use map files to debug crashes:

# Generate map file during linking
-Wl,-Map=output.map

# When program terminates at specific PC, find the function:
grep "0x40b7b0" output.map

4. Incremental Testing

Test components in isolation before full integration:

1. Minimal "hello world" to verify basic execution
2. Memory allocation test program
3. File I/O test program
4. Individual library function tests
5. Finally, the full application

Common Pitfalls and Solutions

Pitfall 1: ABI Mismatch Warnings

Problem: Linking soft-float compiled code with hard-float libgcc produces warnings: