Skip to content

vmm: x86_64: synchronize TSC offsets after restoring vCPUs - #6200

Open
JackThomson2 wants to merge 2 commits into
firecracker-microvm:mainfrom
JackThomson2:fix/tsc-offset-sync-series
Open

JackThomson2 wants to merge 2 commits into
firecracker-microvm:mainfrom
JackThomson2:fix/tsc-offset-sync-series

Conversation

@JackThomson2

@JackThomson2 JackThomson2 commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Changes

Restoring TSC MSRs separately can leave vCPUs with different offsets,
allowing guest clocks backed by raw TSC to move backwards when a task
migrates. Add device-attribute accessors and copy the restored vCPU0
offset to all vCPUs before starting their threads. Preserve the
reference timeline and existing VM clock restore policy. Probe for
attribute support and keep synchronization best-effort on hosts where it
is unavailable or fails. No snapshot format changes or runtime test
hooks are introduced.

Related:

Reason

...

License Acceptance

By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache 2.0 license. For more information on following Developer
Certificate of Origin and signing off your commits, please check
CONTRIBUTING.md.

PR Checklist

  • I have read and understand CONTRIBUTING.md.
  • I have run tools/devtool checkbuild --all to verify that the PR passes
    build checks on all supported architectures.
  • I have run tools/devtool checkstyle --no-clippy to verify that the PR
    passes the automated style checks.
  • I have described what is done in these changes, why they are needed, and
    how they are solving the problem in a clear and encompassing way.
  • I have updated any relevant documentation (both in code and in the docs)
    in the PR.
  • I have mentioned all user-facing changes in CHANGELOG.md.
  • If a specific issue led to this PR, this PR closes the issue.
  • When making API changes, I have followed the
    Runbook for Firecracker API changes.
  • I have tested all new and changed functionalities in unit tests and/or
    integration tests.
  • I have linked an issue to every new TODO.

  • This functionality cannot be added in rust-vmm.

@codecov

codecov Bot commented Sep 9, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 71.83099% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.09%. Comparing base (eaba0ed) to head (ac1a211).
⚠️ Report is 26 commits behind head on main.

Files with missing lines Patch % Lines
src/vmm/src/builder.rs 50.00% 18 Missing ⚠️
src/vmm/src/arch/x86_64/vcpu.rs 94.28% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #6200      +/-   ##
==========================================
+ Coverage   83.04%   83.09%   +0.05%     
==========================================
  Files         277      277              
  Lines       31437    31478      +41     
