If you're encountering issues with CSMWrap, this page provides some common problems and potential solutions.

• Symptom: After launching csmwrap.efi, the screen goes black and nothing appears, or the system hangs.
• Possible Causes & Solutions:
  • Above 4G Decoding / Resizable BAR: This is the most common cause.
    • Solution: Enter your UEFI firmware setup and DISABLE "Above 4G Decoding," "Resizable BAR (ReBAR)," "Smart Access Memory (SAM)," or any similar options. These features map PCI resources (especially VRAM) above the 4GB address limit, which legacy VBIOS cannot access.
  • Legacy Region Write Protection: The 0xC0000-0xFFFFF memory region might be write-protected by your firmware, preventing CSMWrap from loading the VBIOS.
    • Check: CSMWrap attempts to unlock this. If it fails, it usually prints an error message before the screen might go blank (if console output works up to that point).
    • Solution: Unfortunately, if the firmware is strictly locking this region and EFI_LEGACY_REGION2_PROTOCOL or chipset hacks don't work, CSMWrap may not function on your system. Look for any "Legacy Option ROM" or "CSM" related settings in your UEFI that might influence this.
  • UEFI CSM Conflict: Your firmware's native CSM might be interfering.
    • Solution: Try DISABLING your motherboard's native CSM support in the UEFI settings. If that doesn't work, try ENABLING it as a last resort, as some boards might need it for low-level init.
  • Incorrect CSMWrap Version: Using an ia32 version on an x86_64 UEFI system or vice-versa.
    • Solution: Ensure you are using the correct csmwrap<ARCH>.efi for your system's UEFI architecture.
  • Video Mode Incompatibility (after initial boot screens): The legacy OS tries to set a video mode that SeaVGABIOS or your GPU's Option ROM doesn't fully support with the current GOP state.
    • Solution (for Windows): Try slipstreaming native legacy GPU drivers into your Windows installation media.

• Symptom: The UEFI firmware shows an error message when trying to launch csmwrap.efi, or it doesn't appear in the boot menu.
• Possible Causes & Solutions:
  • Secure Boot Enabled:
    • Solution: DISABLE Secure Boot in your UEFI firmware settings. CSMWrap is not signed.
  • Incorrect File Path/Name on ESP: The EFI application is not named or placed correctly for automatic discovery.
    • Solution: Ensure the file is at EFI/BOOT/BOOTX64.EFI (for 64-bit) or EFI/BOOT/BOOTIA32.EFI (for 32-bit) on your EFI System Partition. Alternatively, create a custom boot entry using your UEFI's boot manager.
  • Corrupted EFI File: The downloaded or built .efi file might be corrupted.
    • Solution: Re-download or Building from Source CSMWrap.

• Symptom: CSMWrap launches, SeaBIOS screen appears, but the legacy OS installer hangs, errors out, or the installed OS fails to boot.
• Possible Causes & Solutions:
  • ACPI/SMBIOS Issues: The ACPI or SMBIOS tables provided by your UEFI firmware might be incompatible or insufficient for the legacy OS.
    • Solution: This is hard to fix without firmware updates or advanced ACPI table patching (which CSMWrap doesn't extensively do). Check for UEFI firmware updates for your motherboard.
  • Storage Controller Mode: The storage controller (SATA/NVMe) mode in UEFI (AHCI, RAID, IDE) might be incompatible with what the legacy OS expects or has drivers for.
    • Solution: For OSes like Windows XP, you might need to set SATA mode to "IDE" or "Compatible" in UEFI, or slipstream AHCI drivers into the XP installation.
  • Memory Mapping (E820): While CSMWrap tries to create a valid E820 map, complex UEFI memory layouts could lead to issues.
    • Solution: Advanced debugging might be needed. Try simplifying your hardware configuration (e.g., removing unnecessary PCI cards).
  • Boot Media Issues: The legacy OS installation media itself might be faulty or not properly prepared for legacy boot.
    • Solution: Verify your installation media on a known-good legacy BIOS system or VM.

• Symptom: Input devices don't work once the legacy OS starts.
• Possible Causes & Solutions:
  • USB Legacy Support: Your UEFI firmware might not have USB Legacy Support fully enabled or it might be configured in a way that SeaBIOS CSM cannot properly take over.
    • Solution: Check UEFI settings for "USB Legacy Support," "XHCI Hand-off," "EHCI Hand-off" and ensure they are enabled.
  • Missing OS Drivers: The legacy OS might lack generic drivers for your USB controllers.
    • Solution: For very old OSes, you might need PS/2 peripherals or ensure the OS has appropriate USB drivers.

If you need to report an issue:

1. CSMWrap Version: Specify the version or commit hash you are using.
2. Hardware Details: Motherboard model, CPU, GPU.
3. UEFI Firmware Version:
4. CSMWrap Output: If CSMWrap prints any messages before the issue occurs, please include them. If your system has a serial port and you can capture output via it, that's ideal. QEMU allows easy serial log capture.
5. UEFI Settings: Confirm Secure Boot status, Above 4G Decoding status, and native CSM status.
6. Legacy OS: The specific legacy OS and version you are trying to boot.
7. Steps to Reproduce: Detailed steps leading to the problem.

This information will help in diagnosing the problem.