1.. _using_xenomai_as_uos:
2.. _using_xenomai_as_user_vm:
3
4Run Xenomai as the User RTVM OS
5###############################
6
7`Xenomai`_ is a versatile real-time framework that provides support to user space applications that are seamlessly integrated into Linux environments.
8
9This tutorial describes how to run Xenomai as the User VM OS (real-time VM) on the ACRN hypervisor.
10
11.. _Xenomai: https://gitlab.denx.de/Xenomai/xenomai/-/wikis/home
12
13Build the Xenomai Kernel
14************************
15
16Follow these instructions to build the Xenomai kernel:
17
18#. Clone the Xenomai kernel source code::
19
20	$ git clone -b F/4.19.59/base/ipipe/xenomai_3.1 https://github.com/intel/linux-stable-xenomai
21
22#. Go to the directory and select the default ACRN configuration::
23
24	$ cd linux-stable-xenomai && make acrn_defconfig
25
26#. Build the kernel::
27
28	$ make targz-pkg
29
30Upon building completion, verify that you see a tarball that contains the kernel and its modules.
31
32   .. code-block:: none
33      :emphasize-lines: 22
34
35      $ ls -l
36      total 97944
37      drwxr-xr-x  27 tw tw     4096 Feb 20 10:23 arch
38      drwxr-xr-x   3 tw tw    12288 Feb 21 11:01 block
39      -rw-r--r--   1 tw tw   789264 Feb 25 16:17 built-in.a
40      drwxr-xr-x   2 tw tw     4096 Feb 21 11:01 certs
41      -rw-r--r--   1 tw tw      423 Feb 20 10:17 COPYING
42      -rw-r--r--   1 tw tw    98741 Feb 20 10:17 CREDITS
43      drwxr-xr-x   4 tw tw    12288 Feb 21 11:01 crypto
44      drwxr-xr-x 120 tw tw    12288 Feb 20 10:17 Documentation
45      drwxr-xr-x 143 tw tw     4096 Feb 21 10:48 drivers
46      drwxr-xr-x   2 tw tw     4096 Feb 20 10:21 firmware
47      drwxr-xr-x  73 tw tw    12288 Feb 21 11:01 fs
48      drwxr-xr-x  32 tw tw     4096 Feb 20 10:19 include
49      drwxr-xr-x   2 tw tw     4096 Feb 25 16:25 init
50      drwxr-xr-x   2 tw tw     4096 Feb 21 11:01 ipc
51      -rw-r--r--   1 tw tw     2245 Feb 20 10:17 Kbuild
52      -rw-r--r--   1 tw tw      563 Feb 20 10:17 Kconfig
53      drwxr-xr-x  20 tw tw    12288 Feb 25 16:17 kernel
54      drwxr-xr-x  13 tw tw    20480 Feb 21 11:01 lib
55      drwxr-xr-x   5 tw tw     4096 Feb 20 10:17 LICENSES
56      -rw-r--r--   1 tw tw 17572590 Feb 25 16:17 linux-4.19.59-xenomai-3.1-acrn+-x86.tar.gz
57      ...
58
59Launch the RTVM
60***************
61
62#. Prepare a dedicated disk (NVMe or SATA) for the RTVM; in this example, we use ``/dev/sda``.
63
64   a. Download the Preempt-RT VM image::
65
66      $ wget https://github.com/projectacrn/acrn-hypervisor/releases/download/acrn-2020w01.1-140000p/preempt-rt-32030.img.xz
67
68   #. Decompress the ``image.xz`` image::
69
70      $ xz -d preempt-rt-32030.img.xz
71
72   #. Burn the Preempt-RT VM image onto the SATA disk::
73
74      $ sudo dd if=preempt-rt-32030.img of=/dev/sda bs=4M oflag=sync status=progress iflag=fullblock seek=0 conv=notrunc
75
76#. Launch the RTVM via our script. Indicate the location of the root partition (sda3 in our example) and the kernel tarball::
77
78   $ sudo /usr/share/acrn/samples/nuc/launch_xenomai.sh -b /dev/sda3 -k /path/to/linux-4.19.59-xenomai-3.1-acrn+-x86.tar.gz
79
80#. Verify that a login prompt displays::
81
82    ...
83    [  OK  ] Started Permit User Sessions.
84    [  OK  ] Started Getty on tty1.
85    [  OK  ] Started Serial Getty on hvc0.
86    [  OK  ] Reached target Login Prompts.
87    [  OK  ] Started Network Manager Script Dispatcher Service.
88    [  OK  ] Started Proxy AutoConfig runner service.
89    [  OK  ] Started Login Service.
90    [  OK  ] Reached target Multi-User System.
91    [  OK  ] Reached target Graphical Interface.
92
93    clr-c1ff5bba8c3145ac8478e8e1f96e1087 login:
94
95
96Install the Xenomai Libraries and Tools
97***************************************
98
99To build and install Xenomai tools or its libraries in the RVTM, refer to the official
100`Xenomai documentation <https://gitlab.denx.de/Xenomai/xenomai/-/wikis/Installing_Xenomai_3#library-install>`_.
101Note that the current supported version is Xenomai-3.1 with the 4.19.59 kernel.
102