Attention

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

Canonical® Ubuntu® Desktop RTH virtualized-mode GPOS

Note

This guide describes the installation for a Ubuntu® Linux distribution, for other Linux distributions some little adaptions might be necessary. Tested Linux kernel versions: 2.6.32, 3.10, 3.16, 4.4, 4.9, 4.14, 4.19 and 5.4

In Ubuntu GPOS it is installed as a kernel driver when the installation script is run.

The following section is applicable to:

../../_images/target6.png

Instantiate the Ubuntu® Desktop GPOS alternative

Linux is installed and meets the following requirements:

  • If the processor does not support EPT (check for ept in grep flags /proc/cpuinfo) then a 32-bit Linux with non-PAE kernel has to be used. For CentOS 6 the non-PAE kernel are available.

  • Grub2 boot loader is used

  • Headers of installed kernel are available (apt-get install kernel-devel).

  1. Hypervisor setup

    • Make sure the directory /boot/rth/ exists; if it does not, create it.

$ mkdir /boot/rth/

  1. Copy the files and folders rthx86, license.txt`, RTH MultiBoot kernel and initrd images, Linux_Linux.txt from the RTS Hypervisor Software Release Package directory Hypervisor/ to /boot/rth/.

$ cp rthx86 \
    license.txt \
    mbLinuz-5.4.59+gitAUTOINC+b8c82ba373_3747758c5c-r0-intel-corei7-64-20201125084606.bin \
    ecs-image-base-poky-rth-initramfs-intel-corei7-64-20201126164655.rootfs.cpio.gz \
    Linux_Linux.txt /boot/rth/

  1. Optionally: Replace file /boot/splash.xpm.gz by the one found in the RTS Hypervisor Software Release Package directory.

  2. Edit the GRUB configuration file (/boot/grub/custom.conf or /etc/grub.d/41_custom). Create a new entry, or copy and modify an existing one:

  • choose a title, e.g. Real-Time Hypervisor - Ubuntu 16.04 & ECI-R OS0/Ubuntu 16.04 & OS/1/ecs-base-poky.

  • copy the root setting from an existing entry (see custom.conf) to the new entry.

  • configure /boot/rth/rthx86 as kernel.

  • configure /boot/rth/license.txt and /boot/rth/Linux_Linux.txt as grub modules.

  • configure Linux kernel (vmlinuz) and ramdisk (initrd) as modules.

  • configure any other operating system images to be started by the Hypervisor as modules.

Note

Depending on your installation, it is possible that the paths already point to the /boot directory and /boot must therefore be omitted.

Your boot loader entry now should look similar to this:

  • Edit /boot/grub/custom.conf add an ECI-R multiboot grub entry :

...
menuentry "ECI-R (RTS Hypervisor) GPOS Ubuntu 16.04 Desktop and POS Preempt-RT Linux" {
    search --no-floppy --fs-uuid --set=root ae1a66a5-ee9c-4573-9249-dd207ffa6248
    multiboot2 /boot/rth/rthx86
    module2 /boot/rth/license.txt
    module2 /boot/rth/pos-rt/Linux_Linux64_nvme0n1p4.txt
    echo "Loading POS multi-boot Linux Preempt-RT bootable [OVERLAYFS] images..."
    module2 /boot/rth/pos-rt/mbLinuz mbLinuz64
    module2 /boot/rth/pos-rt/initrd-mbLinux64-no-sfs.gz initrd-mbLinux64.gz
    echo "Loading [ROOTFS] GPOS Ubuntu 16.04 Desktop bootable images ..."
    module2 /boot/vmlinuz-4.10.0-42-generic vmlinuz.lnk
    module2 /boot/initrd.img-4.10.0-42-generic initramfs.lnk
}
...

  • Edit /etc/grub.d/41_custom for custom.conf ECI-R multiboot grub entry to be appended :

#!/bin/sh
cat <<EOF
GRUB_HIDDEN_TIMEOUT=-1
GRUB_TIMEOUT=-1
if [ -f  \${config_directory}/custom.cfg ]; then
  source \${config_directory}/custom.cfg
elif [ -z "\${config_directory}" -a -f  \$prefix/custom.cfg ]; then
  source \$prefix/custom.cfg;
fi
EOF

  • Apply the changes by executing the following command:

# update-grub

Note

You may need to add insmod gzio to the menu-entry if Grub2 prints the message: “no multiboot header found”.

Note

The Hypervisor recognizes loaded modules by their names. In case of Grub1, the module name is the name of its file without preceding path (i.e., in the example above the module name for /boot/vmlinuz-2.6.32.el6 is just vmlinuz-2.6.32.el6).

Note

In contrary, Grub2 requires that the module name is specified as the argument. In the example above (for Grub2), the module name for Linux kernel will be vmlinuz, and for its RAM disk initramfs.img.

  • Edit the RTH configuration template file /boot/rth/Linux_Linux.txt.

Make sure that configured image names are identical to the module names in custom.conf. You must modify the Linux command line by changing the bootline entry in the RTH Configuration File Linux_Linux.txt.

If uncertain which bootline to set copy the command line of the installed Linux kernel from the boot loader entry (in /boot/grub/custom.conf) to Linux_Linux.txt.

Configure your Linux Kernel (vmlinuz) as image_0 ``and your ramdisk as ``image_1.

  1. Edit RTH configuration file so it look similar to the following:

# RTH CONFIG
################################################################################
# System
#
[/SYSTEM]
    "IOMMU"          = uint32: 0    # set to 1 to restrict device memory access
    "security_level" = uint32: 0    # set to 1 to restrict API permissions
    "GPU_resource_partitioning" = uint32: 1     # set to 1 to optimize
                                                # CPU resource usage
################################################################################
# OS
#
[/OS/0]
    "name"          = "Ubuntu 16.04.4 Desktop"
    "boot_priority" = uint32: 1             # start first
    "CPU"           = bytelist: 1,2         # e.g. two CPUs: bytelist: 1, 2
    "virtualized"   = uint32: 1

    "virtual_COM-to-log_port" = uint32: 0x3F8
    "trace_partition_number" = uint32: 0    # write log to /SHM/0
    [/OS/0/RUNTIME/0]

        "bootline" = "ro root=UUID=21df467d-01c6-46eb-b99b-4e72d382459d console=tty0"
        "image_0"  = "vmlinuz"
        "image_1"  = "initramfs.img"

[/OS/1]

    "name"          = "Privileged RTOS"
    "boot_priority" = uint32: 2             # start second
    "memory_size"   = uint64: 0x80000000    # 2000 MB
    "virtual_MMU"   = uint32: 1             # set to 1 to restrict memory access
    "restricted_IO" = uint32: 1             # set to 1 to restrict I/O access
    "CPU"           = bytelist: 3,4           # e.g. two CPUs: bytelist: 3, 4

    "virtual_COM-to-log_port" = uint32 : 0x3F8
    "trace_partition_number" = uint32: 1    # write log to /SHM/1

    [/OS/1/RUNTIME/0]

        "bootline" = "diskroot=/dev/hda4 ip=192.168.2.2:::::vnet0  debug=all verbose=all random.trust_cpu=on console=tty0 console=ttyS0,115200n8"
        "image_0"  = "mbLinuz64"
        "image_1"  = "initrd-mbLinux64.gz"

[/IRQ]

    "default" = uint32: 0   # default is Ubuntu

################################################################################
# PCI
#
[/PCI]
    "default" = uint32: 0   # default is Ubuntu

    "auto_interrupt_mode" = uint32: 1   # automatically use MSI to avoid conflicts

# i225 Device assignment with vendor ID / device ID and MSI Mode
[/PCI/0]
    "OS"         = uint32: 1
    "vendor_ID"  = uint32: 0x8086
    "device_ID"  = uint32: 0x15f2
    "interrupt_mode" = uint32: 2

# i210 Device assignment with vendor ID / device ID and MSI Mode to Yocto linux-rt
[/PCI/1]
    "OS"         = uint32: 1
    "vendor_ID"  = uint32: 0x8086
    "device_ID"  = uint32: 0x1533
    "interrupt_mode" = uint32: 2

...

################################################################################
# Shared Memory
#

[/SHM/0]

    "name" = "trace_ubuntu"
    "size" = uint64: 0xF000

[/SHM/1]

    "name" = "trace_1"
    "size" = uint64: 0xF000
...

################################################################################
# NVME or SATA drive
#
[/DRIVE/0]

"default"   = uint32: 0   # default is OS/0
"bus"       = uint32: 1   # 1 0 0   0x8086 0xF1A5 NVMe controller
"device"    = uint32: 0   #
"function"  = uint32: 0   #

    [/DRIVE/0/PARTITION/3]
    "OS" = uint32: 1   # assigned to OS/1
...

  • Shut down and restart PC, select the new configuration entry in boot loader menu.

Note

Optionally you can add ip=W.X.Y.Z/A.B.C.D to your bootline. Replace W.X.Y.Z with an IP address and A.B.C.D with a subnet mask that you want to assign to the vnet adapter in Linux. If you omit the ip= parameter then the default is used (see rthinitVirt)

Install RTH Linux Virtualized-mode BSP

Make sure you have kernel-headers, kernel-devel, and gcc installed.

Copy the contents of BSP/Linux/virtualized/ from the RTS Hypervisor Software Release Package to the target PC and perform the following steps:

  1. Install the rthinitVirt script:

# cp rthinitVirt /etc/init.d/
# chown root:root /etc/init.d/rthinitVirt
# chmod 750 /etc/init.d/rthinitVirt

Depending on the Linux distribution the following command configures the rthinitVirt script to automatically start on every boot:

# update-rc.d rthinitVirt defaults

If not, you have to do it manually:

# ln -sf /etc/init.d/rthinitVirt /etc/rc5.d/S99rthinitVirt
# ln -sf /etc/init.d/rthinitVirt /etc/rc5.d/K99rthinitVirt
# ln -sf /etc/init.d/rthinitVirt /etc/rc3.d/S99rthinitVirt
# ln -sf /etc/init.d/rthinitVirt /etc/rc3.d/K99rthinitVirt

  1. Set your local-time (e.g. Europe/Berlin)

# rm -f /etc/localtime
# ln -sf /usr/share/zoneinfo/Europe/Berlin /etc/localtime

  1. Install the RTH Base driver (required for the RTH user API and communication with RTH):

Note

for Debian/Ubuntu systems, set KERNEL_DIR to /usr/src/linux-headers-`uname -r`

$ tar -xvzf rthBaseDrvVirt.tar.gz
$ cd rthBaseDrvVirt
$ make KERNEL_DIR=/lib/modules/`uname -r`/build/
$ mkdir -p /boot/rth/`uname -r`/
$ cp rthBaseDrvVirt.ko /boot/rth/`uname -r`/

  1. Install the Virtual Network driver (creates a virtual network interface):

Note

WARNING: for Debian/Ubuntu systems, set KERNEL_DIR to /usr/src/linux-headers-`uname -r`

$ tar -xvzf vnetDrvVirt.tar.gz
$ cd vnetDrvVirt
$ make KERNEL_DIR=/lib/modules/`uname -r`/build/
$ mkdir -p /boot/rth/`uname -r`/
$ cp vnetDrvVirt.ko /boot/rth/`uname -r`/

  1. In order to configure the IP address and/or the subnet mask open /etc/init.d/rthinitVirt and modify the following settings:

IP_ADDRESS="192.168.2.1"
NETMASK="255.255.255.0"

#. Install the RTH library (required for the RTH user API): For 64-bit GNU/Linux:

Note

that some GNU/Linux OSs have the 64-bit libraries installed in /usr/lib64/ and others in /usr/lib/. Use the correct 64-bit library path that applies to the installed GNU/Linux OS.

# cp libRth64.so /usr/lib64
# chown root:root /usr/lib64/libRth64.so
# chmod 755 /usr/lib64/libRth64.so

#. Install rthOsCtrlTask (required for receiving OS control commands): For 64-bit GNU/Linux:

# cp rthOsCtrlTask64 /usr/bin/rthOsCtrlTask
# chown root:root /usr/bin/rthOsCtrlTask
# chmod 750 /usr/bin/rthOsCtrlTask

#. Install the readtrace command-line tool: For 64-bit GNU/Linux:

# cp readtrace64 /usr/bin/readtrace
# chgrp root /usr/bin/readtrace
# chmod 755 /usr/bin/readtrace

#. Install the rth command-line tool: For 64-bit GNU/Linux:

# cp rth64 /usr/bin/rth
# chgrp root /usr/bin/rth
# chmod 750 /usr/bin/rth

#. Install the rthtimesync tool (required if you want to query timesync state or change timesync roles from the command line): For 64-bit GNU/Linux:

# cp rthtimesync64 /usr/bin/rthtimesync
# chgrp root /usr/bin/rthtimesync
# chmod 750 /usr/bin/rthtimesync

  1. If Linux already runs on top of the RTS Hypervisor the drivers may now be started:

# /etc/init.d/rthinitVirt start

Use ip link to check if the virtual network interface is active. If another OS with successfully set up Virtual Network is running you should be able to ping it or create a ssh or telnet connection.

For further details about configuring and assigning CPUs and devices to operating systems Please refer to the user documentation _Real-Time Hypervisor – Product Description and User’s Guide_