diff --git a/doc/develop.rst b/doc/develop.rst index 51d37536b..42a727c96 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -43,6 +43,7 @@ User VM Tutorials tutorials/using_zephyr_as_uos tutorials/running_deb_as_user_vm tutorials/running_ubun_as_user_vm + tutorials/using_xenomai_as_uos Enable ACRN Features ******************** diff --git a/doc/tutorials/using_xenomai_as_uos.rst b/doc/tutorials/using_xenomai_as_uos.rst new file mode 100644 index 000000000..82c396dc6 --- /dev/null +++ b/doc/tutorials/using_xenomai_as_uos.rst @@ -0,0 +1,97 @@ +.. _using_xenomai_as_uos: + +Using Xenomai as User OS (Real-Time VM) +####################################### + +`Xenomai`_ is a real-time development framework cooperating with the Linux kernel, to provide a pervasive, interface-agnostic, hard real-time support to user space applications, seamlessly integrated into the Linux environment. + +This tutorial describes how to run Xenomai as the User OS(Real-Time VM) on the ACRN hypervisor. + +.. _Xenomai: https://gitlab.denx.de/Xenomai/xenomai/-/wikis/home + +Build Xenomai kernel +******************** + +#. Clone Xenomai kernel souce code:: + + $ git clone -b F/4.19.59/base/ipipe/xenomai_3.1 https://github.com/intel/linux-stable-xenomai + +#. Enter the directory and select default ACRN configuration:: + + $ cd linux-stable-xenomai && make acrn_defconfig + +#. Then just start building the kernel:: + + $ make targz-pkg + +#. Upon building completion, you will see a tarball containing kernel and its modules. + + .. code-block:: none + :emphasize-lines: 22 + + $ ls -l + total 97944 + drwxr-xr-x 27 tw tw 4096 Feb 20 10:23 arch + drwxr-xr-x 3 tw tw 12288 Feb 21 11:01 block + -rw-r--r-- 1 tw tw 789264 Feb 25 16:17 built-in.a + drwxr-xr-x 2 tw tw 4096 Feb 21 11:01 certs + -rw-r--r-- 1 tw tw 423 Feb 20 10:17 COPYING + -rw-r--r-- 1 tw tw 98741 Feb 20 10:17 CREDITS + drwxr-xr-x 4 tw tw 12288 Feb 21 11:01 crypto + drwxr-xr-x 120 tw tw 12288 Feb 20 10:17 Documentation + drwxr-xr-x 143 tw tw 4096 Feb 21 10:48 drivers + drwxr-xr-x 2 tw tw 4096 Feb 20 10:21 firmware + drwxr-xr-x 73 tw tw 12288 Feb 21 11:01 fs + drwxr-xr-x 32 tw tw 4096 Feb 20 10:19 include + drwxr-xr-x 2 tw tw 4096 Feb 25 16:25 init + drwxr-xr-x 2 tw tw 4096 Feb 21 11:01 ipc + -rw-r--r-- 1 tw tw 2245 Feb 20 10:17 Kbuild + -rw-r--r-- 1 tw tw 563 Feb 20 10:17 Kconfig + drwxr-xr-x 20 tw tw 12288 Feb 25 16:17 kernel + drwxr-xr-x 13 tw tw 20480 Feb 21 11:01 lib + drwxr-xr-x 5 tw tw 4096 Feb 20 10:17 LICENSES + -rw-r--r-- 1 tw tw 17572590 Feb 25 16:17 linux-4.19.59-xenomai-3.1-acrn+-x86.tar.gz + ... + +Launch RTVM +*********** + +#. Prepare a dedicated disk (NVMe or SATA) for RTVM, here we suppose it's ``/dev/sda``. First download the Preempt-RT VM image: + + $ wget https://github.com/projectacrn/acrn-hypervisor/releases/download/acrn-2020w01.1-140000p/preempt-rt-32030.img.xz + +#. Decompress the xz image: + + $ xz -d preempt-rt-32030.img.xz + +#. Burn the Preempt-RT VM image onto the SATA disk: + + $ sudo dd if=preempt-rt-32030.img of=/dev/sda bs=4M oflag=sync status=progress iflag=fullblock seek=0 conv=notrunc + +#. Then you can launch RTVM via our script. We need to tell it where the root partition (here we suppose it's sda3) and kernel tarball are:: + + $ 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 + +#. If everything works, you will see a login prompt:: + + ... + [ OK ] Started Permit User Sessions. + [ OK ] Started Getty on tty1. + [ OK ] Started Serial Getty on hvc0. + [ OK ] Reached target Login Prompts. + [ OK ] Started Network Manager Script Dispatcher Service. + [ OK ] Started Proxy AutoConfig runner service. + [ OK ] Started Login Service. + [ OK ] Reached target Multi-User System. + [ OK ] Reached target Graphical Interface. + + clr-c1ff5bba8c3145ac8478e8e1f96e1087 login: + + +Installing the Xenomai libraries and tools +****************************************** + +To use some Xenomai tools or its libraries, please follow the `official document +`__ +to build and install them in RTVM. Please note that the according version is Xenomai-3.1 with +4.19.59 kernel.