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

[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