[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

[PATCH] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls

[Jiaming Zhang]

The behavior of KVM_SET_PIT2 and KVM_SET_LAPIC conforms to their
respective hardware specifications. Add references to the Intel 8254
PIT datasheet and the Software Developer's Manual (SDM)  to ensure
users can rely on the official datasheets for behavioral details.

Signed-off-by: Jiaming Zhang <r772577952@gmail.com>
---
 Documentation/virt/kvm/api.rst | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 6aa40ee05a4a..d21494aa7dc2 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -2083,6 +2083,11 @@ The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state's
 regs field) depends on the state of the KVM_CAP_X2APIC_API capability.
 See the note in KVM_GET_LAPIC.
 
+.. Tip::
+  ``KVM_SET_LAPIC`` ioctl strictly adheres to Intel® 64 and IA-32 Architectures
+  Software Developer's Manual (SDM). Refer volume 3A of the `Intel SDM <https://
+  www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html>`_.
+
 
 4.59 KVM_IOEVENTFD
 ------------------
@@ -3075,6 +3080,14 @@ This IOCTL replaces the obsolete KVM_GET_PIT.
 Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
 See KVM_GET_PIT2 for details on struct kvm_pit_state2.
 
+.. Tip::
+
+  ``KVM_SET_PIT2`` ioctl strictly adheres to the spec of Intel 8254 PIT.
+  For example, a ``count`` value of 0 in ``struct kvm_pit_channel_state`` is
+  interpreted as 65536, which is the maximum count value. Refer `Intel
+  8254 programmable interval timer <https://www.scs.stanford.edu/10wi-cs140/
+  pintos/specs/8254.pdf>`_.
+
 This IOCTL replaces the obsolete KVM_SET_PIT.
 
 
-- 
2.34.1

Re: [PATCH] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls

[Randy Dunlap]

Hi,

On 9/5/25 12:51 AM, Jiaming Zhang wrote:
> The behavior of KVM_SET_PIT2 and KVM_SET_LAPIC conforms to their
> respective hardware specifications. Add references to the Intel 8254
> PIT datasheet and the Software Developer's Manual (SDM)  to ensure
> users can rely on the official datasheets for behavioral details.
> 
> Signed-off-by: Jiaming Zhang <r772577952@gmail.com>
> ---
>  Documentation/virt/kvm/api.rst | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 6aa40ee05a4a..d21494aa7dc2 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -2083,6 +2083,11 @@ The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state's
>  regs field) depends on the state of the KVM_CAP_X2APIC_API capability.
>  See the note in KVM_GET_LAPIC.
>  
> +.. Tip::
> +  ``KVM_SET_LAPIC`` ioctl strictly adheres to Intel® 64 and IA-32 Architectures
> +  Software Developer's Manual (SDM). Refer volume 3A of the `Intel SDM <https://

                                        Refer to volume 3A of the Intel SDM

> +  www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html>`_.

Please put the full URL on one line -- don't split it on 2 lines.

> +
>  
>  4.59 KVM_IOEVENTFD
>  ------------------
> @@ -3075,6 +3080,14 @@ This IOCTL replaces the obsolete KVM_GET_PIT.
>  Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
>  See KVM_GET_PIT2 for details on struct kvm_pit_state2.
>  
> +.. Tip::
> +
> +  ``KVM_SET_PIT2`` ioctl strictly adheres to the spec of Intel 8254 PIT.
> +  For example, a ``count`` value of 0 in ``struct kvm_pit_channel_state`` is
> +  interpreted as 65536, which is the maximum count value. Refer `Intel

                                                             Refer to

> +  8254 programmable interval timer <https://www.scs.stanford.edu/10wi-cs140/
> +  pintos/specs/8254.pdf>`_.

Put the full URL on one line, please.

> +
>  This IOCTL replaces the obsolete KVM_SET_PIT.
>  
>  
Thanks.
-- 
~Randy

[PATCH v2] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls

[Jiaming Zhang]

Hi Randy,

Thanks for your feedback! I have fixed the grammar and put the full URL on a single line.

Please let me know if any other changes are needed.

Thanks,
Jiaming Zhang

---

The behavior of KVM_SET_PIT2 and KVM_SET_LAPIC conforms to their
respective hardware specifications. Add references to the Intel 8254
PIT datasheet and the Software Developer's Manual (SDM)  to ensure
users can rely on the official datasheets for behavioral details.

Signed-off-by: Jiaming Zhang <r772577952@gmail.com>
---
 Documentation/virt/kvm/api.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 6aa40ee05a4a..f55e1b7562db 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -2083,6 +2083,11 @@ The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state's
 regs field) depends on the state of the KVM_CAP_X2APIC_API capability.
 See the note in KVM_GET_LAPIC.
 
+.. Tip::
+  ``KVM_SET_LAPIC`` ioctl strictly adheres to Intel® 64 and IA-32 Architectures
+  Software Developer's Manual (SDM). Refer to volume 3A of the `Intel SDM
+  <https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html>`_.
+
 
 4.59 KVM_IOEVENTFD
 ------------------
@@ -3075,6 +3080,13 @@ This IOCTL replaces the obsolete KVM_GET_PIT.
 Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
 See KVM_GET_PIT2 for details on struct kvm_pit_state2.
 
+.. Tip::
+
+  ``KVM_SET_PIT2`` ioctl strictly adheres to the spec of Intel 8254 PIT.
+  For example, a ``count`` value of 0 in ``struct kvm_pit_channel_state`` is
+  interpreted as 65536, which is the maximum count value. Refer to `Intel 8254
+  programmable interval timer <https://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf>`_.
+
 This IOCTL replaces the obsolete KVM_SET_PIT.
 
 
