Platforms - FarelRA/CSMWrap GitHub Wiki

Platform-Specific Notes and Guides

This page contains notes, tips, and specific guidance for running CSMWrap on different hardware platforms and virtual machines. Success can vary greatly depending on the specific chipset, firmware, and configuration.

General UEFI Settings (Applicable to Most Platforms)

Before attempting to use CSMWrap, ensure the following UEFI settings are configured:

  1. Secure Boot: MUST be DISABLED.
  2. Above 4G Decoding / Resizable BAR / Smart Access Memory: MUST be DISABLED. This is critical for legacy VBIOS compatibility as it ensures PCI resources (like VRAM) are mapped below the 4GB address space.
  3. CSM (Compatibility Support Module):
    • Try with native CSM DISABLED first. CSMWrap aims to be its own CSM.
    • If issues occur, try enabling the native CSM as some motherboards might require it for initial low-level hardware setup. This can sometimes cause conflicts, so experimentation is key.
  4. SATA Controller Mode: For older OSes like Windows XP, you might need to set your SATA controller to IDE/Compatible mode if AHCI drivers are not available or slipstreamed into your OS installation media.
  5. USB Legacy Support: Ensure this is ENABLED if you plan to use USB keyboards/mice in the legacy OS. Options like "XHCI Hand-off" and "EHCI Hand-off" should generally be enabled.
  6. Boot Order: Set your system to boot from the EFI file/device where CSMWrap is located.

Intel Platforms

  • Legacy Region Unlocking (PAM Registers):
    • CSMWrap attempts to unlock the 0xC0000-0xFFFFF region by modifying PAM (Programmable Attribute Map) registers if EFI_LEGACY_REGION2_PROTOCOL is unavailable.
    • Known supported (or attempted) chipsets:
      • PIIX4-based (e.g., Intel 440FX/BX in QEMU/VMware): Uses PAM registers at offset 0x59-0x5F in PCI device 0, bus 0, function 0.
      • Q35-based (e.g., in QEMU, some older desktops): Uses PAM registers at offset 0x90-0x96 in PCI device 0, bus 0, function 0.
      • Skylake and newer (ICH9/PCH based): May use PAM registers around offset 0x80. CSMWrap includes logic for this, but modern firmware often locks these down tightly. Some PCHs also have a BIOS_CNTL register (e.g., D_LCK bit at PCI dev 0, func 31, offset 0xDC) that can prevent writes to the BIOS region. CSMWrap does not currently attempt to manipulate BIOS_CNTL bits due to potential risks.
  • Intel Integrated Graphics (iGPU):
    • Getting legacy VBIOS support for modern Intel iGPUs can be challenging. SeaVGABIOS relies on GOP information, which might be sufficient for basic display.
    • Native Option ROMs for modern Intel iGPUs are rare in legacy format.
  • 8254CGE Workaround (intel_workarounds.c): Some Intel PCHs have a "Gate Enable" for the Programmable Interval Timer (PIT) that can interfere with legacy OSes. CSMWrap attempts to disable this via the P2SB (Primary to Sideband Bridge) device if detected.

AMD Platforms

  • Legacy Region Unlocking (MTRRs):
    • If EFI_LEGACY_REGION2_PROTOCOL is unavailable, CSMWrap attempts to configure MTRRs (Memory Type Range Registers) to make the 0xC0000-0xFFFFF region write-back. This involves setting MTRRdefType and fixed-range MTRRs.
    • This method is generally more common on AMD systems for controlling this region's cacheability and writability at a low level.
  • AMD Integrated Graphics (APUs):
    • Similar to Intel iGPUs, SeaVGABIOS will try to use GOP information.
    • Legacy Option ROM availability for modern AMD APUs is uncommon.
  • IOMMU: Ensure your IOMMU (AMD-Vi) settings in UEFI are compatible if you encounter issues with peripherals in the legacy OS. Sometimes disabling it can help with legacy compatibility, but this has security implications for modern OSes.

Virtual Machines (VMs)

QEMU

  • Machine Types:
    • pc-q35-x.x (or q35): Generally recommended as it's more modern. CSMWrap's Q35 PAM register unlock logic should work.
    • pc-i440fx-x.x (or piix4): Older, but well-understood by legacy OSes. CSMWrap's PIIX4 PAM register unlock logic should work.
  • Firmware: Use OVMF (the EDK2-based UEFI firmware for QEMU).
    • The Makefile includes rules to download and use appropriate OVMF builds.
    • Ensure you are using an OVMF build without Secure Boot enabled for testing CSMWrap.
  • VGA:
    • -vga std: Standard VGA, usually works well with SeaVGABIOS.
    • -vga virtio: VirtIO-GPU. SeaVGABIOS will use GOP info. Legacy OSes will need VirtIO GPU drivers for good performance.
    • -vga qxl: QXL. SeaVGABIOS will use GOP info. Legacy OSes might need QXL drivers.
  • "Above 4G" in QEMU: The -m XG,slots=Y,maxmem=ZG QEMU memory options can influence how memory is mapped. For CSMWrap, keeping maxmem below or around 4GB (e.g., -m 2G) often simplifies things and avoids Above 4G Decoding issues implicitly. If using larger maxmem, ensure the QEMU machine type and OVMF aren't forcing BARs above 4G.
  • Serial Output: Add -serial stdio or -serial file:serial.log to QEMU flags to capture CSMWrap's printf output for debugging.

VMware Workstation/Player

  • Firmware: Ensure the VM is configured for EFI boot.
  • Above 4G Decoding: VMware generally handles memory mapping well, but if issues arise, check VM settings or .vmx file for related options (though less common to expose directly).
  • Virtual Hardware: Uses emulated Intel chipsets (often PIIX4 or similar for legacy parts, or newer emulated Intel chipsets). CSMWrap's Intel PAM logic might apply.
  • SVGA Adapter: VMware's SVGA adapter usually has good GOP support. Legacy OSes will benefit from VMware Tools installation (which includes the SVGA driver).

VirtualBox

  • Firmware: Ensure EFI is enabled for the VM.
  • Chipset: Typically emulates an Intel PIIX3/ICH9 or similar. CSMWrap's Intel PAM logic might apply.
  • Graphics: VirtualBox's emulated graphics adapter. GOP support is usually present. Guest Additions are recommended for legacy OSes.
  • Above 4G Decoding: Less likely to be an explicit issue unless configuring very large amounts of RAM for the VM.

General Platform Advice

  • Start Simple: When first testing, try with a minimal hardware configuration (e.g., one GPU, one storage drive).
  • Firmware Updates: Ensure your motherboard's UEFI firmware is up-to-date. Sometimes updates improve compatibility or fix bugs related to legacy resource handling. However, updates can also sometimes introduce new restrictions.
  • Check Logs: If your system has a POST code display or serial logging capabilities, these can be invaluable for diagnosing hangs early in CSMWrap's execution.

This page is a work-in-progress. If you have specific experiences or tips for a particular platform, please consider Contributing them!