[Discussion] Undocumented behavior of KVM_SET_PIT2 with count=0

[Discussion] Undocumented behavior of KVM_SET_PIT2 with count=0

[Jiaming Zhang]

Hello KVM maintainers and developers,

I hope this email finds you well.

While fuzzing the KVM subsystem with our modified version of syzkaller
on Linux Kernel, I came across an interesting behavior with the
KVM_SET_PIT2 and KVM_GET_PIT2 ioctls.

Specifically, when setting kvm_pit_state2.channels[c].count to 0 via
KVM_SET_PIT2 and then immediately reading the state back with
KVM_GET_PIT2, the returned count is 65536 (0x10000). This behavior
might be surprising for developers because, intuitively, the data
output via GET should be consistent with the data input via SET. I
could not find this special case mentioned in the KVM API
documentation (Documentation/virt/kvm/api.rst).

After looking into the kernel source (arch/x86/kvm/i8254.c), I
understand this conversion is by design. It correctly emulates the
physical i8254 PIT, which treats a programmed count of 0 as its
maximum value (2^16). While the hardware emulation is perfectly
correct, it may potentially be confusing for users.

To prevent future confusion and improve the API's clarity, I believe
it would be beneficial to add a note to the documentation explaining
this special handling for count = 0.

I'm bringing this to your attention to ask for your thoughts. If you
agree, I would be happy to prepare and submit a documentation patch to
clarify this.

Thank you for your time and for your great work on KVM.

Best Regards,
Jiaming Zhang.

Re: [Discussion] Undocumented behavior of KVM_SET_PIT2 with count=0

[Sean Christopherson]

On Mon, Aug 25, 2025, Jiaming Zhang wrote:
> Hello KVM maintainers and developers,
> 
> I hope this email finds you well.
> 
> While fuzzing the KVM subsystem with our modified version of syzkaller
> on Linux Kernel, I came across an interesting behavior with the
> KVM_SET_PIT2 and KVM_GET_PIT2 ioctls.
> 
> Specifically, when setting kvm_pit_state2.channels[c].count to 0 via
> KVM_SET_PIT2 and then immediately reading the state back with
> KVM_GET_PIT2, the returned count is 65536 (0x10000). This behavior
> might be surprising for developers because, intuitively, the data
> output via GET should be consistent with the data input via SET. I
> could not find this special case mentioned in the KVM API
> documentation (Documentation/virt/kvm/api.rst).
> 
> After looking into the kernel source (arch/x86/kvm/i8254.c), I
> understand this conversion is by design. It correctly emulates the
> physical i8254 PIT, which treats a programmed count of 0 as its
> maximum value (2^16). While the hardware emulation is perfectly
> correct, it may potentially be confusing for users.
> 
> To prevent future confusion and improve the API's clarity, I believe
> it would be beneficial to add a note to the documentation explaining
> this special handling for count = 0.
> 
> I'm bringing this to your attention to ask for your thoughts. If you
> agree, I would be happy to prepare and submit a documentation patch to
> clarify this.

I have no objection, especially since you're volunteering to do the work of
actually writing the documentation :-)

Somewhat of a side topic, I expect KVM_SET_LAPIC and KVM_GET_LAPIC have similar
behavior, as KVM applies fixup on the incoming local APIC state, e.g. to force
LDR for x2APIC mode according to hardware specs.

I wouldn't be surprised if there are other SET+GET pairs that aren't "pure".
If you run into more surprises, definitely free to submit documentation patches.

Re: [Discussion] Undocumented behavior of KVM_SET_PIT2 with count=0

[Jiaming Zhang]

Hi Sean,

Thank you for the reply!

I will prepare the documentation patch and plan to submit it in the
next few days.

And thank you for the additional context on KVM_SET_LAPIC and
KVM_GET_LAPIC; it's very helpful to understand that other GET/SET
pairs might have similar fixups. I'll keep that in mind.

Thanks again,

Jiaming Zhang