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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20250905075115.779749-1-r772577952@gmail.com>
Date: Fri,  5 Sep 2025 15:51:15 +0800
From: Jiaming Zhang <r772577952@...il.com>
To: pbonzini@...hat.com,
	seanjc@...gle.com,
	corbet@....net,
	kvm@...r.kernel.org
Cc: linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	Jiaming Zhang <r772577952@...il.com>
Subject: [PATCH] Documentation: KVM: Add reference specs for PIT and LAPIC ioctls

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@...il.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