==========================================
+ Hits        26106    26157      +51     
+ Misses       5331     5321      -10     
Flag Coverage Δ
5.10-m5n.metal 83.21% <23.94%> (-0.06%) ⬇️
5.10-m6a.metal 82.58% <23.94%> (-0.07%) ⬇️
5.10-m6g.metal 80.15% <0.00%> (+0.03%) ⬆️
5.10-m6i.metal 83.21% <23.94%> (-0.07%) ⬇️
5.10-m7a.metal-48xl 82.57% <23.94%> (-0.07%) ⬇️
5.10-m7g.metal 80.15% <0.00%> (+0.03%) ⬆️
5.10-m7i.metal-24xl 83.18% <23.94%> (-0.07%) ⬇️
5.10-m7i.metal-48xl 83.18% <23.94%> (-0.07%) ⬇️
5.10-m8g.metal-24xl 80.15% <0.00%> (+0.03%) ⬆️
5.10-m8g.metal-48xl 80.15% <0.00%> (+0.03%) ⬆️
5.10-m8i.metal-48xl 83.18% <23.94%> (-0.07%) ⬇️
5.10-m8i.metal-96xl 83.18% <23.94%> (-0.07%) ⬇️
5.10-m9g.metal-48xl 80.15% <0.00%> (+0.03%) ⬆️
6.1-m5n.metal 83.34% <69.01%> (+0.04%) ⬆️
6.1-m6a.metal 82.72% <69.01%> (+0.04%) ⬆️
6.1-m6g.metal 80.15% <0.00%> (+0.03%) ⬆️
6.1-m6i.metal 83.34% <69.01%> (+0.04%) ⬆️
6.1-m7a.metal-48xl 82.71% <69.01%> (+0.04%) ⬆️
6.1-m7g.metal 80.15% <0.00%> (+0.03%) ⬆️
6.1-m7i.metal-24xl 83.35% <69.01%> (+0.04%) ⬆️
6.1-m7i.metal-48xl 83.36% <69.01%> (+0.04%) ⬆️
6.1-m8g.metal-24xl 80.15% <0.00%> (+0.03%) ⬆️
6.1-m8g.metal-48xl 80.15% <0.00%> (+0.03%) ⬆️
6.1-m8i.metal-48xl 83.36% <69.01%> (+0.04%) ⬆️
6.1-m8i.metal-96xl 83.36% <69.01%> (+0.04%) ⬆️
6.1-m9g.metal-48xl 80.15% <0.00%> (+0.03%) ⬆️
6.18-m5n.metal 83.34% <69.01%> (+0.04%) ⬆️
6.18-m6a.metal 82.72% <69.01%> (+0.05%) ⬆️
6.18-m6g.metal 80.26% <0.00%> (+0.03%) ⬆️
6.18-m6i.metal 83.34% <69.01%> (+0.04%) ⬆️
6.18-m7a.metal-48xl 82.71% <69.01%> (+0.04%) ⬆️
6.18-m7g.metal 80.26% <0.00%> (+0.03%) ⬆️
6.18-m7i.metal-24xl 83.35% <69.01%> (+0.04%) ⬆️
6.18-m7i.metal-48xl 83.36% <69.01%> (+0.05%) ⬆️
6.18-m8g.metal-24xl 80.26% <0.00%> (+0.03%) ⬆️
6.18-m8g.metal-48xl 80.26% <0.00%> (+0.03%) ⬆️
6.18-m8i.metal-48xl 83.36% <69.01%> (+0.04%) ⬆️
6.18-m8i.metal-96xl 83.36% <69.01%> (+0.04%) ⬆️
6.18-m9g.metal-48xl 80.26% <0.00%> (+0.03%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@zulinx86 zulinx86 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't we need to follow the instruction described in https://docs.kernel.org/virt/kvm/devices/vcpu.html#group-kvm-vcpu-tsc-ctrl ?

@JackThomson2

Copy link
Copy Markdown
Contributor Author

Don't we need to follow the instruction described in docs.kernel.org/virt/kvm/devices/vcpu.html#group-kvm-vcpu-tsc-ctrl ?

Yeah I think we could follow this in the future, but I read it as a possible algorithm for maintaining a consistent TSC during live migration. Here the goal is just keeping the vCPUs in sync.

@zulinx86 zulinx86 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't we need to follow the instruction described in docs.kernel.org/virt/kvm/devices/vcpu.html#group-kvm-vcpu-tsc-ctrl ?

Yeah I think we could follow this in the future, but I read it as a possible algorithm for maintaining a consistent TSC during live migration. Here the goal is just keeping the vCPUs in sync.

OK. I'm fine to keep this PR focused on the offset synchronization.

I'll dive deeper into whether it's fine to not account for elapsed time especially when clock_realtime=true.

Comment thread tests/integration_tests/functional/test_snapshot_basic.py Outdated
Comment thread src/vmm/src/builder.rs
Comment thread src/vmm/src/builder.rs Outdated
Comment thread src/vmm/src/builder.rs Outdated
Comment thread src/vmm/src/arch/x86_64/vcpu.rs
Comment thread tests/integration_tests/functional/test_snapshot_basic.py Outdated
Comment thread tests/integration_tests/functional/test_snapshot_basic.py Outdated
@Manciukic

Copy link
Copy Markdown
Contributor

I'll dive deeper into whether it's fine to not account for elapsed time especially when clock_realtime=true.

When I introduced clock_realtime I had TSC in mind as well. I think it would be fair to advance TSC as well if that's passed, but it'd be a small change. The current PR seems to just maintain the current behaviour and fix the bug.

Restoring TSC MSRs separately can leave vCPUs with different offsets,
allowing guest clocks backed by raw TSC to move backwards when a task
migrates. Add device-attribute accessors and copy the restored vCPU0
offset to all vCPUs before starting their threads. Preserve the
reference timeline and existing VM clock restore policy. Probe for
attribute support and keep synchronization best-effort on hosts where it
is unavailable or fails. No snapshot format changes or runtime test
hooks are introduced.

Signed-off-by: Jack Thomson <jackabt@amazon.com>
Exercise signed TSC offset access and synchronization using real KVM
vCPUs restored into a fresh VM. Cover unequal offsets, an already
synchronized pair and a single vCPU, then verify that VM clock
restoration preserves the reference offset. Extend the raw-TSC snapshot
test with bounded CPU migration sampling across both vCPUs. Require
non-realtime clock restoration to resume near snapshot time rather than
merely differ from elapsed host time. Keep skew injection in Rust test
code instead of adding production environment hooks.

Signed-off-by: Jack Thomson <jackabt@amazon.com>
@JackThomson2
JackThomson2 force-pushed the fix/tsc-offset-sync-series branch from a292420 to ac1a211 Compare September 14, 2026 12:55
@JackThomson2 JackThomson2 added the Status: Awaiting review Indicates that a pull request is ready to be reviewed label Sep 14, 2026

@zulinx86 zulinx86 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM (with a minor comment)

Comment on lines +834 to +835
if not clock_realtime:
assert 0 <= guest_delta < 5.0, f"Unexpected clock delta: {guest_delta:.6f}s"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do we want to ensure with this? How is this related to the TSC offset synchronization between vCPUs?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left it in while asserting the behaviour before and after this change. I can remove if we want

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the assertion itself is useful, but could we move it below the diagnostic prints, next to assert jumped == clock_realtime? That would keep the measurements and jumped calculation together, followed by the assertions.

@zulinx86

Copy link
Copy Markdown
Contributor

Do you think it's worth adding this fix to the changelog?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Status: Awaiting review Indicates that a pull request is ready to be reviewed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants