* [PATCH] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls [not found] <CANypQFZKnwafAFm2v5S_kbgr=p0UBBsmcSVsE2r65cayObaoiA@mail.gmail.com> @ 2025-09-05 7:51 ` Jiaming Zhang 2025-09-05 16:51 ` Randy Dunlap 0 siblings, 1 reply; 6+ messages in thread From: Jiaming Zhang @ 2025-09-05 7:51 UTC (permalink / raw) To: pbonzini, seanjc, corbet, kvm; +Cc: linux-doc, linux-kernel, 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 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls 2025-09-05 7:51 ` [PATCH] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls Jiaming Zhang @ 2025-09-05 16:51 ` Randy Dunlap 2025-09-05 17:47 ` [PATCH v2] " Jiaming Zhang 0 siblings, 1 reply; 6+ messages in thread From: Randy Dunlap @ 2025-09-05 16:51 UTC (permalink / raw) To: Jiaming Zhang, pbonzini, seanjc, corbet, kvm; +Cc: linux-doc, linux-kernel 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH v2] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls 2025-09-05 16:51 ` Randy Dunlap @ 2025-09-05 17:47 ` Jiaming Zhang 2025-09-05 19:17 ` Randy Dunlap 2025-09-16 0:25 ` Sean Christopherson 0 siblings, 2 replies; 6+ messages in thread From: Jiaming Zhang @ 2025-09-05 17:47 UTC (permalink / raw) To: rdunlap; +Cc: corbet, kvm, linux-doc, linux-kernel, pbonzini, r772577952, seanjc 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 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH v2] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls 2025-09-05 17:47 ` [PATCH v2] " Jiaming Zhang @ 2025-09-05 19:17 ` Randy Dunlap 2025-09-16 0:25 ` Sean Christopherson 1 sibling, 0 replies; 6+ messages in thread From: Randy Dunlap @ 2025-09-05 19:17 UTC (permalink / raw) To: Jiaming Zhang; +Cc: corbet, kvm, linux-doc, linux-kernel, pbonzini, seanjc 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v2] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls 2025-09-05 17:47 ` [PATCH v2] " Jiaming Zhang 2025-09-05 19:17 ` Randy Dunlap @ 2025-09-16 0:25 ` Sean Christopherson 2025-09-16 20:02 ` Sean Christopherson 1 sibling, 1 reply; 6+ messages in thread From: Sean Christopherson @ 2025-09-16 0:25 UTC (permalink / raw) To: Sean Christopherson, rdunlap, Jiaming Zhang Cc: corbet, kvm, linux-doc, linux-kernel, pbonzini 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v2] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls 2025-09-16 0:25 ` Sean Christopherson @ 2025-09-16 20:02 ` Sean Christopherson 0 siblings, 0 replies; 6+ messages in thread From: Sean Christopherson @ 2025-09-16 20:02 UTC (permalink / raw) To: rdunlap, Jiaming Zhang; +Cc: corbet, kvm, linux-doc, linux-kernel, pbonzini 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2025-09-16 20:02 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <CANypQFZKnwafAFm2v5S_kbgr=p0UBBsmcSVsE2r65cayObaoiA@mail.gmail.com>
2025-09-05 7:51 ` [PATCH] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls Jiaming Zhang
2025-09-05 16:51 ` Randy Dunlap
2025-09-05 17:47 ` [PATCH v2] " Jiaming Zhang
2025-09-05 19:17 ` Randy Dunlap
2025-09-16 0:25 ` Sean Christopherson
2025-09-16 20:02 ` Sean Christopherson
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).