Windows Platform Adaptation Summary for Machina

[Lfan-ke]

Windows compilation failure due to POSIX-specific mmap usage

Issue Type: Bug
Priority: High
Affected Platforms: Windows (x86_64)
Working Platforms: WSL2, Linux, macOS

Problem Description

The machina-memory crate fails to compile on native Windows environments due to the use of POSIX-specific memory mapping functions that are not available in the Windows version of the libc crate.

Error Details

The compilation fails with 7 errors related to missing symbols in the libc crate:

• mmap function not found
• munmap function not found
• Constants not found: PROT_READ, PROT_WRITE, MAP_PRIVATE, MAP_ANONYMOUS, MAP_FAILED

   Compiling machina-memory v0.1.0 (machina\memory)
error[E0425]: cannot find function `mmap` in crate `libc`
  --> memory\src\ram.rs:17:19
   |
17 |             libc::mmap(
   |                   ^^^^ not found in `libc`

error[E0425]: cannot find value `PROT_READ` in crate `libc`
  --> memory\src\ram.rs:20:23
   |
20 |                 libc::PROT_READ | libc::PROT_WRITE,
   |                       ^^^^^^^^^ not found in `libc`

error[E0425]: cannot find value `PROT_WRITE` in crate `libc`
  --> memory\src\ram.rs:20:41
   |
20 |                 libc::PROT_READ | libc::PROT_WRITE,
   |                                         ^^^^^^^^^^ not found in `libc`

error[E0425]: cannot find value `MAP_PRIVATE` in crate `libc`
  --> memory\src\ram.rs:21:23
   |
21 |                 libc::MAP_PRIVATE | libc::MAP_ANONYMOUS,
   |                       ^^^^^^^^^^^ not found in `libc`

error[E0425]: cannot find value `MAP_ANONYMOUS` in crate `libc`
  --> memory\src\ram.rs:21:43
   |
21 |                 libc::MAP_PRIVATE | libc::MAP_ANONYMOUS,
   |                                           ^^^^^^^^^^^^^ not found in `libc`

error[E0425]: cannot find value `MAP_FAILED` in crate `libc`
  --> memory\src\ram.rs:27:44
   |
27 |             !ptr.is_null() && ptr != libc::MAP_FAILED as *mut u8,
   |                                            ^^^^^^^^^^ not found in `libc`

error[E0425]: cannot find function `munmap` in crate `libc`
  --> memory\src\ram.rs:52:19
   |
52 |             libc::munmap(self.ptr as *mut libc::c_void, self.size as usize);
   |                   ^^^^^^ not found in `libc`

For more information about this error, try `rustc --explain E0425`.
error: could not compile `machina-memory` (lib) due to 7 previous errors

Root Cause

The RamBlock implementation in memory/src/ram.rs uses Unix-specific memory mapping APIs that are not portable to Windows. The libc crate on Windows does not provide these POSIX functions.

Affected Code

File: memory/src/ram.rs

• Lines 17-27: mmap call with Unix-specific flags
• Line 52: munmap call

Expected Behavior

The crate should compile successfully on both Windows and Unix-like systems.

Proposed Solutions

1. Use conditional compilation: Implement platform-specific code using #[cfg(target_os = "windows")] and #[cfg(unix)]
2. Use cross-platform memory mapping crate: Consider using memmap2 or similar crates that provide portable memory mapping
3. Implement Windows-specific memory allocation: Use VirtualAlloc/VirtualFree on Windows while keeping mmap on Unix

Temporary Workaround

Use WSL2 for development on Windows systems.

Reproduction Steps

1. Clone repository on native Windows (not WSL2)
2. Run cargo build
3. Observe compilation failures in machina-memory crate

Environment

• OS: Windows 11 x86_64
• Rust: Latest stable
• libc: 0.2.183

---

Windows Platform Adaptation Summary for Machina

Overview

This document summarizes all the modifications made to adapt the Machina RISC-V emulator from Linux-only to Windows-compatible. The adaptation includes dependency management, conditional compilation, platform abstraction, and build system enhancements.

Detailed File Modifications

1. Dependency Configuration

File: machina/util/Cargo.toml

Changes:

[target.'cfg(windows)'.dependencies]
windows-sys = { version = "0.61", features = [
    "Win32_System_Memory",
    "Win32_System_SystemInformation",
    "Win32_Foundation", 
    "Win32_System_Threading",
    "Win32_System_Diagnostics",
    "Win32_System_Diagnostics_Debug",
] }

[target.'cfg(unix)'.dependencies]
libc = "0.2"

Purpose: Platform-specific dependency isolation to avoid conflicts and ensure proper Windows API support.

2. Conditional Compilation for Unix-specific Features

File: machina/tests/src/tools/mod.rs (Lines 310-313)

Changes:

// Kill the process (it will loop forever).
#[cfg(unix)]
unsafe {
    libc::kill(child.id() as libc::pid_t, libc::SIGTERM);
}

Purpose: Protect Unix-specific signal handling code from compilation on Windows platforms.

3. Build Documentation

File: machina/docs/zh/windows-build.md (New file)

Content: Complete Windows build guide including:

• MSYS2/MinGW-w64 environment setup
• Rust toolchain configuration for Windows
• Build instructions and dependency installation
• Platform compatibility notes and known issues

4. Environment Check Script

File: machina/scripts/check_windows_env.ps1 (New file)

Functionality:

• Windows environment dependency validation
• Support for both WSL and native MSYS2 build methods
• Alternative solutions and error handling

5. Platform Abstraction Layer

Memory Management:

• Unix: Uses mmap/mprotect/munmap
• Windows: Uses windows-sys with memmap2 for compatibility

Terminal and Signal Handling:

• Unix-specific features protected with cfg(unix) conditional compilation
• Safe fallback or skip mechanisms for Windows

6. Build System Configuration

Changes:

• Support for x86_64-pc-windows-gnu toolchain
• Windows-specific build targets configuration
• Test adaptation to handle platform differences

Adaptation Strategy

1. Conditional Compilation: Strict separation using cfg(unix) and cfg(windows) attributes
2. Dependency Isolation: Platform-specific dependencies to prevent conflicts
3. Feature Degradation: Safe handling of Windows-unsupported Unix features
4. Unified Interface: Consistent cross-platform APIs to minimize platform-specific code

Key Technical Changes

1. Signal Handling: Unix-specific signal processing protected by conditional compilation
2. Memory Management: Platform-specific memory allocation and protection APIs
3. Process Management: Alternative process termination methods for Windows
4. Build Configuration: Full Windows toolchain support and target configuration

Status

✅ Build: Machina successfully builds on Windows platforms
✅ Basic Functionality: Core emulator functionality works on Windows
⚠️ Testing: Some Unix-specific tests are conditionally compiled and skipped on Windows
⚠️ Advanced Features: Certain Unix-only features have limited functionality on Windows

The adaptation ensures Machina can be built and run on Windows while maintaining full compatibility with Linux platforms. All modifications follow Rust best practices and use conditional compilation to manage platform differences effectively.

[Lfan-ke]

need to support mingw, crt64, msys2 ...

[Lfan-ke]

#3