4. Hypervisor Guests - General

The RTOSVisor supports two different kinds of guest operating systems.

  • Unmodified, non Real-time operating systems, for example Windows 10 or Ubuntu 22.04. These guests run in a virtual machine under control of the KVM hypervisor technology.

  • Para-virtualized Real-time operating systems (RTOS), for example Real-time Linux. These guests use the Virtual Machine Framework (VMF) paravirtualization and run bare metal on the physical hardware.

A single guest is located in its respective guest folder.

4.1. Example guests

Some pre-configured guests are provided in RTOSVisor for test (see Example guest folders). It is not recommended to create new guest folders manually, for this purpose the graphical System Manager tool shall be used.

4.2. Guest filesystem access

The Hypervisor Host provides access to its filesystem (located on a physical hard disk or SSD) to guests. By default the /hv/guests folder is exposed to all guests.

4.3. General guest folder content

All guest folders contain the following files.

  • guest_config.sh: the main guest configuration script, you must not change this file

  • usr_guest_config.sh: user specific guest configuration script

  • guest.config: guest specific configuration, you must not change this file

  • usr.config: user specific guest configuration

  • vm_shutdown_hook.sh: guest shutdown hook

Additional configuration files may exist depending on the guest type and operation mode.

4.4. Example guest folders

Initially there are no example guest folders on the Hypervisor Host. If you would like to switch to an example guest you have to call the depending initialization. There are several different example guest configurations you can choose:

  • rt-linux : RT-Linux guest in /hv/guests/guestrtlinux

  • rtos-32 : On Time RTOS-32 in /hv/guests/guestrtos32

  • vxworks : VxWorks in /hv/guests/guestvxworks

  • windows_rtlinux : windows in /hv/guests/guestwindows and RT-Linux guest in /hv/guests/guestrtlinux

  • ubunutu_rtlinux : Ubuntu in /hv/guests/guestubuntu and RT-Linux guest in /hv/guests/guestrtlinux

Initialize the desired example with the commands hv_open_example, hv_sync_example and the name of the configuration. To load RT-Linux you can call

hv_open_example rt-linux
hv_sync_example rt-linux
cd /hv/guests/guestrtlinux

Caution

When the example guests are initialized, the corresponding pre-configured System Manager projects will be loaded. This process will delete any existing guests, subject to your confirmation. You can preserve your current configuration by using the System Manager to save it before initializing an example. Ensure you also save any manually added content in the /hv/guests/guestxxxx folders, as these will be deleted as well.

Each configuration is designed to operate a single RTOS. Both the Windows and Ubuntu configurations are capable of running RT-Linux simultaneously.

The Windows and Ubuntu guests are initialized without an installed operating system. For installation, the guest expects a suitable installation file in .iso format with the following name upon startup:

  • Windows guest - /hv/iso/windows.iso.

  • Ubuntu guest - /hv/iso/ubuntu.iso.

A detailed description how to transfer the .iso file can be found in the according Guest Guides.

During the installation of Windows or Ubuntu example guests, disk image files are generated in:

  • Windows guest - /hv/VMs/example_win/windows.qcow2

  • Ubuntu guest - /hv/VMs/example_ubuntu/ubuntu.qcow2

Caution

If in your own projects no Disk Image File is specified, then the image will be created in the Guest-Folder, and if the guest is deleted, the image and thus the entire installation and all settings in the Windows or Ubuntu guest will also be deleted.

Hint

The hypervisor uses the configuration stored in /hv/config/hv.config. This file is read and written by the System Manager configuration tool. Editing this file manually is not recommended.

4.5. Guest operation

To operate with a specific guest, you need to initialize the desired example configuration as described in Example guest folders. Then switch into the guest folder first. The following shows how to select the shipped Real-time Linux example guest.

hv_open_example rt-linux
hv_sync_example rt-linux
cd /hv/guests/guestrtlinux

The following operations are supported to operate with guests:

  • hv_vmf_start [config_file]: Load the VMF and the hypervisor configuration. If no configuration file is given, the one in the current guest folder is used.

  • hv_vmf_is_loaded: Returns information if the VMF is loaded

  • hv_vmf_stop: Stop all RTOS guests and unload VMF. It is not recommended to use this command while guests are running.

  • hv_guest_start [-view]: Boot a currently powered off guest. The -view option will automatically open the console to interact with the guest.

  • hv_guest_restart [-view]: Reboot a guest without reloading the Hypervisor configuration (only supported for RTOS guests).

  • hv_guest_console: Open the console to interact with the guest. The console for RTOS guests is a shell like interface, the console for KVM guests typically is the guest desktop.

  • hv_guest_stop: Stop the guest.

Caution

Only one debug console windows for each RTOS guest is supported. If multiple console windows are opened, the behavior is undefined.