Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

time ABI: extend maximum snapshot downtime to one year

Open
  • Is something wrong?
#516 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
c, linux, python
Domain
backend, infrastructure

Research direction

Start with vmm_core/virt/src/time_abi/downtime.rs and guest/common/nvx-time.c, then review the boundary cases in scripts/test_guest_time.py and the compatibility decision for older snapshots. Read the time ABI and snapshot design documents before changing the contract. Done means the 365-day boundary, D + Q behavior, and hook-based restore qualification are covered, with the required documentation updated.

Written by the indexing model from the issue text.

Description

Problem

NVX time ABI v1 currently accepts snapshot downtime D only when 0 <= D <= 30 days. A restore after that boundary fails before any guest vCPU runs with E_DOWNTIME_EXCESSIVE.

This is also an artifact-retention limit: restores always measure from the original capture anchor, repeated restores do not renew it, and OpenVMM does not allow a restored microVM to capture a replacement snapshot. An artifact that crosses the boundary is therefore permanently unusable.

The 30-day value is a policy bound, not a demonstrated clock-repair or representation limit. We should extend it for longer-lived snapshot artifacts.

Proposed direction

Increase the maximum accepted downtime to exactly 365 days:

  • 31,536,000 seconds
  • 31,536,000,000,000,000 nanoseconds
  • retain the inclusive boundary and E_DOWNTIME_EXCESSIVE for values above it
  • define this as a fixed duration, not a calendar-year anniversary

Do not remove the upper bound entirely. An unbounded policy would expose several unrelated implicit limits whose effective boundary depends on the snapshot's TSC frequency and timestamp:

  • u64 downtime in nanoseconds: about 584 years
  • signed Linux ktime_t: about 292 years
  • at the maximum accepted 10 GHz TSC rate, half-counter ambiguity begins around 29 years and the TSC wraps around 58 years
  • restore UTC must fit the guest packet's signed-nanosecond checks

A fixed one-year limit has wide headroom below all of these.

Feasibility findings

One year fits the existing representations and checked arithmetic with substantial margin:

  • restore packet downtime: about 0.171% of u64
  • TSC advance at 10 GHz: about 1.71% of u64
  • LAPIC ticks at 1 GHz: about 0.171% of u64
  • VM time in 100 ns units: about 0.00171% of u64
  • RTC millisecond advance: negligible relative to i64

The host paths already use u128 or checked arithmetic for TSC, LAPIC, and RTC advancement. Linux 6.18 timekeeping consumes large clocksource deltas logarithmically, updates missed jiffies arithmetically, and advances the timer wheel by pending buckets rather than iterating over every elapsed tick. The NVX guest uses HZ=100; its timer wheel's ordinary range is already about 15 days, so the current 30-day contract already exercises the overdue-timer path.

One remaining qualification gap is scheduler accounting: sched_clock uses the raw TSC, so a simulated one-year restore must prove that process runtime, scheduler statistics, and cgroup CPU accounting do not incorrectly charge frozen workload tasks for the downtime.

Required changes

OpenVMM
  • Raise vmm_core/virt/src/time_abi/downtime.rs::MAX_DOWNTIME_NS to 365 days.
  • Preserve negative-downtime and target-overflow checks.
  • Update boundary and LAPIC arithmetic tests.
  • Update Guide/src/user_guide/openvmm/snapshots.md.
  • Account for the VM-time cut work being promoted by #491: both anchor downtime D and combined VM-time downtime D + Q must remain bounded, with the exact boundary semantics documented.
NVX guest and integration
  • Raise guest/common/nvx-time.c::DOWNTIME_LIMIT_NS and update its diagnostic.
  • Update scripts/test_guest_time.py packet-boundary cases.
  • Update doc/design/time-abi.md, doc/design/snapshot-and-restore.md, and CI documentation.
  • Update the excessive-downtime test hook case from 2592001 seconds to the new boundary plus one.
  • Add a hook-based one-year restore qualification; do not wait one year in real time.

Compatibility

Changing only OpenVMM is insufficient: a snapshot containing the old guest still rejects a restore packet above 30 days with G_REPAIR_PACKET.

The one-year guarantee should therefore apply only to snapshots captured with both the updated guest and updated OpenVMM. Before implementation, decide and document whether this requires a time-ABI version/capability change or whether release-level compatibility metadata is sufficient. Do not claim that existing artifacts acquire the longer retention period automatically.

Acceptance criteria

  • Exactly 365 days is accepted by both OpenVMM and the guest; 365 days plus one nanosecond (or the narrowest testable increment) is rejected with the expected stable code.
  • A simulated 365-day restore succeeds on KVM, MSHV, and WHP at 1 and 8 vCPUs.
  • Normal and expedited RCU configurations pass, including the debug kernel's stall, soft-lockup, and hung-task detectors.
  • Guest monotonic/boottime advances by the simulated downtime and realtime converges to host UTC.
  • Warp probes and time ABI restore checks pass after the jump.
  • Expired kernel timers are handled without an unbounded restore/readiness delay.
  • Process CPU time, scheduler runtime/statistics, and cgroup CPU accounting do not charge frozen workloads for the downtime.
  • Same-boot monotonic-source and simulated cross-boot/cross-host UTC-source restores both pass.
  • The D + Q boundary from #491 is covered, including exact-boundary and overflow cases.
  • Documentation states that the limit is a fixed 365-day duration and explains compatibility with older snapshots.

Out of scope

Removing the upper bound entirely. That should not be considered without a separate contract and qualification effort covering all implicit TSC, kernel-time, UTC, and serialization limits.

Dominant language
Python
Stars
380
Forks
24
Avg merge
12h 2m
Merged PRs (30d)
291

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/nvx

All issues in microsoft/nvx

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.