1.. _using_vxworks_as_uos:
2.. _using_vxworks_as_user_vm:
3
4Run VxWorks as the User RTVM OS
5###############################
6
7`VxWorks`_\* is a real-time proprietary OS designed for use in embedded systems requiring real-time, deterministic
8performance. This tutorial describes how to run VxWorks as the User VM on the ACRN hypervisor
9based on Ubuntu Service VM (ACRN tag v2.0).
10
11.. note:: You'll need to be a Wind River* customer and have purchased VxWorks to follow this tutorial.
12
13Steps for Using VxWorks as User VM
14**********************************
15
16#. Build VxWorks
17
18   Follow the `VxWorks Getting Started Guide <https://docs.windriver.com/bundle/vxworks_7_tutorial_kernel_application_workbench_sr0610/page/rbu1422461642318.html>`_
19   to set up the VxWorks development environment and build the VxWorks Image.
20
21   .. note::
22      The following kernel configuration should be **excluded**:
23        * INCLUDE_PC_CONSOLE
24        * DRV_SIO_PCI_NS16550
25        * SELECT_PC_CONSOLE_KBD
26
27      The following kernel configuration should be **included**:
28        * DRV_SIO_IA_NS16550
29        * DRV_SIO_FDT_NS16550
30
31      The following kernel configuration value should be **set**:
32        * CONSOLE_BAUD_RATE = 115200
33        * SYS_CLK_RATE_MAX = 1000
34
35#. Build GRUB2 bootloader Image
36
37   We use grub-2.02 as the bootloader of VxWorks in this tutorial; other versions may also work.
38
39   .. code-block:: none
40
41      $ curl ftp://ftp.gnu.org/gnu/grub/grub-2.02.tar.xz | tar xJv
42      $ cd grub-2.02
43      $ ./autogen.sh
44      $ ./configure --with-platform=efi --target=x86_64
45      $ make
46      $ ./grub-mkimage -p /EFI/BOOT -d ./grub-core/ -O x86_64-efi -o grub_x86_64.efi \
47            boot efifwsetup efi_gop efinet efi_uga lsefimmap lsefi lsefisystab \
48            exfat fat multiboot2 multiboot terminal part_msdos part_gpt normal \
49            all_video aout configfile echo file fixvideo fshelp gfxterm gfxmenu \
50            gfxterm_background gfxterm_menu legacycfg video_bochs video_cirrus \
51            video_colors video_fb videoinfo video net tftp
52
53   This will build a ``grub_x86_64.efi`` image in the current directory.
54
55#. Preparing the Boot Device
56
57   .. code-block:: none
58
59      $ dd if=/dev/zero of=VxWorks.img bs=1M count=35
60      $ mkfs.vfat -F 32 VxWorks.img
61      $ sudo mount `sudo losetup -f -P --show VxWorks.img` /mnt
62
63   Create the following directories.
64
65   .. code-block:: none
66
67      $ sudo mkdir -p /mnt/efi/boot
68      $ sudo mkdir -p /mnt/kernel
69
70   Copy ``vxWorks`` and ``grub_x86_64.efi``.
71
72   .. code-block:: none
73
74      $ sudo cp vxWorks /mnt/kernel/
75      $ sudo cp grub-2.02/grub_x86_64.efi /mnt/efi/boot/bootx64.efi
76
77   Create ``/mnt/efi/boot/grub.cfg`` containing the following:
78
79   .. code-block:: none
80
81      set default=0
82      set timeout=5
83
84      menuentry "VxWorks Guest" {
85          multiboot /kernel/vxWorks
86      }
87
88   Unmount the loopback device:
89
90   .. code-block:: none
91
92      $ sudo umount /mnt
93
94   You now have a virtual disk image with bootable VxWorks in ``VxWorks.img``.
95
96#. Follow :ref:`gsg` to boot the ACRN Service VM.
97
98
99#. Boot VxWorks as User VM.
100
101   On the ACRN Service VM, prepare a directory and populate it with VxWorks files.
102
103   .. code-block:: none
104
105      $ mkdir vxworks && cd vxworks
106      $ cp /usr/share/acrn/samples/nuc/launch_vxworks.sh .
107
108   You will also need to copy the ``VxWorks.img`` created in the VxWorks build environment into directory
109   ``vxworks`` (via, e.g. a USB drive or network).
110
111   Run the ``launch_vxworks.sh`` script to launch VxWorks as the User VM.
112
113   .. code-block:: none
114
115      $ sudo ./launch_vxworks.sh
116
117   Then VxWorks will boot automatically. You will see the prompt.
118
119   .. code-block:: console
120
121                     VxWorks 7 SMP 64-bit
122
123      Copyright 1984-2019 Wind River Systems, Inc.
124
125            Core Kernel version: 1.2.7.0
126                     Build date: May  5 2019 21:40:28
127                          Board: x86 Processor (ACPI_BOOT_OP) SMP/SMT
128                      CPU Count: 1
129                 OS Memory Size: ~1982MB
130               ED&R Policy Mode: Permanently Deployed
131
132      Adding 9315 symbols for standalone.
133
134      ->
135
136   Finally, you can type ``help`` to see available VxWorks commands.
137
138   .. code-block:: console
139
140      -> help
141
142      help                           Print this list
143      dbgHelp                        Print debugger help info
144      edrHelp                        Print ED&R help info
145      ioHelp                         Print I/O utilities help info
146      nfsHelp                        Print nfs help info
147      netHelp                        Print network help info
148      rtpHelp                        Print process help info
149      spyHelp                        Print task histogrammer help info
150      timexHelp                      Print execution timer help info
151      h         [n]                  Print (or set) shell history
152      i         [task]               Summary of tasks' TCBs
153      ti        task                 Complete info on TCB for task
154      sp        adr,args...          Spawn a task, pri=100, opt=0x19, stk=20000
155      taskSpawn name,pri,opt,stk,adr,args... Spawn a task
156      tip       "dev=device1#tag=tagStr1", "dev=device2#tag=tagStr2", ...
157                                     Connect to one or multiple serial lines
158      td        task                 Delete a task
159      ts        task                 Suspend a task
160      tr        task                 Resume a task
161
162      Type <CR> to continue, Q<CR> or q<CR> to stop:
163
164.. _VxWorks: https://www.windriver.com/products/vxworks/
165