-- 
2.34.1

Re: [PATCH v2] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls

[Randy Dunlap]

On 9/5/25 10:47 AM, Jiaming Zhang wrote:
> ---
> 
> The behavior of KVM_SET_PIT2 and KVM_SET_LAPIC conforms to their
> respective hardware specifications. Add references to the Intel 8254
> PIT datasheet and the Software Developer's Manual (SDM)  to ensure
> users can rely on the official datasheets for behavioral details.
> 
> Signed-off-by: Jiaming Zhang <r772577952@gmail.com>

Thanks. LGTM.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Documentation/virt/kvm/api.rst | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 6aa40ee05a4a..f55e1b7562db 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -2083,6 +2083,11 @@ The format of the APIC ID register (bytes 32-35 of struct kvm_lapic_state's
>  regs field) depends on the state of the KVM_CAP_X2APIC_API capability.
>  See the note in KVM_GET_LAPIC.
>  
> +.. Tip::
> +  ``KVM_SET_LAPIC`` ioctl strictly adheres to Intel® 64 and IA-32 Architectures
> +  Software Developer's Manual (SDM). Refer to volume 3A of the `Intel SDM
> +  <https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html>`_.
> +
>  
>  4.59 KVM_IOEVENTFD
>  ------------------
> @@ -3075,6 +3080,13 @@ This IOCTL replaces the obsolete KVM_GET_PIT.
>  Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
>  See KVM_GET_PIT2 for details on struct kvm_pit_state2.
>  
> +.. Tip::
> +
> +  ``KVM_SET_PIT2`` ioctl strictly adheres to the spec of Intel 8254 PIT.
> +  For example, a ``count`` value of 0 in ``struct kvm_pit_channel_state`` is
> +  interpreted as 65536, which is the maximum count value. Refer to `Intel 8254
> +  programmable interval timer <https://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf>`_.
> +
>  This IOCTL replaces the obsolete KVM_SET_PIT.
>  
>  

-- 
~Randy

Re: [PATCH v2] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls

[Sean Christopherson]

On Sat, 06 Sep 2025 01:47:36 +0800, Jiaming Zhang wrote:
> Thanks for your feedback! I have fixed the grammar and put the full URL on a single line.
> 
> Please let me know if any other changes are needed.
> 
> Thanks,
> Jiaming Zhang
> 
> [...]

Applied to kvm-x86 misc, but only for the PIT documentation update.  The LAPIC
ioctls do muck with state, but unlike the PIT behavior, KVM isn't _just_ strictly
following any spec.  The LDR fixup is arguably KVM honoring the architecture,
but the ID fixups for x2apic_format=false are very much the opposite of what the
architecture says should happen.

I honestly don't know how to document the LAPIC ioctls, or even if it's worth
doing so.  But that's not a reason to hold up the PIT documentations.

[1/1] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls
      https://github.com/kvm-x86/linux/commit/3f0bb03b9db7

--
https://github.com/kvm-x86/linux/tree/next

Re: [PATCH v2] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls

[Sean Christopherson]

On Mon, Sep 15, 2025, Sean Christopherson wrote:
> On Sat, 06 Sep 2025 01:47:36 +0800, Jiaming Zhang wrote:
> > Thanks for your feedback! I have fixed the grammar and put the full URL on a single line.
> > 
> > Please let me know if any other changes are needed.
> > 
> > Thanks,
> > Jiaming Zhang
> > 
> > [...]
> 
> Applied to kvm-x86 misc, but only for the PIT documentation update.

...

> [1/1] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls
>       https://github.com/kvm-x86/linux/commit/3f0bb03b9db7

I force pushed to fixup an unrelated commit, new hash:

      https://github.com/kvm-x86/linux/commit/5b5133e6a55b