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.
