1.. _using_windows_as_uos:
2.. _using_windows_as_user_vm:
3
4Run Windows as the User VM OS
5#############################
6
7This tutorial describes how to launch Windows as a Guest (WaaG) User VM on the
8ACRN hypervisor.
9
10
11ACRN Service VM Setup
12*********************
13
14Follow the steps in this :ref:`gsg` to set up ACRN
15based on Ubuntu and launch the Service VM.
16
17Setup for Using Windows as the Guest VM
18***************************************
19
20In the following steps, you'll first create a Windows image
21in the Service VM, and then launch that image as a Guest VM.
22
23
24Verified Version
25================
26
27* Windows 10 Version:
28
29  - Microsoft Windows 10 Enterprise LTSC Evaluation
30
31* Windows graphics driver:
32
33  - igfx_win10_100.9030.zip
34
35   .. note::
36
37      WHL needs the following BIOS setting:
38      set **DVMT Pre-Allocated** to **64MB** and set **PM Support**
39      to **Enabled**.
40
41Create a Windows 10 Image in the Service VM
42===========================================
43
44Create a Windows 10 image to install Windows 10 onto a virtual disk.
45
46Download Win10 Image and Drivers
47--------------------------------
48
49#. Download `MediaCreationTool20H2.exe <https://www.microsoft.com/software-download/windows10>`_.
50
51   - Run this file and select **Create installation media(USB flash drive, DVD, or ISO file) for another PC**;
52     Then click **ISO file** to create ``Windows10.iso``.
53
54#. Download the `Oracle Windows driver <https://edelivery.oracle.com/osdc/faces/SoftwareDelivery>`_.
55
56   - Sign in. If you do not have an Oracle account, register for one.
57   - Select **Download Package**. Key in **Oracle Linux 7.6** and click
58     **Search**.
59   - Click **DLP: Oracle Linux 7.6** to add to your Cart.
60   - Click **Checkout**, which is located at the top-right corner.
61   - Under **Platforms/Language**, select **x86 64-bit**. Click **Continue**.
62   - Check **I accept the terms in the license agreement**. Click **Continue**.
63   - From the list, right check the item labeled **Oracle VirtIO Drivers
64     Version for Microsoft Windows 1.1.x, yy MB**, and then **Save link as
65     ...**. It is named ``V982789-01.zip``.
66   - Click **Download**. When the download is complete, unzip the file. You
67     will see an ISO named ``winvirtio.iso``.
68
69Create a Raw Disk
70-----------------
71
72Run these commands on the Service VM::
73
74   $ sudo apt-get install qemu-utils
75   $ mkdir /home/acrn/work
76   $ cd /home/acrn/work
77   $ qemu-img create -f raw win10-ltsc.img 30G
78
79Prepare the Script to Create an Image
80-------------------------------------
81
82#. Refer :ref:`gpu-passthrough` to enable GVT-d GOP feature; then copy above .iso files and  the built OVMF.fd to /home/acrn/work
83#. Prepare WaaG install script, a **/home/acrn/work/install_win.sh** file should be created with the following content.
84
85.. code-block:: bash
86
87   #!/bin/bash
88   function launch_win()
89   {
90   vm_name=win_vm$1
91   #check if the vm is running or not
92   vm_ps=$(pgrep -a -f acrn-dm)
93   result=$(echo $vm_ps | grep "${vm_name}")
94   if [[ "$result" != "" ]]; then
95     echo "$vm_name is running, can't create twice!"
96     exit
97   fi
98   echo "8086 9ded" > /sys/bus/pci/drivers/pci-stub/new_id
99   echo "0000:00:14.0" > /sys/bus/pci/devices/0000:00:14.0/driver/unbind
100   echo "0000:00:14.0" > /sys/bus/pci/drivers/pci-stub/bind
101   echo "8086 3ea0" > /sys/bus/pci/drivers/pci-stub/new_id
102   echo "0000:00:02.0" > /sys/bus/pci/devices/0000:00:02.0/driver/unbind
103   echo "0000:00:02.0" > /sys/bus/pci/drivers/pci-stub/bind
104   #for memsize setting
105   mem_size=4096M
106   acrn-dm -m $mem_size -s 0:0,hostbridge -s 1:0,lpc -l com1,stdio \
107     -s 2,passthru,0/2/0 \
108     -s 8,virtio-net,tap=tap0 \
109     -s 4,virtio-blk,/home/acrn/work/win10-ltsc.img
110     -s 5,ahci,cd:/home/acrn/work/Windows10.iso \
111     -s 6,ahci,cd:/home/acrn/work/winvirtio.iso \
112     -s 7,passthru,0/14/0,d3hot_reset \
113     --ovmf /home/acrn/work/OVMF.fd \
114     --windows \
115     $vm_name
116   }
117   # offline Service VM CPUs except BSP before launching User VM
118   for i in `ls -d /sys/devices/system/cpu/cpu[1-99]`; do
119           online=`cat $i/online`
120           idx=`echo $i | tr -cd "[1-99]"`
121           echo cpu$idx online=$online
122           if [ "$online" = "1" ]; then
123                   echo 0 > $i/online
124                   # during boot time, cpu hotplug may be disabled by pci_device_probe during a pci module insmod
125                  while [ "$online" = "1" ]; do
126                           sleep 1
127                           echo 0 > $i/online
128                           online=`cat $i/online`
129                   done
130                   echo $idx > /sys/devices/virtual/misc/acrn_hsm/remove_cpu
131           fi
132   done
133   launch_win 1
134
135Install Windows 10 by GVT-d
136---------------------------
137
138#. Run **install_win.sh**
139
140   .. code-block:: bash
141
142      cd /home/acrn/work/
143      sudo chmod +x install_win.sh
144      sudo ./install_win.sh
145
146When you see the UEFI shell, input **exit**.
147
148#. Select **Boot Manager** and boot from Win10 ISO.
149
150#. When the display reads **Press any key to boot from CD or DVD** on the
151   monitor, press any key in the terminal on the **Host** side.
152
153   .. figure:: images/windows_install_1.png
154      :align: center
155
156   .. figure:: images/windows_install_2.png
157      :align: center
158
159   .. figure:: images/windows_install_3.png
160      :align: center
161
162#. Click **Load driver**.
163
164   .. figure:: images/windows_install_4.png
165      :align: center
166
167#. Click **Browser** and go to the drive that includes the virtio
168   Windows drivers. Select **all** under **vio\\w10\\amd64**. Install the
169   following drivers into the image:
170
171   - Virtio-balloon
172   - Virtio-net
173   - Virtio-rng
174   - Virtio-scsi
175   - Virtio-serial
176   - Virtio-block
177   - Virtio-input
178
179   .. note:: Be sure to unselect **Hide Drivers that aren't compatible with
180      this computer's hardware** near the bottom of the page.
181
182   .. figure:: images/windows_install_5.png
183      :align: center
184
185#. Click **Next**.
186
187   .. figure:: images/windows_install_6.png
188      :align: center
189
190#. Continue with the installation.
191
192   .. figure:: images/windows_install_7.png
193      :align: center
194
195#. Verify that the system restarts.
196
197   .. figure:: images/windows_install_8.png
198      :align: center
199
200#. Configure your system when Windows completes its restart cycle.
201
202   .. figure:: images/windows_install_9.png
203      :align: center
204
205#. Verify that the Windows desktop displays after the Windows installation is complete.
206
207   .. figure:: images/windows_install_10.png
208      :align: center
209
210#. Download the `Intel DCH Graphics Driver
211   <https://downloadcenter.intel.com/download/30066?v=t>`__ in
212   Windows and install in safe mode.
213   Version 27.20.100.9030 was verified on WHL. You should use the same version as the one in native Windows 10 on your board.
214
215Boot Windows on ACRN With a Default Configuration
216=================================================
217
218#. Prepare WaaG launch script::
219
220      cp /home/acrn/work/install_win.sh  /home/acrn/work/launch_win.sh
221
222   Remove following lines in launch_win.sh
223
224   .. code-block:: bash
225
226      -s 5,ahci,cd:/home/acrn/work/Windows10.iso \
227      -s 6,ahci,cd:/home/acrn/work/winvirtio.iso \
228
229#. Launch WaaG
230
231   .. code-block:: bash
232
233      cd /home/acrn/work/
234      sudo ./launch_win.sh
235
236The WaaG desktop displays on the monitor.
237
238ACRN Windows Verified Feature List
239**********************************
240
241.. csv-table::
242   :header: "Items", "Details", "Status"
243
244    "IO Devices", "Virtio block as the boot device", "Working"
245                , "AHCI CD-ROM",                     "Working"
246                , "Virtio network",                  "Working"
247                , "Virtio input - mouse",            "Working"
248                , "Virtio input - keyboard",         "Working"
249    "GVT-d",      "GVT-d with local display",        "Working"
250    "Tools",      "WinDbg",                          "Working"
251    "Test cases", "Install Windows 10 from scratch", "OK"
252                , "Windows reboot",                  "OK"
253                , "Windows shutdown",                "OK"
254    "Built-in Apps", "Microsoft Edge",               "OK"
255                   , "Maps",                         "OK"
256                   , "Microsoft Store",              "OK"
257                   , "3D Viewer",                    "OK"
258
259Explanation for acrn-dm Popular Command Lines
260*********************************************
261
262.. note:: Use these acrn-dm command line entries according to your
263   real requirements.
264
265* ``-s 2,passthru,0/2/0``:
266  This is GVT-d to passthrough the VGA controller to Windows.
267  You may need to change 0/2/0 to match the bdf of the VGA controller on your platform.
268
269* ``-s 8,virtio-net,tap=tap0``:
270  This is for the network virtualization.
271
272* ``-s 3,virtio-input,/dev/input/event4``:
273  This is to passthrough the mouse/keyboard to Windows via virtio.
274  Change ``event4`` accordingly. Use the following command to check
275  the event node on your Service VM::
276
277   <To get the input event of mouse>
278   # cat /proc/bus/input/devices | grep mouse
279
280* ``-s 5,ahci,cd:/home/acrn/work/Windows10.iso``:
281  This is the IOS image used to install Windows 10. It appears as a CD-ROM
282  device. Make sure that it points to your win10 ISO path.
283
284* ``-s 6,ahci,cd:/home/acrn/work/winvirtio.iso``:
285  This is CD-ROM device to install the virtio Windows driver. Make sure it points to your VirtIO ISO path.
286
287* ``-s 7,passthru,0/14/0,d3hot_reset``:
288  This is to passthrough the USB controller to Windows;d3hot_reset is needed for WaaG reboot when USB controller is passthroughed to Windows.
289  You may need to change ``0/14/0`` to match the BDF of the USB controller on
290  your platform.
291
292* ``--ovmf /home/acrn/work/OVMF.fd``:
293  Make sure it points to your OVMF binary path.
294
295* ``--windows``:
296  Specify this to use the Windows ORACLE virtio device when enabling secure boot in Windows; otherwise, the REDHAT virtio device will be used.
297
298Secure Boot Enabling
299********************
300Refer to the steps in :ref:`How-to-enable-secure-boot-for-windows` for
301secure boot enabling.
302
303Activate Windows 10
304********************
305If you use a trial version of Windows 10, you might find that some
306apps and features do not work or that Windows 10 automatically gets shut
307down by the Windows licensing monitoring service. To avoid these issues,
308obtain a licensed version of Windows.
309
310For Windows 10 activation steps, refer to
311`Activate Windows 10 <https://support.microsoft.com/en-us/help/12440/windows-10-activate>`__.
312