Attention

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

ACRN - Windows as a Guest¶

To enable Windows OS as a guest, refer to the ACRN project documentation.

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 is 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. For more details, refer to the ACRN project documentation.

ivshmem Driver for Windows¶

A ivshmem driver must be installed in the Windows Guest-OS 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 on how to build and install Windows driver, refer to the Windows hardware developer documentation.

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

Build Driver¶

To build the driver, install the Windows Driver Kit and associated dependencies on the Windows build machine:

Install Window Driver Kit (WDK).
Install Windows Visual Studio.
Install Windows SDK (10.0.19041.1).

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

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, use third-party tools like GnuWin of CygWin.

Open the ivshmem.sln solution in Visual Studio.
Check whether the patch file has modified the solution to SDK10.
1. In the Solution Explorer of Visual Studio, right-click project ivshmem, click 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 cannot be selected, re-target the project - right-click project ivshmem, click Retarget Projects, and select Windows SDK Version 10.0 (corresponding to your installed SDK version).
2. In the Solution Explorer of Visual Studio, right-click project ivshmem-test, click Properties, and check that Configuration Properties|General|Windows SDK Version shows 10.0.
  
  If this cannot be selected, re-target the project - right-click project ivshmem, click Retarget Projects, and select Windows SDK Version 10.0 (corresponding to your installed SDK version).
Windows 10 installs signed drivers only. Refer to Microsoft Driver Development documentation for details. As a sanity check test, do the following to enable signing:
1. In the Solution Explorer of Visual Studio, right-click project ivshmem and click 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 field of the form CN=”WDKTestCert <USER>, <NUMBER>”|<NUMBER>. Memorize the certificate name for later export operation.
  4. Click OK to close the Property page.
Follow the menu path Build > Build Solution. The driver files are stored in the <repo path>\\kvm-guest-drivers-windows\\ivshmem\\Install\\Win10\\amd64 directory.

Launch 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 6,ivshmem,dm:/shmem,128

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

Install Driver¶

Export the certificate:
- Open certmgr.msc (Press Windows + R and type certmgr.msc).
- From the left page, double-click Personal and then double-click Certificates. The certificates will be displayed on the right pane.
- Right-click the certificate that matches the certificate name that you memorized earlier.
- From the context menu, select All Tasks > Export….
- In the Certificate Export Wizard, select No, do not export private key and click Next.
- Select DER encoded binary X.509 (.CER) and click Next.
- Input a file name to store the certificate. (Recommendation: Choose the install directory of the other driver files).
- Click Next and Finish.
Copy all files in the installation directory (including the exported certificate file) to the Windows guest (for example, via USB thumb drive if USB is allocated to the Windows guest or via a share if network connection is established).
Enable test-signing for the Windows guest VM. Open a command window as administrator and type the following:
```
bcdedit /set testsigning on
```
Import the certificate:
- Open certmgr.msc on the Windows VM.
- Right-click Personal and select All Tasks > Import… from the context menu. Click Next.
- Enter the certificate file. Click Open.
- Make sure that Personal is provides as Certificate Store.
- Click Next and Finish.
Reboot the VM to activate the test signing mode.
Open the Device Manager. Expand System Devices and right-click RAM Storage Device. Select Update driver.

In the popup window, select option Browse my computer for driver software. Then, select the option Let me pick from a list of available drivers in my computer.

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

Accept to install unsigned driver.

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 a sanity check to see if the access to the shared memory works.