This guide explains how to use CSMWrap to boot a legacy operating system on a UEFI system.

1. CSMWrap EFI Application:

   • You need the compiled csmwrap.efi file for your system's architecture (csmwrapx64.efi for 64-bit UEFI, csmwrapia32.efi for 32-bit UEFI).
   • You can either download this from the project's Releases page or Building from Source.

2. UEFI System Configuration:

   • Secure Boot MUST be DISABLED. CSMWrap is not signed and modifies low-level system settings, which is incompatible with Secure Boot.
   • Above 4G Decoding / Resizable BAR / Smart Access Memory MUST be DISABLED. Legacy VBIOS and Option ROMs are typically 32-bit and cannot access PCI BARs (like video RAM) mapped above the 4GB address space. Disabling this feature ensures hardware is mapped within the compatible 32-bit range.
   • CSM (Compatibility Support Module) in UEFI settings:
     • Try disabling it first: Your firmware's native CSM might conflict with CSMWrap. CSMWrap aims to be its own CSM.
     • If CSMWrap fails: Some motherboards might require their native CSM to be enabled for certain low-level hardware initializations or to allow legacy Option ROM execution, even if CSMWrap then takes over. Experiment if you encounter issues.
   • Boot Order: Ensure your UEFI firmware is set to boot from the device where you place CSMWrap and your legacy OS.

3. Legacy OS Installation Media: You'll need a bootable disk (or image for VMs) for the legacy OS you intend to install or run (e.g., FreeDOS, Windows XP, Windows 7).

1. Copy CSMWrap to EFI System Partition (ESP):

   • Identify your ESP. This is typically a FAT32 partition.
   • Create the directory EFI/BOOT on the ESP if it doesn't exist.
   • Copy the csmwrap<ARCH>.efi file to this directory and rename it according to your architecture:
     • For 64-bit UEFI: EFI/BOOT/BOOTX64.EFI
     • For 32-bit UEFI: EFI/BOOT/BOOTIA32.EFI
   • Alternatively, you can place it in a custom path (e.g., EFI/CSMWrap/csmwrap.efi) and use your UEFI firmware's boot manager to create a boot entry for it.

2. Prepare Legacy OS Boot Media:

   • Ensure your legacy OS installation media is connected (e.g., USB drive, CD/DVD) or configured in your VM.
   • CSMWrap will attempt to boot from devices in the order detected by the SeaBIOS CSM, typically: Floppy, Hard Disk, CD-ROM.

3. Boot your System:

   • Restart your computer.
   • Enter your UEFI firmware setup (usually by pressing Del, F2, F10, F12, or Esc during startup).
   • Verify the prerequisite UEFI settings (Secure Boot, Above 4G Decoding).
   • Select the boot entry for CSMWrap (either the default EFI/BOOT/BOOTX64.EFI or your custom entry).

4. CSMWrap Execution:

   • CSMWrap will initialize, set up the legacy environment, and then attempt to boot from available legacy devices.
   • You should see the SeaBIOS boot screen, followed by your legacy OS booting.

• FreeDOS
• Windows XP (32-bit)
• Windows 7 (32-bit and 64-bit, though 32-bit is more aligned with the legacy target)

Compatibility with other legacy OSes may vary.

• Hardware Compatibility: CSMWrap's success heavily depends on the specific UEFI firmware and hardware components of your system. Not all systems will work flawlessly.
• Legacy Region Unlocking: CSMWrap needs to make the legacy BIOS region (0xC0000-0xFFFFF) writable. It first tries using the EFI_LEGACY_REGION2_PROTOCOL. If unavailable, it attempts chipset-specific PCI configuration hacks (e.g., for Intel PAM registers or AMD MTRRs). These hacks may not work on all chipsets or could be blocked by firmware. See Limitations and Known Issues.
• Video Modesetting: Windows XP/7 might have issues with video modesetting after handing over from the VESA VBIOS, potentially causing flickering or black screens. See Troubleshooting.
• Peripheral Support: Support for specific peripherals in the legacy environment depends on the drivers available within SeaBIOS and the legacy OS.

If you encounter issues, please refer to the Troubleshooting page and the Limitations and Known Issues page.