CSMWrap is an EFI application designed to be a drop-in solution to enable legacy BIOS booting on modern UEFI-only (class 3) systems. It achieves this by wrapping a Compatibility Support Module (CSM) build of the SeaBIOS project as an out-of-firmware EFI application, effectively creating a compatibility layer for traditional PC BIOS operation.

The idea is to drop the 64-bit or 32-bit version of CSMWrap (depending on the hardware, dropping both also works) into a /EFI/BOOT/ directory on a FAT (12, 16, or 32) partition on the medium containing the legacy BIOS OS. UEFI firmware will pick this up and show the medium as a bootable device. Ideally, that's all that would be needed.

1. Download: Get the latest csmwrap<ARCH>.efi from the Releases page.
2. Deploy: Copy csmwrap<ARCH>.efi to a FAT-formatted partition, typically as /EFI/BOOT/BOOTX64.EFI (for 64-bit) or /EFI/BOOT/BOOTIA32.EFI (for 32-bit) (the hardcoded path is needed so that the firmware picks it up automatically).
3. Boot: Select the UEFI boot entry for the drive onto which CSMWrap was deployed.

It is highly recommended that the partition table used is MBR (MS-DOS partition table), as UEFI firmwares are perfectly capable of booting off of this format, and because it is the most compatible with most legacy OSes one may want to boot.

Secure boot should be disabled unless one wants to manually sign the CSMWrap EFI application, which is possible, but beyond the scope of this README.

CSMWrap is designed to be as drop-in as possible, without requiring changes to firmware for settings that may not even be exposed (depending on the firmware), or that might conflict with other UEFI OSes being multi-booted on the system. That said, if at all possible, disabling these settings is highly recommended for best legacy OS compatibility:

1. X2APIC

Additional settings to try to disable if things still do not work (ideally this should not be necessary, please report an issue if you need this on your hardware!):

1. Above 4G Decoding
2. Resizable BAR/Smart Access Memory

CSMWrap also wraps the "SeaVGABIOS" module of SeaBIOS for providing a bare bones implementation of a legacy Video BIOS. That said, SeaVGABIOS is far from ideal, and many, many things requiring more direct access to legacy video modes won't work properly (e.g. pretty much all MS-DOS games, MS-DOS Editor, etc.). More modern OSes using the VESA BIOS extensions (VBE) standard only (e.g. more modern Windows NT, Linux, etc.) should still work fine, though.

Therefore it is highly recommended, if possible, to install a legacy-capable video card. If one is present, its Video BIOS will be used instead of SeaVGABIOS, providing a much better, pretty much native-like, experience.

CSMWrap supports an optional INI-style configuration file. Place a file named csmwrap.ini in the same directory as the CSMWrap EFI executable (e.g. /EFI/BOOT/csmwrap.ini). If the file is absent, sensible defaults are used.

Boolean values accept true/yes/1 and false/no/0 (case-insensitive). Comments start with ; or #.

; CSMWrap configuration
serial = true
serial_port = 0x3f8
serial_baud = 115200
vgabios = \EFI\CSMWrap\vgabios.bin
iommu_disable = true

No! At least not in the sense of it being a full-screened emulator window. Running a legacy OS with CSMWrap means that it is natively running on the system. CSMWrap attempts to recreate, natively, and as closely as possible, a legacy BIOS PC environment on modern UEFI class 3 systems.

This is expected. CSMWrap reserves 1 logical processor for "system" use due to the limitations of running out-of-firmware and not being able to use SMM (System Management Mode).

Therefore, this means that CSMWrap does not support running on systems with only 1 logical processor (i.e. only 1 core and no SMT/hyperthreading). That said, most systems that CSMWrap targets (i.e. modern UEFI class 3 systems) will definitely have way more than a single logical processor, so this is mostly a non-issue.

Yes! Native CSM firmware is often riddled with issues and hardly tested against legacy OSes anymore. CSMWrap ships a reliable, free, and open-source legacy BIOS implementation - SeaBIOS - and it is tested against legacy OSes. Issues affecting modern, commonly shipped CSM implementations do not affect CSMWrap, like for example:

• Dirty control register values at handoff. (This is something that cregfix was created to work around).
• Legacy BIOS routines failing to reliably run when called from Virtual 8086 Mode. EMM386, Windows 3.x under 386 enhanced mode, and more, are affected by this issue and it results in crashes. The reason for this is a bit technical for this README file, but CSMWrap is not affected.

And when it comes to improvements that are not necessarily bugs in CSM implementations, CSMWrap, amongst other things:

• Generates MP tables for legacy OSes that support the legacy Intel MultiProcessor Specification standard but not ACPI.
• Allows one to select a non-primary video card for VGA output which native CSM implementations do not allow. This is useful for multi-booting modern and legacy OSes.

For detailed installation, usage, advanced scenarios, and troubleshooting, please consult our Wiki.

Please note that the Wiki is contributed by the community and may be incomplete or inaccurate as per the latest CSMWrap releases!

Contributions are welcome! Whether it's reporting bugs, suggesting features, improving documentation, or submitting code changes, your help is appreciated. Please read the Contributing guide for more details.

Additionally, one can join our Discord server for any project-related discussion, or to otherwise chat with likeminded people.

• The SeaBIOS project for their CSM and VBIOS code.
• PicoEFI for the EFI C runtime, build system, and headers.
• EDK2 (TianoCore) for UEFI specifications and some code snippets.
• uACPI for ACPI table handling.
• @CanonKong for test feedback and general knowledge.
• All contributors and testers from the community!