diff --git a/doc/developer-guides/images/watchdog-image1.png b/doc/developer-guides/images/watchdog-image1.png new file mode 100644 index 000000000..3887f3430 Binary files /dev/null and b/doc/developer-guides/images/watchdog-image1.png differ diff --git a/doc/developer-guides/images/watchdog-image2.png b/doc/developer-guides/images/watchdog-image2.png new file mode 100644 index 000000000..b8f777756 Binary files /dev/null and b/doc/developer-guides/images/watchdog-image2.png differ diff --git a/doc/developer-guides/index.rst b/doc/developer-guides/index.rst index 11c8d8540..6f02567bb 100644 --- a/doc/developer-guides/index.rst +++ b/doc/developer-guides/index.rst @@ -28,6 +28,7 @@ specific areas within the ACRN hypervisor system. APL_GVT-g-hld.rst GVT-g-porting.rst security-hld.rst + watchdog-hld.rst Contributing to the project *************************** diff --git a/doc/developer-guides/watchdog-hld.rst b/doc/developer-guides/watchdog-hld.rst new file mode 100644 index 000000000..be03b6253 --- /dev/null +++ b/doc/developer-guides/watchdog-hld.rst @@ -0,0 +1,98 @@ +.. _watchdog-hld: + +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 +:numref:`watchdog-device` shows the watchdog device workflow: + +.. figure:: images/watchdog-image2.png + :align: center + :width: 900px + :name: watchdog-device + + Watchdog device flow + +The DM in the Service OS (SOS) 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 OS (UOS) +watchdog driver. + +UOS watchdog work flow +********************** + +When the UOS 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 SOS/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 SOS/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 UOS-related VCPU registers and resume UOS so the +UOS watchdog driver will get the return values (or return status). The +:numref:`watchdog-workflow` below is a typical operation flow: +from UOS to SOS and return back: + +.. figure:: images/watchdog-image1.png + :align: center + :width: 900px + :name: watchdog-workflow + + 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``): + +.. code-block:: c + + 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 UOS, it resets the timer. If the timer expires before getting a +timely kick action, it will call DM API to reboot that UOS. + +In the UOS 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 UOS kernel has the I6300ESB driver enabled: ``CONFIG_I6300ESB_WDT=y``. After the UOS +boots up, the watchdog device will be created as node ``/dev/watchdog``, +and can be used as a normal device file. + +Usually the UOS 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 UOS system is hung, the watchdog +will timeout and the DM will reboot the UOS.