From patchwork Tue Jan 28 14:00:02 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354485 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 090831398 for ; Tue, 28 Jan 2020 14:49:56 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id DCB3F2173E for ; Tue, 28 Jan 2020 14:49:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580222995; bh=RQJBSrCBQoRjRPzNpPiEOUwoi4zmhWHM5Ddo22O4ojU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=Mquz/Fw3g1S759F+YqDzrvScss7Pq3oDEuyWD+xCTa11pcc+q2FU1c1K19rlrCr7c oRLq6OZOJK67ppXoISyHM9VDsmUA3SzuczTbngJ1Pwjf2+o1JNvPVNda22e57dYdy0 5qCqoT3GtY+vfksXMjGpLwuBwGTUcmSCX7ZGTCAM= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727423AbgA1Oty (ORCPT ); Tue, 28 Jan 2020 09:49:54 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59266 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726401AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=/hfBTm+pwI/qMUzI6610HUXH01FV0FRb49kTIzGz0Ww=; b=E/bWrY8g75zMz0ST+qe+W7HFkj wDMeKMTZMTAyuysD4oyzDqiPBfq5PJjaqrBHRbO3DRwETGjT76NiTJ+IDOMcElzDWhEGVr0YMtfgb Clq9k7LePmOncq0P8ZEpqRb4REj15uCz1EE3YO/SQx7Te3aX6CBCynK+ysJpcYHSeApyw70qoM2FZ CygR3aUEr9lg6MIKD0scM8wD3QBwwk1XO81cIcUdFdBrMDw8SKV1R3NrFnsnmCuKVVR1x3S50fLpY ev1Ps5YqW1PODTcpYMtybxkqWu9DCRG1cTwVDZKrG4uz8OS7M4zwQegY/h4bWibcDsKxbLZ6dt7Ny MU2bgp0A==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007iZ-9c; Tue, 28 Jan 2020 14:00:45 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BNG-6Z; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 01/27] docs: kvm: add arm/pvtime.rst to index.rst Date: Tue, 28 Jan 2020 15:00:02 +0100 Message-Id: <8efe846ddd76d97a62a150a997619e5d7d992774.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org Add this file to a new kvm/arm index.rst, in order for it to be shown as part of the virt book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/arm/index.rst | 10 ++++++++++ Documentation/virt/kvm/index.rst | 2 ++ 2 files changed, 12 insertions(+) create mode 100644 Documentation/virt/kvm/arm/index.rst diff --git a/Documentation/virt/kvm/arm/index.rst b/Documentation/virt/kvm/arm/index.rst new file mode 100644 index 000000000000..e039d9b1e076 --- /dev/null +++ b/Documentation/virt/kvm/arm/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=== +ARM +=== + +.. toctree:: + :maxdepth: 2 + + pvtime diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index ada224a511fe..488c6370a447 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -10,3 +10,5 @@ KVM amd-memory-encryption cpuid vcpu-requests + + arm/index From patchwork Tue Jan 28 14:00:06 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354361 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id D870114B4 for ; Tue, 28 Jan 2020 14:01:19 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id AE2762468E for ; Tue, 28 Jan 2020 14:01:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220079; bh=a6mkRzjWhCmIHE9IUbkl8qYiPklT0cEDtjZ7TXoFbrE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=fCkbCM0KQ8i7M9EbAgC7toMGsH6EhquaEvixoDCD1rvHc4z6h/PQbCdS54ySGe7wT kKNLzyRlQkN0CE1OYTUBn8ZLQGfXPWQQS3iWbQeLzWET+znOTXvwNBH8TJj8kgGcsx m5yx0msUOoyPJtlJNDURaZOzLu2+zhD82uygk89A= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726989AbgA1OBP (ORCPT ); Tue, 28 Jan 2020 09:01:15 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59306 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727297AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=/9G2blGVWjqgR965RRc1wFm/0hKu3kd3si70pvH2CPo=; b=h3dKn3NPPEjfnXRXe/6ajZsD0D 91dZ0ibztBRd911ztaZtHOy6t76huzWm4uuaNsfVaQ0LtoxEDCFo3aWVH91Qvyo8HvUZDGST13iNC OgzIpUXrWvOlWISQdQIlYcQcJfdtRXW4/fCcFC45eR4peyJSpweBCsKWjgcFDZaIgKp+qGquYytzr 4WvNtNHzg4jgyj5eOrMTAROoE0VW9x4QTzSfUg6t4NzwF1gTRw7/xaHCDyVgZqAJl1PMc7Eo7iKVU xU2j5TIMiz3PvKTkdMtzs9MZP5QPEMUgJ7NLW0m4x2Gty6vgOFuCQWsuBBBs/tTWY5CsCi/P/YRnm kCqVv44Q==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ6-0007io-09; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BNa-BR; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 05/27] docs: virt: convert halt-polling.txt to ReST format Date: Tue, 28 Jan 2020 15:00:06 +0100 Message-Id: X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Fix document title to match ReST format - Convert the table to be properly recognized - Some indentation fixes to match ReST syntax. Signed-off-by: Mauro Carvalho Chehab --- .../{halt-polling.txt => halt-polling.rst} | 84 ++++++++++--------- Documentation/virt/kvm/index.rst | 1 + 2 files changed, 44 insertions(+), 41 deletions(-) rename Documentation/virt/kvm/{halt-polling.txt => halt-polling.rst} (64%) diff --git a/Documentation/virt/kvm/halt-polling.txt b/Documentation/virt/kvm/halt-polling.rst similarity index 64% rename from Documentation/virt/kvm/halt-polling.txt rename to Documentation/virt/kvm/halt-polling.rst index 4f791b128dd2..d8f7516bd8d9 100644 --- a/Documentation/virt/kvm/halt-polling.txt +++ b/Documentation/virt/kvm/halt-polling.rst @@ -1,3 +1,4 @@ +=========================== The KVM halt polling system =========================== @@ -68,7 +69,8 @@ steady state polling interval but will only really do a good job for wakeups which come at an approximately constant rate, otherwise there will be constant adjustment of the polling interval. -[0] total block time: the time between when the halt polling function is +[0] total block time: + the time between when the halt polling function is invoked and a wakeup source received (irrespective of whether the scheduler is invoked within that function). @@ -81,31 +83,32 @@ shrunk. These variables are defined in include/linux/kvm_host.h and as module parameters in virt/kvm/kvm_main.c, or arch/powerpc/kvm/book3s_hv.c in the powerpc kvm-hv case. -Module Parameter | Description | Default Value --------------------------------------------------------------------------------- -halt_poll_ns | The global max polling | KVM_HALT_POLL_NS_DEFAULT - | interval which defines | - | the ceiling value of the | - | polling interval for | (per arch value) - | each vcpu. | --------------------------------------------------------------------------------- -halt_poll_ns_grow | The value by which the | 2 - | halt polling interval is | - | multiplied in the | - | grow_halt_poll_ns() | - | function. | --------------------------------------------------------------------------------- -halt_poll_ns_grow_start | The initial value to grow | 10000 - | to from zero in the | - | grow_halt_poll_ns() | - | function. | --------------------------------------------------------------------------------- -halt_poll_ns_shrink | The value by which the | 0 - | halt polling interval is | - | divided in the | - | shrink_halt_poll_ns() | - | function. | --------------------------------------------------------------------------------- ++-----------------------+---------------------------+-------------------------+ +|Module Parameter | Description | Default Value | ++-----------------------+---------------------------+-------------------------+ +|halt_poll_ns | The global max polling | KVM_HALT_POLL_NS_DEFAULT| +| | interval which defines | | +| | the ceiling value of the | | +| | polling interval for | (per arch value) | +| | each vcpu. | | ++-----------------------+---------------------------+-------------------------+ +|halt_poll_ns_grow | The value by which the | 2 | +| | halt polling interval is | | +| | multiplied in the | | +| | grow_halt_poll_ns() | | +| | function. | | ++-----------------------+---------------------------+-------------------------+ +|halt_poll_ns_grow_start| The initial value to grow | 10000 | +| | to from zero in the | | +| | grow_halt_poll_ns() | | +| | function. | | ++-----------------------+---------------------------+-------------------------+ +|halt_poll_ns_shrink | The value by which the | 0 | +| | halt polling interval is | | +| | divided in the | | +| | shrink_halt_poll_ns() | | +| | function. | | ++-----------------------+---------------------------+-------------------------+ These module parameters can be set from the debugfs files in: @@ -117,20 +120,19 @@ Note: that these module parameters are system wide values and are not able to Further Notes ============= -- Care should be taken when setting the halt_poll_ns module parameter as a -large value has the potential to drive the cpu usage to 100% on a machine which -would be almost entirely idle otherwise. This is because even if a guest has -wakeups during which very little work is done and which are quite far apart, if -the period is shorter than the global max polling interval (halt_poll_ns) then -the host will always poll for the entire block time and thus cpu utilisation -will go to 100%. +- Care should be taken when setting the halt_poll_ns module parameter as a large value + has the potential to drive the cpu usage to 100% on a machine which would be almost + entirely idle otherwise. This is because even if a guest has wakeups during which very + little work is done and which are quite far apart, if the period is shorter than the + global max polling interval (halt_poll_ns) then the host will always poll for the + entire block time and thus cpu utilisation will go to 100%. -- Halt polling essentially presents a trade off between power usage and latency -and the module parameters should be used to tune the affinity for this. Idle -cpu time is essentially converted to host kernel time with the aim of decreasing -latency when entering the guest. +- Halt polling essentially presents a trade off between power usage and latency and + the module parameters should be used to tune the affinity for this. Idle cpu time is + essentially converted to host kernel time with the aim of decreasing latency when + entering the guest. -- Halt polling will only be conducted by the host when no other tasks are -runnable on that cpu, otherwise the polling will cease immediately and -schedule will be invoked to allow that other task to run. Thus this doesn't -allow a guest to denial of service the cpu. +- Halt polling will only be conducted by the host when no other tasks are runnable on + that cpu, otherwise the polling will cease immediately and schedule will be invoked to + allow that other task to run. Thus this doesn't allow a guest to denial of service the + cpu. diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index 488c6370a447..b39f4894b61d 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -9,6 +9,7 @@ KVM amd-memory-encryption cpuid + halt-polling vcpu-requests arm/index From patchwork Tue Jan 28 14:00:07 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354349 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 4B6FF14E3 for ; Tue, 28 Jan 2020 14:01:12 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 2A6CA24685 for ; Tue, 28 Jan 2020 14:01:12 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220072; bh=Y5aV3hZGIyPek7EfsIo9rePy4FvllvoqLQ1StFaYEGQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=Rfc3D0rx4P+Hqx3yizonegG0CXdstlAndxdRFVK4N5oBWsJ1AQByYvc9dZ9fC241P wAEQeWSFjAWFVS7NCYIB5qv4VjqScdcHlu0ZpPXpmUxHudche7tr8X6QKwrvKmKDIH 4UEQWeJImItEIWSKsPpkx5rny4PNT/UJMTWeeayo= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727368AbgA1OBJ (ORCPT ); Tue, 28 Jan 2020 09:01:09 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59450 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727311AbgA1OAr (ORCPT ); Tue, 28 Jan 2020 09:00:47 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=O3Bsu4uD9UgtNB0QQELv28C8SHkVh8CCN2pYgVVPZ10=; b=I0e2f7UEc79N0R0e+SyV3a4k27 Jhspr8AL1tInGYrZ8JjTBVPQtfOaKY2XaSNFqf4YN7m15p/L8/p6Nbbb0/yVnNi8ZlqUPVJ0lP2wK IBv9BKo3MFlg/Oj9f6cPKONdSGK27BdrspYv2anEIzwH+wNzvtJ+UNoJj9Pxw21dNmLX765CTSbMn ryFYXBvJ3jK4qWWcbJ0EpxsA1yWpBxsH5rEIhNsSx93JDtcyNlSCZgNAamDB59mgQbvRZImDzLE7y zzneoKH8qQUyLUtsaqEiRFMS4kDvKc/0ijPCke3dMLPFGWoJAsa8i3KINZnj+brjGH7qklYO5BcuP htt730EQ==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007ik-G8; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BNf-CM; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 06/27] docs: virt: Convert msr.txt to ReST format Date: Tue, 28 Jan 2020 15:00:07 +0100 Message-Id: <00eb6bb2ec51ac985360c5231fc416342c2782df.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use document title markup; - Convert tables; - Add blank lines and adjust indentation. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/index.rst | 1 + Documentation/virt/kvm/{msr.txt => msr.rst} | 145 ++++++++++++-------- 2 files changed, 91 insertions(+), 55 deletions(-) rename Documentation/virt/kvm/{msr.txt => msr.rst} (75%) diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index b39f4894b61d..cc6dde47b267 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -10,6 +10,7 @@ KVM amd-memory-encryption cpuid halt-polling + msr vcpu-requests arm/index diff --git a/Documentation/virt/kvm/msr.txt b/Documentation/virt/kvm/msr.rst similarity index 75% rename from Documentation/virt/kvm/msr.txt rename to Documentation/virt/kvm/msr.rst index df1f4338b3ca..952ac339765b 100644 --- a/Documentation/virt/kvm/msr.txt +++ b/Documentation/virt/kvm/msr.rst @@ -1,6 +1,8 @@ -KVM-specific MSRs. -Glauber Costa , Red Hat Inc, 2010 -===================================================== +================= +KVM-specific MSRs +================= + +:Author: Glauber Costa , Red Hat Inc, 2010 KVM makes use of some custom MSRs to service some requests. @@ -9,34 +11,39 @@ Custom MSRs have a range reserved for them, that goes from but they are deprecated and their use is discouraged. Custom MSR list --------- +--------------- The current supported Custom MSR list is: -MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00 +MSR_KVM_WALL_CLOCK_NEW: + 0x4b564d00 - data: 4-byte alignment physical address of a memory area which must be +data: + 4-byte alignment physical address of a memory area which must be in guest RAM. This memory is expected to hold a copy of the following - structure: + structure:: - struct pvclock_wall_clock { + struct pvclock_wall_clock { u32 version; u32 sec; u32 nsec; - } __attribute__((__packed__)); + } __attribute__((__packed__)); whose data will be filled in by the hypervisor. The hypervisor is only guaranteed to update this data at the moment of MSR write. Users that want to reliably query this information more than once have to write more than once to this MSR. Fields have the following meanings: - version: guest has to check version before and after grabbing + version: + guest has to check version before and after grabbing time information and check that they are both equal and even. An odd version indicates an in-progress update. - sec: number of seconds for wallclock at time of boot. + sec: + number of seconds for wallclock at time of boot. - nsec: number of nanoseconds for wallclock at time of boot. + nsec: + number of nanoseconds for wallclock at time of boot. In order to get the current wallclock time, the system_time from MSR_KVM_SYSTEM_TIME_NEW needs to be added. @@ -47,13 +54,15 @@ MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00 Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid leaf prior to usage. -MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 +MSR_KVM_SYSTEM_TIME_NEW: + 0x4b564d01 - data: 4-byte aligned physical address of a memory area which must be in +data: + 4-byte aligned physical address of a memory area which must be in guest RAM, plus an enable bit in bit 0. This memory is expected to hold - a copy of the following structure: + a copy of the following structure:: - struct pvclock_vcpu_time_info { + struct pvclock_vcpu_time_info { u32 version; u32 pad0; u64 tsc_timestamp; @@ -62,7 +71,7 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 s8 tsc_shift; u8 flags; u8 pad[2]; - } __attribute__((__packed__)); /* 32 bytes */ + } __attribute__((__packed__)); /* 32 bytes */ whose data will be filled in by the hypervisor periodically. Only one write, or registration, is needed for each VCPU. The interval between @@ -72,23 +81,28 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 Fields have the following meanings: - version: guest has to check version before and after grabbing + version: + guest has to check version before and after grabbing time information and check that they are both equal and even. An odd version indicates an in-progress update. - tsc_timestamp: the tsc value at the current VCPU at the time + tsc_timestamp: + the tsc value at the current VCPU at the time of the update of this structure. Guests can subtract this value from current tsc to derive a notion of elapsed time since the structure update. - system_time: a host notion of monotonic time, including sleep + system_time: + a host notion of monotonic time, including sleep time at the time this structure was last updated. Unit is nanoseconds. - tsc_to_system_mul: multiplier to be used when converting + tsc_to_system_mul: + multiplier to be used when converting tsc-related quantity to nanoseconds - tsc_shift: shift to be used when converting tsc-related + tsc_shift: + shift to be used when converting tsc-related quantity to nanoseconds. This shift will ensure that multiplication with tsc_to_system_mul does not overflow. A positive value denotes a left shift, a negative value @@ -96,7 +110,7 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 The conversion from tsc to nanoseconds involves an additional right shift by 32 bits. With this information, guests can - derive per-CPU time by doing: + derive per-CPU time by doing:: time = (current_tsc - tsc_timestamp) if (tsc_shift >= 0) @@ -106,29 +120,34 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 time = (time * tsc_to_system_mul) >> 32 time = time + system_time - flags: bits in this field indicate extended capabilities + flags: + bits in this field indicate extended capabilities coordinated between the guest and the hypervisor. Availability of specific flags has to be checked in 0x40000001 cpuid leaf. Current flags are: - flag bit | cpuid bit | meaning - ------------------------------------------------------------- - | | time measures taken across - 0 | 24 | multiple cpus are guaranteed to - | | be monotonic - ------------------------------------------------------------- - | | guest vcpu has been paused by - 1 | N/A | the host - | | See 4.70 in api.txt - ------------------------------------------------------------- + + +-----------+--------------+----------------------------------+ + | flag bit | cpuid bit | meaning | + +-----------+--------------+----------------------------------+ + | | | time measures taken across | + | 0 | 24 | multiple cpus are guaranteed to | + | | | be monotonic | + +-----------+--------------+----------------------------------+ + | | | guest vcpu has been paused by | + | 1 | N/A | the host | + | | | See 4.70 in api.txt | + +-----------+--------------+----------------------------------+ Availability of this MSR must be checked via bit 3 in 0x4000001 cpuid leaf prior to usage. -MSR_KVM_WALL_CLOCK: 0x11 +MSR_KVM_WALL_CLOCK: + 0x11 - data and functioning: same as MSR_KVM_WALL_CLOCK_NEW. Use that instead. +data and functioning: + same as MSR_KVM_WALL_CLOCK_NEW. Use that instead. This MSR falls outside the reserved KVM range and may be removed in the future. Its usage is deprecated. @@ -136,9 +155,11 @@ MSR_KVM_WALL_CLOCK: 0x11 Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid leaf prior to usage. -MSR_KVM_SYSTEM_TIME: 0x12 +MSR_KVM_SYSTEM_TIME: + 0x12 - data and functioning: same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead. +data and functioning: + same as MSR_KVM_SYSTEM_TIME_NEW. Use that instead. This MSR falls outside the reserved KVM range and may be removed in the future. Its usage is deprecated. @@ -146,7 +167,7 @@ MSR_KVM_SYSTEM_TIME: 0x12 Availability of this MSR must be checked via bit 0 in 0x4000001 cpuid leaf prior to usage. - The suggested algorithm for detecting kvmclock presence is then: + The suggested algorithm for detecting kvmclock presence is then:: if (!kvm_para_available()) /* refer to cpuid.txt */ return NON_PRESENT; @@ -163,8 +184,11 @@ MSR_KVM_SYSTEM_TIME: 0x12 } else return NON_PRESENT; -MSR_KVM_ASYNC_PF_EN: 0x4b564d02 - data: Bits 63-6 hold 64-byte aligned physical address of a +MSR_KVM_ASYNC_PF_EN: + 0x4b564d02 + +data: + Bits 63-6 hold 64-byte aligned physical address of a 64 byte memory area which must be in guest RAM and must be zeroed. Bits 5-3 are reserved and should be zero. Bit 0 is 1 when asynchronous page faults are enabled on the vcpu 0 when @@ -200,20 +224,22 @@ MSR_KVM_ASYNC_PF_EN: 0x4b564d02 Currently type 2 APF will be always delivered on the same vcpu as type 1 was, but guest should not rely on that. -MSR_KVM_STEAL_TIME: 0x4b564d03 +MSR_KVM_STEAL_TIME: + 0x4b564d03 - data: 64-byte alignment physical address of a memory area which must be +data: + 64-byte alignment physical address of a memory area which must be in guest RAM, plus an enable bit in bit 0. This memory is expected to - hold a copy of the following structure: + hold a copy of the following structure:: - struct kvm_steal_time { + struct kvm_steal_time { __u64 steal; __u32 version; __u32 flags; __u8 preempted; __u8 u8_pad[3]; __u32 pad[11]; - } + } whose data will be filled in by the hypervisor periodically. Only one write, or registration, is needed for each VCPU. The interval between @@ -224,25 +250,32 @@ MSR_KVM_STEAL_TIME: 0x4b564d03 Fields have the following meanings: - version: a sequence counter. In other words, guest has to check + version: + a sequence counter. In other words, guest has to check this field before and after grabbing time information and make sure they are both equal and even. An odd version indicates an in-progress update. - flags: At this point, always zero. May be used to indicate + flags: + At this point, always zero. May be used to indicate changes in this structure in the future. - steal: the amount of time in which this vCPU did not run, in + steal: + the amount of time in which this vCPU did not run, in nanoseconds. Time during which the vcpu is idle, will not be reported as steal time. - preempted: indicate the vCPU who owns this struct is running or + preempted: + indicate the vCPU who owns this struct is running or not. Non-zero values mean the vCPU has been preempted. Zero means the vCPU is not preempted. NOTE, it is always zero if the the hypervisor doesn't support this field. -MSR_KVM_EOI_EN: 0x4b564d04 - data: Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0 +MSR_KVM_EOI_EN: + 0x4b564d04 + +data: + Bit 0 is 1 when PV end of interrupt is enabled on the vcpu; 0 when disabled. Bit 1 is reserved and must be zero. When PV end of interrupt is enabled (bit 0 set), bits 63-2 hold a 4-byte aligned physical address of a 4 byte memory area which must be in guest RAM and @@ -274,11 +307,13 @@ MSR_KVM_EOI_EN: 0x4b564d04 clear it using a single CPU instruction, such as test and clear, or compare and exchange. -MSR_KVM_POLL_CONTROL: 0x4b564d05 +MSR_KVM_POLL_CONTROL: + 0x4b564d05 + Control host-side polling. - data: Bit 0 enables (1) or disables (0) host-side HLT polling logic. +data: + Bit 0 enables (1) or disables (0) host-side HLT polling logic. KVM guests can request the host not to poll on HLT, for example if they are performing polling themselves. - From patchwork Tue Jan 28 14:00:08 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354459 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id C43EA1398 for ; Tue, 28 Jan 2020 14:49:38 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 99C8924688 for ; Tue, 28 Jan 2020 14:49:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580222978; bh=NUa9wOdnULSFN80KMTvTexLw0fLdLRakNVV/kz8ETNU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=xzL3oS8udZaszEY7cmu4CMibvYAVXldbLz2AkT3dKrJmzNx1UqeuiUT09aIlL0WTw hTWwat+s1YTBoAhBO6tFW6MDmJcbzDPtni4VdBf/ZnV4H7xUGsenOIIo1N9LfylP4i oxzypP8dUzFvx+XIZFtFnAVEHAeO84Ld/NHX2Zcc= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727386AbgA1OBO (ORCPT ); Tue, 28 Jan 2020 09:01:14 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59362 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727304AbgA1OAr (ORCPT ); Tue, 28 Jan 2020 09:00:47 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=cLewyjoNlj0NAqOJ/2/JgEHHKOKhNDS+TNzq9GjVM+s=; b=F82CP3TWym1rOqd5pGItFGmp6C ECE5dgZy+glq4bt83wBr4EtHrVKQmsHgCWa3TM3pSD41ACxHWN9FDcC0kbwhZghig8soTOZpEvJgZ 42pUebPmzdZYkZFy5OkaLToN8iwkeLx6UfiQ7Qqge8i5vXVG+8iXyGC4hpwn7eJ59EmtQZlQTtDJj GdpCYJMF31KvLev8T3KHfXrhKBv3mXo2HenZ/rIaL6JHRn+tbEW+izBil4jEvWPBUA0Zduk2F2qrX ATDc+Hf27dsyJJG0vUOlDYYkhd0bffEzDGIXrNC0txF1bOvIQtZ3ZkZd0XtXUkme5KXgps2nwHHJY dEJDbQjw==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007ii-WF; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BNk-DW; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 07/27] docs: kvm: devices/arm-vgic-its.txt to ReST format Date: Tue, 28 Jan 2020 15:00:08 +0100 Message-Id: <5681dbc80e10388917107f3d0b33eb90e2e4b5a3.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Fix document title to match ReST format - Convert the table to be properly recognized - use proper markups for literal blocks - Some indentation fixes to match ReST While here, add an index for kvm devices. Signed-off-by: Mauro Carvalho Chehab --- .../{arm-vgic-its.txt => arm-vgic-its.rst} | 104 +++++++++++------- Documentation/virt/kvm/devices/index.rst | 10 ++ Documentation/virt/kvm/index.rst | 1 + 3 files changed, 76 insertions(+), 39 deletions(-) rename Documentation/virt/kvm/devices/{arm-vgic-its.txt => arm-vgic-its.rst} (71%) create mode 100644 Documentation/virt/kvm/devices/index.rst diff --git a/Documentation/virt/kvm/devices/arm-vgic-its.txt b/Documentation/virt/kvm/devices/arm-vgic-its.rst similarity index 71% rename from Documentation/virt/kvm/devices/arm-vgic-its.txt rename to Documentation/virt/kvm/devices/arm-vgic-its.rst index eeaa95b893a8..4197d9d6a870 100644 --- a/Documentation/virt/kvm/devices/arm-vgic-its.txt +++ b/Documentation/virt/kvm/devices/arm-vgic-its.rst @@ -1,3 +1,4 @@ +=============================================== ARM Virtual Interrupt Translation Service (ITS) =============================================== @@ -12,22 +13,32 @@ There can be multiple ITS controllers per guest, each of them has to have a separate, non-overlapping MMIO region. -Groups: - KVM_DEV_ARM_VGIC_GRP_ADDR +Groups +====== + +KVM_DEV_ARM_VGIC_GRP_ADDR +------------------------- + Attributes: KVM_VGIC_ITS_ADDR_TYPE (rw, 64-bit) Base address in the guest physical address space of the GICv3 ITS control register frame. This address needs to be 64K aligned and the region covers 128K. + Errors: - -E2BIG: Address outside of addressable IPA range - -EINVAL: Incorrectly aligned address - -EEXIST: Address already configured - -EFAULT: Invalid user pointer for attr->addr. - -ENODEV: Incorrect attribute or the ITS is not supported. + ======= ================================================= + -E2BIG Address outside of addressable IPA range + -EINVAL Incorrectly aligned address + -EEXIST Address already configured + -EFAULT Invalid user pointer for attr->addr. + -ENODEV Incorrect attribute or the ITS is not supported. + ======= ================================================= + + +KVM_DEV_ARM_VGIC_GRP_CTRL +------------------------- - KVM_DEV_ARM_VGIC_GRP_CTRL Attributes: KVM_DEV_ARM_VGIC_CTRL_INIT request the initialization of the ITS, no additional parameter in @@ -58,16 +69,21 @@ Groups: "ITS Restore Sequence". Errors: - -ENXIO: ITS not properly configured as required prior to setting + + ======= ========================================================== + -ENXIO ITS not properly configured as required prior to setting this attribute - -ENOMEM: Memory shortage when allocating ITS internal data - -EINVAL: Inconsistent restored data - -EFAULT: Invalid guest ram access - -EBUSY: One or more VCPUS are running - -EACCES: The virtual ITS is backed by a physical GICv4 ITS, and the + -ENOMEM Memory shortage when allocating ITS internal data + -EINVAL Inconsistent restored data + -EFAULT Invalid guest ram access + -EBUSY One or more VCPUS are running + -EACCES The virtual ITS is backed by a physical GICv4 ITS, and the state is not available + ======= ========================================================== + +KVM_DEV_ARM_VGIC_GRP_ITS_REGS +----------------------------- - KVM_DEV_ARM_VGIC_GRP_ITS_REGS Attributes: The attr field of kvm_device_attr encodes the offset of the ITS register, relative to the ITS control frame base address @@ -78,6 +94,7 @@ Groups: be accessed with full length. Writes to read-only registers are ignored by the kernel except for: + - GITS_CREADR. It must be restored otherwise commands in the queue will be re-executed after restoring CWRITER. GITS_CREADR must be restored before restoring the GITS_CTLR which is likely to enable the @@ -91,30 +108,36 @@ Groups: For other registers, getting or setting a register has the same effect as reading/writing the register on real hardware. + Errors: - -ENXIO: Offset does not correspond to any supported register - -EFAULT: Invalid user pointer for attr->addr - -EINVAL: Offset is not 64-bit aligned - -EBUSY: one or more VCPUS are running - ITS Restore Sequence: - ------------------------- + ======= ==================================================== + -ENXIO Offset does not correspond to any supported register + -EFAULT Invalid user pointer for attr->addr + -EINVAL Offset is not 64-bit aligned + -EBUSY one or more VCPUS are running + ======= ==================================================== + +ITS Restore Sequence: +--------------------- The following ordering must be followed when restoring the GIC and the ITS: + a) restore all guest memory and create vcpus b) restore all redistributors c) provide the ITS base address (KVM_DEV_ARM_VGIC_GRP_ADDR) d) restore the ITS in the following order: - 1. Restore GITS_CBASER - 2. Restore all other GITS_ registers, except GITS_CTLR! - 3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES) - 4. Restore GITS_CTLR + + 1. Restore GITS_CBASER + 2. Restore all other ``GITS_`` registers, except GITS_CTLR! + 3. Load the ITS table data (KVM_DEV_ARM_ITS_RESTORE_TABLES) + 4. Restore GITS_CTLR Then vcpus can be started. - ITS Table ABI REV0: - ------------------- +ITS Table ABI REV0: +------------------- Revision 0 of the ABI only supports the features of a virtual GICv3, and does not support a virtual GICv4 with support for direct injection of virtual @@ -125,12 +148,13 @@ Then vcpus can be started. entries in the collection are listed in no particular order. All entries are 8 bytes. - Device Table Entry (DTE): + Device Table Entry (DTE):: - bits: | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 | - values: | V | next | ITT_addr | Size | + bits: | 63| 62 ... 49 | 48 ... 5 | 4 ... 0 | + values: | V | next | ITT_addr | Size | + + where: - where; - V indicates whether the entry is valid. If not, other fields are not meaningful. - next: equals to 0 if this entry is the last one; otherwise it @@ -140,32 +164,34 @@ Then vcpus can be started. - Size specifies the supported number of bits for the EventID, minus one - Collection Table Entry (CTE): + Collection Table Entry (CTE):: - bits: | 63| 62 .. 52 | 51 ... 16 | 15 ... 0 | - values: | V | RES0 | RDBase | ICID | + bits: | 63| 62 .. 52 | 51 ... 16 | 15 ... 0 | + values: | V | RES0 | RDBase | ICID | where: + - V indicates whether the entry is valid. If not, other fields are not meaningful. - RES0: reserved field with Should-Be-Zero-or-Preserved behavior. - RDBase is the PE number (GICR_TYPER.Processor_Number semantic), - ICID is the collection ID - Interrupt Translation Entry (ITE): + Interrupt Translation Entry (ITE):: - bits: | 63 ... 48 | 47 ... 16 | 15 ... 0 | - values: | next | pINTID | ICID | + bits: | 63 ... 48 | 47 ... 16 | 15 ... 0 | + values: | next | pINTID | ICID | where: + - next: equals to 0 if this entry is the last one; otherwise it corresponds to the EventID offset to the next ITE capped by 2^16 -1. - pINTID is the physical LPI ID; if zero, it means the entry is not valid and other fields are not meaningful. - ICID is the collection ID - ITS Reset State: - ---------------- +ITS Reset State: +---------------- RESET returns the ITS to the same state that it was when first created and initialized. When the RESET command returns, the following things are diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst new file mode 100644 index 000000000000..2aad8d426097 --- /dev/null +++ b/Documentation/virt/kvm/devices/index.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +Devices +======= + +.. toctree:: + :maxdepth: 2 + + arm-vgic-its diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index cc6dde47b267..24d1076ec680 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -14,3 +14,4 @@ KVM vcpu-requests arm/index + devices/index From patchwork Tue Jan 28 14:00:09 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354325 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id A55DF14B4 for ; Tue, 28 Jan 2020 14:00:54 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 7B07C2468E for ; Tue, 28 Jan 2020 14:00:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220054; bh=8ZS/6n8J5UB5wubzZ7z35fAmP7GS0V68re8Wr+VDze8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=SmLwS8iNkg/v4nOpf6ORtJDiELHb+vdSnF1VSUrsOpOJqJ+3VPe9w9VfWrdAJMuHa KRlAu5bDlbIDAc/MlrafcNEd1hIJ8cj9b/6e2ax31/RGjhDO7ar5Up0/LYjwG4BZwL v6Sum3S97TvVq8gPQNcm4Cge4mmO1dEt1ufMUXc0= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727348AbgA1OAt (ORCPT ); Tue, 28 Jan 2020 09:00:49 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59418 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727306AbgA1OAr (ORCPT ); Tue, 28 Jan 2020 09:00:47 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=47knvKP2hkOqYj0lWrn/u5a+ztvae81C4pMTyKp2WE4=; b=qv6nbjlQmpV9D0gQtQlJLKkXio klniMlQpj/3q2O56PvvRtTdG6KxobJfOEPbh+CMHI2Jhj6LdDOaXPtx8fk8PO40Ay1KgzD4dqWhC2 wvjOjOUwYskxfjmL2yGzI7kiX++7xVYxeKfwxG0hMBf5jgPSYp3thtaEHJxgwF1ZqQt8M/wko5efC wvTzI+8L2UNbCh4Kb88/vbF1kft4wUiyxOfGkkykfnTIHyknpn1CC4TSBe2+eC5B9NcxCkrgcAa2j dhwn1vaTYhQgcHOXU2WwOgPjUr7IgpQ4CCVjjDm77YQ4JUP9enL+gCCt3vMpwHvHJsqb2Q8yUf82v X5LV+RNA==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007if-Ey; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BNp-EV; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 08/27] docs: kvm: devices/arm-vgit-v3.txt to ReST Date: Tue, 28 Jan 2020 15:00:09 +0100 Message-Id: <20d4b1a9338c37ef127e3d1801c1d14f8353b9f0.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use title markups; - change indent to match ReST syntax; - use proper table markups; - use literal block markups. Signed-off-by: Mauro Carvalho Chehab --- .../{arm-vgic-v3.txt => arm-vgic-v3.rst} | 130 +++++++++++------- Documentation/virt/kvm/devices/index.rst | 1 + 2 files changed, 85 insertions(+), 46 deletions(-) rename Documentation/virt/kvm/devices/{arm-vgic-v3.txt => arm-vgic-v3.rst} (77%) diff --git a/Documentation/virt/kvm/devices/arm-vgic-v3.txt b/Documentation/virt/kvm/devices/arm-vgic-v3.rst similarity index 77% rename from Documentation/virt/kvm/devices/arm-vgic-v3.txt rename to Documentation/virt/kvm/devices/arm-vgic-v3.rst index ff290b43c8e5..1a64644d1a43 100644 --- a/Documentation/virt/kvm/devices/arm-vgic-v3.txt +++ b/Documentation/virt/kvm/devices/arm-vgic-v3.rst @@ -1,9 +1,10 @@ +============================================================== ARM Virtual Generic Interrupt Controller v3 and later (VGICv3) ============================================================== Device types supported: - KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0 + - KVM_DEV_TYPE_ARM_VGIC_V3 ARM Generic Interrupt Controller v3.0 Only one VGIC instance may be instantiated through this API. The created VGIC will act as the VM interrupt controller, requiring emulated user-space devices @@ -15,7 +16,8 @@ Creating a guest GICv3 device requires a host GICv3 as well. Groups: KVM_DEV_ARM_VGIC_GRP_ADDR - Attributes: + Attributes: + KVM_VGIC_V3_ADDR_TYPE_DIST (rw, 64-bit) Base address in the guest physical address space of the GICv3 distributor register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. @@ -29,21 +31,25 @@ Groups: This address needs to be 64K aligned. KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION (rw, 64-bit) - The attribute data pointed to by kvm_device_attr.addr is a __u64 value: - bits: | 63 .... 52 | 51 .... 16 | 15 - 12 |11 - 0 - values: | count | base | flags | index + The attribute data pointed to by kvm_device_attr.addr is a __u64 value:: + + bits: | 63 .... 52 | 51 .... 16 | 15 - 12 |11 - 0 + values: | count | base | flags | index + - index encodes the unique redistributor region index - flags: reserved for future use, currently 0 - base field encodes bits [51:16] of the guest physical base address of the first redistributor in the region. - count encodes the number of redistributors in the region. Must be greater than 0. + There are two 64K pages for each redistributor in the region and redistributors are laid out contiguously within the region. Regions are filled with redistributors in the index order. The sum of all region count fields must be greater than or equal to the number of VCPUs. Redistributor regions must be registered in the incremental index order, starting from index 0. + The characteristics of a specific redistributor region can be read by presetting the index field in the attr data. Only valid for KVM_DEV_TYPE_ARM_VGIC_V3. @@ -52,23 +58,27 @@ Groups: KVM_VGIC_V3_ADDR_TYPE_REDIST_REGION attributes. Errors: - -E2BIG: Address outside of addressable IPA range - -EINVAL: Incorrectly aligned address, bad redistributor region + + ======= ============================================================= + -E2BIG Address outside of addressable IPA range + -EINVAL Incorrectly aligned address, bad redistributor region count/index, mixed redistributor region attribute usage - -EEXIST: Address already configured - -ENOENT: Attempt to read the characteristics of a non existing + -EEXIST Address already configured + -ENOENT Attempt to read the characteristics of a non existing redistributor region - -ENXIO: The group or attribute is unknown/unsupported for this device + -ENXIO The group or attribute is unknown/unsupported for this device or hardware support is missing. - -EFAULT: Invalid user pointer for attr->addr. + -EFAULT Invalid user pointer for attr->addr. + ======= ============================================================= - KVM_DEV_ARM_VGIC_GRP_DIST_REGS - KVM_DEV_ARM_VGIC_GRP_REDIST_REGS - Attributes: - The attr field of kvm_device_attr encodes two values: - bits: | 63 .... 32 | 31 .... 0 | - values: | mpidr | offset | + KVM_DEV_ARM_VGIC_GRP_DIST_REGS, KVM_DEV_ARM_VGIC_GRP_REDIST_REGS + Attributes: + + The attr field of kvm_device_attr encodes two values:: + + bits: | 63 .... 32 | 31 .... 0 | + values: | mpidr | offset | All distributor regs are (rw, 32-bit) and kvm_device_attr.addr points to a __u32 value. 64-bit registers must be accessed by separately accessing the @@ -93,7 +103,8 @@ Groups: redistributor is accessed. The mpidr is ignored for the distributor. The mpidr encoding is based on the affinity information in the - architecture defined MPIDR, and the field is encoded as follows: + architecture defined MPIDR, and the field is encoded as follows:: + | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | | Aff3 | Aff2 | Aff1 | Aff0 | @@ -148,24 +159,30 @@ Groups: ignored. Errors: - -ENXIO: Getting or setting this register is not yet supported - -EBUSY: One or more VCPUs are running + + ====== ===================================================== + -ENXIO Getting or setting this register is not yet supported + -EBUSY One or more VCPUs are running + ====== ===================================================== KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS - Attributes: - The attr field of kvm_device_attr encodes two values: - bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 | - values: | mpidr | RES | instr | + Attributes: + + The attr field of kvm_device_attr encodes two values:: + + bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 | + values: | mpidr | RES | instr | The mpidr field encodes the CPU ID based on the affinity information in the - architecture defined MPIDR, and the field is encoded as follows: + architecture defined MPIDR, and the field is encoded as follows:: + | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | | Aff3 | Aff2 | Aff1 | Aff0 | The instr field encodes the system register to access based on the fields defined in the A64 instruction set encoding for system register access - (RES means the bits are reserved for future use and should be zero): + (RES means the bits are reserved for future use and should be zero):: | 15 ... 14 | 13 ... 11 | 10 ... 7 | 6 ... 3 | 2 ... 0 | | Op 0 | Op1 | CRn | CRm | Op2 | @@ -178,26 +195,35 @@ Groups: CPU interface registers access is not implemented for AArch32 mode. Error -ENXIO is returned when accessed in AArch32 mode. + Errors: - -ENXIO: Getting or setting this register is not yet supported - -EBUSY: VCPU is running - -EINVAL: Invalid mpidr or register value supplied + + ======= ===================================================== + -ENXIO Getting or setting this register is not yet supported + -EBUSY VCPU is running + -EINVAL Invalid mpidr or register value supplied + ======= ===================================================== KVM_DEV_ARM_VGIC_GRP_NR_IRQS - Attributes: + Attributes: + A value describing the number of interrupts (SGI, PPI and SPI) for this GIC instance, ranging from 64 to 1024, in increments of 32. kvm_device_attr.addr points to a __u32 value. Errors: - -EINVAL: Value set is out of the expected range - -EBUSY: Value has already be set. + + ======= ====================================== + -EINVAL Value set is out of the expected range + -EBUSY Value has already be set. + ======= ====================================== KVM_DEV_ARM_VGIC_GRP_CTRL - Attributes: + Attributes: + KVM_DEV_ARM_VGIC_CTRL_INIT request the initialization of the VGIC, no additional parameter in kvm_device_attr.addr. @@ -205,20 +231,26 @@ Groups: save all LPI pending bits into guest RAM pending tables. The first kB of the pending table is not altered by this operation. + Errors: - -ENXIO: VGIC not properly configured as required prior to calling - this attribute - -ENODEV: no online VCPU - -ENOMEM: memory shortage when allocating vgic internal data - -EFAULT: Invalid guest ram access - -EBUSY: One or more VCPUS are running + + ======= ======================================================== + -ENXIO VGIC not properly configured as required prior to calling + this attribute + -ENODEV no online VCPU + -ENOMEM memory shortage when allocating vgic internal data + -EFAULT Invalid guest ram access + -EBUSY One or more VCPUS are running + ======= ======================================================== KVM_DEV_ARM_VGIC_GRP_LEVEL_INFO - Attributes: - The attr field of kvm_device_attr encodes the following values: - bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 | - values: | mpidr | info | vINTID | + Attributes: + + The attr field of kvm_device_attr encodes the following values:: + + bits: | 63 .... 32 | 31 .... 10 | 9 .... 0 | + values: | mpidr | info | vINTID | The vINTID specifies which set of IRQs is reported on. @@ -228,6 +260,7 @@ Groups: VGIC_LEVEL_INFO_LINE_LEVEL: Get/Set the input level of the IRQ line for a set of 32 contiguously numbered interrupts. + vINTID must be a multiple of 32. kvm_device_attr.addr points to a __u32 value which will contain a @@ -243,9 +276,14 @@ Groups: reported with the same value regardless of the mpidr specified. The mpidr field encodes the CPU ID based on the affinity information in the - architecture defined MPIDR, and the field is encoded as follows: + architecture defined MPIDR, and the field is encoded as follows:: + | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | | Aff3 | Aff2 | Aff1 | Aff0 | + Errors: - -EINVAL: vINTID is not multiple of 32 or - info field is not VGIC_LEVEL_INFO_LINE_LEVEL + + ======= ============================================= + -EINVAL vINTID is not multiple of 32 or info field is + not VGIC_LEVEL_INFO_LINE_LEVEL + ======= ============================================= diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst index 2aad8d426097..80c1e0e225f4 100644 --- a/Documentation/virt/kvm/devices/index.rst +++ b/Documentation/virt/kvm/devices/index.rst @@ -8,3 +8,4 @@ Devices :maxdepth: 2 arm-vgic-its + arm-vgic-v3 From patchwork Tue Jan 28 14:00:10 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354479 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 573CB1398 for ; Tue, 28 Jan 2020 14:49:53 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 2DA8E24683 for ; Tue, 28 Jan 2020 14:49:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580222993; bh=NoI27l/cCtHM2oMOjtSzMqwiz1a5EKr0KHNB3L2+DUE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=Bz+CtgMqYxxU1uNOlMjje7fckAJYrC3b5o5qq8eNXBOU37CtjpPO6G/qc3zQBJpoL 9eTsjaFLx9+Bx9VxMRRr+6Aw+WqRMWvaCNvVMiZtTFBJ5ZMbbfbivq/Mb3VnJPT8w8 EV7udkK0cUr6+PKHUUAAdSHlbi26QSGPfdyEgwY4= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727224AbgA1Otw (ORCPT ); Tue, 28 Jan 2020 09:49:52 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59288 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727285AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=BCH2exYpaTXxc+kQslPFBsbgIXC7remIkotVPujXUxc=; b=u8XTUhmGA2bFEcFdqnn+WUlgkh qfKkyu2iGKzOQfmkY5Ak8KYJOripGOY1cDy6qDcwxyzxOMNjBxA2pP75O+TuKKzZpmsMDqv+j7Vbh a6bGpoYyu1iFcM/IZ52PUYbt0xlzRf9OjWHWpjmBGyzpNQWkCpaeyhBIusu0u4uMZ5eGZFvN2ga9K T3SI8RmHSJ0fRhFSxUYT9QxF2vzOykn/YsrGVeeGZfFOqLdQ8FFh/ELcLkcPVKllsZfOsu6m4u68a ATDiREnvVseD/EMEpkzG2O+912y/oTu9H3i7n2Vl5UI/X7S2wz9rNjD6WMhVXJM+XkBHWC+xxPwva w6JG2vHw==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007ig-Vl; Tue, 28 Jan 2020 14:00:45 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BNu-G0; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 09/27] docs: kvm: convert devices/arm-vgit.txt to ReST Date: Tue, 28 Jan 2020 15:00:10 +0100 Message-Id: X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use title markups; - change indent to match ReST syntax; - use proper table markups; - use literal block markups. Signed-off-by: Mauro Carvalho Chehab --- .../devices/{arm-vgic.txt => arm-vgic.rst} | 87 ++++++++++++------- Documentation/virt/kvm/devices/index.rst | 1 + 2 files changed, 58 insertions(+), 30 deletions(-) rename Documentation/virt/kvm/devices/{arm-vgic.txt => arm-vgic.rst} (66%) diff --git a/Documentation/virt/kvm/devices/arm-vgic.txt b/Documentation/virt/kvm/devices/arm-vgic.rst similarity index 66% rename from Documentation/virt/kvm/devices/arm-vgic.txt rename to Documentation/virt/kvm/devices/arm-vgic.rst index 97b6518148f8..882a7ecf317e 100644 --- a/Documentation/virt/kvm/devices/arm-vgic.txt +++ b/Documentation/virt/kvm/devices/arm-vgic.rst @@ -1,8 +1,10 @@ +================================================== ARM Virtual Generic Interrupt Controller v2 (VGIC) ================================================== Device types supported: - KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0 + + - KVM_DEV_TYPE_ARM_VGIC_V2 ARM Generic Interrupt Controller v2.0 Only one VGIC instance may be instantiated through either this API or the legacy KVM_CREATE_IRQCHIP API. The created VGIC will act as the VM interrupt @@ -17,7 +19,8 @@ create both a GICv3 and GICv2 device on the same VM. Groups: KVM_DEV_ARM_VGIC_GRP_ADDR - Attributes: + Attributes: + KVM_VGIC_V2_ADDR_TYPE_DIST (rw, 64-bit) Base address in the guest physical address space of the GIC distributor register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2. @@ -27,19 +30,25 @@ Groups: Base address in the guest physical address space of the GIC virtual cpu interface register mappings. Only valid for KVM_DEV_TYPE_ARM_VGIC_V2. This address needs to be 4K aligned and the region covers 4 KByte. + Errors: - -E2BIG: Address outside of addressable IPA range - -EINVAL: Incorrectly aligned address - -EEXIST: Address already configured - -ENXIO: The group or attribute is unknown/unsupported for this device + + ======= ============================================================= + -E2BIG Address outside of addressable IPA range + -EINVAL Incorrectly aligned address + -EEXIST Address already configured + -ENXIO The group or attribute is unknown/unsupported for this device or hardware support is missing. - -EFAULT: Invalid user pointer for attr->addr. + -EFAULT Invalid user pointer for attr->addr. + ======= ============================================================= KVM_DEV_ARM_VGIC_GRP_DIST_REGS - Attributes: - The attr field of kvm_device_attr encodes two values: - bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | - values: | reserved | vcpu_index | offset | + Attributes: + + The attr field of kvm_device_attr encodes two values:: + + bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | + values: | reserved | vcpu_index | offset | All distributor regs are (rw, 32-bit) @@ -58,16 +67,22 @@ Groups: KVM_DEV_ARM_VGIC_GRP_DIST_REGS and KVM_DEV_ARM_VGIC_GRP_CPU_REGS) to ensure the expected behavior. Unless GICD_IIDR has been set from userspace, writes to the interrupt group registers (GICD_IGROUPR) are ignored. + Errors: - -ENXIO: Getting or setting this register is not yet supported - -EBUSY: One or more VCPUs are running - -EINVAL: Invalid vcpu_index supplied + + ======= ===================================================== + -ENXIO Getting or setting this register is not yet supported + -EBUSY One or more VCPUs are running + -EINVAL Invalid vcpu_index supplied + ======= ===================================================== KVM_DEV_ARM_VGIC_GRP_CPU_REGS - Attributes: - The attr field of kvm_device_attr encodes two values: - bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | - values: | reserved | vcpu_index | offset | + Attributes: + + The attr field of kvm_device_attr encodes two values:: + + bits: | 63 .... 40 | 39 .. 32 | 31 .... 0 | + values: | reserved | vcpu_index | offset | All CPU interface regs are (rw, 32-bit) @@ -101,27 +116,39 @@ Groups: value left by 3 places to obtain the actual priority mask level. Errors: - -ENXIO: Getting or setting this register is not yet supported - -EBUSY: One or more VCPUs are running - -EINVAL: Invalid vcpu_index supplied + + ======= ===================================================== + -ENXIO Getting or setting this register is not yet supported + -EBUSY One or more VCPUs are running + -EINVAL Invalid vcpu_index supplied + ======= ===================================================== KVM_DEV_ARM_VGIC_GRP_NR_IRQS - Attributes: + Attributes: + A value describing the number of interrupts (SGI, PPI and SPI) for this GIC instance, ranging from 64 to 1024, in increments of 32. Errors: - -EINVAL: Value set is out of the expected range - -EBUSY: Value has already be set, or GIC has already been initialized - with default values. + + ======= ============================================================= + -EINVAL Value set is out of the expected range + -EBUSY Value has already be set, or GIC has already been initialized + with default values. + ======= ============================================================= KVM_DEV_ARM_VGIC_GRP_CTRL - Attributes: + Attributes: + KVM_DEV_ARM_VGIC_CTRL_INIT request the initialization of the VGIC or ITS, no additional parameter in kvm_device_attr.addr. + Errors: - -ENXIO: VGIC not properly configured as required prior to calling - this attribute - -ENODEV: no online VCPU - -ENOMEM: memory shortage when allocating vgic internal data + + ======= ========================================================= + -ENXIO VGIC not properly configured as required prior to calling + this attribute + -ENODEV no online VCPU + -ENOMEM memory shortage when allocating vgic internal data + ======= ========================================================= diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst index 80c1e0e225f4..7eabce80c61e 100644 --- a/Documentation/virt/kvm/devices/index.rst +++ b/Documentation/virt/kvm/devices/index.rst @@ -8,4 +8,5 @@ Devices :maxdepth: 2 arm-vgic-its + arm-vgic arm-vgic-v3 From patchwork Tue Jan 28 14:00:11 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354491 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 2B3C213A4 for ; Tue, 28 Jan 2020 14:50:02 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 0952E207FD for ; Tue, 28 Jan 2020 14:50:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580223002; bh=4KbYRGFqJZ7ieywXsFZMMJVdhzIfilUrd/qsaKkEEAQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=okWCoy1+EfPYwbJJ020yZhNuW80LH0kIN4cqf6SAf1h0875WP8p/wyLtyxYivLb8t 5YNC9F+hped/OvjwXNjIQ8vedcnTZLe4i4v1X/R2o3ZLHCIdpV7k1ICLgmHxa8EjSR TXmcq1pGIfUFHgmXukxIalxAY0LDabTWbCZKazTY= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727219AbgA1OuA (ORCPT ); Tue, 28 Jan 2020 09:50:00 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59280 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727140AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=H1nRRjrZGeu/PASJbR2ix7tpTPDW4y35R3IZ+NkvAB8=; b=lMc7rGguapyL8NhwV4j/uuQM0t p89ipN0XtzsMKNDMc6Z3dY/mtPjxFkftxHz6vUbbP533m3dHPnHQdovrJaJLx9dCWjp9r45i6kvY7 tZToXlLBQCryC+Ep5swpooGbhL3PxErelLu6IEtwzpi6eZHaXbvIPa31JzJis2VyMaCmV9FK6x/S3 LyNfBzf0ADrJqMJKZpSirulPsW7yhva9CI0PWyXZCCrpUnucYRuPqwfYoJzvLBeNUH32zJDsqZ7L4 BxYRgk8hqxva4jKxliivBVc58ac+A+i4Pyf6nsZgcvgeZkjwc/qVyU/niE0n7jdDnXU3FWyHeHxRi x39Dh7Tw==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007ie-UC; Tue, 28 Jan 2020 14:00:45 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BNz-Gu; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 10/27] docs: kvm: convert devices/mpic.txt to ReST Date: Tue, 28 Jan 2020 15:00:11 +0100 Message-Id: <11aa35fac07b299da862706325b194164548549b.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org This document is almost in ReST format. The only thing needed is to mark a list as such and to add an extra whitespace. Yet, let's also use the standard document title markup, as it makes easier if anyone wants later to add sessions to it. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/devices/index.rst | 1 + Documentation/virt/kvm/devices/{mpic.txt => mpic.rst} | 9 ++++++--- 2 files changed, 7 insertions(+), 3 deletions(-) rename Documentation/virt/kvm/devices/{mpic.txt => mpic.rst} (92%) diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst index 7eabce80c61e..9e5586e371de 100644 --- a/Documentation/virt/kvm/devices/index.rst +++ b/Documentation/virt/kvm/devices/index.rst @@ -10,3 +10,4 @@ Devices arm-vgic-its arm-vgic arm-vgic-v3 + mpic diff --git a/Documentation/virt/kvm/devices/mpic.txt b/Documentation/virt/kvm/devices/mpic.rst similarity index 92% rename from Documentation/virt/kvm/devices/mpic.txt rename to Documentation/virt/kvm/devices/mpic.rst index 8257397adc3c..571b2bc72b5e 100644 --- a/Documentation/virt/kvm/devices/mpic.txt +++ b/Documentation/virt/kvm/devices/mpic.rst @@ -1,9 +1,11 @@ +========================= MPIC interrupt controller ========================= Device types supported: - KVM_DEV_TYPE_FSL_MPIC_20 Freescale MPIC v2.0 - KVM_DEV_TYPE_FSL_MPIC_42 Freescale MPIC v4.2 + + - KVM_DEV_TYPE_FSL_MPIC_20 Freescale MPIC v2.0 + - KVM_DEV_TYPE_FSL_MPIC_42 Freescale MPIC v4.2 Only one MPIC instance, of any type, may be instantiated. The created MPIC will act as the system interrupt controller, connecting to each @@ -11,7 +13,8 @@ vcpu's interrupt inputs. Groups: KVM_DEV_MPIC_GRP_MISC - Attributes: + Attributes: + KVM_DEV_MPIC_BASE_ADDR (rw, 64-bit) Base address of the 256 KiB MPIC register space. Must be naturally aligned. A value of zero disables the mapping. From patchwork Tue Jan 28 14:00:12 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354497 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 256B31398 for ; Tue, 28 Jan 2020 14:50:07 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 03FE224683 for ; Tue, 28 Jan 2020 14:50:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580223007; bh=rbPvMROj4Jp8r5A5ZVQZZCrKLe+WvU3VXIOCB9zTPF4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=sV7R/DPSMCoej4mG6fKUFqqdCcsEqgiSKxqY1AAE5WayxP8rw97W2AH8FAI37cj+w 7LonuJWvG5jqd66v1fmhTOFUUbvNDTWfocKMRIGLFPZD+wpW34FGhLCp0zg9LI+25B O2EJ4Hp2mpPHXjlIwPfEwInIKLoPDLOgjzqRwiEs= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727258AbgA1OuE (ORCPT ); Tue, 28 Jan 2020 09:50:04 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59268 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726783AbgA1OAp (ORCPT ); Tue, 28 Jan 2020 09:00:45 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=RXe1JKO96FijdOP7zXpZboFzdx1W+5+6NP6MZ/BiAps=; b=beuEPbyeIpzelBJJ/6g1xXQxDJ qdoXbAvrO546aLL63BpdwHX/SbPhIuuZQYa1HVf83cgV/jVkUFnmb7x+rDueGKgafSvgoQYl8D6o/ cKcsb91ZVVQiqZMDae6IUXF+Nuivzn4gXqJLs86vDJpH5HuK2b3tFiVU7bm1QeBuua3aAzgCvaTW1 H9Q/JR91YYEyshXA9K+ii95nAr5X+dhZA0S+EMuNNHMpTfPLuQfd0U2ueRrlP2nLk5if/0tCQjfP5 lDiHKNBzxqkT8m27WoKrhKOf93tQ1SVp1QCxkgDOJAYU2egSFbjCJDkJTU5AC1iyEM1VGzx2RRVWs L84gTGDw==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007ic-DK; Tue, 28 Jan 2020 14:00:45 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BO4-Hu; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 11/27] docs: kvm: convert devices/s390_flic.txt to ReST Date: Tue, 28 Jan 2020 15:00:12 +0100 Message-Id: <12634be89f4a8b662bf4bc0a0c7baef42675548f.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use standard markup for document title; - Adjust indentation and add blank lines as needed; - use the notes markup; - mark code blocks as such. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Cornelia Huck --- Documentation/virt/kvm/devices/index.rst | 1 + .../devices/{s390_flic.txt => s390_flic.rst} | 68 +++++++++++-------- 2 files changed, 39 insertions(+), 30 deletions(-) rename Documentation/virt/kvm/devices/{s390_flic.txt => s390_flic.rst} (88%) diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst index 9e5586e371de..e6caccc36623 100644 --- a/Documentation/virt/kvm/devices/index.rst +++ b/Documentation/virt/kvm/devices/index.rst @@ -11,3 +11,4 @@ Devices arm-vgic arm-vgic-v3 mpic + s390_flic diff --git a/Documentation/virt/kvm/devices/s390_flic.txt b/Documentation/virt/kvm/devices/s390_flic.rst similarity index 88% rename from Documentation/virt/kvm/devices/s390_flic.txt rename to Documentation/virt/kvm/devices/s390_flic.rst index a4e20a090174..860fa0dec9b7 100644 --- a/Documentation/virt/kvm/devices/s390_flic.txt +++ b/Documentation/virt/kvm/devices/s390_flic.rst @@ -1,3 +1,4 @@ +==================================== FLIC (floating interrupt controller) ==================================== @@ -31,8 +32,10 @@ Groups: Copies all floating interrupts into a buffer provided by userspace. When the buffer is too small it returns -ENOMEM, which is the indication for userspace to try again with a bigger buffer. + -ENOBUFS is returned when the allocation of a kernelspace buffer has failed. + -EFAULT is returned when copying data to userspace failed. All interrupts remain pending, i.e. are not deleted from the list of currently pending interrupts. @@ -60,38 +63,41 @@ Groups: KVM_DEV_FLIC_ADAPTER_REGISTER Register an I/O adapter interrupt source. Takes a kvm_s390_io_adapter - describing the adapter to register: + describing the adapter to register:: -struct kvm_s390_io_adapter { - __u32 id; - __u8 isc; - __u8 maskable; - __u8 swap; - __u8 flags; -}; + struct kvm_s390_io_adapter { + __u32 id; + __u8 isc; + __u8 maskable; + __u8 swap; + __u8 flags; + }; id contains the unique id for the adapter, isc the I/O interruption subclass to use, maskable whether this adapter may be masked (interrupts turned off), swap whether the indicators need to be byte swapped, and flags contains further characteristics of the adapter. + Currently defined values for 'flags' are: + - KVM_S390_ADAPTER_SUPPRESSIBLE: adapter is subject to AIS (adapter-interrupt-suppression) facility. This flag only has an effect if the AIS capability is enabled. + Unknown flag values are ignored. KVM_DEV_FLIC_ADAPTER_MODIFY Modifies attributes of an existing I/O adapter interrupt source. Takes - a kvm_s390_io_adapter_req specifying the adapter and the operation: + a kvm_s390_io_adapter_req specifying the adapter and the operation:: -struct kvm_s390_io_adapter_req { - __u32 id; - __u8 type; - __u8 mask; - __u16 pad0; - __u64 addr; -}; + struct kvm_s390_io_adapter_req { + __u32 id; + __u8 type; + __u8 mask; + __u16 pad0; + __u64 addr; + }; id specifies the adapter and type the operation. The supported operations are: @@ -103,8 +109,9 @@ struct kvm_s390_io_adapter_req { perform a gmap translation for the guest address provided in addr, pin a userspace page for the translated address and add it to the list of mappings - Note: A new mapping will be created unconditionally; therefore, - the calling code should avoid making duplicate mappings. + + .. note:: A new mapping will be created unconditionally; therefore, + the calling code should avoid making duplicate mappings. KVM_S390_IO_ADAPTER_UNMAP release a userspace page for the translated address specified in addr @@ -112,16 +119,17 @@ struct kvm_s390_io_adapter_req { KVM_DEV_FLIC_AISM modify the adapter-interruption-suppression mode for a given isc if the - AIS capability is enabled. Takes a kvm_s390_ais_req describing: + AIS capability is enabled. Takes a kvm_s390_ais_req describing:: -struct kvm_s390_ais_req { - __u8 isc; - __u16 mode; -}; + struct kvm_s390_ais_req { + __u8 isc; + __u16 mode; + }; isc contains the target I/O interruption subclass, mode the target adapter-interruption-suppression mode. The following modes are currently supported: + - KVM_S390_AIS_MODE_ALL: ALL-Interruptions Mode, i.e. airq injection is always allowed; - KVM_S390_AIS_MODE_SINGLE: SINGLE-Interruption Mode, i.e. airq @@ -139,12 +147,12 @@ struct kvm_s390_ais_req { KVM_DEV_FLIC_AISM_ALL Gets or sets the adapter-interruption-suppression mode for all ISCs. Takes - a kvm_s390_ais_all describing: + a kvm_s390_ais_all describing:: -struct kvm_s390_ais_all { - __u8 simm; /* Single-Interruption-Mode mask */ - __u8 nimm; /* No-Interruption-Mode mask * -}; + struct kvm_s390_ais_all { + __u8 simm; /* Single-Interruption-Mode mask */ + __u8 nimm; /* No-Interruption-Mode mask * + }; simm contains Single-Interruption-Mode mask for all ISCs, nimm contains No-Interruption-Mode mask for all ISCs. Each bit in simm and nimm corresponds @@ -159,5 +167,5 @@ ENXIO, as specified in the API documentation). It is not possible to conclude that a FLIC operation is unavailable based on the error code resulting from a usage attempt. -Note: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a zero -schid is specified. +.. note:: The KVM_DEV_FLIC_CLEAR_IO_IRQ ioctl will return EINVAL in case a + zero schid is specified. From patchwork Tue Jan 28 13:58:08 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354311 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id C7A0114E3 for ; Tue, 28 Jan 2020 13:58:51 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id A5F4824685 for ; Tue, 28 Jan 2020 13:58:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580219931; bh=oDp2GFCusvjVIy+pDKtbQhh1Q7QweP/hmVWzwiRJCEk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=UfLaeZLBvQrJ+H2Uf+yi62jEanneFuJkbjTyosp4Zzlw5ZC0yA2rS9o+4skCo57PW G8IyHRWvdEXCMSJL6FC10zgrk4amU6lR/Hr7kiznE2fTNpco/dlE5vx2Y0SlyCcmIO wrYxo/3dwSEFCqLZEVAssv34QJOaj9ltdKUDF2lM= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726655AbgA1N6s (ORCPT ); Tue, 28 Jan 2020 08:58:48 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:58556 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726598AbgA1N6p (ORCPT ); Tue, 28 Jan 2020 08:58:45 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=RPG23Q5VInCW2/dcxso2308vuKWS9qa+8lTMVckj8OQ=; b=eg5ZPQ+jkf5/TY0Rys9EIBpi9w lpGsfmLgEdCaNAhDfz2ektRx2hLoN3Y/S1gMneYm1BwNvGnBZEXXPr0KbiY7Rz7LVscOv8wwT6ZjZ WThohdGrbyxcS0EhgISXN0vgqw8DjXWt0hcCRAHH6k6XavK5A2pbxUM4ZPT0MW+JKziSvERBknhlD 2gOD6WrQ/Rg4lFYv7LJ0J3Yqi8UCdZm7QKfZ+xn+G5OA4/VM7RT0vSjMKmbI0Ao3EU93HGOYWEbOf VgNp5d5jhN7geEmpW9XagwrYN/e6JBmx16uCe8jVM1qgvvMXq8tyiP86eIamWutjku2bTx34Q1JnY 3uH8HWvQ==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRO8-0006Kb-Ja; Tue, 28 Jan 2020 13:58:45 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRNq-001BJx-GA; Tue, 28 Jan 2020 14:58:26 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 12/27] docs: kvm: convert devices/vcpu.txt to ReST Date: Tue, 28 Jan 2020 14:58:08 +0100 Message-Id: <10cb8731b167ee8f0bbec245a9f89af3842bc279.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use title markups; - adjust indentation and add blank lines as needed; - adjust tables to match ReST accepted formats; - use :field: markups; - mark code blocks as such. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/devices/index.rst | 1 + Documentation/virt/kvm/devices/vcpu.rst | 112 +++++++++++++++++++++++ Documentation/virt/kvm/devices/vcpu.txt | 76 --------------- 3 files changed, 113 insertions(+), 76 deletions(-) create mode 100644 Documentation/virt/kvm/devices/vcpu.rst delete mode 100644 Documentation/virt/kvm/devices/vcpu.txt diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst index e6caccc36623..5a61838f0e61 100644 --- a/Documentation/virt/kvm/devices/index.rst +++ b/Documentation/virt/kvm/devices/index.rst @@ -12,3 +12,4 @@ Devices arm-vgic-v3 mpic s390_flic + vcpu diff --git a/Documentation/virt/kvm/devices/vcpu.rst b/Documentation/virt/kvm/devices/vcpu.rst new file mode 100644 index 000000000000..1270fd7f2cff --- /dev/null +++ b/Documentation/virt/kvm/devices/vcpu.rst @@ -0,0 +1,112 @@ +====================== +Generic vcpu interface +====================== + +The virtual cpu "device" also accepts the ioctls KVM_SET_DEVICE_ATTR, +KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same struct +kvm_device_attr as other devices, but targets VCPU-wide settings and controls. + +The groups and attributes per virtual cpu, if any, are architecture specific. + +1. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL +================================== + +:Architectures: ARM64 + +1.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ +--------------------------------------- + +:Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a + pointer to an int + +Returns: + + ======= ======================================================== + -EBUSY The PMU overflow interrupt is already set + -ENXIO The overflow interrupt not set when attempting to get it + -ENODEV PMUv3 not supported + -EINVAL Invalid PMU overflow interrupt number supplied or + trying to set the IRQ number without using an in-kernel + irqchip. + ======= ======================================================== + +A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt +number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt +type must be same for each vcpu. As a PPI, the interrupt number is the same for +all vcpus, while as an SPI it must be a separate number per vcpu. + +1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT +--------------------------------------- + +:Parameters: no additional parameter in kvm_device_attr.addr + +Returns: + + ======= ====================================================== + -ENODEV PMUv3 not supported or GIC not initialized + -ENXIO PMUv3 not properly configured or in-kernel irqchip not + configured as required prior to calling this attribute + -EBUSY PMUv3 already initialized + ======= ====================================================== + +Request the initialization of the PMUv3. If using the PMUv3 with an in-kernel +virtual GIC implementation, this must be done after initializing the in-kernel +irqchip. + + +2. GROUP: KVM_ARM_VCPU_TIMER_CTRL +================================= + +:Architectures: ARM,ARM64 + +2.1. ATTRIBUTES: KVM_ARM_VCPU_TIMER_IRQ_VTIMER, KVM_ARM_VCPU_TIMER_IRQ_PTIMER +----------------------------------------------------------------------------- + +:Parameters: in kvm_device_attr.addr the address for the timer interrupt is a + pointer to an int + +Returns: + + ======= ================================= + -EINVAL Invalid timer interrupt number + -EBUSY One or more VCPUs has already run + ======= ================================= + +A value describing the architected timer interrupt number when connected to an +in-kernel virtual GIC. These must be a PPI (16 <= intid < 32). Setting the +attribute overrides the default values (see below). + +============================= ========================================== +KVM_ARM_VCPU_TIMER_IRQ_VTIMER The EL1 virtual timer intid (default: 27) +KVM_ARM_VCPU_TIMER_IRQ_PTIMER The EL1 physical timer intid (default: 30) +============================= ========================================== + +Setting the same PPI for different timers will prevent the VCPUs from running. +Setting the interrupt number on a VCPU configures all VCPUs created at that +time to use the number provided for a given timer, overwriting any previously +configured values on other VCPUs. Userspace should configure the interrupt +numbers on at least one VCPU after creating all VCPUs and before running any +VCPUs. + +3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL +================================== + +:Architectures: ARM64 + +3.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA +-------------------------------------- + +:Parameters: 64-bit base address + +Returns: + + ======= ====================================== + -ENXIO Stolen time not implemented + -EEXIST Base address already set for this VCPU + -EINVAL Base address not 64 byte aligned + ======= ====================================== + +Specifies the base address of the stolen time structure for this VCPU. The +base address must be 64 byte aligned and exist within a valid guest memory +region. See Documentation/virt/kvm/arm/pvtime.txt for more information +including the layout of the stolen time structure. diff --git a/Documentation/virt/kvm/devices/vcpu.txt b/Documentation/virt/kvm/devices/vcpu.txt deleted file mode 100644 index 6f3bd64a05b0..000000000000 --- a/Documentation/virt/kvm/devices/vcpu.txt +++ /dev/null @@ -1,76 +0,0 @@ -Generic vcpu interface -==================================== - -The virtual cpu "device" also accepts the ioctls KVM_SET_DEVICE_ATTR, -KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same struct -kvm_device_attr as other devices, but targets VCPU-wide settings and controls. - -The groups and attributes per virtual cpu, if any, are architecture specific. - -1. GROUP: KVM_ARM_VCPU_PMU_V3_CTRL -Architectures: ARM64 - -1.1. ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_IRQ -Parameters: in kvm_device_attr.addr the address for PMU overflow interrupt is a - pointer to an int -Returns: -EBUSY: The PMU overflow interrupt is already set - -ENXIO: The overflow interrupt not set when attempting to get it - -ENODEV: PMUv3 not supported - -EINVAL: Invalid PMU overflow interrupt number supplied or - trying to set the IRQ number without using an in-kernel - irqchip. - -A value describing the PMUv3 (Performance Monitor Unit v3) overflow interrupt -number for this vcpu. This interrupt could be a PPI or SPI, but the interrupt -type must be same for each vcpu. As a PPI, the interrupt number is the same for -all vcpus, while as an SPI it must be a separate number per vcpu. - -1.2 ATTRIBUTE: KVM_ARM_VCPU_PMU_V3_INIT -Parameters: no additional parameter in kvm_device_attr.addr -Returns: -ENODEV: PMUv3 not supported or GIC not initialized - -ENXIO: PMUv3 not properly configured or in-kernel irqchip not - configured as required prior to calling this attribute - -EBUSY: PMUv3 already initialized - -Request the initialization of the PMUv3. If using the PMUv3 with an in-kernel -virtual GIC implementation, this must be done after initializing the in-kernel -irqchip. - - -2. GROUP: KVM_ARM_VCPU_TIMER_CTRL -Architectures: ARM,ARM64 - -2.1. ATTRIBUTE: KVM_ARM_VCPU_TIMER_IRQ_VTIMER -2.2. ATTRIBUTE: KVM_ARM_VCPU_TIMER_IRQ_PTIMER -Parameters: in kvm_device_attr.addr the address for the timer interrupt is a - pointer to an int -Returns: -EINVAL: Invalid timer interrupt number - -EBUSY: One or more VCPUs has already run - -A value describing the architected timer interrupt number when connected to an -in-kernel virtual GIC. These must be a PPI (16 <= intid < 32). Setting the -attribute overrides the default values (see below). - -KVM_ARM_VCPU_TIMER_IRQ_VTIMER: The EL1 virtual timer intid (default: 27) -KVM_ARM_VCPU_TIMER_IRQ_PTIMER: The EL1 physical timer intid (default: 30) - -Setting the same PPI for different timers will prevent the VCPUs from running. -Setting the interrupt number on a VCPU configures all VCPUs created at that -time to use the number provided for a given timer, overwriting any previously -configured values on other VCPUs. Userspace should configure the interrupt -numbers on at least one VCPU after creating all VCPUs and before running any -VCPUs. - -3. GROUP: KVM_ARM_VCPU_PVTIME_CTRL -Architectures: ARM64 - -3.1 ATTRIBUTE: KVM_ARM_VCPU_PVTIME_IPA -Parameters: 64-bit base address -Returns: -ENXIO: Stolen time not implemented - -EEXIST: Base address already set for this VCPU - -EINVAL: Base address not 64 byte aligned - -Specifies the base address of the stolen time structure for this VCPU. The -base address must be 64 byte aligned and exist within a valid guest memory -region. See Documentation/virt/kvm/arm/pvtime.txt for more information -including the layout of the stolen time structure. From patchwork Tue Jan 28 14:00:14 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354355 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 7CA3914E3 for ; Tue, 28 Jan 2020 14:01:18 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 5B38524685 for ; Tue, 28 Jan 2020 14:01:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220078; bh=QMjmcSh5y1m0k4nqwk+54CZiksCu9gEv/xL2K68cAOc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=v3hfobPjq1mCcldcIakzvF9t+VuvR+sj90nUH4W59pgYJHOGCC2A/UzeLU+HkinZ+ UYz7PZbOCYPDKJGbkJBTXnuzGIyJJ7zsDB7fMFmvOaf4odxyzmDwAel50MrkMPMqrN kxtoLWzMr3daPR1Wj+qnj0ivuemZKqx7tNtDLZ9g= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727404AbgA1OBQ (ORCPT ); Tue, 28 Jan 2020 09:01:16 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59282 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727290AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=MfbPPBfVOsZ1ekqbduEWSsRYBXTtAjqiqdXfPqQdPuI=; b=aBQ9Hrv/71Hg26WLtVc5E2auPr 2GVZK3Jem/WMCd+XFWJdaVxcFuZNej7dVqKOpzjW3z3176P3ZBWtwNXnirpuqn+I+nASxQKziHiPX drN3T03CZq7FsHD1IHKK3SsYjqr/WINVz6gHeK6DD6XwEY0PLg2l6cka31NEASl2Kmrq0bHctPHZQ /lNpx8z2c6ZFRzStR+dv/iUkEtbGYGTHf7Ri4ASls5f55llAKrHsml082OHDjjHDtaToYjfgdyCb9 3azeYHt82sOALev1WwPGxWYWC3/IlkzukhQS2E9drF256+r/TU23DcUEy1feot3iAVFJMy3oy7rNF Kojul6SA==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007ir-V2; Tue, 28 Jan 2020 14:00:45 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BOE-Kd; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 13/27] docs: kvm: convert devices/vcpu.txt to ReST Date: Tue, 28 Jan 2020 15:00:14 +0100 Message-Id: X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use standard title markup; - adjust lists; - mark code blocks as such. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/devices/index.rst | 1 + .../virt/kvm/devices/{vfio.txt => vfio.rst} | 23 +++++++++++-------- 2 files changed, 14 insertions(+), 10 deletions(-) rename Documentation/virt/kvm/devices/{vfio.txt => vfio.rst} (74%) diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst index 5a61838f0e61..cbbadda080d0 100644 --- a/Documentation/virt/kvm/devices/index.rst +++ b/Documentation/virt/kvm/devices/index.rst @@ -13,3 +13,4 @@ Devices mpic s390_flic vcpu + vfio diff --git a/Documentation/virt/kvm/devices/vfio.txt b/Documentation/virt/kvm/devices/vfio.rst similarity index 74% rename from Documentation/virt/kvm/devices/vfio.txt rename to Documentation/virt/kvm/devices/vfio.rst index 528c77c8022c..07a1acde25e4 100644 --- a/Documentation/virt/kvm/devices/vfio.txt +++ b/Documentation/virt/kvm/devices/vfio.rst @@ -1,8 +1,10 @@ +=================== VFIO virtual device =================== Device types supported: - KVM_DEV_TYPE_VFIO + + - KVM_DEV_TYPE_VFIO Only one VFIO instance may be created per VM. The created device tracks VFIO groups in use by the VM and features of those groups @@ -23,14 +25,15 @@ KVM_DEV_VFIO_GROUP attributes: for the VFIO group. KVM_DEV_VFIO_GROUP_SET_SPAPR_TCE: attaches a guest visible TCE table allocated by sPAPR KVM. - kvm_device_attr.addr points to a struct: + kvm_device_attr.addr points to a struct:: - struct kvm_vfio_spapr_tce { - __s32 groupfd; - __s32 tablefd; - }; + struct kvm_vfio_spapr_tce { + __s32 groupfd; + __s32 tablefd; + }; - where - @groupfd is a file descriptor for a VFIO group; - @tablefd is a file descriptor for a TCE table allocated via - KVM_CREATE_SPAPR_TCE. + where: + + - @groupfd is a file descriptor for a VFIO group; + - @tablefd is a file descriptor for a TCE table allocated via + KVM_CREATE_SPAPR_TCE. From patchwork Tue Jan 28 14:00:15 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354347 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0489F92A for ; Tue, 28 Jan 2020 14:01:12 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id BAA0024685 for ; Tue, 28 Jan 2020 14:01:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220071; bh=I2BhXYr4D0j6Y7cTfsuoGiVS0oSjL3AedkKyFaRDD00=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=oFS3Mkcg9wa1wh3qnaiZFa3CLYAPWqJGga3ZG4mLtqhEjnv125/gWwHj4LWYWmUIe miUn1WpCXO858wPFnlQ//ufwdibT7oWqz/pewaFVOuOsbTpnbJkdyoOdAsQFnAfwFl cP3rQZotOkWSHUkNMb2bj1YfANkKP+56prz6QIhA= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727377AbgA1OBK (ORCPT ); Tue, 28 Jan 2020 09:01:10 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59412 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727307AbgA1OAr (ORCPT ); Tue, 28 Jan 2020 09:00:47 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=XbGNFtogCQRMXF01dSGrQnNJXmqzkuMVFSbrbXMmdyA=; b=T5erDewSOCIkVuioArn/lOnduC 7Umjk7HM4nMWuWmMYGfMh92fdLqvJoc1x9WYff/auJwTc0OLvHNcOOOZfOpd0tK/5uaF8s/MN0mbF fEBs6w1sFFvZL5qa79V8ve87t8/sfhY2k5/6PxNqB0GZnLBFNypQaVeAOBXuGzoE6C9EMm47OVTXG /RQOI+Vq7EZ2mKmIgrozy3vWIQKkaz+1hBruGBqXQtFJVikNpIXjBtsu6GzMJjPT1ddMuRr/TiZyU dENx7cZHWaL1MM42XOe2bmjz9guEICLcyOWiL2YHdNnyb1Jkr/fkBSs7RdXpY6V4S4bs5rGjblYLA a0yQlh2A==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007in-Ex; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BOJ-Le; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 14/27] docs: kvm: convert devices/vm.txt to ReST Date: Tue, 28 Jan 2020 15:00:15 +0100 Message-Id: <11ebca7843c1fd54a328e9260c552fe2d2cc5503.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use title markups; - adjust indentation and add blank lines as needed; - use :field: markups; - Use cross-references; - mark code blocks as such. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/devices/index.rst | 1 + .../virt/kvm/devices/{vm.txt => vm.rst} | 204 +++++++++++------- 2 files changed, 125 insertions(+), 80 deletions(-) rename Documentation/virt/kvm/devices/{vm.txt => vm.rst} (61%) diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst index cbbadda080d0..29f8ecdf7fa0 100644 --- a/Documentation/virt/kvm/devices/index.rst +++ b/Documentation/virt/kvm/devices/index.rst @@ -14,3 +14,4 @@ Devices s390_flic vcpu vfio + vm diff --git a/Documentation/virt/kvm/devices/vm.txt b/Documentation/virt/kvm/devices/vm.rst similarity index 61% rename from Documentation/virt/kvm/devices/vm.txt rename to Documentation/virt/kvm/devices/vm.rst index 4ffb82b02468..4bcbc730265f 100644 --- a/Documentation/virt/kvm/devices/vm.txt +++ b/Documentation/virt/kvm/devices/vm.rst @@ -1,5 +1,6 @@ +==================== Generic vm interface -==================================== +==================== The virtual machine "device" also accepts the ioctls KVM_SET_DEVICE_ATTR, KVM_GET_DEVICE_ATTR, and KVM_HAS_DEVICE_ATTR. The interface uses the same @@ -10,30 +11,38 @@ The groups and attributes per virtual machine, if any, are architecture specific. 1. GROUP: KVM_S390_VM_MEM_CTRL -Architectures: s390 +============================== + +:Architectures: s390 1.1. ATTRIBUTE: KVM_S390_VM_MEM_ENABLE_CMMA -Parameters: none -Returns: -EBUSY if a vcpu is already defined, otherwise 0 +------------------------------------------- + +:Parameters: none +:Returns: -EBUSY if a vcpu is already defined, otherwise 0 Enables Collaborative Memory Management Assist (CMMA) for the virtual machine. 1.2. ATTRIBUTE: KVM_S390_VM_MEM_CLR_CMMA -Parameters: none -Returns: -EINVAL if CMMA was not enabled - 0 otherwise +---------------------------------------- + +:Parameters: none +:Returns: -EINVAL if CMMA was not enabled; + 0 otherwise Clear the CMMA status for all guest pages, so any pages the guest marked as unused are again used any may not be reclaimed by the host. 1.3. ATTRIBUTE KVM_S390_VM_MEM_LIMIT_SIZE -Parameters: in attr->addr the address for the new limit of guest memory -Returns: -EFAULT if the given address is not accessible - -EINVAL if the virtual machine is of type UCONTROL - -E2BIG if the given guest memory is to big for that machine - -EBUSY if a vcpu is already defined - -ENOMEM if not enough memory is available for a new shadow guest mapping - 0 otherwise +----------------------------------------- + +:Parameters: in attr->addr the address for the new limit of guest memory +:Returns: -EFAULT if the given address is not accessible; + -EINVAL if the virtual machine is of type UCONTROL; + -E2BIG if the given guest memory is to big for that machine; + -EBUSY if a vcpu is already defined; + -ENOMEM if not enough memory is available for a new shadow guest mapping; + 0 otherwise. Allows userspace to query the actual limit and set a new limit for the maximum guest memory size. The limit will be rounded up to @@ -42,78 +51,92 @@ the number of page table levels. In the case that there is no limit we will set the limit to KVM_S390_NO_MEM_LIMIT (U64_MAX). 2. GROUP: KVM_S390_VM_CPU_MODEL -Architectures: s390 +=============================== + +:Architectures: s390 2.1. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE (r/o) +--------------------------------------------- -Allows user space to retrieve machine and kvm specific cpu related information: +Allows user space to retrieve machine and kvm specific cpu related information:: -struct kvm_s390_vm_cpu_machine { + struct kvm_s390_vm_cpu_machine { __u64 cpuid; # CPUID of host __u32 ibc; # IBC level range offered by host __u8 pad[4]; __u64 fac_mask[256]; # set of cpu facilities enabled by KVM __u64 fac_list[256]; # set of cpu facilities offered by host -} + } -Parameters: address of buffer to store the machine related cpu data - of type struct kvm_s390_vm_cpu_machine* -Returns: -EFAULT if the given address is not accessible from kernel space - -ENOMEM if not enough memory is available to process the ioctl - 0 in case of success +:Parameters: address of buffer to store the machine related cpu data + of type struct kvm_s390_vm_cpu_machine* +:Returns: -EFAULT if the given address is not accessible from kernel space; + -ENOMEM if not enough memory is available to process the ioctl; + 0 in case of success. 2.2. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR (r/w) +=============================================== -Allows user space to retrieve or request to change cpu related information for a vcpu: +Allows user space to retrieve or request to change cpu related information for a vcpu:: -struct kvm_s390_vm_cpu_processor { + struct kvm_s390_vm_cpu_processor { __u64 cpuid; # CPUID currently (to be) used by this vcpu __u16 ibc; # IBC level currently (to be) used by this vcpu __u8 pad[6]; __u64 fac_list[256]; # set of cpu facilities currently (to be) used - # by this vcpu -} + # by this vcpu + } KVM does not enforce or limit the cpu model data in any form. Take the information retrieved by means of KVM_S390_VM_CPU_MACHINE as hint for reasonable configuration setups. Instruction interceptions triggered by additionally set facility bits that are not handled by KVM need to by imlemented in the VM driver code. -Parameters: address of buffer to store/set the processor related cpu - data of type struct kvm_s390_vm_cpu_processor*. -Returns: -EBUSY in case 1 or more vcpus are already activated (only in write case) - -EFAULT if the given address is not accessible from kernel space - -ENOMEM if not enough memory is available to process the ioctl - 0 in case of success +:Parameters: address of buffer to store/set the processor related cpu + data of type struct kvm_s390_vm_cpu_processor*. +:Returns: -EBUSY in case 1 or more vcpus are already activated (only in write case); + -EFAULT if the given address is not accessible from kernel space; + -ENOMEM if not enough memory is available to process the ioctl; + 0 in case of success. + +.. _KVM_S390_VM_CPU_MACHINE_FEAT: 2.3. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_FEAT (r/o) +-------------------------------------------------- Allows user space to retrieve available cpu features. A feature is available if provided by the hardware and supported by kvm. In theory, cpu features could even be completely emulated by kvm. -struct kvm_s390_vm_cpu_feat { - __u64 feat[16]; # Bitmap (1 = feature available), MSB 0 bit numbering -}; +:: -Parameters: address of a buffer to load the feature list from. -Returns: -EFAULT if the given address is not accessible from kernel space. - 0 in case of success. + struct kvm_s390_vm_cpu_feat { + __u64 feat[16]; # Bitmap (1 = feature available), MSB 0 bit numbering + }; + +:Parameters: address of a buffer to load the feature list from. +:Returns: -EFAULT if the given address is not accessible from kernel space; + 0 in case of success. 2.4. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_FEAT (r/w) +---------------------------------------------------- Allows user space to retrieve or change enabled cpu features for all VCPUs of a VM. Features that are not available cannot be enabled. -See 2.3. for a description of the parameter struct. +See :ref:`KVM_S390_VM_CPU_MACHINE_FEAT` for +a description of the parameter struct. -Parameters: address of a buffer to store/load the feature list from. -Returns: -EFAULT if the given address is not accessible from kernel space. - -EINVAL if a cpu feature that is not available is to be enabled. - -EBUSY if at least one VCPU has already been defined. +:Parameters: address of a buffer to store/load the feature list from. +:Returns: -EFAULT if the given address is not accessible from kernel space; + -EINVAL if a cpu feature that is not available is to be enabled; + -EBUSY if at least one VCPU has already been defined; 0 in case of success. +.. _KVM_S390_VM_CPU_MACHINE_SUBFUNC: + 2.5. ATTRIBUTE: KVM_S390_VM_CPU_MACHINE_SUBFUNC (r/o) +----------------------------------------------------- Allows user space to retrieve available cpu subfunctions without any filtering done by a set IBC. These subfunctions are indicated to the guest VCPU via @@ -126,7 +149,9 @@ contained in the returned struct. If the affected instruction indicates subfunctions via a "test bit" mechanism, the subfunction codes are contained in the returned struct in MSB 0 bit numbering. -struct kvm_s390_vm_cpu_subfunc { +:: + + struct kvm_s390_vm_cpu_subfunc { u8 plo[32]; # always valid (ESA/390 feature) u8 ptff[16]; # valid with TOD-clock steering u8 kmac[16]; # valid with Message-Security-Assist @@ -143,13 +168,14 @@ struct kvm_s390_vm_cpu_subfunc { u8 kma[16]; # valid with Message-Security-Assist-Extension 8 u8 kdsa[16]; # valid with Message-Security-Assist-Extension 9 u8 reserved[1792]; # reserved for future instructions -}; + }; -Parameters: address of a buffer to load the subfunction blocks from. -Returns: -EFAULT if the given address is not accessible from kernel space. +:Parameters: address of a buffer to load the subfunction blocks from. +:Returns: -EFAULT if the given address is not accessible from kernel space; 0 in case of success. 2.6. ATTRIBUTE: KVM_S390_VM_CPU_PROCESSOR_SUBFUNC (r/w) +------------------------------------------------------- Allows user space to retrieve or change cpu subfunctions to be indicated for all VCPUs of a VM. This attribute will only be available if kernel and @@ -164,107 +190,125 @@ As long as no data has been written, a read will fail. The IBC will be used to determine available subfunctions in this case, this will guarantee backward compatibility. -See 2.5. for a description of the parameter struct. +See :ref:`KVM_S390_VM_CPU_MACHINE_SUBFUNC` for a +description of the parameter struct. -Parameters: address of a buffer to store/load the subfunction blocks from. -Returns: -EFAULT if the given address is not accessible from kernel space. - -EINVAL when reading, if there was no write yet. - -EBUSY if at least one VCPU has already been defined. +:Parameters: address of a buffer to store/load the subfunction blocks from. +:Returns: -EFAULT if the given address is not accessible from kernel space; + -EINVAL when reading, if there was no write yet; + -EBUSY if at least one VCPU has already been defined; 0 in case of success. 3. GROUP: KVM_S390_VM_TOD -Architectures: s390 +========================= + +:Architectures: s390 3.1. ATTRIBUTE: KVM_S390_VM_TOD_HIGH +------------------------------------ Allows user space to set/get the TOD clock extension (u8) (superseded by KVM_S390_VM_TOD_EXT). -Parameters: address of a buffer in user space to store the data (u8) to -Returns: -EFAULT if the given address is not accessible from kernel space +:Parameters: address of a buffer in user space to store the data (u8) to +:Returns: -EFAULT if the given address is not accessible from kernel space; -EINVAL if setting the TOD clock extension to != 0 is not supported 3.2. ATTRIBUTE: KVM_S390_VM_TOD_LOW +----------------------------------- Allows user space to set/get bits 0-63 of the TOD clock register as defined in the POP (u64). -Parameters: address of a buffer in user space to store the data (u64) to -Returns: -EFAULT if the given address is not accessible from kernel space +:Parameters: address of a buffer in user space to store the data (u64) to +:Returns: -EFAULT if the given address is not accessible from kernel space 3.3. ATTRIBUTE: KVM_S390_VM_TOD_EXT +----------------------------------- + Allows user space to set/get bits 0-63 of the TOD clock register as defined in the POP (u64). If the guest CPU model supports the TOD clock extension (u8), it also allows user space to get/set it. If the guest CPU model does not support it, it is stored as 0 and not allowed to be set to a value != 0. -Parameters: address of a buffer in user space to store the data - (kvm_s390_vm_tod_clock) to -Returns: -EFAULT if the given address is not accessible from kernel space +:Parameters: address of a buffer in user space to store the data + (kvm_s390_vm_tod_clock) to +:Returns: -EFAULT if the given address is not accessible from kernel space; -EINVAL if setting the TOD clock extension to != 0 is not supported 4. GROUP: KVM_S390_VM_CRYPTO -Architectures: s390 +============================ + +:Architectures: s390 4.1. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_AES_KW (w/o) +------------------------------------------------------ Allows user space to enable aes key wrapping, including generating a new wrapping key. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 4.2. ATTRIBUTE: KVM_S390_VM_CRYPTO_ENABLE_DEA_KW (w/o) +------------------------------------------------------ Allows user space to enable dea key wrapping, including generating a new wrapping key. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 4.3. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_AES_KW (w/o) +------------------------------------------------------- Allows user space to disable aes key wrapping, clearing the wrapping key. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 4.4. ATTRIBUTE: KVM_S390_VM_CRYPTO_DISABLE_DEA_KW (w/o) +------------------------------------------------------- Allows user space to disable dea key wrapping, clearing the wrapping key. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 5. GROUP: KVM_S390_VM_MIGRATION -Architectures: s390 +=============================== + +:Architectures: s390 5.1. ATTRIBUTE: KVM_S390_VM_MIGRATION_STOP (w/o) +------------------------------------------------ Allows userspace to stop migration mode, needed for PGSTE migration. Setting this attribute when migration mode is not active will have no effects. -Parameters: none -Returns: 0 +:Parameters: none +:Returns: 0 5.2. ATTRIBUTE: KVM_S390_VM_MIGRATION_START (w/o) +------------------------------------------------- Allows userspace to start migration mode, needed for PGSTE migration. Setting this attribute when migration mode is already active will have no effects. -Parameters: none -Returns: -ENOMEM if there is not enough free memory to start migration mode - -EINVAL if the state of the VM is invalid (e.g. no memory defined) +:Parameters: none +:Returns: -ENOMEM if there is not enough free memory to start migration mode; + -EINVAL if the state of the VM is invalid (e.g. no memory defined); 0 in case of success. 5.3. ATTRIBUTE: KVM_S390_VM_MIGRATION_STATUS (r/o) +-------------------------------------------------- Allows userspace to query the status of migration mode. -Parameters: address of a buffer in user space to store the data (u64) to; - the data itself is either 0 if migration mode is disabled or 1 - if it is enabled -Returns: -EFAULT if the given address is not accessible from kernel space +:Parameters: address of a buffer in user space to store the data (u64) to; + the data itself is either 0 if migration mode is disabled or 1 + if it is enabled +:Returns: -EFAULT if the given address is not accessible from kernel space; 0 in case of success. From patchwork Tue Jan 28 14:00:16 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354477 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id C51501398 for ; Tue, 28 Jan 2020 14:49:50 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id A4EF9207FD for ; Tue, 28 Jan 2020 14:49:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580222990; bh=l4Dy/nc9l2l/dLSwIzDxThpTPMaVLxv+C84DZJAeXoQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=xboNtXWN2aJZNjgElgQGBgHNQNX8eYENpBa7ggALH6RM9LYn811Y+mT9TYyJnk8Jw S+NUw4g+QIavFQamgW/rFXHl/9QZ/iq7+mmr12sSpbbbVN09GsCUOcKPyoMEoFS2wM IVF12ou9pz87z25ueb9m2T7pD62lTdmyyRFIzogQ= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726789AbgA1Otk (ORCPT ); Tue, 28 Jan 2020 09:49:40 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59292 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727287AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=jCGNvxr49Lix6H95n0igp3NkedHJdEszNuxewfmtp4U=; b=fc1iY6Qx1yxSY+62KFqb/Clia9 OYMkvWWkR2paMXKhmnjOBuzaKgV4Fnj3tCcWxxWsPGGpwPlfd4FwU4ZNJrCD2axU49+P7xMsEZmC9 uWL/3zfYB+LS52QsgFLaFweeGd1SCMsQnXoOHQvKsTbA7ZQpmjOm69YifcTOfo2ft9cnDOCYAlmYh xt8sfvCT30mLzamI4qwPr9JyJ2GEMoXLSibP0E7uclu84q/KXaABqGTaPkr+6YUeI/LX839RXw4BU H2XceMpCByAw264O0SuA9EnqzIbOESmFWqwCzbZAt6WU0yu/K3HzPRIj9n36xc5UOrvD35bsWn9/Q pinGjYiw==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007ip-UM; Tue, 28 Jan 2020 14:00:45 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BOO-Mg; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 15/27] docs: kvm: convert devices/xics.txt to ReST Date: Tue, 28 Jan 2020 15:00:16 +0100 Message-Id: X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use title markups; - adjust indentation and add blank lines as needed; - adjust tables to match ReST accepted formats; - use :field: markups. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/devices/index.rst | 1 + .../virt/kvm/devices/{xics.txt => xics.rst} | 26 ++++++++++++++----- 2 files changed, 21 insertions(+), 6 deletions(-) rename Documentation/virt/kvm/devices/{xics.txt => xics.rst} (85%) diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst index 29f8ecdf7fa0..63b61369d09b 100644 --- a/Documentation/virt/kvm/devices/index.rst +++ b/Documentation/virt/kvm/devices/index.rst @@ -15,3 +15,4 @@ Devices vcpu vfio vm + xics diff --git a/Documentation/virt/kvm/devices/xics.txt b/Documentation/virt/kvm/devices/xics.rst similarity index 85% rename from Documentation/virt/kvm/devices/xics.txt rename to Documentation/virt/kvm/devices/xics.rst index 423332dda7bc..74e36dbea0fd 100644 --- a/Documentation/virt/kvm/devices/xics.txt +++ b/Documentation/virt/kvm/devices/xics.rst @@ -1,20 +1,29 @@ +========================= XICS interrupt controller +========================= Device type supported: KVM_DEV_TYPE_XICS Groups: 1. KVM_DEV_XICS_GRP_SOURCES - Attributes: One per interrupt source, indexed by the source number. + Attributes: + One per interrupt source, indexed by the source number. 2. KVM_DEV_XICS_GRP_CTRL - Attributes: - 2.1 KVM_DEV_XICS_NR_SERVERS (write only) + Attributes: + + 2.1 KVM_DEV_XICS_NR_SERVERS (write only) + The kvm_device_attr.addr points to a __u32 value which is the number of interrupt server numbers (ie, highest possible vcpu id plus one). + Errors: - -EINVAL: Value greater than KVM_MAX_VCPU_ID. - -EFAULT: Invalid user pointer for attr->addr. - -EBUSY: A vcpu is already connected to the device. + + ======= ========================================== + -EINVAL Value greater than KVM_MAX_VCPU_ID. + -EFAULT Invalid user pointer for attr->addr. + -EBUSY A vcpu is already connected to the device. + ======= ========================================== This device emulates the XICS (eXternal Interrupt Controller Specification) defined in PAPR. The XICS has a set of interrupt @@ -53,24 +62,29 @@ the interrupt source number. The 64 bit state word has the following bitfields, starting from the least-significant end of the word: * Destination (server number), 32 bits + This specifies where the interrupt should be sent, and is the interrupt server number specified for the destination vcpu. * Priority, 8 bits + This is the priority specified for this interrupt source, where 0 is the highest priority and 255 is the lowest. An interrupt with a priority of 255 will never be delivered. * Level sensitive flag, 1 bit + This bit is 1 for a level-sensitive interrupt source, or 0 for edge-sensitive (or MSI). * Masked flag, 1 bit + This bit is set to 1 if the interrupt is masked (cannot be delivered regardless of its priority), for example by the ibm,int-off RTAS call, or 0 if it is not masked. * Pending flag, 1 bit + This bit is 1 if the source has a pending interrupt, otherwise 0. Only one XICS instance may be created per VM. From patchwork Tue Jan 28 14:00:17 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354453 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 18ED81398 for ; Tue, 28 Jan 2020 14:49:35 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id D856124688 for ; Tue, 28 Jan 2020 14:49:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580222975; bh=D1FWdsnA7nLngLah5lSD/OjUTqeHAjWlBi/Tx5+dYsU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=QVZCHUjlEAkc5Cl7VlorF1DAW3Fx8HBDQZrpj1KYrSU+xtSwBqDHqMLtT3r8o1wpN sqzGaFEFprVyG/vQWkxUQVwsS4qcYnasy4s9kf/6cqb+UHsv2owq0TKSZe90i9KK5x TxTCDDZkNRXnDR6kHsj9teH/WXvG8G21JvNxX6Vk= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727307AbgA1OBO (ORCPT ); Tue, 28 Jan 2020 09:01:14 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59358 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727303AbgA1OAr (ORCPT ); Tue, 28 Jan 2020 09:00:47 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=x2sp6iOc0E903sdVig18K8EVOnXyeDCsbEfAqgSYd/k=; b=GzW5tuhw0/UVkEKTt12cdFXIdP acieGBF+dJF3ESI1fKqsSaSOMJydY3YH2QHL6YYURRmr24NwKzdPR5xZ6g/tLxFCw0JDbHwGgGr3h r5/6AdlH6r+HlLl6FRNrD0oc3VuCMozX6Et5yTNGLVU2TNP28fqYVvkkq+oV2MUhdAYM8blefzxIV 0047eZ0Ph8Nw6N3+/uiQnrQZH7AS0ge4MiQVOhu8/gMol6aBb4H/Zs9y5iKfBrB0WfDVvz4CFM5PT Y618f0hYArDAuaemOj2SdMfh+RqoTqC2XV7By1DUvL9bzVaailrKKoZm/DaCD+M8Esj3+QcfDwuOH OQ94ndig==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007il-Ve; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BOT-Nn; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 16/27] docs: kvm: convert devices/xive.txt to ReST Date: Tue, 28 Jan 2020 15:00:17 +0100 Message-Id: <126a26241472a0df74b8c19f489162ddc1edfc4b.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use title markups; - adjust indentation and add blank lines as needed; - adjust tables to match ReST accepted formats; - mark code blocks as such. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/devices/index.rst | 1 + .../virt/kvm/devices/{xive.txt => xive.rst} | 146 +++++++++++------- 2 files changed, 94 insertions(+), 53 deletions(-) rename Documentation/virt/kvm/devices/{xive.txt => xive.rst} (63%) diff --git a/Documentation/virt/kvm/devices/index.rst b/Documentation/virt/kvm/devices/index.rst index 63b61369d09b..192cda7405c8 100644 --- a/Documentation/virt/kvm/devices/index.rst +++ b/Documentation/virt/kvm/devices/index.rst @@ -16,3 +16,4 @@ Devices vfio vm xics + xive diff --git a/Documentation/virt/kvm/devices/xive.txt b/Documentation/virt/kvm/devices/xive.rst similarity index 63% rename from Documentation/virt/kvm/devices/xive.txt rename to Documentation/virt/kvm/devices/xive.rst index f5d1d6b5af61..e3947089b19c 100644 --- a/Documentation/virt/kvm/devices/xive.txt +++ b/Documentation/virt/kvm/devices/xive.rst @@ -1,8 +1,9 @@ +=========================================================== POWER9 eXternal Interrupt Virtualization Engine (XIVE Gen1) -========================================================== +=========================================================== Device types supported: - KVM_DEV_TYPE_XIVE POWER9 XIVE Interrupt Controller generation 1 + - KVM_DEV_TYPE_XIVE POWER9 XIVE Interrupt Controller generation 1 This device acts as a VM interrupt controller. It provides the KVM interface to configure the interrupt sources of a VM in the underlying @@ -64,72 +65,100 @@ the legacy interrupt mode, referred as XICS (POWER7/8). * Groups: - 1. KVM_DEV_XIVE_GRP_CTRL - Provides global controls on the device +1. KVM_DEV_XIVE_GRP_CTRL + Provides global controls on the device + Attributes: 1.1 KVM_DEV_XIVE_RESET (write only) Resets the interrupt controller configuration for sources and event queues. To be used by kexec and kdump. + Errors: none 1.2 KVM_DEV_XIVE_EQ_SYNC (write only) Sync all the sources and queues and mark the EQ pages dirty. This to make sure that a consistent memory state is captured when migrating the VM. + Errors: none 1.3 KVM_DEV_XIVE_NR_SERVERS (write only) The kvm_device_attr.addr points to a __u32 value which is the number of interrupt server numbers (ie, highest possible vcpu id plus one). + Errors: - -EINVAL: Value greater than KVM_MAX_VCPU_ID. - -EFAULT: Invalid user pointer for attr->addr. - -EBUSY: A vCPU is already connected to the device. - 2. KVM_DEV_XIVE_GRP_SOURCE (write only) - Initializes a new source in the XIVE device and mask it. + ======= ========================================== + -EINVAL Value greater than KVM_MAX_VCPU_ID. + -EFAULT Invalid user pointer for attr->addr. + -EBUSY A vCPU is already connected to the device. + ======= ========================================== + +2. KVM_DEV_XIVE_GRP_SOURCE (write only) + Initializes a new source in the XIVE device and mask it. + Attributes: Interrupt source number (64-bit) - The kvm_device_attr.addr points to a __u64 value: - bits: | 63 .... 2 | 1 | 0 - values: | unused | level | type + + The kvm_device_attr.addr points to a __u64 value:: + + bits: | 63 .... 2 | 1 | 0 + values: | unused | level | type + - type: 0:MSI 1:LSI - level: assertion level in case of an LSI. + Errors: - -E2BIG: Interrupt source number is out of range - -ENOMEM: Could not create a new source block - -EFAULT: Invalid user pointer for attr->addr. - -ENXIO: Could not allocate underlying HW interrupt - 3. KVM_DEV_XIVE_GRP_SOURCE_CONFIG (write only) - Configures source targeting + ======= ========================================== + -E2BIG Interrupt source number is out of range + -ENOMEM Could not create a new source block + -EFAULT Invalid user pointer for attr->addr. + -ENXIO Could not allocate underlying HW interrupt + ======= ========================================== + +3. KVM_DEV_XIVE_GRP_SOURCE_CONFIG (write only) + Configures source targeting + Attributes: Interrupt source number (64-bit) - The kvm_device_attr.addr points to a __u64 value: - bits: | 63 .... 33 | 32 | 31 .. 3 | 2 .. 0 - values: | eisn | mask | server | priority + + The kvm_device_attr.addr points to a __u64 value:: + + bits: | 63 .... 33 | 32 | 31 .. 3 | 2 .. 0 + values: | eisn | mask | server | priority + - priority: 0-7 interrupt priority level - server: CPU number chosen to handle the interrupt - mask: mask flag (unused) - eisn: Effective Interrupt Source Number + Errors: - -ENOENT: Unknown source number - -EINVAL: Not initialized source number - -EINVAL: Invalid priority - -EINVAL: Invalid CPU number. - -EFAULT: Invalid user pointer for attr->addr. - -ENXIO: CPU event queues not configured or configuration of the - underlying HW interrupt failed - -EBUSY: No CPU available to serve interrupt - 4. KVM_DEV_XIVE_GRP_EQ_CONFIG (read-write) - Configures an event queue of a CPU + ======= ======================================================= + -ENOENT Unknown source number + -EINVAL Not initialized source number + -EINVAL Invalid priority + -EINVAL Invalid CPU number. + -EFAULT Invalid user pointer for attr->addr. + -ENXIO CPU event queues not configured or configuration of the + underlying HW interrupt failed + -EBUSY No CPU available to serve interrupt + ======= ======================================================= + +4. KVM_DEV_XIVE_GRP_EQ_CONFIG (read-write) + Configures an event queue of a CPU + Attributes: EQ descriptor identifier (64-bit) - The EQ descriptor identifier is a tuple (server, priority) : - bits: | 63 .... 32 | 31 .. 3 | 2 .. 0 - values: | unused | server | priority - The kvm_device_attr.addr points to : + + The EQ descriptor identifier is a tuple (server, priority):: + + bits: | 63 .... 32 | 31 .. 3 | 2 .. 0 + values: | unused | server | priority + + The kvm_device_attr.addr points to:: + struct kvm_ppc_xive_eq { __u32 flags; __u32 qshift; @@ -138,8 +167,9 @@ the legacy interrupt mode, referred as XICS (POWER7/8). __u32 qindex; __u8 pad[40]; }; + - flags: queue flags - KVM_XIVE_EQ_ALWAYS_NOTIFY (required) + KVM_XIVE_EQ_ALWAYS_NOTIFY (required) forces notification without using the coalescing mechanism provided by the XIVE END ESBs. - qshift: queue size (power of 2) @@ -147,22 +177,31 @@ the legacy interrupt mode, referred as XICS (POWER7/8). - qtoggle: current queue toggle bit - qindex: current queue index - pad: reserved for future use + Errors: - -ENOENT: Invalid CPU number - -EINVAL: Invalid priority - -EINVAL: Invalid flags - -EINVAL: Invalid queue size - -EINVAL: Invalid queue address - -EFAULT: Invalid user pointer for attr->addr. - -EIO: Configuration of the underlying HW failed - 5. KVM_DEV_XIVE_GRP_SOURCE_SYNC (write only) - Synchronize the source to flush event notifications + ======= ========================================= + -ENOENT Invalid CPU number + -EINVAL Invalid priority + -EINVAL Invalid flags + -EINVAL Invalid queue size + -EINVAL Invalid queue address + -EFAULT Invalid user pointer for attr->addr. + -EIO Configuration of the underlying HW failed + ======= ========================================= + +5. KVM_DEV_XIVE_GRP_SOURCE_SYNC (write only) + Synchronize the source to flush event notifications + Attributes: Interrupt source number (64-bit) + Errors: - -ENOENT: Unknown source number - -EINVAL: Not initialized source number + + ======= ============================= + -ENOENT Unknown source number + -EINVAL Not initialized source number + ======= ============================= * VCPU state @@ -175,11 +214,12 @@ the legacy interrupt mode, referred as XICS (POWER7/8). as it synthesizes the priorities of the pending interrupts. We capture a bit more to report debug information. - KVM_REG_PPC_VP_STATE (2 * 64bits) - bits: | 63 .... 32 | 31 .... 0 | - values: | TIMA word0 | TIMA word1 | - bits: | 127 .......... 64 | - values: | unused | + KVM_REG_PPC_VP_STATE (2 * 64bits):: + + bits: | 63 .... 32 | 31 .... 0 | + values: | TIMA word0 | TIMA word1 | + bits: | 127 .......... 64 | + values: | unused | * Migration: @@ -196,7 +236,7 @@ the legacy interrupt mode, referred as XICS (POWER7/8). 3. Capture the state of the source targeting, the EQs configuration and the state of thread interrupt context registers. - Restore is similar : + Restore is similar: 1. Restore the EQ configuration. As targeting depends on it. 2. Restore targeting From patchwork Tue Jan 28 14:00:19 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354483 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 19BBF924 for ; Tue, 28 Jan 2020 14:49:55 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id ED93F207FD for ; Tue, 28 Jan 2020 14:49:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580222995; bh=XJBqHP9X6xdwKnRYGlBBnIC+Wnep6UMrJLUN94RU6hE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=xmDKH0HlotNIiDCDXulpNOI7WiT3nu+HwNLIbOwzeuzjZLm+iaExaNK2Kuovdym0E gmduCYiPF6jVrCEfH+IdH74h0EwrjBS31aoWHOi56dJV12m6Li6zodsx5bbPDGaXtq 6Cpu6Y60XAFZ6Pdab1lGSzx98kFKH+fhWoDxP8DM= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727405AbgA1Otx (ORCPT ); Tue, 28 Jan 2020 09:49:53 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59296 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727296AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=pdZ8qcVwJgau11WErg9V3Yc+VhPbjBFzGGVo//flLAo=; b=sySpSqJoeSAZ6nqHqhBfl+XL21 5TpZr0mZuhA3gjKteTVLv/eqBXj3j7v3SR1IaT6AyaLkVi3P4i120VOT1GYEelIixnpAIOMp3avUF dWcV5qIF8XF9ZnBIr9iXJTJe7MY/1z3Z31t0hDyHWgbw23m7VunkcFNqCC8Lm8sxfmfcEZhjKd/Hx nbff9DxLcKkcvU9gyzcTNaaEfwwssfyhaayE8Ohm4Rhd5zovUeG4zPiap29IglIpc4Wuh7PJgtMEK Gm8rcvGV2v6NOPWzyyspbvE4H4nXlHJNNtTz/xOxOdik+kQXZGDOgtULAm98Rq3XeAtvhaMKEr/Lk l7p89GIA==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007ij-Uh; Tue, 28 Jan 2020 14:00:45 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BOd-RL; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 18/27] docs: kvm: convert arm/hyp-abi.txt to ReST Date: Tue, 28 Jan 2020 15:00:19 +0100 Message-Id: <707c15ba05c14b49801e29840154ee1aed5cd910.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Add proper markups for titles; - Adjust whitespaces and blank lines to match ReST needs; - Mark literal blocks as such. Signed-off-by: Mauro Carvalho Chehab --- .../virt/kvm/arm/{hyp-abi.txt => hyp-abi.rst} | 26 ++++++++++++------- Documentation/virt/kvm/arm/index.rst | 1 + 2 files changed, 18 insertions(+), 9 deletions(-) rename Documentation/virt/kvm/arm/{hyp-abi.txt => hyp-abi.rst} (80%) diff --git a/Documentation/virt/kvm/arm/hyp-abi.txt b/Documentation/virt/kvm/arm/hyp-abi.rst similarity index 80% rename from Documentation/virt/kvm/arm/hyp-abi.txt rename to Documentation/virt/kvm/arm/hyp-abi.rst index a20a0bee268d..cf74b5b87df6 100644 --- a/Documentation/virt/kvm/arm/hyp-abi.txt +++ b/Documentation/virt/kvm/arm/hyp-abi.rst @@ -1,4 +1,6 @@ -* Internal ABI between the kernel and HYP +======================================= +Internal ABI between the kernel and HYP +======================================= This file documents the interaction between the Linux kernel and the hypervisor layer when running Linux as a hypervisor (for example @@ -19,25 +21,31 @@ and only act on individual CPUs. Unless specified otherwise, any built-in hypervisor must implement these functions (see arch/arm{,64}/include/asm/virt.h): -* r0/x0 = HVC_SET_VECTORS - r1/x1 = vectors +* :: + + r0/x0 = HVC_SET_VECTORS + r1/x1 = vectors Set HVBAR/VBAR_EL2 to 'vectors' to enable a hypervisor. 'vectors' must be a physical address, and respect the alignment requirements of the architecture. Only implemented by the initial stubs, not by Linux hypervisors. -* r0/x0 = HVC_RESET_VECTORS +* :: + + r0/x0 = HVC_RESET_VECTORS Turn HYP/EL2 MMU off, and reset HVBAR/VBAR_EL2 to the initials stubs' exception vector value. This effectively disables an existing hypervisor. -* r0/x0 = HVC_SOFT_RESTART - r1/x1 = restart address - x2 = x0's value when entering the next payload (arm64) - x3 = x1's value when entering the next payload (arm64) - x4 = x2's value when entering the next payload (arm64) +* :: + + r0/x0 = HVC_SOFT_RESTART + r1/x1 = restart address + x2 = x0's value when entering the next payload (arm64) + x3 = x1's value when entering the next payload (arm64) + x4 = x2's value when entering the next payload (arm64) Mask all exceptions, disable the MMU, move the arguments into place (arm64 only), and jump to the restart address while at HYP/EL2. This diff --git a/Documentation/virt/kvm/arm/index.rst b/Documentation/virt/kvm/arm/index.rst index e039d9b1e076..134fa5fa77e5 100644 --- a/Documentation/virt/kvm/arm/index.rst +++ b/Documentation/virt/kvm/arm/index.rst @@ -7,4 +7,5 @@ ARM .. toctree:: :maxdepth: 2 + hyp-abi pvtime From patchwork Tue Jan 28 14:00:20 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354461 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 5D2391398 for ; Tue, 28 Jan 2020 14:49:42 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 3B3EB24683 for ; Tue, 28 Jan 2020 14:49:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580222982; bh=Sb/Hso3qzAp/GG1dD7fNZoQ6ftlA7QzLpHUxJn5c08A=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=mI5ysSN1WzEnNpGE/lZUbR7CCdS3bLWf1RgPbIxZVn8k+t6vO+j0A2g8Dk66DnrQF uSqKs/8JI32Bo9SHa1SmQFVq4oMLOOkkzFf4HvFhDfB1cDNMgCQsK2GpS3J/GuUiCt B7bVqXgNuu7jc69aY4fdSFTcauLVFAgtbIlCLWz8= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726393AbgA1Otl (ORCPT ); Tue, 28 Jan 2020 09:49:41 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59298 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727291AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=c3O1qU0BaMW0VdPESODOU6k7pCSNM7sfr+uBlXdB8Yc=; b=VnbMV/CL+BuVOTSUlJU69re/gN FEb0itjrAe+qnYYATKh8N1q7AaJ+B6+OuxF0xqUKvnVL+1YhGqR/HN1iKiUvg2zxUh/TfdJLgHSBj /bXuWZCWr+nuImnMTYfUeHbstcaxUQAsUvvlCYbOs/RoYUaM5WCs9MnwH4xcXi8iIy9TLgSasrPyq zRPwqgg0kZkqJdAAyRjnJKGhMAZFYJhUXkEl65agnbjLhXZlr23Er+oG0Er5jZ8NDEPvIvQMWvlmq NGVAK+dbGkTMSwxK7ufEDRTk+YosYBBxm1BleU+raNfUnk82vye7ajAgcKT4tLRiDUZumhkmrwWRF qmFXuChA==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007iq-W1; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BOi-SH; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 19/27] docs: kvm: arm/psci.txt: convert to ReST Date: Tue, 28 Jan 2020 15:00:20 +0100 Message-Id: X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Add a title for the document; - Adjust whitespaces for it to be properly formatted after parsed. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/arm/index.rst | 1 + .../virt/kvm/arm/{psci.txt => psci.rst} | 44 ++++++++++++------- 2 files changed, 30 insertions(+), 15 deletions(-) rename Documentation/virt/kvm/arm/{psci.txt => psci.rst} (61%) diff --git a/Documentation/virt/kvm/arm/index.rst b/Documentation/virt/kvm/arm/index.rst index 134fa5fa77e5..3e2b2aba90fc 100644 --- a/Documentation/virt/kvm/arm/index.rst +++ b/Documentation/virt/kvm/arm/index.rst @@ -8,4 +8,5 @@ ARM :maxdepth: 2 hyp-abi + psci pvtime diff --git a/Documentation/virt/kvm/arm/psci.txt b/Documentation/virt/kvm/arm/psci.rst similarity index 61% rename from Documentation/virt/kvm/arm/psci.txt rename to Documentation/virt/kvm/arm/psci.rst index 559586fc9d37..5cdf8fb86779 100644 --- a/Documentation/virt/kvm/arm/psci.txt +++ b/Documentation/virt/kvm/arm/psci.rst @@ -1,3 +1,7 @@ +========================================= +Power State Coordination Interface (PSCI) +========================================= + KVM implements the PSCI (Power State Coordination Interface) specification in order to provide services such as CPU on/off, reset and power-off to the guest. @@ -30,32 +34,42 @@ The following register is defined: - Affects the whole VM (even if the register view is per-vcpu) * KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1: - Holds the state of the firmware support to mitigate CVE-2017-5715, as - offered by KVM to the guest via a HVC call. The workaround is described - under SMCCC_ARCH_WORKAROUND_1 in [1]. + Holds the state of the firmware support to mitigate CVE-2017-5715, as + offered by KVM to the guest via a HVC call. The workaround is described + under SMCCC_ARCH_WORKAROUND_1 in [1]. + Accepted values are: - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_AVAIL: KVM does not offer + + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_AVAIL: + KVM does not offer firmware support for the workaround. The mitigation status for the guest is unknown. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_AVAIL: The workaround HVC call is + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_AVAIL: + The workaround HVC call is available to the guest and required for the mitigation. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_REQUIRED: The workaround HVC call + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_1_NOT_REQUIRED: + The workaround HVC call is available to the guest, but it is not needed on this VCPU. * KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2: - Holds the state of the firmware support to mitigate CVE-2018-3639, as - offered by KVM to the guest via a HVC call. The workaround is described - under SMCCC_ARCH_WORKAROUND_2 in [1]. + Holds the state of the firmware support to mitigate CVE-2018-3639, as + offered by KVM to the guest via a HVC call. The workaround is described + under SMCCC_ARCH_WORKAROUND_2 in [1]_. + Accepted values are: - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_AVAIL: A workaround is not + + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_AVAIL: + A workaround is not available. KVM does not offer firmware support for the workaround. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_UNKNOWN: The workaround state is + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_UNKNOWN: + The workaround state is unknown. KVM does not offer firmware support for the workaround. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_AVAIL: The workaround is available, + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_AVAIL: + The workaround is available, and can be disabled by a vCPU. If KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_ENABLED is set, it is active for this vCPU. - KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_REQUIRED: The workaround is - always active on this vCPU or it is not needed. + KVM_REG_ARM_SMCCC_ARCH_WORKAROUND_2_NOT_REQUIRED: + The workaround is always active on this vCPU or it is not needed. -[1] https://developer.arm.com/-/media/developer/pdf/ARM_DEN_0070A_Firmware_interfaces_for_mitigating_CVE-2017-5715.pdf +.. [1] https://developer.arm.com/-/media/developer/pdf/ARM_DEN_0070A_Firmware_interfaces_for_mitigating_CVE-2017-5715.pdf From patchwork Tue Jan 28 14:00:21 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354465 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 2396F1398 for ; Tue, 28 Jan 2020 14:49:45 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 028562173E for ; Tue, 28 Jan 2020 14:49:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580222985; bh=UJ/CLYBBn6wHB9tWc1xNzUBDjNwGM2S5kzW6xD/rgaM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=qmwaALAoNuP4qjt3uSHJkeBdN6/upyOwRrJcuO80dmSeKUpx46+hlP9xMFufzVa7D 1+0mgKxWKMO5TNXOKkjzLtiPk6x4XlwhOA6NRVhzq9Sk3jfafMDunNRf1Lr8zEJq19 Rsp1JsHgSorQB7+mXNJXliW9M1XVyF+1Q40nEkFI= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727354AbgA1Otn (ORCPT ); Tue, 28 Jan 2020 09:49:43 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59334 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727301AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=dAo4MTL8JFdzXH3mr7nnacHwuW8dPHCRz9vjZt/hWIQ=; b=WAadUwL58lCZBVEy3y/ogU2LhJ f+MMiWFe9vYhV9avZodl6RO0D12Y0lmDAsdN08pqEvqwdO7xkhAwaDRqi8C/pM3s2IlaIJ1ziLKKf t57fBQA0MjJmNlc2LrGj+yS26ZdUslWww5rhlgbKgD20sgfknHVqzUH0umkbYb8XahAngEUoCvjL0 ZdJ90Z1NJaQryGPoVFONXmBWz+rWkOv1U/BXj5LI2PtD2/Xpjsjn9Mp2V8LABLFffPtfaemXvc5Dk /kPDqGQj3lOCLdm9k0/TLoYAfz4tdDrYo3Oimj+rK+qnGx30CuygdEmLu1Rixn2gpEK42tFZsOx43 xCiwt4sg==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007id-OA; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BOn-TF; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 20/27] docs: kvm: Convert hypercalls.txt to ReST format Date: Tue, 28 Jan 2020 15:00:21 +0100 Message-Id: X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use document title and chapter markups; - Convert tables; - Add markups for literal blocks; - use :field: for field descriptions; - Add blank lines and adjust indentation Signed-off-by: Mauro Carvalho Chehab --- .../kvm/{hypercalls.txt => hypercalls.rst} | 127 ++++++++++-------- Documentation/virt/kvm/index.rst | 2 + 2 files changed, 73 insertions(+), 56 deletions(-) rename Documentation/virt/kvm/{hypercalls.txt => hypercalls.rst} (55%) diff --git a/Documentation/virt/kvm/hypercalls.txt b/Documentation/virt/kvm/hypercalls.rst similarity index 55% rename from Documentation/virt/kvm/hypercalls.txt rename to Documentation/virt/kvm/hypercalls.rst index 5f6d291bd004..fb4ccaf8641a 100644 --- a/Documentation/virt/kvm/hypercalls.txt +++ b/Documentation/virt/kvm/hypercalls.rst @@ -1,5 +1,7 @@ -Linux KVM Hypercall: =================== +Linux KVM Hypercall +=================== + X86: KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall instruction. The hypervisor can replace it with instructions that are @@ -20,7 +22,7 @@ S390: For further information on the S390 diagnose call as supported by KVM, refer to Documentation/virt/kvm/s390-diag.txt. - PowerPC: +PowerPC: It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers. Return value is placed in R3. @@ -34,7 +36,8 @@ MIPS: the return value is placed in $2 (v0). KVM Hypercalls Documentation -=========================== +============================ + The template for each hypercall is: 1. Hypercall name. 2. Architecture(s) @@ -43,56 +46,64 @@ The template for each hypercall is: 1. KVM_HC_VAPIC_POLL_IRQ ------------------------ -Architecture: x86 -Status: active -Purpose: Trigger guest exit so that the host can check for pending -interrupts on reentry. + +:Architecture: x86 +:Status: active +:Purpose: Trigger guest exit so that the host can check for pending + interrupts on reentry. 2. KVM_HC_MMU_OP ------------------------- -Architecture: x86 -Status: deprecated. -Purpose: Support MMU operations such as writing to PTE, -flushing TLB, release PT. +---------------- + +:Architecture: x86 +:Status: deprecated. +:Purpose: Support MMU operations such as writing to PTE, + flushing TLB, release PT. 3. KVM_HC_FEATURES ------------------------- -Architecture: PPC -Status: active -Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid -used to enumerate which hypercalls are available. On PPC, either device tree -based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration -mechanism (which is this hypercall) can be used. +------------------ + +:Architecture: PPC +:Status: active +:Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid + used to enumerate which hypercalls are available. On PPC, either + device tree based lookup ( which is also what EPAPR dictates) + OR KVM specific enumeration mechanism (which is this hypercall) + can be used. 4. KVM_HC_PPC_MAP_MAGIC_PAGE ------------------------- -Architecture: PPC -Status: active -Purpose: To enable communication between the hypervisor and guest there is a -shared page that contains parts of supervisor visible register state. -The guest can map this shared page to access its supervisor register through -memory using this hypercall. +---------------------------- + +:Architecture: PPC +:Status: active +:Purpose: To enable communication between the hypervisor and guest there is a + shared page that contains parts of supervisor visible register state. + The guest can map this shared page to access its supervisor register + through memory using this hypercall. 5. KVM_HC_KICK_CPU ------------------------- -Architecture: x86 -Status: active -Purpose: Hypercall used to wakeup a vcpu from HLT state -Usage example : A vcpu of a paravirtualized guest that is busywaiting in guest -kernel mode for an event to occur (ex: a spinlock to become available) can -execute HLT instruction once it has busy-waited for more than a threshold -time-interval. Execution of HLT instruction would cause the hypervisor to put -the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the -same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall, -specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0) -is used in the hypercall for future use. +------------------ + +:Architecture: x86 +:Status: active +:Purpose: Hypercall used to wakeup a vcpu from HLT state +:Usage example: + A vcpu of a paravirtualized guest that is busywaiting in guest + kernel mode for an event to occur (ex: a spinlock to become available) can + execute HLT instruction once it has busy-waited for more than a threshold + time-interval. Execution of HLT instruction would cause the hypervisor to put + the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the + same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall, + specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0) + is used in the hypercall for future use. 6. KVM_HC_CLOCK_PAIRING ------------------------- -Architecture: x86 -Status: active -Purpose: Hypercall used to synchronize host and guest clocks. +----------------------- +:Architecture: x86 +:Status: active +:Purpose: Hypercall used to synchronize host and guest clocks. + Usage: a0: guest physical address where host copies @@ -101,6 +112,8 @@ a0: guest physical address where host copies a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0) is supported (corresponding to the host's CLOCK_REALTIME clock). + :: + struct kvm_clock_pairing { __s64 sec; __s64 nsec; @@ -123,15 +136,16 @@ Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource, or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK. 6. KVM_HC_SEND_IPI ------------------------- -Architecture: x86 -Status: active -Purpose: Send IPIs to multiple vCPUs. +------------------ -a0: lower part of the bitmap of destination APIC IDs -a1: higher part of the bitmap of destination APIC IDs -a2: the lowest APIC ID in bitmap -a3: APIC ICR +:Architecture: x86 +:Status: active +:Purpose: Send IPIs to multiple vCPUs. + +- a0: lower part of the bitmap of destination APIC IDs +- a1: higher part of the bitmap of destination APIC IDs +- a2: the lowest APIC ID in bitmap +- a3: APIC ICR The hypercall lets a guest send multicast IPIs, with at most 128 128 destinations per hypercall in 64-bit mode and 64 vCPUs per @@ -143,12 +157,13 @@ corresponds to the APIC ID a2+1, and so on. Returns the number of CPUs to which the IPIs were delivered successfully. 7. KVM_HC_SCHED_YIELD ------------------------- -Architecture: x86 -Status: active -Purpose: Hypercall used to yield if the IPI target vCPU is preempted +--------------------- + +:Architecture: x86 +:Status: active +:Purpose: Hypercall used to yield if the IPI target vCPU is preempted a0: destination APIC ID -Usage example: When sending a call-function IPI-many to vCPUs, yield if -any of the IPI target vCPUs was preempted. +:Usage example: When sending a call-function IPI-many to vCPUs, yield if + any of the IPI target vCPUs was preempted. diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index 6fe79185b9bc..ac83bc588f7e 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -11,8 +11,10 @@ KVM amd-memory-encryption cpuid halt-polling + hypercalls msr vcpu-requests arm/index + devices/index From patchwork Tue Jan 28 14:00:22 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354315 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0F23792A for ; Tue, 28 Jan 2020 14:00:51 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id CF50A2469F for ; Tue, 28 Jan 2020 14:00:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220051; bh=PcE8BBpEouu6QcFp0wL9wrsi5teS0iVNnlOia6qoxTg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=jpPOhgpaUoUmnHe5+KPlFjRqbCFqqqpAb5syiRyaAKGP+4hs26X/snKfHGv8uF8bx JtUxaMo4K4X5GP4Caequbqax2X/kSb+d2DxFN23Y96h4LZlusfko+Az21vg1GV4dNB hZvVyFWAKJGsHRJwWtfbd+OVZbVtNnV/yvYsgGn0= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727354AbgA1OAu (ORCPT ); Tue, 28 Jan 2020 09:00:50 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59428 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727308AbgA1OAr (ORCPT ); Tue, 28 Jan 2020 09:00:47 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=qSQNK5Ivf59NAVe6e3CbDIPuMhg/3mhXwdp9SJF3SBc=; b=dbi4rOLWK4VPc4F5gqe5vAiWbW zHY6QmdxRQO3QfkDrqx0CbpJv2TFp0MgelsMkzZN6LxkeGpgMu0ADBhNsdidm5iiVTrXtBpF2pUM0 7lnduDY7uX/oa+pjLPnepXOljxyV93LJX1g3TeBS9sdfbdGPkARNp9eUmOBCOpKyegzv6zsHsHlUK dGgq5rBhzeMtU1nxnFlpSGtw/z7BIAzrHArV8vZy2NKycFDGnMV4XAfIy83NzjP8UedBGFwPpVnaG YWcUZqTy+Ih/NtDbZBug5r0GTYxG7j6pOSo4VxzULrUhQC96pmXya9PrfGjO8ycjWm+U2z0LwEOYe PCmCItCQ==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ6-0007ix-95; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BOs-Uo; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 21/27] docs: kvm: Convert locking.txt to ReST format Date: Tue, 28 Jan 2020 15:00:22 +0100 Message-Id: <31d840edcc924b6b4d6f3f6b3f130623c2a4d91c.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use document title and chapter markups; - Add markups for literal blocks; - use :field: for field descriptions; - Add blank lines and adjust indentation. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/index.rst | 1 + .../virt/kvm/{locking.txt => locking.rst} | 109 ++++++++++-------- 2 files changed, 61 insertions(+), 49 deletions(-) rename Documentation/virt/kvm/{locking.txt => locking.rst} (79%) diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index ac83bc588f7e..9be8f53b729d 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -12,6 +12,7 @@ KVM cpuid halt-polling hypercalls + locking msr vcpu-requests diff --git a/Documentation/virt/kvm/locking.txt b/Documentation/virt/kvm/locking.rst similarity index 79% rename from Documentation/virt/kvm/locking.txt rename to Documentation/virt/kvm/locking.rst index 635cd6eaf714..065706a9155e 100644 --- a/Documentation/virt/kvm/locking.txt +++ b/Documentation/virt/kvm/locking.rst @@ -1,3 +1,4 @@ +================= KVM Lock Overview ================= @@ -18,7 +19,7 @@ On x86, vcpu->mutex is taken outside kvm->arch.hyperv.hv_lock. Everything else is a leaf: no other lock is taken inside the critical sections. -2: Exception +2. Exception ------------ Fast page fault: @@ -28,15 +29,16 @@ the mmu-lock on x86. Currently, the page fault can be fast in one of the following two cases: 1. Access Tracking: The SPTE is not present, but it is marked for access -tracking i.e. the SPTE_SPECIAL_MASK is set. That means we need to -restore the saved R/X bits. This is described in more detail later below. + tracking i.e. the SPTE_SPECIAL_MASK is set. That means we need to + restore the saved R/X bits. This is described in more detail later below. 2. Write-Protection: The SPTE is present and the fault is -caused by write-protect. That means we just need to change the W bit of the -spte. + caused by write-protect. That means we just need to change the W bit of + the spte. What we use to avoid all the race is the SPTE_HOST_WRITEABLE bit and SPTE_MMU_WRITEABLE bit on the spte: + - SPTE_HOST_WRITEABLE means the gfn is writable on host. - SPTE_MMU_WRITEABLE means the gfn is writable on mmu. The bit is set when the gfn is writable on guest mmu and it is not write-protected by shadow @@ -48,19 +50,23 @@ restore the saved R/X bits if VMX_EPT_TRACK_ACCESS mask is set, or both. This is safe because whenever changing these bits can be detected by cmpxchg. But we need carefully check these cases: -1): The mapping from gfn to pfn + +1) The mapping from gfn to pfn + The mapping from gfn to pfn may be changed since we can only ensure the pfn is not changed during cmpxchg. This is a ABA problem, for example, below case will happen: -At the beginning: -gpte = gfn1 -gfn1 is mapped to pfn1 on host -spte is the shadow page table entry corresponding with gpte and -spte = pfn1 +At the beginning:: - VCPU 0 VCPU0 -on fast page fault path: + gpte = gfn1 + gfn1 is mapped to pfn1 on host + spte is the shadow page table entry corresponding with gpte and + spte = pfn1 + + VCPU 0 VCPU0 + +on fast page fault path:: old_spte = *spte; pfn1 is swapped out: @@ -81,6 +87,7 @@ We dirty-log for gfn1, that means gfn2 is lost in dirty-bitmap. For direct sp, we can easily avoid it since the spte of direct sp is fixed to gfn. For indirect sp, before we do cmpxchg, we call gfn_to_pfn_atomic() to pin gfn to pfn, because after gfn_to_pfn_atomic(): + - We have held the refcount of pfn that means the pfn can not be freed and be reused for another gfn. - The pfn is writable that means it can not be shared between different gfns @@ -91,7 +98,8 @@ Then, we can ensure the dirty bitmaps is correctly set for a gfn. Currently, to simplify the whole things, we disable fast page fault for indirect shadow page. -2): Dirty bit tracking +2) Dirty bit tracking + In the origin code, the spte can be fast updated (non-atomically) if the spte is read-only and the Accessed bit has already been set since the Accessed bit and Dirty bit can not be lost. @@ -99,12 +107,14 @@ Accessed bit and Dirty bit can not be lost. But it is not true after fast page fault since the spte can be marked writable between reading spte and updating spte. Like below case: -At the beginning: -spte.W = 0 -spte.Accessed = 1 +At the beginning:: - VCPU 0 VCPU0 -In mmu_spte_clear_track_bits(): + spte.W = 0 + spte.Accessed = 1 + + VCPU 0 VCPU0 + +In mmu_spte_clear_track_bits():: old_spte = *spte; @@ -134,7 +144,8 @@ In order to avoid this kind of issue, we always treat the spte as "volatile" if it can be updated out of mmu-lock, see spte_has_volatile_bits(), it means, the spte is always atomically updated in this case. -3): flush tlbs due to spte updated +3) flush tlbs due to spte updated + If the spte is updated from writable to readonly, we should flush all TLBs, otherwise rmap_write_protect will find a read-only spte, even though the writable spte might be cached on a CPU's TLB. @@ -166,47 +177,47 @@ which time it will be set using the Dirty tracking mechanism described above. 3. Reference ------------ -Name: kvm_lock -Type: mutex -Arch: any -Protects: - vm_list +:Name: kvm_lock +:Type: mutex +:Arch: any +:Protects: - vm_list -Name: kvm_count_lock -Type: raw_spinlock_t -Arch: any -Protects: - hardware virtualization enable/disable -Comment: 'raw' because hardware enabling/disabling must be atomic /wrt +:Name: kvm_count_lock +:Type: raw_spinlock_t +:Arch: any +:Protects: - hardware virtualization enable/disable +:Comment: 'raw' because hardware enabling/disabling must be atomic /wrt migration. -Name: kvm_arch::tsc_write_lock -Type: raw_spinlock -Arch: x86 -Protects: - kvm_arch::{last_tsc_write,last_tsc_nsec,last_tsc_offset} +:Name: kvm_arch::tsc_write_lock +:Type: raw_spinlock +:Arch: x86 +:Protects: - kvm_arch::{last_tsc_write,last_tsc_nsec,last_tsc_offset} - tsc offset in vmcb -Comment: 'raw' because updating the tsc offsets must not be preempted. +:Comment: 'raw' because updating the tsc offsets must not be preempted. -Name: kvm->mmu_lock -Type: spinlock_t -Arch: any -Protects: -shadow page/shadow tlb entry -Comment: it is a spinlock since it is used in mmu notifier. +:Name: kvm->mmu_lock +:Type: spinlock_t +:Arch: any +:Protects: -shadow page/shadow tlb entry +:Comment: it is a spinlock since it is used in mmu notifier. -Name: kvm->srcu -Type: srcu lock -Arch: any -Protects: - kvm->memslots +:Name: kvm->srcu +:Type: srcu lock +:Arch: any +:Protects: - kvm->memslots - kvm->buses -Comment: The srcu read lock must be held while accessing memslots (e.g. +:Comment: The srcu read lock must be held while accessing memslots (e.g. when using gfn_to_* functions) and while accessing in-kernel MMIO/PIO address->device structure mapping (kvm->buses). The srcu index can be stored in kvm_vcpu->srcu_idx per vcpu if it is needed by multiple functions. -Name: blocked_vcpu_on_cpu_lock -Type: spinlock_t -Arch: x86 -Protects: blocked_vcpu_on_cpu -Comment: This is a per-CPU lock and it is used for VT-d posted-interrupts. +:Name: blocked_vcpu_on_cpu_lock +:Type: spinlock_t +:Arch: x86 +:Protects: blocked_vcpu_on_cpu +:Comment: This is a per-CPU lock and it is used for VT-d posted-interrupts. When VT-d posted-interrupts is supported and the VM has assigned devices, we put the blocked vCPU on the list blocked_vcpu_on_cpu protected by blocked_vcpu_on_cpu_lock, when VT-d hardware issues From patchwork Tue Jan 28 14:00:23 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354353 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id C8E8A92A for ; Tue, 28 Jan 2020 14:01:17 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 9EF3F24685 for ; Tue, 28 Jan 2020 14:01:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220077; bh=0QE9r9M4nSusoBtn0uQmTsBwPDzhFl/0GJzag3gO7W4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=gJt6yAsrlxQwK9XlTIsCFNt/sSFljZXMmXZgD9RD1HC56E/s4F2qjdBaoThab81+Q Zk/iwJq/C5cZ3I4cejBKe+brkzxIum2wxBoPmww2gs4SpyCYMN7qI5tl6eBsLOIUpK ck9AHVJZ4tm3fFPy5VWGOD6be7jCiLn7SnKZeEp0= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727406AbgA1OBQ (ORCPT ); Tue, 28 Jan 2020 09:01:16 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59352 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726824AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=F1P+6+TuszupGu0Tp2g0JB6lrpho1zIIc3pb798RBPM=; b=W1KEICt4HTRfCqH6HDrd2RpgfF Jb4fIstRpNv/q1FMnmdjYqMGqtZhcInwnHmqMAgON6KJWcuX7kxArsd9ETe3BJXdGrU+CcOJw6V7p wHRVaCSE4BpuHf0uDYmJEslSy49sZrQuXZT+nXOENWRcv60emPPxH53Wkugt1thfA1Wit6vVKC1by 700qXBQn6bT4M8td7hHrdTCGEhcYka9wahJUjvelgx7gbfo2vRysg/Tf0AgbGeo27SrOkxHnxSFYU Vw3UDE/5jL2zO1rgHdR3Oouo9P3GPtcUYY0YWNbkRz8fn8+c40gSoe+KMQo09m22K/fEli60/KOA6 rQHNFnwA==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007iv-VI; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPp-001BOx-Vo; Tue, 28 Jan 2020 15:00:29 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 22/27] docs: kvm: Convert mmu.txt to ReST format Date: Tue, 28 Jan 2020 15:00:23 +0100 Message-Id: <5e12ebc5b94bfd269d18d1e56d8b71c9f86a9ff2.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use document title and chapter markups; - Add markups for tables; - Add markups for literal blocks; - Add blank lines and adjust indentation. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/index.rst | 1 + Documentation/virt/kvm/{mmu.txt => mmu.rst} | 60 ++++++++++++++++----- 2 files changed, 47 insertions(+), 14 deletions(-) rename Documentation/virt/kvm/{mmu.txt => mmu.rst} (94%) diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index 9be8f53b729d..95e2487d38f4 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -13,6 +13,7 @@ KVM halt-polling hypercalls locking + mmu msr vcpu-requests diff --git a/Documentation/virt/kvm/mmu.txt b/Documentation/virt/kvm/mmu.rst similarity index 94% rename from Documentation/virt/kvm/mmu.txt rename to Documentation/virt/kvm/mmu.rst index dadb29e8738f..bf700a9a95fa 100644 --- a/Documentation/virt/kvm/mmu.txt +++ b/Documentation/virt/kvm/mmu.rst @@ -1,3 +1,4 @@ +====================== The x86 kvm shadow mmu ====================== @@ -7,27 +8,37 @@ physical addresses to host physical addresses. The mmu code attempts to satisfy the following requirements: -- correctness: the guest should not be able to determine that it is running +- correctness: + the guest should not be able to determine that it is running on an emulated mmu except for timing (we attempt to comply with the specification, not emulate the characteristics of a particular implementation such as tlb size) -- security: the guest must not be able to touch host memory not assigned +- security: + the guest must not be able to touch host memory not assigned to it -- performance: minimize the performance penalty imposed by the mmu -- scaling: need to scale to large memory and large vcpu guests -- hardware: support the full range of x86 virtualization hardware -- integration: Linux memory management code must be in control of guest memory +- performance: + minimize the performance penalty imposed by the mmu +- scaling: + need to scale to large memory and large vcpu guests +- hardware: + support the full range of x86 virtualization hardware +- integration: + Linux memory management code must be in control of guest memory so that swapping, page migration, page merging, transparent hugepages, and similar features work without change -- dirty tracking: report writes to guest memory to enable live migration +- dirty tracking: + report writes to guest memory to enable live migration and framebuffer-based displays -- footprint: keep the amount of pinned kernel memory low (most memory +- footprint: + keep the amount of pinned kernel memory low (most memory should be shrinkable) -- reliability: avoid multipage or GFP_ATOMIC allocations +- reliability: + avoid multipage or GFP_ATOMIC allocations Acronyms ======== +==== ==================================================================== pfn host page frame number hpa host physical address hva host virtual address @@ -41,6 +52,7 @@ pte page table entry (used also to refer generically to paging structure gpte guest pte (referring to gfns) spte shadow pte (referring to pfns) tdp two dimensional paging (vendor neutral term for NPT and EPT) +==== ==================================================================== Virtual and real hardware supported =================================== @@ -90,11 +102,13 @@ Events The mmu is driven by events, some from the guest, some from the host. Guest generated events: + - writes to control registers (especially cr3) - invlpg/invlpga instruction execution - access to missing or protected translations Host generated events: + - changes in the gpa->hpa translation (either through gpa->hva changes or through hva->hpa changes) - memory pressure (the shrinker) @@ -117,16 +131,19 @@ Leaf ptes point at guest pages. The following table shows translations encoded by leaf ptes, with higher-level translations in parentheses: - Non-nested guests: + Non-nested guests:: + nonpaging: gpa->hpa paging: gva->gpa->hpa paging, tdp: (gva->)gpa->hpa - Nested guests: + + Nested guests:: + non-tdp: ngva->gpa->hpa (*) tdp: (ngva->)ngpa->gpa->hpa -(*) the guest hypervisor will encode the ngva->gpa translation into its page - tables if npt is not present + (*) the guest hypervisor will encode the ngva->gpa translation into its page + tables if npt is not present Shadow pages contain the following information: role.level: @@ -291,28 +308,41 @@ Handling a page fault is performed as follows: - if the RSV bit of the error code is set, the page fault is caused by guest accessing MMIO and cached MMIO information is available. + - walk shadow page table - check for valid generation number in the spte (see "Fast invalidation of MMIO sptes" below) - cache the information to vcpu->arch.mmio_gva, vcpu->arch.mmio_access and vcpu->arch.mmio_gfn, and call the emulator + - If both P bit and R/W bit of error code are set, this could possibly be handled as a "fast page fault" (fixed without taking the MMU lock). See the description in Documentation/virt/kvm/locking.txt. + - if needed, walk the guest page tables to determine the guest translation (gva->gpa or ngpa->gpa) + - if permissions are insufficient, reflect the fault back to the guest + - determine the host page + - if this is an mmio request, there is no host page; cache the info to vcpu->arch.mmio_gva, vcpu->arch.mmio_access and vcpu->arch.mmio_gfn + - walk the shadow page table to find the spte for the translation, instantiating missing intermediate page tables as necessary + - If this is an mmio request, cache the mmio info to the spte and set some reserved bit on the spte (see callers of kvm_mmu_set_mmio_spte_mask) + - try to unsynchronize the page + - if successful, we can let the guest continue and modify the gpte + - emulate the instruction + - if failed, unshadow the page and let the guest continue + - update any translations that were modified by the instruction invlpg handling: @@ -324,10 +354,12 @@ invlpg handling: Guest control register updates: - mov to cr3 + - look up new shadow roots - synchronize newly reachable shadow pages - mov to cr0/cr4/efer + - set up mmu context for new paging mode - look up new shadow roots - synchronize newly reachable shadow pages @@ -358,6 +390,7 @@ on fault type: (user write faults generate a #PF) In the first case there are two additional complications: + - if CR4.SMEP is enabled: since we've turned the page into a kernel page, the kernel may now execute it. We handle this by also setting spte.nx. If we get a user fetch or read fault, we'll change spte.u=1 and @@ -446,4 +479,3 @@ Further reading - NPT presentation from KVM Forum 2008 http://www.linux-kvm.org/images/c/c8/KvmForum2008%24kdf2008_21.pdf - From patchwork Tue Jan 28 14:00:24 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354329 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 9A02392A for ; Tue, 28 Jan 2020 14:00:55 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 78A2524685 for ; Tue, 28 Jan 2020 14:00:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220055; bh=sGk0BrUSu5QXbj5v/8QRxYs4iY17tAGC+ZJwXkfkCGU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=Rr4eAIcNnPnfUspCaoFzDnEt7PZc96lCOCjA03JqVa89iF00m6PfVjfwM/X+sQnbg 1qSp0sibCtpjBAwaB8Nvj91gM5/qkQobnrq8rp7UAqjucvHh1FTsJddL1XugAdOdlj ylx57KPmc7bbSKxNDSep6qc7ze+MTL9+f6f7sc9s= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727340AbgA1OAs (ORCPT ); Tue, 28 Jan 2020 09:00:48 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59366 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727305AbgA1OAr (ORCPT ); Tue, 28 Jan 2020 09:00:47 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=vckRGT1a+50xrf38zV+HbwSHDdDQVhODH0o9Xm2cn8g=; b=rrs1VPIIVbr+Y9y298ws/9HrHG jfht9ve1xN9Wozx/momDeScw4XmhMrl/CVw4F2xOnwASR1YL/AjyQMSXyjx4R0lUThKHRZXOs+gel iT7+tAE8gRMa8ZZXERY3ndnEc44gn3RkZ30iCzwLAMScP7zlthlDLe0BofZbIRIVfCK0plBqzDTSC QLwVEq1ynKm12+UYXsfUpoMpt9ax1vB9vSVDx++RDTSpXfQgOCWGd8ke+J85f1dGK5l2/vEo1LsBL vvIFUqDa64CirLDAJAv9b34fzXDiXKbCPnVoxki4rvtY9FsRS2+kzKl1sLTNHTAlG+NLFwbjWcTy3 bBeOjVew==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ6-0007iy-JT; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPq-001BP2-0X; Tue, 28 Jan 2020 15:00:30 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 23/27] docs: kvm: Convert nested-vmx.txt to ReST format Date: Tue, 28 Jan 2020 15:00:24 +0100 Message-Id: X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org This file is almost in ReST format. Just a small set of changes were needed: - Add markups for lists; - Add markups for a literal block; - Adjust whitespaces. While here, use the standard markup for the document title. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/index.rst | 1 + .../kvm/{nested-vmx.txt => nested-vmx.rst} | 35 ++++++++++--------- 2 files changed, 20 insertions(+), 16 deletions(-) rename Documentation/virt/kvm/{nested-vmx.txt => nested-vmx.rst} (90%) diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index 95e2487d38f4..123385d0a74a 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -15,6 +15,7 @@ KVM locking mmu msr + nested-vmx vcpu-requests arm/index diff --git a/Documentation/virt/kvm/nested-vmx.txt b/Documentation/virt/kvm/nested-vmx.rst similarity index 90% rename from Documentation/virt/kvm/nested-vmx.txt rename to Documentation/virt/kvm/nested-vmx.rst index 97eb1353e962..7f28a5d2c135 100644 --- a/Documentation/virt/kvm/nested-vmx.txt +++ b/Documentation/virt/kvm/nested-vmx.rst @@ -1,3 +1,4 @@ +========== Nested VMX ========== @@ -41,9 +42,9 @@ No modifications are required to user space (qemu). However, qemu's default emulated CPU type (qemu64) does not list the "VMX" CPU feature, so it must be explicitly enabled, by giving qemu one of the following options: - -cpu host (emulated CPU has all features of the real CPU) + - cpu host (emulated CPU has all features of the real CPU) - -cpu qemu64,+vmx (add just the vmx feature to a named CPU type) + - cpu qemu64,+vmx (add just the vmx feature to a named CPU type) ABIs @@ -75,6 +76,8 @@ of this structure changes, this can break live migration across KVM versions. VMCS12_REVISION (from vmx.c) should be changed if struct vmcs12 or its inner struct shadow_vmcs is ever changed. +:: + typedef u64 natural_width; struct __packed vmcs12 { /* According to the Intel spec, a VMCS region must start with @@ -220,21 +223,21 @@ Authors ------- These patches were written by: - Abel Gordon, abelg il.ibm.com - Nadav Har'El, nyh il.ibm.com - Orit Wasserman, oritw il.ibm.com - Ben-Ami Yassor, benami il.ibm.com - Muli Ben-Yehuda, muli il.ibm.com + - Abel Gordon, abelg il.ibm.com + - Nadav Har'El, nyh il.ibm.com + - Orit Wasserman, oritw il.ibm.com + - Ben-Ami Yassor, benami il.ibm.com + - Muli Ben-Yehuda, muli il.ibm.com With contributions by: - Anthony Liguori, aliguori us.ibm.com - Mike Day, mdday us.ibm.com - Michael Factor, factor il.ibm.com - Zvi Dubitzky, dubi il.ibm.com + - Anthony Liguori, aliguori us.ibm.com + - Mike Day, mdday us.ibm.com + - Michael Factor, factor il.ibm.com + - Zvi Dubitzky, dubi il.ibm.com And valuable reviews by: - Avi Kivity, avi redhat.com - Gleb Natapov, gleb redhat.com - Marcelo Tosatti, mtosatti redhat.com - Kevin Tian, kevin.tian intel.com - and others. + - Avi Kivity, avi redhat.com + - Gleb Natapov, gleb redhat.com + - Marcelo Tosatti, mtosatti redhat.com + - Kevin Tian, kevin.tian intel.com + - and others. From patchwork Tue Jan 28 14:00:25 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354365 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 592C992A for ; Tue, 28 Jan 2020 14:01:21 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 389882468A for ; Tue, 28 Jan 2020 14:01:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220081; bh=795yPTUSfVe+hG1rmaDX94jxZ1VuKXvbMxuir2oih+c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=Br4yb3B7my8OYlHc4nKwyelUd1VhYXnGTLEqduaAqGYBOt6TyyhdvRxgcOgANtDF8 6UQqM5/OTcbAY+p3ghz+GNC1QVFJtJq7sFPxZ3f+E3w7sIR3A93n2v3TfHzlRIEMbT mR6DOb2eQBuOqIZ997q8LEGCus4hprwMCpnkHJk8= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727390AbgA1OBP (ORCPT ); Tue, 28 Jan 2020 09:01:15 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59438 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727309AbgA1OAr (ORCPT ); Tue, 28 Jan 2020 09:00:47 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=+WNxyocIFkVeesp32YWC96UEF5Kc5LQkXGQZYQc6ySw=; b=lofLN/PNx5ng4DvM87w0teY51F 5MqToNnN3tHh5RHU5Ijrvf1i1/xKqzcLdLJltGkrfu1V+jyQTfh4fNFn3kqTGgYQ7aGxzo5tTEVm9 uKAeYiId8kCFYuxyEWW64aVagkWTFsh4gbnVVWq4ByqVrqEIR4rh4B8PQLBT8qdObMZvdzhqb0jb2 I/YXCC4RTN9KwlgT5gpx5bfUk1tcMpjSyiiN4gpGD8NhS+Ts2VS2ytqVmscgh43Otx0VqZ6DvsF8T bdKL3WH/A5jPRpQZmnKfrLC9tCLoQ70MQfaJC1b2tETMBvahSorZo4OTmXd07J7XnX6S8C6OxYjl3 fyR3gPrQ==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ6-0007iz-QJ; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPq-001BP7-1Y; Tue, 28 Jan 2020 15:00:30 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 24/27] docs: kvm: Convert ppc-pv.txt to ReST format Date: Tue, 28 Jan 2020 15:00:25 +0100 Message-Id: <5b9b75925f0d56324168884576639d9ebdf071a7.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use document title and chapter markups; - Add markups for tables; - Use list markups; - Add markups for literal blocks; - Add blank lines. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/index.rst | 1 + .../virt/kvm/{ppc-pv.txt => ppc-pv.rst} | 24 ++++++++++++------- 2 files changed, 17 insertions(+), 8 deletions(-) rename Documentation/virt/kvm/{ppc-pv.txt => ppc-pv.rst} (91%) diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index 123385d0a74a..d0e17e717461 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -16,6 +16,7 @@ KVM mmu msr nested-vmx + ppc-pv vcpu-requests arm/index diff --git a/Documentation/virt/kvm/ppc-pv.txt b/Documentation/virt/kvm/ppc-pv.rst similarity index 91% rename from Documentation/virt/kvm/ppc-pv.txt rename to Documentation/virt/kvm/ppc-pv.rst index e26115ce4258..9c46e8cd57aa 100644 --- a/Documentation/virt/kvm/ppc-pv.txt +++ b/Documentation/virt/kvm/ppc-pv.rst @@ -1,3 +1,4 @@ +================================= The PPC KVM paravirtual interface ================================= @@ -34,8 +35,9 @@ up the hypercall. To call a hypercall, just call these instructions. The parameters are as follows: + ======== ================ ================ Register IN OUT - + ======== ================ ================ r0 - volatile r3 1st parameter Return code r4 2nd parameter 1st output value @@ -47,6 +49,7 @@ The parameters are as follows: r10 8th parameter 7th output value r11 hypercall number 8th output value r12 - volatile + ======== ================ ================ Hypercall definitions are shared in generic code, so the same hypercall numbers apply for x86 and powerpc alike with the exception that each KVM hypercall @@ -54,11 +57,13 @@ also needs to be ORed with the KVM vendor code which is (42 << 16). Return codes can be as follows: + ==== ========================= Code Meaning - + ==== ========================= 0 Success 12 Hypercall not implemented <0 Error + ==== ========================= The magic page ============== @@ -72,7 +77,7 @@ desired location. The first parameter indicates the effective address when the MMU is enabled. The second parameter indicates the address in real mode, if applicable to the target. For now, we always map the page to -4096. This way we can access it using absolute load and store functions. The following -instruction reads the first field of the magic page: +instruction reads the first field of the magic page:: ld rX, -4096(0) @@ -93,8 +98,10 @@ a bitmap of available features inside the magic page. The following enhancements to the magic page are currently available: + ============================ ======================================= KVM_MAGIC_FEAT_SR Maps SR registers r/w in the magic page KVM_MAGIC_FEAT_MAS0_TO_SPRG7 Maps MASn, ESR, PIR and high SPRGs + ============================ ======================================= For enhanced features in the magic page, please check for the existence of the feature before using them! @@ -121,8 +128,8 @@ when entering the guest or don't have any impact on the hypervisor's behavior. The following bits are safe to be set inside the guest: - MSR_EE - MSR_RI + - MSR_EE + - MSR_RI If any other bit changes in the MSR, please still use mtmsr(d). @@ -138,9 +145,9 @@ guest. Implementing any of those mappings is optional, as the instruction traps also act on the shared page. So calling privileged instructions still works as before. +======================= ================================ From To -==== == - +======================= ================================ mfmsr rX ld rX, magic_page->msr mfsprg rX, 0 ld rX, magic_page->sprg0 mfsprg rX, 1 ld rX, magic_page->sprg1 @@ -173,7 +180,7 @@ mtsrin rX, rY b [BookE only] wrteei [0|1] b - +======================= ================================ Some instructions require more logic to determine what's going on than a load or store instruction can deliver. To enable patching of those, we keep some @@ -191,6 +198,7 @@ for example. Hypercall ABIs in KVM on PowerPC ================================= + 1) KVM hypercalls (ePAPR) These are ePAPR compliant hypercall implementation (mentioned above). Even From patchwork Tue Jan 28 14:00:26 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354469 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0B0031398 for ; Tue, 28 Jan 2020 14:49:46 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id DE3E124683 for ; Tue, 28 Jan 2020 14:49:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580222985; bh=JQBwOUwZBEbNLgL4NUKye2Z47Qz39/TtXsJJ0DxHe9c=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=VFutZoEYKeSf9onQTPR9jWNnr49nohkinnQz+nZazHtbsP1ldKUxs0vM8hIXfPYTq 8ZNBHn0Gl464lzNP5+Oo4YFFiu9MlHIDjzYhWxBJkwzOdamg+A05p+MIrj6DvrD2tx UTZAit1R367d0bsP1bt2oKxHvT0cENcrWpAaCvR4= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726841AbgA1Otm (ORCPT ); Tue, 28 Jan 2020 09:49:42 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59312 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727299AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=Z/uTEaWAPqmykjmqaZJAVwB7XFP3pqrhmBP5QoZS5Zs=; b=qJPLbzXcEiZ1owWxQ+X1YPgKmB bD/hbUfLcFZJqiCaNBg18VT8UA15JUP1ie36FNMBuG7DTaqbw2bnCvWSq9U7zTUMPrxS4iHs6cOMC Mt6n7xMRKkbC/7laVaZVi/QX6B6ePgz7MALctCl1pAeB89tW5ulMnADvrgCOm/S9XsRo3wQq1Ni9h LLg+cRbikYkDsYEd1Imxsk3999p1klFAPjbkvItkb3IfjVIO58pF4Y/ht7B2x5Bxa9sI6VYrYY+NS TDH97hjVmZqPfkK8/VhHDOgVa5BgSo2SSetR6jqV5EbSLWTBvC/wtbHd6RvRrt7wssdwEzxWlNrDF hVwQL/RQ==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007iu-Vm; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPq-001BPC-39; Tue, 28 Jan 2020 15:00:30 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 25/27] docs: kvm: Convert s390-diag.txt to ReST format Date: Tue, 28 Jan 2020 15:00:26 +0100 Message-Id: <614882a25b34203f6e1de2982b2d619bf1cfddc1.1580219586.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org This file is almost in ReST format. Just one change was needed: - Add markups for a literal block and change its indentation. While here, use the standard markup for the document title. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Cornelia Huck --- Documentation/virt/kvm/index.rst | 1 + .../virt/kvm/{s390-diag.txt => s390-diag.rst} | 11 ++++++----- 2 files changed, 7 insertions(+), 5 deletions(-) rename Documentation/virt/kvm/{s390-diag.txt => s390-diag.rst} (91%) diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index d0e17e717461..e5ea75f97d52 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -17,6 +17,7 @@ KVM msr nested-vmx ppc-pv + s390-diag vcpu-requests arm/index diff --git a/Documentation/virt/kvm/s390-diag.txt b/Documentation/virt/kvm/s390-diag.rst similarity index 91% rename from Documentation/virt/kvm/s390-diag.txt rename to Documentation/virt/kvm/s390-diag.rst index 7c52e5f8b210..db6eb7a06b2a 100644 --- a/Documentation/virt/kvm/s390-diag.txt +++ b/Documentation/virt/kvm/s390-diag.rst @@ -1,3 +1,4 @@ +============================= The s390 DIAGNOSE call on KVM ============================= @@ -16,12 +17,12 @@ DIAGNOSE calls by the guest cause a mandatory intercept. This implies all supported DIAGNOSE calls need to be handled by either KVM or its userspace. -All DIAGNOSE calls supported by KVM use the RS-a format: +All DIAGNOSE calls supported by KVM use the RS-a format:: --------------------------------------- -| '83' | R1 | R3 | B2 | D2 | --------------------------------------- -0 8 12 16 20 31 + -------------------------------------- + | '83' | R1 | R3 | B2 | D2 | + -------------------------------------- + 0 8 12 16 20 31 The second-operand address (obtained by the base/displacement calculation) is not used to address data. Instead, bits 48-63 of this address specify From patchwork Tue Jan 28 14:00:27 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354341 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0CC7992A for ; Tue, 28 Jan 2020 14:01:03 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id CB6B9205F4 for ; Tue, 28 Jan 2020 14:01:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220062; bh=mO5QnGsw8qoTC/tzUoGDcUqIfuDEZ4CZdHsN7p1sHus=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=q8BkEyhlGFN4D/qjGR6+lWen9xbkCmjSKleDnfmWRPDSMdUssOZzEFDl9Uv3J8HOT 4hMtgl/GyvUDeJ+1UN6QNdhO8skr57tGqnOvIntHNjuRFBRGWfwhhWC+96zsMLdrbG ksu9XAELylKX6x/hgCFWmbsuxAg5CdFpMlnbungI= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726651AbgA1OBA (ORCPT ); Tue, 28 Jan 2020 09:01:00 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59458 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727312AbgA1OAs (ORCPT ); Tue, 28 Jan 2020 09:00:48 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=k7mipT3BnzZ+PHC6NfLwqWczHTzUdENJjYd9bPWXMwA=; b=gAwFtK9v/aki0/G4X/AOBrhS8Z SH7ASIawfR5k6boJuwEzIoepKWKEk5+IU1dp0Dc2RCQ6/0rLDEUKB6mtzGWKuvhUakw5IlOBEenDO tlu6pwShaH9xxRYQNdxpOW83U3RKmfcTk9OMl3CX7IqwoCxqh3n0TrV0DKYSvtxJjcZsuaq9euAhB OrfTnlM13UE+fzzemXC2Ynuce0VunszkE2DR/lFFz71EvnplhkZk9x4LAZ/k+tKX30G1IRPEfZGV4 243+GsOzr+ZR6aVHJpbvkcxfRTbj7FN3zheQvp8Vq/MtcZPWJrvpTPpM8FoSXKxXzxEIieZqdGror Dbiv/6+g==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ5-0007it-UO; Tue, 28 Jan 2020 14:00:47 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPq-001BPH-4A; Tue, 28 Jan 2020 15:00:30 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 26/27] docs: kvm: Convert timekeeping.txt to ReST format Date: Tue, 28 Jan 2020 15:00:27 +0100 Message-Id: X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org - Use document title and chapter markups; - Add markups for literal blocks; - Add markups for tables; - use :field: for field descriptions; - Add blank lines and adjust indentation. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/index.rst | 1 + .../kvm/{timekeeping.txt => timekeeping.rst} | 221 ++++++++++-------- 2 files changed, 127 insertions(+), 95 deletions(-) rename Documentation/virt/kvm/{timekeeping.txt => timekeeping.rst} (85%) diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index e5ea75f97d52..7c1be8910837 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -18,6 +18,7 @@ KVM nested-vmx ppc-pv s390-diag + timekeeping vcpu-requests arm/index diff --git a/Documentation/virt/kvm/timekeeping.txt b/Documentation/virt/kvm/timekeeping.rst similarity index 85% rename from Documentation/virt/kvm/timekeeping.txt rename to Documentation/virt/kvm/timekeeping.rst index 76808a17ad84..78f8979e1471 100644 --- a/Documentation/virt/kvm/timekeeping.txt +++ b/Documentation/virt/kvm/timekeeping.rst @@ -1,17 +1,19 @@ +====================================================== +Timekeeping Virtualization for X86-Based Architectures +====================================================== - Timekeeping Virtualization for X86-Based Architectures +:Author: Zachary Amsden +:Copyright: (c) 2010, Red Hat. All rights reserved. - Zachary Amsden - Copyright (c) 2010, Red Hat. All rights reserved. +.. Contents -1) Overview -2) Timing Devices -3) TSC Hardware -4) Virtualization Problems + 1) Overview + 2) Timing Devices + 3) TSC Hardware + 4) Virtualization Problems -========================================================================= - -1) Overview +1. Overview +=========== One of the most complicated parts of the X86 platform, and specifically, the virtualization of this platform is the plethora of timing devices available @@ -27,15 +29,15 @@ The purpose of this document is to collect data and information relevant to timekeeping which may be difficult to find elsewhere, specifically, information relevant to KVM and hardware-based virtualization. -========================================================================= - -2) Timing Devices +2. Timing Devices +================= First we discuss the basic hardware devices available. TSC and the related KVM clock are special enough to warrant a full exposition and are described in the following section. -2.1) i8254 - PIT +2.1. i8254 - PIT +---------------- One of the first timer devices available is the programmable interrupt timer, or PIT. The PIT has a fixed frequency 1.193182 MHz base clock and three @@ -50,13 +52,13 @@ The PIT uses I/O ports 0x40 - 0x43. Access to the 16-bit counters is done using single or multiple byte access to the I/O ports. There are 6 modes available, but not all modes are available to all timers, as only timer 2 has a connected gate input, required for modes 1 and 5. The gate line is -controlled by port 61h, bit 0, as illustrated in the following diagram. +controlled by port 61h, bit 0, as illustrated in the following diagram:: - -------------- ---------------- -| | | | -| 1.1932 MHz |---------->| CLOCK OUT | ---------> IRQ 0 -| Clock | | | | - -------------- | +->| GATE TIMER 0 | + -------------- ---------------- + | | | | + | 1.1932 MHz|---------->| CLOCK OUT | ---------> IRQ 0 + | Clock | | | | + -------------- | +->| GATE TIMER 0 | | ---------------- | | ---------------- @@ -70,29 +72,33 @@ controlled by port 61h, bit 0, as illustrated in the following diagram. | | | |------>| CLOCK OUT | ---------> Port 61h, bit 5 | | | -Port 61h, bit 0 ---------->| GATE TIMER 2 | \_.---- ____ + Port 61h, bit 0 -------->| GATE TIMER 2 | \_.---- ____ ---------------- _| )--|LPF|---Speaker / *---- \___/ -Port 61h, bit 1 -----------------------------------/ + Port 61h, bit 1 ---------------------------------/ The timer modes are now described. -Mode 0: Single Timeout. This is a one-shot software timeout that counts down +Mode 0: Single Timeout. + This is a one-shot software timeout that counts down when the gate is high (always true for timers 0 and 1). When the count reaches zero, the output goes high. -Mode 1: Triggered One-shot. The output is initially set high. When the gate +Mode 1: Triggered One-shot. + The output is initially set high. When the gate line is set high, a countdown is initiated (which does not stop if the gate is lowered), during which the output is set low. When the count reaches zero, the output goes high. -Mode 2: Rate Generator. The output is initially set high. When the countdown +Mode 2: Rate Generator. + The output is initially set high. When the countdown reaches 1, the output goes low for one count and then returns high. The value is reloaded and the countdown automatically resumes. If the gate line goes low, the count is halted. If the output is low when the gate is lowered, the output automatically goes high (this only affects timer 2). -Mode 3: Square Wave. This generates a high / low square wave. The count +Mode 3: Square Wave. + This generates a high / low square wave. The count determines the length of the pulse, which alternates between high and low when zero is reached. The count only proceeds when gate is high and is automatically reloaded on reaching zero. The count is decremented twice at @@ -103,12 +109,14 @@ Mode 3: Square Wave. This generates a high / low square wave. The count values are not observed when reading. This is the intended mode for timer 2, which generates sine-like tones by low-pass filtering the square wave output. -Mode 4: Software Strobe. After programming this mode and loading the counter, +Mode 4: Software Strobe. + After programming this mode and loading the counter, the output remains high until the counter reaches zero. Then the output goes low for 1 clock cycle and returns high. The counter is not reloaded. Counting only occurs when gate is high. -Mode 5: Hardware Strobe. After programming and loading the counter, the +Mode 5: Hardware Strobe. + After programming and loading the counter, the output remains high. When the gate is raised, a countdown is initiated (which does not stop if the gate is lowered). When the counter reaches zero, the output goes low for 1 clock cycle and then returns high. The counter is @@ -118,49 +126,49 @@ In addition to normal binary counting, the PIT supports BCD counting. The command port, 0x43 is used to set the counter and mode for each of the three timers. -PIT commands, issued to port 0x43, using the following bit encoding: +PIT commands, issued to port 0x43, using the following bit encoding:: -Bit 7-4: Command (See table below) -Bit 3-1: Mode (000 = Mode 0, 101 = Mode 5, 11X = undefined) -Bit 0 : Binary (0) / BCD (1) + Bit 7-4: Command (See table below) + Bit 3-1: Mode (000 = Mode 0, 101 = Mode 5, 11X = undefined) + Bit 0 : Binary (0) / BCD (1) -Command table: +Command table:: -0000 - Latch Timer 0 count for port 0x40 + 0000 - Latch Timer 0 count for port 0x40 sample and hold the count to be read in port 0x40; additional commands ignored until counter is read; mode bits ignored. -0001 - Set Timer 0 LSB mode for port 0x40 + 0001 - Set Timer 0 LSB mode for port 0x40 set timer to read LSB only and force MSB to zero; mode bits set timer mode -0010 - Set Timer 0 MSB mode for port 0x40 + 0010 - Set Timer 0 MSB mode for port 0x40 set timer to read MSB only and force LSB to zero; mode bits set timer mode -0011 - Set Timer 0 16-bit mode for port 0x40 + 0011 - Set Timer 0 16-bit mode for port 0x40 set timer to read / write LSB first, then MSB; mode bits set timer mode -0100 - Latch Timer 1 count for port 0x41 - as described above -0101 - Set Timer 1 LSB mode for port 0x41 - as described above -0110 - Set Timer 1 MSB mode for port 0x41 - as described above -0111 - Set Timer 1 16-bit mode for port 0x41 - as described above + 0100 - Latch Timer 1 count for port 0x41 - as described above + 0101 - Set Timer 1 LSB mode for port 0x41 - as described above + 0110 - Set Timer 1 MSB mode for port 0x41 - as described above + 0111 - Set Timer 1 16-bit mode for port 0x41 - as described above -1000 - Latch Timer 2 count for port 0x42 - as described above -1001 - Set Timer 2 LSB mode for port 0x42 - as described above -1010 - Set Timer 2 MSB mode for port 0x42 - as described above -1011 - Set Timer 2 16-bit mode for port 0x42 as described above + 1000 - Latch Timer 2 count for port 0x42 - as described above + 1001 - Set Timer 2 LSB mode for port 0x42 - as described above + 1010 - Set Timer 2 MSB mode for port 0x42 - as described above + 1011 - Set Timer 2 16-bit mode for port 0x42 as described above -1101 - General counter latch + 1101 - General counter latch Latch combination of counters into corresponding ports Bit 3 = Counter 2 Bit 2 = Counter 1 Bit 1 = Counter 0 Bit 0 = Unused -1110 - Latch timer status + 1110 - Latch timer status Latch combination of counter mode into corresponding ports Bit 3 = Counter 2 Bit 2 = Counter 1 @@ -177,7 +185,8 @@ Command table: Bit 3-1 = Mode Bit 0 = Binary (0) / BCD mode (1) -2.2) RTC +2.2. RTC +-------- The second device which was available in the original PC was the MC146818 real time clock. The original device is now obsolete, and usually emulated by the @@ -201,21 +210,21 @@ in progress, as indicated in the status register. The clock uses a 32.768kHz crystal, so bits 6-4 of register A should be programmed to a 32kHz divider if the RTC is to count seconds. -This is the RAM map originally used for the RTC/CMOS: +This is the RAM map originally used for the RTC/CMOS:: -Location Size Description ------------------------------------------- -00h byte Current second (BCD) -01h byte Seconds alarm (BCD) -02h byte Current minute (BCD) -03h byte Minutes alarm (BCD) -04h byte Current hour (BCD) -05h byte Hours alarm (BCD) -06h byte Current day of week (BCD) -07h byte Current day of month (BCD) -08h byte Current month (BCD) -09h byte Current year (BCD) -0Ah byte Register A + Location Size Description + ------------------------------------------ + 00h byte Current second (BCD) + 01h byte Seconds alarm (BCD) + 02h byte Current minute (BCD) + 03h byte Minutes alarm (BCD) + 04h byte Current hour (BCD) + 05h byte Hours alarm (BCD) + 06h byte Current day of week (BCD) + 07h byte Current day of month (BCD) + 08h byte Current month (BCD) + 09h byte Current year (BCD) + 0Ah byte Register A bit 7 = Update in progress bit 6-4 = Divider for clock 000 = 4.194 MHz @@ -234,7 +243,7 @@ Location Size Description 1101 = 125 mS 1110 = 250 mS 1111 = 500 mS -0Bh byte Register B + 0Bh byte Register B bit 7 = Run (0) / Halt (1) bit 6 = Periodic interrupt enable bit 5 = Alarm interrupt enable @@ -243,19 +252,20 @@ Location Size Description bit 2 = BCD calendar (0) / Binary (1) bit 1 = 12-hour mode (0) / 24-hour mode (1) bit 0 = 0 (DST off) / 1 (DST enabled) -OCh byte Register C (read only) + OCh byte Register C (read only) bit 7 = interrupt request flag (IRQF) bit 6 = periodic interrupt flag (PF) bit 5 = alarm interrupt flag (AF) bit 4 = update interrupt flag (UF) bit 3-0 = reserved -ODh byte Register D (read only) + ODh byte Register D (read only) bit 7 = RTC has power bit 6-0 = reserved -32h byte Current century BCD (*) + 32h byte Current century BCD (*) (*) location vendor specific and now determined from ACPI global tables -2.3) APIC +2.3. APIC +--------- On Pentium and later processors, an on-board timer is available to each CPU as part of the Advanced Programmable Interrupt Controller. The APIC is @@ -276,7 +286,8 @@ timer is programmed through the LVT (local vector timer) register, is capable of one-shot or periodic operation, and is based on the bus clock divided down by the programmable divider register. -2.4) HPET +2.4. HPET +--------- HPET is quite complex, and was originally intended to replace the PIT / RTC support of the X86 PC. It remains to be seen whether that will be the case, as @@ -297,7 +308,8 @@ indicated through ACPI tables by the BIOS. Detailed specification of the HPET is beyond the current scope of this document, as it is also very well documented elsewhere. -2.5) Offboard Timers +2.5. Offboard Timers +-------------------- Several cards, both proprietary (watchdog boards) and commonplace (e1000) have timing chips built into the cards which may have registers which are accessible @@ -307,9 +319,8 @@ general frowned upon as not playing by the agreed rules of the game. Such a timer device would require additional support to be virtualized properly and is not considered important at this time as no known operating system does this. -========================================================================= - -3) TSC Hardware +3. TSC Hardware +=============== The TSC or time stamp counter is relatively simple in theory; it counts instruction cycles issued by the processor, which can be used as a measure of @@ -340,7 +351,8 @@ allows the guest visible TSC to be offset by a constant. Newer implementations promise to allow the TSC to additionally be scaled, but this hardware is not yet widely available. -3.1) TSC synchronization +3.1. TSC synchronization +------------------------ The TSC is a CPU-local clock in most implementations. This means, on SMP platforms, the TSCs of different CPUs may start at different times depending @@ -357,7 +369,8 @@ practice, getting a perfectly synchronized TSC will not be possible unless all values are read from the same clock, which generally only is possible on single socket systems or those with special hardware support. -3.2) TSC and CPU hotplug +3.2. TSC and CPU hotplug +------------------------ As touched on already, CPUs which arrive later than the boot time of the system may not have a TSC value that is synchronized with the rest of the system. @@ -367,7 +380,8 @@ a guarantee. This can have the effect of bringing a system from a state where TSC is synchronized back to a state where TSC synchronization flaws, however small, may be exposed to the OS and any virtualization environment. -3.3) TSC and multi-socket / NUMA +3.3. TSC and multi-socket / NUMA +-------------------------------- Multi-socket systems, especially large multi-socket systems are likely to have individual clocksources rather than a single, universally distributed clock. @@ -385,7 +399,8 @@ standards for telecommunications and computer equipment. It is recommended not to trust the TSCs to remain synchronized on NUMA or multiple socket systems for these reasons. -3.4) TSC and C-states +3.4. TSC and C-states +--------------------- C-states, or idling states of the processor, especially C1E and deeper sleep states may be problematic for TSC as well. The TSC may stop advancing in such @@ -396,7 +411,8 @@ based on CPU and chipset identifications. The TSC in such a case may be corrected by catching it up to a known external clocksource. -3.5) TSC frequency change / P-states +3.5. TSC frequency change / P-states +------------------------------------ To make things slightly more interesting, some CPUs may change frequency. They may or may not run the TSC at the same rate, and because the frequency change @@ -416,14 +432,16 @@ other processors. In such cases, the TSC on halted CPUs could advance faster than that of non-halted processors. AMD Turion processors are known to have this problem. -3.6) TSC and STPCLK / T-states +3.6. TSC and STPCLK / T-states +------------------------------ External signals given to the processor may also have the effect of stopping the TSC. This is typically done for thermal emergency power control to prevent an overheating condition, and typically, there is no way to detect that this condition has happened. -3.7) TSC virtualization - VMX +3.7. TSC virtualization - VMX +----------------------------- VMX provides conditional trapping of RDTSC, RDMSR, WRMSR and RDTSCP instructions, which is enough for full virtualization of TSC in any manner. In @@ -431,14 +449,16 @@ addition, VMX allows passing through the host TSC plus an additional TSC_OFFSET field specified in the VMCS. Special instructions must be used to read and write the VMCS field. -3.8) TSC virtualization - SVM +3.8. TSC virtualization - SVM +----------------------------- SVM provides conditional trapping of RDTSC, RDMSR, WRMSR and RDTSCP instructions, which is enough for full virtualization of TSC in any manner. In addition, SVM allows passing through the host TSC plus an additional offset field specified in the SVM control block. -3.9) TSC feature bits in Linux +3.9. TSC feature bits in Linux +------------------------------ In summary, there is no way to guarantee the TSC remains in perfect synchronization unless it is explicitly guaranteed by the architecture. Even @@ -448,13 +468,16 @@ despite being locally consistent. The following feature bits are used by Linux to signal various TSC attributes, but they can only be taken to be meaningful for UP or single node systems. -X86_FEATURE_TSC : The TSC is available in hardware -X86_FEATURE_RDTSCP : The RDTSCP instruction is available -X86_FEATURE_CONSTANT_TSC : The TSC rate is unchanged with P-states -X86_FEATURE_NONSTOP_TSC : The TSC does not stop in C-states -X86_FEATURE_TSC_RELIABLE : TSC sync checks are skipped (VMware) +========================= ======================================= +X86_FEATURE_TSC The TSC is available in hardware +X86_FEATURE_RDTSCP The RDTSCP instruction is available +X86_FEATURE_CONSTANT_TSC The TSC rate is unchanged with P-states +X86_FEATURE_NONSTOP_TSC The TSC does not stop in C-states +X86_FEATURE_TSC_RELIABLE TSC sync checks are skipped (VMware) +========================= ======================================= -4) Virtualization Problems +4. Virtualization Problems +========================== Timekeeping is especially problematic for virtualization because a number of challenges arise. The most obvious problem is that time is now shared between @@ -473,7 +496,8 @@ BIOS, but not in such an extreme fashion. However, the fact that SMM mode may cause similar problems to virtualization makes it a good justification for solving many of these problems on bare metal. -4.1) Interrupt clocking +4.1. Interrupt clocking +----------------------- One of the most immediate problems that occurs with legacy operating systems is that the system timekeeping routines are often designed to keep track of @@ -502,7 +526,8 @@ thus requires interrupt slewing to keep proper time. It does use a low enough rate (ed: is it 18.2 Hz?) however that it has not yet been a problem in practice. -4.2) TSC sampling and serialization +4.2. TSC sampling and serialization +----------------------------------- As the highest precision time source available, the cycle counter of the CPU has aroused much interest from developers. As explained above, this timer has @@ -524,7 +549,8 @@ it may be necessary for an implementation to guard against "backwards" reads of the TSC as seen from other CPUs, even in an otherwise perfectly synchronized system. -4.3) Timespec aliasing +4.3. Timespec aliasing +---------------------- Additionally, this lack of serialization from the TSC poses another challenge when using results of the TSC when measured against another time source. As @@ -548,7 +574,8 @@ This aliasing requires care in the computation and recalibration of kvmclock and any other values derived from TSC computation (such as TSC virtualization itself). -4.4) Migration +4.4. Migration +-------------- Migration of a virtual machine raises problems for timekeeping in two ways. First, the migration itself may take time, during which interrupts cannot be @@ -566,7 +593,8 @@ always be caught up to the original rate. KVM clock avoids these problems by simply storing multipliers and offsets against the TSC for the guest to convert back into nanosecond resolution values. -4.5) Scheduling +4.5. Scheduling +--------------- Since scheduling may be based on precise timing and firing of interrupts, the scheduling algorithms of an operating system may be adversely affected by @@ -579,7 +607,8 @@ In an attempt to work around this, several implementations have provided a paravirtualized scheduler clock, which reveals the true amount of CPU time for which a virtual machine has been running. -4.6) Watchdogs +4.6. Watchdogs +-------------- Watchdog timers, such as the lock detector in Linux may fire accidentally when running under hardware virtualization due to timer interrupts being delayed or @@ -587,7 +616,8 @@ misinterpretation of the passage of real time. Usually, these warnings are spurious and can be ignored, but in some circumstances it may be necessary to disable such detection. -4.7) Delays and precision timing +4.7. Delays and precision timing +-------------------------------- Precise timing and delays may not be possible in a virtualized system. This can happen if the system is controlling physical hardware, or issues delays to @@ -600,7 +630,8 @@ The second issue may cause performance problems, but this is unlikely to be a significant issue. In many cases these delays may be eliminated through configuration or paravirtualization. -4.8) Covert channels and leaks +4.8. Covert channels and leaks +------------------------------ In addition to the above problems, time information will inevitably leak to the guest about the host in anything but a perfect implementation of virtualized From patchwork Tue Jan 28 14:00:28 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11354333 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id D801714B4 for ; Tue, 28 Jan 2020 14:00:58 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id B64C42468A for ; Tue, 28 Jan 2020 14:00:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1580220058; bh=jZNHsHOqCO64/b4cFrzFhkGrWSynCIXBkSudBt4Qs7U=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=U1O5CSD9Y2PV+5/Mvnhfa+IKquiZ1GvFSLAVhC48ris81mCzQxsXe6UCbdqPe0PZN FLOgfMKCkCYAVscQnfCD95VfYg35bUO2mDDB0/9YoDoZgi5epCGLnYh0gMxvCsOThF xpNJUMJy8kfxpgNzU+QleYmiQEEHivRUtc0Lr4jw= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727333AbgA1OAs (ORCPT ); Tue, 28 Jan 2020 09:00:48 -0500 Received: from bombadil.infradead.org ([198.137.202.133]:59318 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727300AbgA1OAq (ORCPT ); Tue, 28 Jan 2020 09:00:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=Tz48VZFw6Pyql4H3D79rMXp5boRr/1YzcV0w5QihF6k=; b=Mgx+5Is4LK6AQZN1NvMRds73I/ olXZWwA+nV2dCq76W6DvszQM20mr/QeWB5OMlccpTB4drRHwddZy2Fzh1XsX13HF7xOJKReiJFoqB zwpBSf8vvu0lkQj6Ap3ZPY72BaGLHEk3lI3YBzhO2eF8okyDtpZoZrIQoTG5UOUmWqo/mER00yyTw UhmsOtJ3vNK9LMyRuUmk4L6gUJWY053m7aue6ZkELS0F6Jn0KA0YXCIRTbOZs2FpcBLdcn3G1pcg2 mjH1DhMQ/8Zi3a1PX2ijXIitZilaux7DVWE/ebcTjsSzBTnbTVLhPl+yORMbCGHjE9llvH+tk1HT7 2ewzq2Bw==; Received: from [177.41.103.99] (helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.92.3 #3 (Red Hat Linux)) id 1iwRQ6-0007iw-8u; Tue, 28 Jan 2020 14:00:46 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92.3) (envelope-from ) id 1iwRPq-001BPM-5A; Tue, 28 Jan 2020 15:00:30 +0100 From: Mauro Carvalho Chehab To: Linux Media Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Paolo Bonzini , Jonathan Corbet , kvm@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 27/27] docs: kvm: review-checklist.txt: rename to ReST Date: Tue, 28 Jan 2020 15:00:28 +0100 Message-Id: X-Mailer: git-send-email 2.24.1 In-Reply-To: References: MIME-Version: 1.0 Sender: kvm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: kvm@vger.kernel.org This file is already in ReST compatible format. So, rename it and add to the kvm's index.rst. While here, use the standard conversion for document titles. Signed-off-by: Mauro Carvalho Chehab --- Documentation/virt/kvm/index.rst | 2 ++ .../virt/kvm/{review-checklist.txt => review-checklist.rst} | 1 + 2 files changed, 3 insertions(+) rename Documentation/virt/kvm/{review-checklist.txt => review-checklist.rst} (97%) diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst index 7c1be8910837..774deaebf7fa 100644 --- a/Documentation/virt/kvm/index.rst +++ b/Documentation/virt/kvm/index.rst @@ -21,6 +21,8 @@ KVM timekeeping vcpu-requests + review-checklist + arm/index devices/index diff --git a/Documentation/virt/kvm/review-checklist.txt b/Documentation/virt/kvm/review-checklist.rst similarity index 97% rename from Documentation/virt/kvm/review-checklist.txt rename to Documentation/virt/kvm/review-checklist.rst index 499af499e296..d52e0bf96121 100644 --- a/Documentation/virt/kvm/review-checklist.txt +++ b/Documentation/virt/kvm/review-checklist.rst @@ -1,3 +1,4 @@ +================================ Review checklist for kvm patches ================================