4. Hypervisor Guests - General

The RTOSVisor supports two different kind 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 uses 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 the /hv/guests/examples folder. New guests can be created based on template files stored in /hv/templates. It is not recommended to create new guest folders manually, for this purpose the graphical System Manager tool shall be used.

Caution

The example guests share some configuration files with System Manager configured guests. This may lead to inconsistencies if the System Manager was used to configure guests before. In such case, before starting one of the example guests again, the configuration has to be reset. Run the following steps to do so:

hv_resethv
sudo reboot

The hv_resethv command will backup the existing /hv/config and /hv/guests/examples folder and reset then to the initial content. See also Reset Hypervisor Initialization for more details.

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

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

4.4. Example guest folders

All pre-configured guests are stored in the /hv/guests/examples folder. A configuration to run one single RTOS in conjunction with one Windows and/or one Ubuntu guest folder is supported. The hypervisor configuration file hv.config is located in the respective guest folder and used for the global hypervisor configuration.

Hint

If the System Manger tool is used to configure guests, the hypervisor configuration stored in /hv/config/hv.config is used instead.

Hint

In case the example Windows or Ubuntu guest is started before starting an RTOS guest, the hv.config file in the Windows or Ubuntu guest is used. By default, the hv.config file located in the Windows or Ubuntu example guest is a link to the hv.config file of the RT-Linux example guest. If another example RTOS guest shall be used, this link needs to be adjusted. For example, if the example VxWorks guest shall be used together with the example Windows or Ubuntu guest, proceed as follows:

cd /hv/guests/examples/windows
rm hv.config
ln -s /hv/guests/examples/vxworks/hv.config hv.config
cd /hv/guests/examples/ubuntu
rm hv.config
ln -s /hv/guests/examples/vxworks/hv.config hv.config

4.5. Guest operation

To operate with a specific guest, you need to switch into the guest folder first. The following shows how to select the shipped Real-time Linux example guest.

cd /hv/guests/examples/rt-linux

The following operations are supported to operate with guests:

  • hv_vmf_start [config_file]: Load the VMF and the hypervisor configuration. If not 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.