Hypervisor Configuration

The prplHypervisor™ is configured through text files (cfg). During the compilation, the cfg file is read and interpreted to generate the config.h header in the platform folder. The prpl-hypervisor/platform//cfg folder has some configuration file samples. The cfg files are organized in two main groups: system and virtual_machines. The system group contains system-wide configurations, while the virtual_machines group contains the configurations of each VM. The properties of each group are specified below.

Description of the System Group

Propriety	Type	Description	Valid Range
debug	Array of strings	Optional list of defines for output messages for debug purposes.	WARNINGS, INFOS, and ERRORS.
uart_speed	integer	Console UART baudrate.	115200, 57600 and 9600. Other baud rates may be used.
scheduler_quantum_ms	integer	Timer interval in milliseconds for the hypervisor scheduler timer.	Positive integers.
guest_quantum_ms	integer	Interval in milliseconds for the virtual timer interrupt injection in guests.	Positive integers greater than or equal to 3.

Example of a valid system configuration

system = {
   debug =  [ "WARNINGS", "INFOS", "ERRORS"];
   uart_speed = 115200;
   scheduler_quantum_ms = 10;
   guest_quantum_ms = 1;
};

The scheduler_quantum_ms property determines the interval between guests' context switching in milliseconds. Thus, a value of 10 means that a guest will perform during 10ms before being preempted. Because the pic32mz does not implement the interrupt pass-through feature, timer interrupts cannot be directly handled by the guests. To emulate guest timer interrupts the hypervisor injects virtual interrupts on the guests in intervals of guest_quantum_ms (in milliseconds).

Description of the Virtual Machines Group

Property	Type	Description	Valid Range
app_name	string	Name of the bare-metal application directory.	Any valid bare-metal app directory name.
os_type	string	Type of the virtualized OS.	BARE_METAL
priority	integer	Round-robin scheduler priority.	From 0 to 255.
RAM_size_bytes	string	Size of the VM's RAM.	MEM_SIZE_32KB, MEM_SIZE_64KB, MEM_SIZE_128KB, MEM_SIZE_256KB.
flash_size_bytes	string	Size of the VM's FLASH.	MEM_SIZE_32KB, MEM_SIZE_64KB, MEM_SIZE_128KB, MEM_SIZE_256KB, MEM_SIZE_512KB, MEM_SIZE_1MB.
fast_interrupts	Array of strings	List of associated interrupts. Allows the hypervisor to quickly deliver an interrupt to a VM.	IRQ_ETH
device_mapping	Array of strings	List of associated devices for virtualized I/O.	PORTA through PORTK, UART1 through UART6, SPI1 through SP6, PM and AD1.
interrupt_redirect	Array of strings	List of interrupts to redirect to the guest.	All possible IRQs. For example, IRQ_U2RX. See the complete list in pic32mz.h file.
memory_maps	Array of properties	Indicate the VM's memory mapping.	Not applicable.
memory_maps.base_addr	integer	Memory mapping base address	Any virtual address
memory_maps.page_size	string	Memory mapping size	MEM_SIZE_4KB, MEM_SIZE_8KB, MEM_SIZE_16KB, MEM_SIZE_32KB, MEM_SIZE_64KB, MEM_SIZE_128KB, MEM_SIZE_256KB, MEM_SIZE_512KB, MEM_SIZE_1MB.

Example of a valid virtual_machines configuration

The ping VM has 32KB of SRAM, 64KB of FLASH access to PORTH, and UART2 through the virtualized I/O. The pong VM has 32KB of SRAM and FLASH, access to UART2 through virtualized I/O, and a 4KB page mapped for direct peripheral access on base address 0xbf860000.

virtual_machines = (
    { 
        app_name = "ping";
        os_type = "BARE_METAL";
        priority = 100;
        RAM_size_bytes = "MEM_SIZE_32KB";
        flash_size_bytes = "MEM_SIZE_64KB";
        device_mapping = [ "UART2", "PORTH" ];
    },
    { 
        app_name = "pong";
        os_type = "BARE_METAL";
        priority = 100;
        RAM_size_bytes = "MEM_SIZE_32KB";
        flash_size_bytes = "MEM_SIZE_32KB";
        device_mapping = [ "UART2" ];
        memory_maps = ({
               base_addr = 0xbf860000;
               page_size = "MEM_SIZE_4KB";
           })
    }
);

memory_maps versus device_mapping

The property memory_maps is an array of memory addresses and sizes that allows memory areas to be directly mapped. It is useful when low virtualization overhead is desired, since a guest can have direct access to one or more peripherals. However, it is impossible to separate peripherals that are in the same virtual memory page, like the UARTs in the PIC32MZ. For example, it is not possible to map UART1 to guest 1 and UART2 to guest 2 using direct memory mapping and still keep them separated. In this case, the virtualized I/O is preferable.

Use the device_mapping property to allow guests to have access to specific peripherals. device_mapping makes it possible to map UART1 to guest 1 and UART2 to guest 2 and still keep them completely separate. Because the hypervisor knows the space address of each peripheral, it can control guests’ access to the hardware. When using the virtualized I/O, the guest must use read()/write() hypercalls to access the peripherals. See the Virtualized I/O section.

interrupt_redirect property

The PIC32MZ processor does not implement the interrupt pass-through feature, making it impossible for a guest to handle an interrupt without hypervisor intervention. The prplHypervisor implements interrupt redirection to the guests using the interrupt_redirect property. The interrupts associated with the guest must be indicated in this property. The hypervisor enables the associated interrupts and injects virtual interrupts into the guests when necessary.

This feature is especially useful when implementing device drivers at the guest level, since it allows for the guest to receive events generated by the hardware controllers. See the Virtualized I/O section.