HVM timeoffsets

Time(zone) support for Windows guests

Introduction

This is a breif overview of the components involved in telling the time to Windows HVM guests with PV drivers.

Overview

Windows handles all time localisation by setting its hardware clock rather than keeping hold of and using an offset on the RTC. So if you change the time, Windows will update the RTC. The same is true if you change timezone.

Although QEMU is used for the device model, the RTC is emulated by Xen directly. However, since Xen does not interact with XenStore, QEMU does play a part in communicating the timeoffset to the toolstack so it can be persisted.

The timeoffset for the VM is stored in XenStore at /vm/<uuid>/rtc/timeoffset.

VM start of day

1. xapi: receives VM.start API call
   1. xapi: Create domain via libxc (xc_domain_create)
   2. xapi: write timeoffset from VM record to XenStore (Domain.build_hvm)
   3. xapi: start qemu (Device.Dm.start)
      1. qemu: read timeoffset from XenStore (xen_init_fv)
      2. qemu: update domain time via libxc (xc_domain_set_time_offset)

Handling in-guest clock changes

1. guest: Set clock within guest (e.g. change timezone)
   1. xen: Handle write to hardware clock (rtc_ioport_write)
   2. xen: signal qemu via the timeoffset ioreq
      1. qemu: update cached timeoffset (__handle_io_req)
      2. qemu: write the value to XenStore (privsep_set_rtc_timeoffset)

Suspend/resume

This has the added complication that, along with the the same steps in #VM tart of day the Windows guest agent comes into play. This is because Windows wouldn't bother to read the time again from the RTC without provokation. The guest agent makes a hypercall to read XenTime and compares this with the guest's localtime and makes adjustments where necessary, setting the RTC through the Win32 API.

Care has now been taken to stop the .NET libraries caching the localisation settings which has caused problems with handling timezones across suspend/resume/migrate since the update of the RTC will trigger the steps in #Handling in-guest clock changes