Watchdog Virtualization in Device Model

This document describes the watchdog virtualization implementation in ACRN device model.

Overview

A watchdog is an important hardware component in embedded systems, used to monitor the system’s running status, and resets the processor if the software crashes. In general, hardware watchdogs rely on a piece of software running on the machine which must “kick” the watchdog device regularly, say every 10 seconds. If the watchdog doesn’t get “kicked” after 60 seconds, for example, then the watchdog device asserts the RESET line which results in a hard reboot.

For ACRN we emulate the watchdog hardware in the Intel 6300ESB chipset as a PCI device called 6300ESB watchdog and is added into the Device Model following the PCI device framework. The following Figure 209 shows the watchdog device workflow:

../../_images/watchdog-image2.png

Figure 209 Watchdog device flow

The DM in the Service VM treats the watchdog as a passive device. It receives read/write commands from the watchdog driver, does the actions, and returns. In ACRN, the commands are from User VM watchdog driver.

User VM watchdog work flow

When the User VM does a read or write operation on the watchdog device’s registers or memory space (Port IO or Memory map I/O), it will trap into the hypervisor. The hypervisor delivers the operation to the Service VM/DM through IPI (inter-process interrupt) or shared memory, and the DM dispatches the operation to the watchdog emulation code.

After the DM watchdog finishes emulating the read or write operation, it then calls ioctl to the Service VM/kernel (/dev/acrn_vhm). VHM will call a hypercall to trap into the hypervisor to tell it the operation is done, and the hypervisor will set User VM-related VCPU registers and resume the User VM so the User VM watchdog driver will get the return values (or return status). The Figure 210 below is a typical operation flow: from a User VM to the Service VM and return back:

../../_images/watchdog-image1.png

Figure 210 Watchdog operation workflow

Implementation in ACRN and how to use it

In ACRN, the Intel 6300ESB watchdog device emulation is added into the DM PCI device tree. Its interface structure is (see devicemodel/include/pci_core.h):

struct pci_vdev_ops pci_ops_wdt = {
   .class_name     = "wdt-i6300esb",
   .vdev_init      = pci_wdt_init,
   .vdev_deinit    = pci_wdt_deinit,
   .vdev_cfgwrite  = pci_wdt_cfg_write,
   .vdev_cfgread   = pci_wdt_cfg_read,
   .vdev_barwrite  = pci_wdt_bar_write,
   .vdev_barread   = pci_wdt_bar_read
};

All functions follow the pci_vdev_ops definitions for PCI device emulation.

The main part in the watchdog emulation is the timer thread. It emulates the watchdog device timeout management. When it gets the kick action from the User VM, it resets the timer. If the timer expires before getting a timely kick action, it will call DM API to reboot that User VM.

In the User VM launch script, add: -s xx,wdt-i6300esb into DM parameters. (xx is the virtual PCI BDF number as with other PCI devices)

Make sure the User VM kernel has the I6300ESB driver enabled: CONFIG_I6300ESB_WDT=y. After the User VM boots up, the watchdog device will be created as node /dev/watchdog, and can be used as a normal device file.

Usually the User VM needs a watchdog service (daemon) to run in userland and kick the watchdog periodically. If something prevents the daemon from kicking the watchdog, for example the User VM system is hung, the watchdog will timeout and the DM will reboot the User VM.