driver: Add guest-side clock synchronization Operating Modes - #31
Open
changyeon-jo wants to merge 1 commit into
Open
changyeon-jo wants to merge 1 commit into
changyeon-jo wants to merge 1 commit into
Conversation
changyeon-jo
force-pushed
the
clock-sync-opmodes
branch
from
July 12, 2026 17:39
2ed96a3 to
1d8eacb
Compare
The Guest-side External Camera HAL queries buffer age against Guest
CLOCK_MONOTONIC, while the Host-side emulated virtio-media device
timestamp is generated in the Host's CLOCK_MONOTONIC domain. Because
the Host and Guest boot times differ (creating a monotonic offset of
~190 seconds on Cuttlefish), this clock domain mismatch causes the HAL
to reject all dequeued buffers as "too old" and drops 100% of frames,
yielding a "can't connect to camera" timeout in the camera app.
This change introduces three guest-side clock synchronization
operating modes to bridge the monotonic gap inside the guest driver:
* Mode 0 (Passthrough): Verbatim Host-domain timestamp passthrough
(Backward-compatible default).
* Mode 1 (Guest Stamping): Statelessly overwrites incoming buffer
timestamps with the Guest's live CLOCK_MONOTONIC (ktime_get_ns())
upon dequeue. Foolproof and immune to VM suspend/resume.
* Mode 2 (Dynamic Translation): Dynamically translates Host timestamps
onto the Guest timeline via real-time adaptive offset tracking:
- Startup Calibration: Uses a 10-frame sliding window to isolate the
absolute least-latency delivery baseline on cold start.
- Continuous Bounded Slew: Asymmetrically tracks positive clock drift
instantly (capped at 1ms/frame) while decaying downward via a /1024
exponential filter to gracefully ignore high-latency host spikes.
- Step Recalibration: Immediately snaps on supra-threshold jumps
(default 1s, tunable via sysfs) to support seamless VM Resume, and
flushes the +1us monotonicity clamp to avoid downstream throttling.
- Resilience Strike Latching: Automatically falls back to Mode 0 on
sustained bi-directional wild jitter strikes to guarantee UVC safety.
Both the active mode and recalibration threshold can be dynamically
toggled and inspected at runtime via writeable module parameters in
sysfs:
# Toggle to Mode 2 (Dynamic Offset Translation)
echo 2 > /sys/module/virtio_media/parameters/timestamp_mode
# Configure recalibration threshold (e.g. 1 second default)
echo 1000000000 > \
/sys/module/virtio_media/parameters/recalib_threshold_ns
# Confirm the current calibrated parameters
cat /sys/module/virtio_media/parameters/timestamp_mode
changyeon-jo
force-pushed
the
clock-sync-opmodes
branch
from
July 13, 2026 17:02
1d8eacb to
6d49f29
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The Guest-side External Camera HAL queries buffer age against Guest
CLOCK_MONOTONIC, while the Host-side emulated virtio-media device
timestamp is generated in the Host's CLOCK_MONOTONIC domain. Because
the Host and Guest boot times differ (creating a monotonic offset of
~190 seconds on Cuttlefish), this clock domain mismatch causes the HAL
to reject all dequeued buffers as "too old" and drops 100% of frames,
yielding a "can't connect to camera" timeout in the camera app.
This change introduces three guest-side clock synchronization operating
modes to bridge the monotonic gap inside the guest driver:
(Backward-compatible default).
timestamps with the Guest's live CLOCK_MONOTONIC (ktime_get_ns())
upon dequeue. Foolproof and immune to VM suspend/resume.
onto the Guest timeline using a min-filtered calibration baseline and
auto-recalibration (150ms optimized threshold) on VM resume.
Both the active mode and recalibration threshold can be dynamically
toggled and inspected at runtime via writeable module parameters in sysfs: