Attention

You are viewing an older version of the documentation. The latest version is v3.3.

Windows as a Guest

To enable Windows OS as a guest, please refer to the ACRN project documentation at: https://projectacrn.github.io/latest/tutorials/using_windows_as_uos.html

Inter VM communication via shared memory

For inter VM communication a shared memory region can be utilized which is managed by the SOS. The shared memory to provided to a VM as a memory region of a PCI device. By device model configuration the PCI device is assigned to the Guest OS. Please refer to the ACRN project documentation for more details: https://projectacrn.github.io/latest/developer-guides/hld/ivshmem-hld.html

ivshmem Driver for Windows

A ivshmem driver must be installed in the Windows Guest-OS in order to use the shared memory. The sources for the driver are available at: https://github.com/virtio-win/kvm-guest-drivers-windows/tree/master/ivshmem/. For detailed information how to build and install Windows driver please refer to Windows hardware developer documentation.

Note

For Windows 10 drivers must be signed by an official authority.

Building the driver

To build the driver, the Windows Driver Kit and associated dependencies must be installed on the Windows build machine.

  1. Install Window Driver Kit (WDK).

  2. Install Windows Visual Studio.

  3. Install Windows SDK (10.0.19041.1).

    See WDK documentation on how to install the SDK with Visual Studio.

  4. Clone the source repository to commit edda3f50a17015aab1450ca09e3263c7409e4001 and apply patch file 0001-Ivshmem-SDK10.patch.

    # git clone https://github.com/virtio-win/kvm-guest-drivers-windows.git
# cd kvm-guest-drivers-windows
# git checkout edda3f50a17015aab1450ca09e3263c7409e4001
# patch -p1 < <path to 0001-Ivshmem-SDK10.patch>

    Note

    For Windows build hosts 3rd party tools like GnuWin of CygWin could be used.

  5. Open solution ivshmem.sln in Visual Studio.

  6. Check that the solution is correctly modified to SDK10 by the patch file.

    1. In the Solution Explorer of Visual Studio, right-click on project ivshmem, click on properties and check that Configuration Properties|General|Platform Toolset shows WindowsKernelModeDriver10.0 and Configuration Properties|General|Windows SDK Version shows 10.0 (corresponding to the installed SDK version).

      If this can not be selected, re-target the project by right-clicking on project ivshmem by clicking Retarget Projects and selecting Windows SDK Version 10.0 (corresponding to your installed SDK version).

    2. In the Solution Explorer of Visual Studio, right-click on project ivshmem-test, click on properties and check that Configuration Properties|General|Windows SDK Version shows 10.0.

      If this can not be selected, re-target the project by right-clicking on project ivshmem by clicking Retarget Projects and selecting Windows SDK Version 10.0 (corresponding to your installed SDK version).

  7. Windows 10 installs signed drivers only. Please refer to Microsoft Driver Development documentation for details. As a sanity check test signing can be enabled as follows:

    1. In the Solution Explorer of Visual Studio, right-click on project ivshmem, click on properties.

      1. Make sure that Run Inf2Cat is set to yes in Inf2Cat|General.

      2. Set Sign Mode to Test Sign in Driver Signing|General.

      3. Select <Create Test Certificate…> for Test Certificate entry. The name of the test certificate will appear in the filed of the form CN=”WDKTestCert <USER>, <NUMBER>”|<NUMBER>. Memorize the certificate name for later export operation.

      ../../_images/key1.png

      1. Close the Property page by clicking OK

  8. Build the solution by selecting selecting Build Solution of the Build menu. The driver files are stored in <repo path>\kvm-guest-drivers-windows\ivshmem\Install\Win10\amd64 directory.

Launch a Window Guest VM with IVSHMEM

The shared memory region must be enabled at startup of the Windows guest VM. Adapt the launch script located in /var/lib/machines of the root file system of the SOS by adding:

-s 8,ivshmem,shmem,4096

This adds a shared memory device of size 4096 bytes with the name shmem as slot 8 (only the device type ivshmem is a fixed parameter). The size and name parameter must be the same among the acrn-dm calls for both VMs that are supposed to communicate with the shared memory region.

Driver installation

  1. Export the certificate. Open certmgr.msc (Press Windows+R and type certmgr.msc). On the left side click on double-click on Personal and then click on Certificates. Click on the certificate with the memorized name on the right side of the window. In the context menu select All Tasks|Export…. In the dialog that appears select No, do not export private key, press Next. Select DER encoded binary X.509 (.CER), press Next and input a file name to store the certificate. (Recommendation: Chose the install directory of the other driver files as directory) Press Next and Finish.

    ../../_images/certmgr.png

  2. Copy all files in the installation directory (including the exported certificate file) to the Windows guest (e.g. via USB thumb drive if USB is allocated to the Windows guest or via a share in case network connection is established).

  3. Enable testsigning for the Windows guest VM. Open a command window as administrator and type

    bcdedit /set testsigning on

  4. Import the certificate. Open certmgr.msc like described above on Windows VM. Right-click on Personal and select All Tasks|Import… in the context menu. Press Next and enter the certificate file. Press Open. Make sure Personal is given as Certificate Store. Press Next and Finish.

  5. Reboot the VM to activate the test signing mode.

  6. Open the device manager and right-click on RAM Storage Device under System Devices. Select Update driver.

    ../../_images/RAMController.png

    In the popup windows select the item that contains Browse my computer for driver software. Click on the item Let me pick from a list of available drivers in my computer.

    ../../_images/RAMController3.png

    Press Have Disk and enter the location of the certificate file. In the file select box select ivshmem.inf and press Open, then OK. Now select IVSHMEM under Model and press Next.

    ../../_images/RAMController5.png

    Accept to install unsigned driver.

    ../../_images/RAMController6.png

  7. The installation of the driver is now completed. IVSHMEM should now appear in the device manager under System Devices.

Local driver test

Run ivshmem-test.exe as sanity check that access to the shared memory works.

../../_images/test.png