From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Media Mailing List <linux-media@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
Mauro Carvalho Chehab <mchehab@infradead.org>,
Paolo Bonzini <pbonzini@redhat.com>,
Jonathan Corbet <corbet@lwn.net>,
kvm@vger.kernel.org, linux-doc@vger.kernel.org
Subject: [PATCH 16/28] docs: kvm: convert devices/xive.txt to ReST
Date: Mon, 10 Feb 2020 07:02:54 +0100 [thread overview]
Message-ID: <b35f1d6366524884a81bbfdf6733bb3f2531fc61.1581314317.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1581314316.git.mchehab+huawei@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 <mchehab+huawei@kernel.org>
---
Documentation/virt/kvm/devices/index.rst | 1 +
.../virt/kvm/devices/{xive.txt => xive.rst} | 148 +++++++++++-------
2 files changed, 96 insertions(+), 53 deletions(-)
rename Documentation/virt/kvm/devices/{xive.txt => xive.rst} (62%)
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 62%
rename from Documentation/virt/kvm/devices/xive.txt
rename to Documentation/virt/kvm/devices/xive.rst
index f5d1d6b5af61..8bdf3dc38f01 100644
--- a/Documentation/virt/kvm/devices/xive.txt
+++ b/Documentation/virt/kvm/devices/xive.rst
@@ -1,8 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================================================
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 +67,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 +169,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 +179,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 +216,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 +238,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
--
2.24.1
next prev parent reply other threads:[~2020-02-10 6:03 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-10 6:02 [PATCH 00/28] docs: virt: manually convert text documents to ReST format Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 01/28] docs: kvm: add arm/pvtime.rst to index.rst Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 03/28] docs: virt: user_mode_linux.rst: update compiling instructions Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 04/28] docs: virt: user_mode_linux.rst: fix URL references Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 05/28] docs: virt: convert halt-polling.txt to ReST format Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 06/28] docs: virt: Convert msr.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 07/28] docs: kvm: devices/arm-vgic-its.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 08/28] docs: kvm: devices/arm-vgit-v3.txt to ReST Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 09/28] docs: kvm: convert devices/arm-vgit.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 10/28] docs: kvm: convert devices/mpic.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 11/28] docs: kvm: convert devices/s390_flic.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 12/28] docs: kvm: convert devices/vcpu.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 13/28] docs: kvm: convert devices/vfio.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 14/28] docs: kvm: convert devices/vm.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 15/28] docs: kvm: convert devices/xics.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` Mauro Carvalho Chehab [this message]
2020-02-10 6:02 ` [PATCH 18/28] docs: kvm: convert arm/hyp-abi.txt " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 19/28] docs: kvm: arm/psci.txt: convert " Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 20/28] docs: kvm: Convert hypercalls.txt to ReST format Mauro Carvalho Chehab
2020-02-10 6:02 ` [PATCH 21/28] docs: kvm: Convert locking.txt " Mauro Carvalho Chehab
2020-02-10 6:03 ` [PATCH 22/28] docs: kvm: Convert mmu.txt " Mauro Carvalho Chehab
2020-02-10 6:03 ` [PATCH 23/28] docs: kvm: Convert nested-vmx.txt " Mauro Carvalho Chehab
2020-02-10 6:03 ` [PATCH 24/28] docs: kvm: Convert ppc-pv.txt " Mauro Carvalho Chehab
2020-02-10 6:03 ` [PATCH 25/28] docs: kvm: Convert s390-diag.txt " Mauro Carvalho Chehab
2020-02-10 6:03 ` [PATCH 26/28] docs: kvm: Convert timekeeping.txt " Mauro Carvalho Chehab
2020-02-10 6:03 ` [PATCH 27/28] docs: kvm: review-checklist.txt: rename to ReST Mauro Carvalho Chehab
2020-02-10 6:03 ` [PATCH 28/28] docs: virt: guest-halt-polling.txt convert " Mauro Carvalho Chehab
2020-02-12 13:57 ` [PATCH 00/28] docs: virt: manually convert text documents to ReST format Paolo Bonzini
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=b35f1d6366524884a81bbfdf6733bb3f2531fc61.1581314317.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=kvm@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=mchehab@infradead.org \
--cc=pbonzini@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).