
QEMU for MSYS2/Windows
======================

Usage
-----

QEMU - if installed to MINGW64 subsystem for example - can be run using the
MINGW64 shell natively. Because of the shell's automatic path conversion to
Windows paths the usage is transparent. QEMU itself doesn't understand
MSYS2-paths. This is the reason why the following command is valid:

```
$ qemu-img create -f qcow2 /tmp/test.qcow2 1G
```

QEMU is native Windows software, but relies on its subsystem's libraries. QEMU
can also be run by an alternative CLI. Cygwin was successfully tested:

```
$ export PATH="/cygdrive/<MSYS2_INST_DIR>/mingw64/bin:$PATH"
$ qemu-img create -f qcow2 $(cygpath -w -m /tmp/test.qcow2) 1G
```

Hardware acceleration
---------------------

Make sure you are either using Windows 10 Pro and you've enabled WHPX or you
own an Intel CPU and you've installed HAX. Otherwise no hardware acceleration
can be used.
https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v
https://github.com/intel/haxm

Tests and examples
------------------

msys2.examples.tests.sh contains several demo use and test cases which can be
executed easily in MINGW64 shell:

```
$ /mingw64/share/doc/qemu/msys2.examples.tests.sh
```

Most demo use cases are VMs taken from QEMU Advent Calendar
https://www.qemu-advent-calendar.org/
which were adjusted to run on MSYS2/Windows as well as on Linux.

Desktop use cases were integrated to show different options how to run a Linux
desktop using SPICE, SDL, GTK and VNC.

All demo use cases can be used to perform a regression test on MSYS2, too:
The script supports comparing two specified versions of qemu by executing the
use cases with both versions consecutively

Hints
-----

* Starting Linux kernel images via QEMU command line

  Absolute paths are converted to windows paths in MINGW64 shell automatically
  and therefore get invalid occasionally, which can be mitigated:

    ```
    $ export MSYS2_ARG_CONV_EXCL='*'
    $ qemu-system-x86_64 -append root=/dev/hda
    $ unset MSYS2_ARG_CONV_EXCL
    ```

  Make sure you do not use any further (absolute) paths in the command, which
  need to be converted


Issues
------

Since 6.0.0 and earlier:

* Plain WHPX-acceleration shows these messages

    ```
    $ qemu-system-x86_64 -accel whpx
    WHPX: setting APIC emulation mode in the hypervisor
    whpx: injection failed, MSI (0, 0) delivery: 0, dest_mode: 0, trigger mode: 0, vector: 0, lost
    ```

  and causes https://gitlab.com/qemu-project/qemu/-/issues/346 occasionally,
  which can be mitigated by invocing acceleration like

    ```
    $ qemu-system-x86_64 -accel whpx,kernel-irqchip=off
    ```

* Using UEFI firmware and WHPX-acceleration in combination with pflash fails

    ```
    $ qemu-system-x86_64 -accel whpx -pflash <UEFI_FIRMWARE>
    or
    $ qemu-system-x86_64 -accel whpx -drive if=pflash,file=<UEFI_FIRMWARE>
    ```

  with error messages

    ```
    WHPX: Failed to emulate MMIO access with EmulatorReturnStatus: 2
    WHPX: Failed to exec a virtual processor
    ```

  see https://gitlab.com/qemu-project/qemu/-/issues/513

  As WA use '-bios' with concatenated firmware

    ```
    $ cat /mingw64/share/qemu/edk2-i386-vars.fd \
        /mingw64/share/qemu/edk2-x86_64-code.fd > edk2-x86_64.fd
    $ qemu-system-x86_64 -accel whpx -bios edk2-x86_64.fd
    ```

* `qemu-img convert -O vhdx` produces invalid images

  WA: use qemu-img in WSL

