⚠ This page is served via a proxy. Original site: https://github.com
This service does not collect credentials or authentication data.
Skip to content

Conversation

@simongdavies
Copy link
Contributor

Hyperlight guests can now read time without expensive VM exits by using a paravirtualized clock shared between host and guest. This enables high-frequency timing operations like benchmarking, rate limiting, and timestamping with minimal overhead.

Paravirtualized clocks work by having the hypervisor populate a shared memory page with clock calibration data. The guest reads this data along with the CPU's TSC to compute the current time entirely in userspace, avoiding the cost of a VM exit.

Reference: https://docs.kernel.org/virt/kvm/x86/msr.html#pvclock

The implementation uses the native mechanism for each hypervisor:

  • KVM: pvclock (MSR 0x4b564d01)
  • MSHV: Hyper-V Reference TSC page
  • WHP: Hyper-V Reference TSC page

Guests have access to:

  • Monotonic time: nanoseconds since sandbox creation, guaranteed to never go backwards
  • Wall-clock time: UTC nanoseconds since Unix epoch
  • Local time: wall-clock adjusted for host timezone captured at sandbox creation

Rust API (hyperlight_guest_bin::time):

  • SystemTime/Instant types mirroring std::time
  • DateTime type for human-readable date/time formatting
  • Weekday/Month enums with name() and short_name() methods

C API (hyperlight_guest_capi):

  • POSIX-compatible: clock_gettime, gettimeofday, time
  • Broken-down time: gmtime_r, localtime_r, mktime, timegm
  • Formatting: strftime with common format specifiers

The feature is gated behind guest_time (enabled by default) and documented in docs/guest-time.md.

Note: The timezone offset is a snapshot from sandbox creation and does not update for DST transitions during the sandbox lifetime.

@simongdavies simongdavies requested a review from danbugs as a code owner January 15, 2026 21:50
@simongdavies simongdavies added the kind/enhancement For PRs adding features, improving functionality, docs, tests, etc. label Jan 15, 2026
Hyperlight guests can now read time without expensive VM exits by
using a paravirtualized clock shared between host and guest. This
enables high-frequency timing operations like benchmarking, rate
limiting, and timestamping with minimal overhead.

Paravirtualized clocks work by having the hypervisor populate a
shared memory page with clock calibration data. The guest reads
this data along with the CPU's TSC to compute the current time
entirely in userspace, avoiding the cost of a VM exit.

Reference: https://docs.kernel.org/virt/kvm/x86/msr.html#pvclock

The implementation uses the native mechanism for each hypervisor:

- KVM: pvclock (MSR 0x4b564d01)
- MSHV: Hyper-V Reference TSC page
- WHP: Hyper-V Reference TSC page

Guests have access to:

- Monotonic time: nanoseconds since sandbox creation, guaranteed
  to never go backwards
- Wall-clock time: UTC nanoseconds since Unix epoch
- Local time: wall-clock adjusted for host timezone captured at
  sandbox creation

Rust API (hyperlight_guest_bin::time):

- SystemTime/Instant types mirroring std::time
- DateTime type for human-readable date/time formatting
- Weekday/Month enums with name() and short_name() methods

C API (hyperlight_guest_capi):

- POSIX-compatible: clock_gettime, gettimeofday, time
- Broken-down time: gmtime_r, localtime_r, mktime, timegm
- Formatting: strftime with common format specifiers

The feature is gated behind `guest_time` (enabled by default) and
documented in docs/guest-time.md.

Note: The timezone offset is a snapshot from sandbox creation and
does not update for DST transitions during the sandbox lifetime.

Signed-off-by: Simon Davies <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

kind/enhancement For PRs adding features, improving functionality, docs, tests, etc.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant