* [PATCH 00/27] docs: virt: convert text documents to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: kvm, linux-doc, Mauro Carvalho Chehab, Richard Weinberger,
Jeff Dike, Jonathan Corbet, linux-um, Mauro Carvalho Chehab,
Paolo Bonzini, Anton Ivanov
Manually convert the documentation under Documentation/virt to ReST,
minimizing the usage of uneeded markups and preserving the documentation
writer's style.
PS.: Patches are against docs-next tree.
Mauro Carvalho Chehab (27):
docs: kvm: add arm/pvtime.rst to index.rst
docs: virt: convert UML documentation to ReST
docs: virt: user_mode_linux.rst: update compiling instructions
docs: virt: user_mode_linux.rst: fix URL references
docs: virt: convert halt-polling.txt to ReST format
docs: virt: Convert msr.txt to ReST format
docs: kvm: devices/arm-vgic-its.txt to ReST format
docs: kvm: devices/arm-vgit-v3.txt to ReST
docs: kvm: convert devices/arm-vgit.txt to ReST
docs: kvm: convert devices/mpic.txt to ReST
docs: kvm: convert devices/s390_flic.txt to ReST
docs: kvm: convert devices/vcpu.txt to ReST
docs: kvm: convert devices/vcpu.txt to ReST
docs: kvm: convert devices/vm.txt to ReST
docs: kvm: convert devices/xics.txt to ReST
docs: kvm: convert devices/xive.txt to ReST
docs: kvm: Convert api.txt to ReST format
docs: kvm: convert arm/hyp-abi.txt to ReST
docs: kvm: arm/psci.txt: convert to ReST
docs: kvm: Convert hypercalls.txt to ReST format
docs: kvm: Convert locking.txt to ReST format
docs: kvm: Convert mmu.txt to ReST format
docs: kvm: Convert nested-vmx.txt to ReST format
docs: kvm: Convert ppc-pv.txt to ReST format
docs: kvm: Convert s390-diag.txt to ReST format
docs: kvm: Convert timekeeping.txt to ReST format
docs: kvm: review-checklist.txt: rename to ReST
Documentation/virt/index.rst | 1 +
Documentation/virt/kvm/{api.txt => api.rst} | 3343 ++++++++++-------
.../virt/kvm/arm/{hyp-abi.txt => hyp-abi.rst} | 26 +-
Documentation/virt/kvm/arm/index.rst | 12 +
.../virt/kvm/arm/{psci.txt => psci.rst} | 44 +-
.../{arm-vgic-its.txt => arm-vgic-its.rst} | 104 +-
.../{arm-vgic-v3.txt => arm-vgic-v3.rst} | 130 +-
.../devices/{arm-vgic.txt => arm-vgic.rst} | 87 +-
Documentation/virt/kvm/devices/index.rst | 19 +
.../virt/kvm/devices/{mpic.txt => mpic.rst} | 9 +-
.../devices/{s390_flic.txt => s390_flic.rst} | 68 +-
Documentation/virt/kvm/devices/vcpu.rst | 112 +
Documentation/virt/kvm/devices/vcpu.txt | 76 -
.../virt/kvm/devices/{vfio.txt => vfio.rst} | 23 +-
.../virt/kvm/devices/{vm.txt => vm.rst} | 204 +-
.../virt/kvm/devices/{xics.txt => xics.rst} | 26 +-
.../virt/kvm/devices/{xive.txt => xive.rst} | 146 +-
.../{halt-polling.txt => halt-polling.rst} | 84 +-
.../kvm/{hypercalls.txt => hypercalls.rst} | 127 +-
Documentation/virt/kvm/index.rst | 16 +
.../virt/kvm/{locking.txt => locking.rst} | 109 +-
Documentation/virt/kvm/{mmu.txt => mmu.rst} | 60 +-
Documentation/virt/kvm/{msr.txt => msr.rst} | 145 +-
.../kvm/{nested-vmx.txt => nested-vmx.rst} | 35 +-
.../virt/kvm/{ppc-pv.txt => ppc-pv.rst} | 24 +-
...iew-checklist.txt => review-checklist.rst} | 1 +
.../virt/kvm/{s390-diag.txt => s390-diag.rst} | 11 +-
.../kvm/{timekeeping.txt => timekeeping.rst} | 221 +-
...odeLinux-HOWTO.txt => user_mode_linux.rst} | 1812 ++++-----
29 files changed, 3954 insertions(+), 3121 deletions(-)
rename Documentation/virt/kvm/{api.txt => api.rst} (71%)
rename Documentation/virt/kvm/arm/{hyp-abi.txt => hyp-abi.rst} (80%)
create mode 100644 Documentation/virt/kvm/arm/index.rst
rename Documentation/virt/kvm/arm/{psci.txt => psci.rst} (61%)
rename Documentation/virt/kvm/devices/{arm-vgic-its.txt => arm-vgic-its.rst} (71%)
rename Documentation/virt/kvm/devices/{arm-vgic-v3.txt => arm-vgic-v3.rst} (77%)
rename Documentation/virt/kvm/devices/{arm-vgic.txt => arm-vgic.rst} (66%)
create mode 100644 Documentation/virt/kvm/devices/index.rst
rename Documentation/virt/kvm/devices/{mpic.txt => mpic.rst} (92%)
rename Documentation/virt/kvm/devices/{s390_flic.txt => s390_flic.rst} (88%)
create mode 100644 Documentation/virt/kvm/devices/vcpu.rst
delete mode 100644 Documentation/virt/kvm/devices/vcpu.txt
rename Documentation/virt/kvm/devices/{vfio.txt => vfio.rst} (74%)
rename Documentation/virt/kvm/devices/{vm.txt => vm.rst} (61%)
rename Documentation/virt/kvm/devices/{xics.txt => xics.rst} (85%)
rename Documentation/virt/kvm/devices/{xive.txt => xive.rst} (63%)
rename Documentation/virt/kvm/{halt-polling.txt => halt-polling.rst} (64%)
rename Documentation/virt/kvm/{hypercalls.txt => hypercalls.rst} (55%)
rename Documentation/virt/kvm/{locking.txt => locking.rst} (79%)
rename Documentation/virt/kvm/{mmu.txt => mmu.rst} (94%)
rename Documentation/virt/kvm/{msr.txt => msr.rst} (75%)
rename Documentation/virt/kvm/{nested-vmx.txt => nested-vmx.rst} (90%)
rename Documentation/virt/kvm/{ppc-pv.txt => ppc-pv.rst} (91%)
rename Documentation/virt/kvm/{review-checklist.txt => review-checklist.rst} (97%)
rename Documentation/virt/kvm/{s390-diag.txt => s390-diag.rst} (91%)
rename Documentation/virt/kvm/{timekeeping.txt => timekeeping.rst} (85%)
rename Documentation/virt/uml/{UserModeLinux-HOWTO.txt => user_mode_linux.rst} (74%)
--
2.24.1
_______________________________________________
linux-um mailing list
linux-um@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-um
^ permalink raw reply [flat|nested] 64+ messages in thread* [PATCH 00/27] docs: virt: convert text documents to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-um,
linux-doc, Paolo Bonzini, kvm, Jeff Dike, Richard Weinberger,
Anton Ivanov, Jonathan Corbet
Manually convert the documentation under Documentation/virt to ReST,
minimizing the usage of uneeded markups and preserving the documentation
writer's style.
PS.: Patches are against docs-next tree.
Mauro Carvalho Chehab (27):
docs: kvm: add arm/pvtime.rst to index.rst
docs: virt: convert UML documentation to ReST
docs: virt: user_mode_linux.rst: update compiling instructions
docs: virt: user_mode_linux.rst: fix URL references
docs: virt: convert halt-polling.txt to ReST format
docs: virt: Convert msr.txt to ReST format
docs: kvm: devices/arm-vgic-its.txt to ReST format
docs: kvm: devices/arm-vgit-v3.txt to ReST
docs: kvm: convert devices/arm-vgit.txt to ReST
docs: kvm: convert devices/mpic.txt to ReST
docs: kvm: convert devices/s390_flic.txt to ReST
docs: kvm: convert devices/vcpu.txt to ReST
docs: kvm: convert devices/vcpu.txt to ReST
docs: kvm: convert devices/vm.txt to ReST
docs: kvm: convert devices/xics.txt to ReST
docs: kvm: convert devices/xive.txt to ReST
docs: kvm: Convert api.txt to ReST format
docs: kvm: convert arm/hyp-abi.txt to ReST
docs: kvm: arm/psci.txt: convert to ReST
docs: kvm: Convert hypercalls.txt to ReST format
docs: kvm: Convert locking.txt to ReST format
docs: kvm: Convert mmu.txt to ReST format
docs: kvm: Convert nested-vmx.txt to ReST format
docs: kvm: Convert ppc-pv.txt to ReST format
docs: kvm: Convert s390-diag.txt to ReST format
docs: kvm: Convert timekeeping.txt to ReST format
docs: kvm: review-checklist.txt: rename to ReST
Documentation/virt/index.rst | 1 +
Documentation/virt/kvm/{api.txt => api.rst} | 3343 ++++++++++-------
.../virt/kvm/arm/{hyp-abi.txt => hyp-abi.rst} | 26 +-
Documentation/virt/kvm/arm/index.rst | 12 +
.../virt/kvm/arm/{psci.txt => psci.rst} | 44 +-
.../{arm-vgic-its.txt => arm-vgic-its.rst} | 104 +-
.../{arm-vgic-v3.txt => arm-vgic-v3.rst} | 130 +-
.../devices/{arm-vgic.txt => arm-vgic.rst} | 87 +-
Documentation/virt/kvm/devices/index.rst | 19 +
.../virt/kvm/devices/{mpic.txt => mpic.rst} | 9 +-
.../devices/{s390_flic.txt => s390_flic.rst} | 68 +-
Documentation/virt/kvm/devices/vcpu.rst | 112 +
Documentation/virt/kvm/devices/vcpu.txt | 76 -
.../virt/kvm/devices/{vfio.txt => vfio.rst} | 23 +-
.../virt/kvm/devices/{vm.txt => vm.rst} | 204 +-
.../virt/kvm/devices/{xics.txt => xics.rst} | 26 +-
.../virt/kvm/devices/{xive.txt => xive.rst} | 146 +-
.../{halt-polling.txt => halt-polling.rst} | 84 +-
.../kvm/{hypercalls.txt => hypercalls.rst} | 127 +-
Documentation/virt/kvm/index.rst | 16 +
.../virt/kvm/{locking.txt => locking.rst} | 109 +-
Documentation/virt/kvm/{mmu.txt => mmu.rst} | 60 +-
Documentation/virt/kvm/{msr.txt => msr.rst} | 145 +-
.../kvm/{nested-vmx.txt => nested-vmx.rst} | 35 +-
.../virt/kvm/{ppc-pv.txt => ppc-pv.rst} | 24 +-
...iew-checklist.txt => review-checklist.rst} | 1 +
.../virt/kvm/{s390-diag.txt => s390-diag.rst} | 11 +-
.../kvm/{timekeeping.txt => timekeeping.rst} | 221 +-
...odeLinux-HOWTO.txt => user_mode_linux.rst} | 1812 ++++-----
29 files changed, 3954 insertions(+), 3121 deletions(-)
rename Documentation/virt/kvm/{api.txt => api.rst} (71%)
rename Documentation/virt/kvm/arm/{hyp-abi.txt => hyp-abi.rst} (80%)
create mode 100644 Documentation/virt/kvm/arm/index.rst
rename Documentation/virt/kvm/arm/{psci.txt => psci.rst} (61%)
rename Documentation/virt/kvm/devices/{arm-vgic-its.txt => arm-vgic-its.rst} (71%)
rename Documentation/virt/kvm/devices/{arm-vgic-v3.txt => arm-vgic-v3.rst} (77%)
rename Documentation/virt/kvm/devices/{arm-vgic.txt => arm-vgic.rst} (66%)
create mode 100644 Documentation/virt/kvm/devices/index.rst
rename Documentation/virt/kvm/devices/{mpic.txt => mpic.rst} (92%)
rename Documentation/virt/kvm/devices/{s390_flic.txt => s390_flic.rst} (88%)
create mode 100644 Documentation/virt/kvm/devices/vcpu.rst
delete mode 100644 Documentation/virt/kvm/devices/vcpu.txt
rename Documentation/virt/kvm/devices/{vfio.txt => vfio.rst} (74%)
rename Documentation/virt/kvm/devices/{vm.txt => vm.rst} (61%)
rename Documentation/virt/kvm/devices/{xics.txt => xics.rst} (85%)
rename Documentation/virt/kvm/devices/{xive.txt => xive.rst} (63%)
rename Documentation/virt/kvm/{halt-polling.txt => halt-polling.rst} (64%)
rename Documentation/virt/kvm/{hypercalls.txt => hypercalls.rst} (55%)
rename Documentation/virt/kvm/{locking.txt => locking.rst} (79%)
rename Documentation/virt/kvm/{mmu.txt => mmu.rst} (94%)
rename Documentation/virt/kvm/{msr.txt => msr.rst} (75%)
rename Documentation/virt/kvm/{nested-vmx.txt => nested-vmx.rst} (90%)
rename Documentation/virt/kvm/{ppc-pv.txt => ppc-pv.rst} (91%)
rename Documentation/virt/kvm/{review-checklist.txt => review-checklist.rst} (97%)
rename Documentation/virt/kvm/{s390-diag.txt => s390-diag.rst} (91%)
rename Documentation/virt/kvm/{timekeeping.txt => timekeeping.rst} (85%)
rename Documentation/virt/uml/{UserModeLinux-HOWTO.txt => user_mode_linux.rst} (74%)
--
2.24.1
^ permalink raw reply [flat|nested] 64+ messages in thread* [PATCH 01/27] docs: kvm: add arm/pvtime.rst to index.rst
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:57 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 01/27] docs: kvm: add arm/pvtime.rst to index.rst
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:57 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 01/27] docs: kvm: add arm/pvtime.rst to index.rst
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 02/27] docs: virt: convert UML documentation to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
(?)
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:57 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jonathan Corbet,
Jeff Dike, Richard Weinberger, Anton Ivanov, linux-doc, linux-um
Despite being an old document, it contains lots of information
that could still be useful.
The document has a nice style with makes easy to convert to
ReST. So, let's convert it to ReST.
This patch does:
- Use proper markups for titles;
- Mark and proper indent literal blocks;
- don't use an 'o' character for lists;
- other minor changes required for the doc to be parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/index.rst | 1 +
...odeLinux-HOWTO.txt => user_mode_linux.rst} | 1703 ++++++++---------
2 files changed, 787 insertions(+), 917 deletions(-)
rename Documentation/virt/uml/{UserModeLinux-HOWTO.txt => user_mode_linux.rst} (75%)
diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst
index 062ffb527043..0a8f7fda64ad 100644
--- a/Documentation/virt/index.rst
+++ b/Documentation/virt/index.rst
@@ -8,6 +8,7 @@ Linux Virtualization Support
:maxdepth: 2
kvm/index
+ uml/user_mode_linux
paravirt_ops
.. only:: html and subproject
diff --git a/Documentation/virt/uml/UserModeLinux-HOWTO.txt b/Documentation/virt/uml/user_mode_linux.rst
similarity index 75%
rename from Documentation/virt/uml/UserModeLinux-HOWTO.txt
rename to Documentation/virt/uml/user_mode_linux.rst
index 87b80f589e1c..98922008be23 100644
--- a/Documentation/virt/uml/UserModeLinux-HOWTO.txt
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -1,12 +1,15 @@
- User Mode Linux HOWTO
- User Mode Linux Core Team
- Mon Nov 18 14:16:16 EST 2002
+=====================
+User Mode Linux HOWTO
+=====================
- This document describes the use and abuse of Jeff Dike's User Mode
- Linux: a port of the Linux kernel as a normal Intel Linux process.
- ______________________________________________________________________
+:Author: User Mode Linux Core Team
+:Last-updated: Mon Nov 18 14:16:16 EST 2002
- Table of Contents
+This document describes the use and abuse of Jeff Dike's User Mode
+Linux: a port of the Linux kernel as a normal Intel Linux process.
+
+
+.. Table of Contents
1. Introduction
@@ -132,19 +135,19 @@
15.5 Other contributions
- ______________________________________________________________________
-
- 1. Introduction
+1. Introduction
+================
Welcome to User Mode Linux. It's going to be fun.
- 1.1. How is User Mode Linux Different?
+1.1. How is User Mode Linux Different?
+---------------------------------------
Normally, the Linux Kernel talks straight to your hardware (video
card, keyboard, hard drives, etc), and any programs which run ask the
- kernel to operate the hardware, like so:
+ kernel to operate the hardware, like so::
@@ -160,10 +163,10 @@
The User Mode Linux Kernel is different; instead of talking to the
- hardware, it talks to a `real' Linux kernel (called the `host kernel'
+ hardware, it talks to a `real` Linux kernel (called the `host kernel`
from now on), like any other program. Programs can then run inside
User-Mode Linux as if they were running under a normal kernel, like
- so:
+ so::
@@ -181,7 +184,8 @@
- 1.2. Why Would I Want User Mode Linux?
+1.2. Why Would I Want User Mode Linux?
+---------------------------------------
1. If User Mode Linux crashes, your host kernel is still fine.
@@ -204,14 +208,16 @@
+.. _Compiling_the_kernel_and_modules:
+2. Compiling the kernel and modules
+====================================
- 2. Compiling the kernel and modules
-
- 2.1. Compiling the kernel
+2.1. Compiling the kernel
+--------------------------
Compiling the user mode kernel is just like compiling any other
@@ -220,7 +226,6 @@
1. Download the latest UML patch from
-
the download page <http://user-mode-linux.sourceforge.net/
In this example, the file is uml-patch-2.4.0-prerelease.bz2.
@@ -230,57 +235,33 @@
such as:
ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
- <ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2>
- .
-
-
- 3. Make a directory and unpack the kernel into it.
+ 3. Make a directory and unpack the kernel into it::
host%
mkdir ~/uml
-
-
-
-
-
host%
cd ~/uml
-
-
-
-
-
host%
tar -xzvf linux-2.4.0-prerelease.tar.bz2
-
-
-
- 4. Apply the patch using
-
-
+ 4. Apply the patch using::
host%
cd ~/uml/linux
-
-
host%
bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
-
-
-
- 5. Run your favorite config; `make xconfig ARCH=um' is the most
- convenient. `make config ARCH=um' and 'make menuconfig ARCH=um'
+ 5. Run your favorite config; ``make xconfig ARCH=um`` is the most
+ convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um``
will work as well. The defaults will give you a useful kernel. If
you want to change something, go ahead, it probably won't hurt
anything.
@@ -288,13 +269,13 @@
Note: If the host is configured with a 2G/2G address space split
rather than the usual 3G/1G split, then the packaged UML binaries
- will not run. They will immediately segfault. See ``UML on 2G/2G
- hosts'' for the scoop on running UML on your system.
+ will not run. They will immediately segfault. See
+ :ref:`UML_on_2G/2G_hosts` for the scoop on running UML on your system.
- 6. Finish with `make linux ARCH=um': the result is a file called
- `linux' in the top directory of your source tree.
+ 6. Finish with ``make linux ARCH=um``: the result is a file called
+ ``linux`` in the top directory of your source tree.
Make sure that you don't build this kernel in /usr/src/linux. On some
distributions, /usr/include/asm is a link into this pool. The user-
@@ -310,7 +291,7 @@
corresponding directory in the appropriate kernel pool.
If you don't have the latest kernel pool, you can get the
- corresponding user-mode sources with
+ corresponding user-mode sources with::
host% cvs co -r v_2_3_x linux
@@ -322,10 +303,11 @@
bug fixes and enhancements that have gone into subsequent releases.
- 2.2. Compiling and installing kernel modules
+2.2. Compiling and installing kernel modules
+---------------------------------------------
UML modules are built in the same way as the native kernel (with the
- exception of the 'ARCH=um' that you always need for UML):
+ exception of the 'ARCH=um' that you always need for UML)::
host% make modules ARCH=um
@@ -337,12 +319,12 @@
the user-mode pool. Modules from the native kernel won't work.
You can install them by using ftp or something to copy them into the
- virtual machine and dropping them into /lib/modules/`uname -r`.
+ virtual machine and dropping them into ``/lib/modules/$(uname -r)``.
You can also get the kernel build process to install them as follows:
1. with the kernel not booted, mount the root filesystem in the top
- level of the kernel pool:
+ level of the kernel pool::
host% mount root_fs mnt -o loop
@@ -352,7 +334,7 @@
- 2. run
+ 2. run::
host%
@@ -363,7 +345,7 @@
- 3. unmount the filesystem
+ 3. unmount the filesystem::
host% umount mnt
@@ -386,22 +368,23 @@
- 2.3. Compiling and installing uml_utilities
+2.3. Compiling and installing uml_utilities
+--------------------------------------------
Many features of the UML kernel require a user-space helper program,
so a uml_utilities package is distributed separately from the kernel
patch which provides these helpers. Included within this is:
- o port-helper - Used by consoles which connect to xterms or ports
+ - port-helper - Used by consoles which connect to xterms or ports
- o tunctl - Configuration tool to create and delete tap devices
+ - tunctl - Configuration tool to create and delete tap devices
- o uml_net - Setuid binary for automatic tap device configuration
+ - uml_net - Setuid binary for automatic tap device configuration
- o uml_switch - User-space virtual switch required for daemon
+ - uml_switch - User-space virtual switch required for daemon
transport
- The uml_utilities tree is compiled with:
+ The uml_utilities tree is compiled with::
host#
@@ -423,19 +406,21 @@
- 3. Running UML and logging in
+3. Running UML and logging in
+==============================
- 3.1. Running UML
+3.1. Running UML
+-----------------
It runs on 2.2.15 or later, and all 2.4 kernels.
Booting UML is straightforward. Simply run 'linux': it will try to
- mount the file `root_fs' in the current directory. You do not need to
- run it as root. If your root filesystem is not named `root_fs', then
- you need to put a `ubd0=root_fs_whatever' switch on the linux command
+ mount the file ``root_fs`` in the current directory. You do not need to
+ run it as root. If your root filesystem is not named ``root_fs``, then
+ you need to put a ``ubd0=root_fs_whatever`` switch on the linux command
line.
@@ -447,14 +432,16 @@
The kernel will boot up and present you with a login prompt.
- Note: If the host is configured with a 2G/2G address space split
+Note:
+ If the host is configured with a 2G/2G address space split
rather than the usual 3G/1G split, then the packaged UML binaries will
- not run. They will immediately segfault. See ``UML on 2G/2G hosts''
+ not run. They will immediately segfault. See :ref:`UML_on_2G/2G_hosts`
for the scoop on running UML on your system.
- 3.2. Logging in
+3.2. Logging in
+----------------
@@ -468,22 +455,22 @@
There are a couple of other ways to log in:
- o On a virtual console
+ - On a virtual console
Each virtual console that is configured (i.e. the device exists in
/dev and /etc/inittab runs a getty on it) will come up in its own
- xterm. If you get tired of the xterms, read ``Setting up serial
- lines and consoles'' to see how to attach the consoles to
- something else, like host ptys.
+ xterm. If you get tired of the xterms, read
+ :ref:`setting_up_serial_lines_and_consoles` to see how to attach
+ the consoles to something else, like host ptys.
- o Over the serial line
+ - Over the serial line
- In the boot output, find a line that looks like:
+ In the boot output, find a line that looks like::
@@ -493,7 +480,7 @@
Attach your favorite terminal program to the corresponding tty. I.e.
- for minicom, the command would be
+ for minicom, the command would be::
host% minicom -o -p /dev/ttyp1
@@ -503,37 +490,41 @@
- o Over the net
+ - Over the net
If the network is running, then you can telnet to the virtual
- machine and log in to it. See ``Setting up the network'' to learn
+ machine and log in to it. See :ref:`Setting_up_the_network` to learn
about setting up a virtual network.
When you're done using it, run halt, and the kernel will bring itself
down and the process will exit.
- 3.3. Examples
+3.3. Examples
+--------------
Here are some examples of UML in action:
- o A login session <http://user-mode-linux.sourceforge.net/login.html>
+ - A login session <http://user-mode-linux.sourceforge.net/login.html>
- o A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+ - A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+.. _UML_on_2G/2G_hosts:
- 4. UML on 2G/2G hosts
+4. UML on 2G/2G hosts
+======================
- 4.1. Introduction
+4.1. Introduction
+------------------
Most Linux machines are configured so that the kernel occupies the
@@ -546,7 +537,8 @@
- 4.2. The problem
+4.2. The problem
+-----------------
The prebuilt UML binaries on this site will not run on 2G/2G hosts
@@ -558,13 +550,14 @@
- 4.3. The solution
+4.3. The solution
+------------------
The fix for this is to rebuild UML from source after enabling
CONFIG_HOST_2G_2G (under 'General Setup'). This will cause UML to
load itself in the top .5G of that smaller process address space,
- where it will run fine. See ``Compiling the kernel and modules'' if
+ where it will run fine. See :ref:`Compiling_the_kernel_and_modules` if
you need help building UML from source.
@@ -573,10 +566,11 @@
+.. _setting_up_serial_lines_and_consoles:
-
- 5. Setting up serial lines and consoles
+5. Setting up serial lines and consoles
+========================================
It is possible to attach UML serial lines and consoles to many types
@@ -584,22 +578,23 @@
You can attach them to host ptys, ttys, file descriptors, and ports.
- This allows you to do things like
+ This allows you to do things like:
- o have a UML console appear on an unused host console,
+ - have a UML console appear on an unused host console,
- o hook two virtual machines together by having one attach to a pty
+ - hook two virtual machines together by having one attach to a pty
and having the other attach to the corresponding tty
- o make a virtual machine accessible from the net by attaching a
+ - make a virtual machine accessible from the net by attaching a
console to a port on the host.
- The general format of the command line option is device=channel.
+ The general format of the command line option is ``device=channel``.
- 5.1. Specifying the device
+5.1. Specifying the device
+---------------------------
Devices are specified with "con" or "ssl" (console or serial line,
respectively), optionally with a device number if you are talking
@@ -613,7 +608,7 @@
A specific device name will override a less general "con=" or "ssl=".
So, for example, you can assign a pty to each of the serial lines
- except for the first two like this:
+ except for the first two like this::
ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1
@@ -626,13 +621,14 @@
- 5.2. Specifying the channel
+5.2. Specifying the channel
+----------------------------
There are a number of different types of channels to attach a UML
device to, each with a different way of specifying exactly what to
attach to.
- o pseudo-terminals - device=pty pts terminals - device=pts
+ - pseudo-terminals - device=pty pts terminals - device=pts
This will cause UML to allocate a free host pseudo-terminal for the
@@ -640,23 +636,23 @@
log. You access it by attaching a terminal program to the
corresponding tty:
- o screen /dev/pts/n
+ - screen /dev/pts/n
- o screen /dev/ttyxx
+ - screen /dev/ttyxx
- o minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
+ - minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
devices
- o kermit - start it up, 'open' the device, then 'connect'
+ - kermit - start it up, 'open' the device, then 'connect'
- o terminals - device=tty:tty device file
+ - terminals - device=tty:tty device file
- This will make UML attach the device to the specified tty (i.e
+ This will make UML attach the device to the specified tty (i.e::
con1=tty:/dev/tty3
@@ -672,7 +668,7 @@
- o xterms - device=xterm
+ - xterms - device=xterm
UML will run an xterm and the device will be attached to it.
@@ -681,12 +677,12 @@
- o Port - device=port:port number
+ - Port - device=port:port number
This will attach the UML devices to the specified host port.
Attaching console 1 to the host's port 9000 would be done like
- this:
+ this::
con1=port:9000
@@ -694,7 +690,7 @@
- Attaching all the serial lines to that port would be done similarly:
+ Attaching all the serial lines to that port would be done similarly::
ssl=port:9000
@@ -702,8 +698,8 @@
- You access these devices by telnetting to that port. Each active tel-
- net session gets a different device. If there are more telnets to a
+ You access these devices by telnetting to that port. Each active
+ telnet session gets a different device. If there are more telnets to a
port than UML devices attached to it, then the extra telnet sessions
will block until an existing telnet detaches, or until another device
becomes active (i.e. by being activated in /etc/inittab).
@@ -725,13 +721,13 @@
- o already-existing file descriptors - device=file descriptor
+ - already-existing file descriptors - device=file descriptor
If you set up a file descriptor on the UML command line, you can
attach a UML device to it. This is most commonly used to put the
main console back on stdin and stdout after assigning all the other
- consoles to something else:
+ consoles to something else::
con0=fd:0,fd:1 con=pts
@@ -743,7 +739,7 @@
- o Nothing - device=null
+ - Nothing - device=null
This allows the device to be opened, in contrast to 'none', but
@@ -754,7 +750,7 @@
- o None - device=none
+ - None - device=none
This causes the device to disappear.
@@ -762,7 +758,7 @@
You can also specify different input and output channels for a device
- by putting a comma between them:
+ by putting a comma between them::
ssl3=tty:/dev/tty2,xterm
@@ -785,14 +781,15 @@
- 5.3. Examples
+5.3. Examples
+--------------
There are a number of interesting things you can do with this
capability.
First, this is how you get rid of those bleeding console xterms by
- attaching them to host ptys:
+ attaching them to host ptys::
con=pty con0=fd:0,fd:1
@@ -802,7 +799,7 @@
This will make a UML console take over an unused host virtual console,
so that when you switch to it, you will see the UML login prompt
- rather than the host login prompt:
+ rather than the host login prompt::
con1=tty:/dev/tty6
@@ -813,7 +810,7 @@
You can attach two virtual machines together with what amounts to a
serial line as follows:
- Run one UML with a serial line attached to a pty -
+ Run one UML with a serial line attached to a pty::
ssl1=pty
@@ -825,7 +822,7 @@
that it got /dev/ptyp1).
Boot the other UML with a serial line attached to the corresponding
- tty -
+ tty::
ssl1=tty:/dev/ttyp1
@@ -838,7 +835,10 @@
prompt of the other virtual machine.
- 6. Setting up the network
+.. _setting_up_the_network:
+
+6. Setting up the network
+==========================
@@ -858,19 +858,19 @@
There are currently five transport types available for a UML virtual
machine to exchange packets with other hosts:
- o ethertap
+ - ethertap
- o TUN/TAP
+ - TUN/TAP
- o Multicast
+ - Multicast
- o a switch daemon
+ - a switch daemon
- o slip
+ - slip
- o slirp
+ - slirp
- o pcap
+ - pcap
The TUN/TAP, ethertap, slip, and slirp transports allow a UML
instance to exchange packets with the host. They may be directed
@@ -893,28 +893,28 @@
With so many host transports, which one should you use? Here's when
you should use each one:
- o ethertap - if you want access to the host networking and it is
+ - ethertap - if you want access to the host networking and it is
running 2.2
- o TUN/TAP - if you want access to the host networking and it is
+ - TUN/TAP - if you want access to the host networking and it is
running 2.4. Also, the TUN/TAP transport is able to use a
preconfigured device, allowing it to avoid using the setuid uml_net
helper, which is a security advantage.
- o Multicast - if you want a purely virtual network and you don't want
+ - Multicast - if you want a purely virtual network and you don't want
to set up anything but the UML
- o a switch daemon - if you want a purely virtual network and you
+ - a switch daemon - if you want a purely virtual network and you
don't mind running the daemon in order to get somewhat better
performance
- o slip - there is no particular reason to run the slip backend unless
+ - slip - there is no particular reason to run the slip backend unless
ethertap and TUN/TAP are just not available for some reason
- o slirp - if you don't have root access on the host to setup
+ - slirp - if you don't have root access on the host to setup
networking, or if you don't want to allocate an IP to your UML
- o pcap - not much use for actual network connectivity, but great for
+ - pcap - not much use for actual network connectivity, but great for
monitoring traffic on the host
Ethertap is available on 2.4 and works fine. TUN/TAP is preferred
@@ -926,7 +926,8 @@
exploit the helper's root privileges.
- 6.1. General setup
+6.1. General setup
+-------------------
First, you must have the virtual network enabled in your UML. If are
running a prebuilt kernel from this site, everything is already
@@ -938,7 +939,7 @@
The next step is to provide a network device to the virtual machine.
This is done by describing it on the kernel command line.
- The general format is
+ The general format is::
eth <n> = <transport> , <transport args>
@@ -947,7 +948,7 @@
For example, a virtual ethernet device may be attached to a host
- ethertap device as follows:
+ ethertap device as follows::
eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
@@ -978,7 +979,7 @@
You can also add devices to a UML and remove them at runtime. See the
- ``The Management Console'' page for details.
+ :ref:`The_Management_Console` page for details.
The sections below describe this in more detail.
@@ -995,7 +996,8 @@
- 6.2. Userspace daemons
+6.2. Userspace daemons
+-----------------------
You will likely need the setuid helper, or the switch daemon, or both.
They are both installed with the RPM and deb, so if you've installed
@@ -1011,7 +1013,8 @@
- 6.3. Specifying ethernet addresses
+6.3. Specifying ethernet addresses
+-----------------------------------
Below, you will see that the TUN/TAP, ethertap, and daemon interfaces
allow you to specify hardware addresses for the virtual ethernet
@@ -1023,21 +1026,21 @@
sufficient to guarantee a unique hardware address for the device. A
couple of exceptions are:
- o Another set of virtual ethernet devices are on the same network and
+ - Another set of virtual ethernet devices are on the same network and
they are assigned hardware addresses using a different scheme which
may conflict with the UML IP address-based scheme
- o You aren't going to use the device for IP networking, so you don't
+ - You aren't going to use the device for IP networking, so you don't
assign the device an IP address
If you let the driver provide the hardware address, you should make
sure that the device IP address is known before the interface is
- brought up. So, inside UML, this will guarantee that:
+ brought up. So, inside UML, this will guarantee that::
- UML#
- ifconfig eth0 192.168.0.250 up
+ UML#
+ ifconfig eth0 192.168.0.250 up
@@ -1049,13 +1052,14 @@
- 6.4. UML interface setup
+6.4. UML interface setup
+-------------------------
Once the network devices have been described on the command line, you
should boot UML and log in.
- The first thing to do is bring the interface up:
+ The first thing to do is bring the interface up::
UML# ifconfig ethn ip-address up
@@ -1067,7 +1071,7 @@
To reach the rest of the world, you should set a default route to the
- host:
+ host::
UML# route add default gw host ip
@@ -1075,7 +1079,7 @@
- Again, with host ip of 192.168.0.4:
+ Again, with host ip of 192.168.0.4::
UML# route add default gw 192.168.0.4
@@ -1097,29 +1101,25 @@
Note: If you can't communicate with other hosts on your physical
ethernet, it's probably because of a network route that's
automatically set up. If you run 'route -n' and see a route that
- looks like this:
+ looks like this::
- Destination Gateway Genmask Flags Metric Ref Use Iface
- 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
+ Destination Gateway Genmask Flags Metric Ref Use Iface
+ 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
with a mask that's not 255.255.255.255, then replace it with a route
- to your host:
+ to your host::
UML#
route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0
-
-
-
-
UML#
route add -host 192.168.0.4 dev eth0
@@ -1131,7 +1131,8 @@
- 6.5. Multicast
+6.5. Multicast
+---------------
The simplest way to set up a virtual network between multiple UMLs is
to use the mcast transport. This was written by Harald Welte and is
@@ -1142,7 +1143,7 @@
messages when you bring the device up inside UML.
- To use it, run two UMLs with
+ To use it, run two UMLs with::
eth0=mcast
@@ -1151,16 +1152,12 @@
on their command lines. Log in, configure the ethernet device in each
- machine with different IP addresses:
+ machine with different IP addresses::
UML1# ifconfig eth0 192.168.0.254
-
-
-
-
UML2# ifconfig eth0 192.168.0.253
@@ -1168,7 +1165,7 @@
and they should be able to talk to each other.
- The full set of command line options for this transport are
+ The full set of command line options for this transport are::
@@ -1186,7 +1183,7 @@
This is useful when your network does not support multicast, and
all network connections are simple point to point links.
- The full set of command line options for this transport are
+ The full set of command line options for this transport are::
ethn=ucast,ethernet address,remote address,listen port,remote port
@@ -1194,7 +1191,8 @@
- 6.6. TUN/TAP with the uml_net helper
+6.6. TUN/TAP with the uml_net helper
+-------------------------------------
TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the
host. The TUN/TAP backend has been in UML since 2.4.9-3um.
@@ -1216,7 +1214,7 @@
kernel or as the tun.o module.
The format of the command line switch to attach a device to a TUN/TAP
- device is
+ device is::
eth <n> =tuntap,,, <IP address>
@@ -1226,7 +1224,7 @@
For example, this argument will attach the UML's eth0 to the next
available tap device and assign an ethernet address to it based on its
- IP address
+ IP address::
eth0=tuntap,,,192.168.0.254
@@ -1247,10 +1245,10 @@
There are a couple potential problems with running the TUN/TAP
transport on a 2.4 host kernel
- o TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
+ - TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
kernel or use the ethertap transport.
- o With an upgraded kernel, TUN/TAP may fail with
+ - With an upgraded kernel, TUN/TAP may fail with::
File descriptor in bad state
@@ -1264,12 +1262,12 @@
kernel.
These were pointed out by Tim Robinson <timro at trkr dot net> in
- <http://www.geocrawler.com/> name="this uml-
- user post"> .
+ <http://www.geocrawler.com/> name="this uml-user post"> .
- 6.7. TUN/TAP with a preconfigured tap device
+6.7. TUN/TAP with a preconfigured tap device
+---------------------------------------------
If you prefer not to have UML use uml_net (which is somewhat
insecure), with UML 2.4.17-11, you can set up a TUN/TAP device
@@ -1277,8 +1275,8 @@
there is no need for root assistance. Setting up the device is done
as follows:
- o Create the device with tunctl (available from the UML utilities
- tarball)
+ - Create the device with tunctl (available from the UML utilities
+ tarball)::
@@ -1291,8 +1289,8 @@
where uid is the user id or username that UML will be run as. This
will tell you what device was created.
- o Configure the device IP (change IP addresses and device name to
- suit)
+ - Configure the device IP (change IP addresses and device name to
+ suit)::
@@ -1303,8 +1301,8 @@
- o Set up routing and arping if desired - this is my recipe, there are
- other ways of doing the same thing
+ - Set up routing and arping if desired - this is my recipe, there are
+ other ways of doing the same thing::
host#
@@ -1313,19 +1311,9 @@
host#
route add -host 192.168.0.253 dev tap0
-
-
-
-
-
host#
bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
-
-
-
-
-
host#
arp -Ds 192.168.0.253 eth0 pub
@@ -1338,76 +1326,43 @@
utility which reads the information from a config file and sets up
devices at boot time.
- o Rather than using up two IPs and ARPing for one of them, you can
+ - Rather than using up two IPs and ARPing for one of them, you can
also provide direct access to your LAN by the UML by using a
- bridge.
+ bridge::
host#
brctl addbr br0
-
-
-
-
host#
ifconfig eth0 0.0.0.0 promisc up
-
-
-
-
host#
ifconfig tap0 0.0.0.0 promisc up
-
-
-
-
host#
ifconfig br0 192.168.0.1 netmask 255.255.255.0 up
-
-
-
-
-
- host#
- brctl stp br0 off
-
-
-
-
+ host#
+ brctl stp br0 off
host#
brctl setfd br0 1
-
-
-
-
host#
brctl sethello br0 1
-
-
-
-
host#
brctl addif br0 eth0
-
-
-
-
host#
brctl addif br0 tap0
@@ -1417,12 +1372,12 @@
Note that 'br0' should be setup using ifconfig with the existing IP
address of eth0, as eth0 no longer has its own IP.
- o
+ -
Also, the /dev/net/tun device must be writable by the user running
UML in order for the UML to use the device that's been configured
- for it. The simplest thing to do is
+ for it. The simplest thing to do is::
host# chmod 666 /dev/net/tun
@@ -1438,14 +1393,14 @@
devices and chgrp /dev/net/tun to that group with mode 664 or 660.
- o Once the device is set up, run UML with 'eth0=tuntap,device name'
+ - Once the device is set up, run UML with 'eth0=tuntap,device name'
(i.e. 'eth0=tuntap,tap0') on the command line (or do it with the
mconsole config command).
- o Bring the eth device up in UML and you're in business.
+ - Bring the eth device up in UML and you're in business.
If you don't want that tap device any more, you can make it non-
- persistent with
+ persistent with::
host# tunctl -d tap device
@@ -1455,7 +1410,7 @@
Finally, tunctl has a -b (for brief mode) switch which causes it to
output only the name of the tap device it created. This makes it
- suitable for capture by a script:
+ suitable for capture by a script::
host# TAP=`tunctl -u 1000 -b`
@@ -1465,7 +1420,8 @@
- 6.8. Ethertap
+6.8. Ethertap
+--------------
Ethertap is the general mechanism on 2.2 for userspace processes to
exchange packets with the kernel.
@@ -1473,7 +1429,7 @@
To use this transport, you need to describe the virtual network device
- on the UML command line. The general format for this is
+ on the UML command line. The general format for this is::
eth <n> =ethertap, <device> , <ethernet address> , <tap IP address>
@@ -1481,7 +1437,7 @@
- So, the previous example
+ So, the previous example::
eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
@@ -1521,7 +1477,7 @@
If you want to set things up yourself, you need to make sure that the
appropriate /dev entry exists. If it doesn't, become root and create
- it as follows:
+ it as follows::
mknod /dev/tap <minor> c 36 <minor> + 16
@@ -1529,7 +1485,7 @@
- For example, this is how to create /dev/tap0:
+ For example, this is how to create /dev/tap0::
mknod /dev/tap0 c 36 0 + 16
@@ -1539,7 +1495,7 @@
You also need to make sure that the host kernel has ethertap support.
If ethertap is enabled as a module, you apparently need to insmod
- ethertap once for each ethertap device you want to enable. So,
+ ethertap once for each ethertap device you want to enable. So,::
host#
@@ -1549,7 +1505,7 @@
will give you the tap0 interface. To get the tap1 interface, you need
- to run
+ to run::
host#
@@ -1561,7 +1517,8 @@
- 6.9. The switch daemon
+6.9. The switch daemon
+-----------------------
Note: This is the daemon formerly known as uml_router, but which was
renamed so the network weenies of the world would stop growling at me.
@@ -1577,7 +1534,7 @@
sockets.
- If you want it to listen on a different pair of sockets, use
+ If you want it to listen on a different pair of sockets, use::
-unix control socket data socket
@@ -1586,7 +1543,7 @@
- If you want it to act as a hub rather than a switch, use
+ If you want it to act as a hub rather than a switch, use::
-hub
@@ -1596,7 +1553,7 @@
If you want the switch to be connected to host networking (allowing
- the umls to get access to the outside world through the host), use
+ the umls to get access to the outside world through the host), use::
-tap tap0
@@ -1610,7 +1567,7 @@
device than tap0, specify that instead of tap0.
- uml_switch can be backgrounded as follows
+ uml_switch can be backgrounded as follows::
host%
@@ -1623,7 +1580,7 @@
stdin for EOF. When it sees that, it exits.
- The general format of the kernel command line switch is
+ The general format of the kernel command line switch is::
@@ -1639,7 +1596,8 @@
how to communicate with the daemon. You should only specify them if
you told the daemon to use different sockets than the default. So, if
you ran the daemon with no arguments, running the UML on the same
- machine with
+ machine with::
+
eth0=daemon
@@ -1649,7 +1607,8 @@
- 6.10. Slip
+6.10. Slip
+-----------
Slip is another, less general, mechanism for a process to communicate
with the host networking. In contrast to the ethertap interface,
@@ -1658,7 +1617,7 @@
IP.
- The general format of the command line switch is
+ The general format of the command line switch is::
@@ -1681,7 +1640,8 @@
- 6.11. Slirp
+6.11. Slirp
+------------
slirp uses an external program, usually /usr/bin/slirp, to provide IP
only networking connectivity through the host. This is similar to IP
@@ -1691,7 +1651,7 @@
root access or setuid binaries on the host.
- The general format of the command line switch for slirp is:
+ The general format of the command line switch for slirp is::
@@ -1716,7 +1676,7 @@
The eth0 interface on UML should be set up with the IP 10.2.0.15,
although you can use anything as long as it is not used by a network
you will be connecting to. The default route on UML should be set to
- use
+ use::
UML#
@@ -1737,10 +1697,11 @@
- 6.12. pcap
+6.12. pcap
+-----------
The pcap transport is attached to a UML ethernet device on the command
- line or with uml_mconsole with the following syntax:
+ line or with uml_mconsole with the following syntax::
@@ -1762,7 +1723,7 @@
expression optimizer is used.
- Example:
+ Example::
@@ -1777,7 +1738,8 @@
- 6.13. Setting up the host yourself
+6.13. Setting up the host yourself
+-----------------------------------
If you don't specify an address for the host side of the ethertap or
slip device, UML won't do any setup on the host. So this is what is
@@ -1785,19 +1747,15 @@
192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your
own network):
- o The device needs to be configured with its IP address. Tap devices
+ - The device needs to be configured with its IP address. Tap devices
are also configured with an mtu of 1484. Slip devices are
configured with a point-to-point address pointing at the UML ip
- address.
+ address::
host# ifconfig tap0 arp mtu 1484 192.168.0.251 up
-
-
-
-
host#
ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up
@@ -1805,7 +1763,7 @@
- o If a tap device is being set up, a route is set to the UML IP.
+ - If a tap device is being set up, a route is set to the UML IP::
UML# route add -host 192.168.0.250 gw 192.168.0.251
@@ -1814,8 +1772,8 @@
- o To allow other hosts on your network to see the virtual machine,
- proxy arp is set up for it.
+ - To allow other hosts on your network to see the virtual machine,
+ proxy arp is set up for it::
host# arp -Ds 192.168.0.250 eth0 pub
@@ -1824,7 +1782,7 @@
- o Finally, the host is set up to route packets.
+ - Finally, the host is set up to route packets::
host# echo 1 > /proc/sys/net/ipv4/ip_forward
@@ -1838,12 +1796,14 @@
- 7. Sharing Filesystems between Virtual Machines
+7. Sharing Filesystems between Virtual Machines
+================================================
- 7.1. A warning
+7.1. A warning
+---------------
Don't attempt to share filesystems simply by booting two UMLs from the
same file. That's the same thing as booting two physical machines
@@ -1851,7 +1811,8 @@
- 7.2. Using layered block devices
+7.2. Using layered block devices
+---------------------------------
The way to share a filesystem between two virtual machines is to use
the copy-on-write (COW) layering capability of the ubd block driver.
@@ -1872,7 +1833,7 @@
To add a copy-on-write layer to an existing block device file, simply
- add the name of the COW file to the appropriate ubd switch:
+ add the name of the COW file to the appropriate ubd switch::
ubd0=root_fs_cow,root_fs_debian_22
@@ -1883,7 +1844,7 @@
where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is
the existing shared filesystem. The COW file need not exist. If it
doesn't, the driver will create and initialize it. Once the COW file
- has been initialized, it can be used on its own on the command line:
+ has been initialized, it can be used on its own on the command line::
ubd0=root_fs_cow
@@ -1896,14 +1857,16 @@
- 7.3. Note!
+7.3. Note!
+-----------
When checking the size of the COW file in order to see the gobs of
space that you're saving, make sure you use 'ls -ls' to see the actual
disk consumption rather than the length of the file. The COW file is
sparse, so the length will be very different from the disk usage.
Here is a 'ls -l' of a COW file and backing file from one boot and
- shutdown:
+ shutdown::
+
host% ls -l cow.debian debian2.2
-rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
-rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
@@ -1911,7 +1874,7 @@
- Doesn't look like much saved space, does it? Well, here's 'ls -ls':
+ Doesn't look like much saved space, does it? Well, here's 'ls -ls'::
host% ls -ls cow.debian debian2.2
@@ -1926,7 +1889,8 @@
- 7.4. Another warning
+7.4. Another warning
+---------------------
Once a filesystem is being used as a readonly backing file for a COW
file, do not boot directly from it or modify it in any way. Doing so
@@ -1952,7 +1916,8 @@
- 7.5. uml_moo : Merging a COW file with its backing file
+7.5. uml_moo : Merging a COW file with its backing file
+--------------------------------------------------------
Depending on how you use UML and COW devices, it may be advisable to
merge the changes in the COW file into the backing file every once in
@@ -1961,7 +1926,7 @@
- The utility that does this is uml_moo. Its usage is
+ The utility that does this is uml_moo. Its usage is::
host% uml_moo COW file new backing file
@@ -2001,7 +1966,8 @@
- 8. Creating filesystems
+8. Creating filesystems
+========================
You may want to create and mount new UML filesystems, either because
@@ -2015,13 +1981,14 @@
should be easy to translate to the filesystem of your choice.
- 8.1. Create the filesystem file
+8.1. Create the filesystem file
+================================
dd is your friend. All you need to do is tell dd to create an empty
file of the appropriate size. I usually make it sparse to save time
and to avoid allocating disk space until it's actually used. For
example, the following command will create a sparse 100 meg file full
- of zeroes.
+ of zeroes::
host%
@@ -2034,9 +2001,9 @@
8.2. Assign the file to a UML device
- Add an argument like the following to the UML command line:
+ Add an argument like the following to the UML command line::
- ubd4=new_filesystem
+ ubd4=new_filesystem
@@ -2053,7 +2020,7 @@
etc), then get them into UML by way of the net or hostfs.
- Make the new filesystem on the device assigned to the new file:
+ Make the new filesystem on the device assigned to the new file::
host# mkreiserfs /dev/ubd/4
@@ -2077,7 +2044,7 @@
- Now, mount it:
+ Now, mount it::
UML#
@@ -2096,7 +2063,8 @@
- 9. Host file access
+9. Host file access
+====================
If you want to access files on the host machine from inside UML, you
@@ -2112,10 +2080,11 @@
files contained in it just as you would on the host.
- 9.1. Using hostfs
+9.1. Using hostfs
+------------------
To begin with, make sure that hostfs is available inside the virtual
- machine with
+ machine with::
UML# cat /proc/filesystems
@@ -2127,7 +2096,7 @@
module and available inside the virtual machine, and insmod it.
- Now all you need to do is run mount:
+ Now all you need to do is run mount::
UML# mount none /mnt/host -t hostfs
@@ -2139,7 +2108,7 @@
If you don't want to mount the host root directory, then you can
- specify a subdirectory to mount with the -o switch to mount:
+ specify a subdirectory to mount with the -o switch to mount::
UML# mount none /mnt/home -t hostfs -o /home
@@ -2151,13 +2120,14 @@
- 9.2. hostfs as the root filesystem
+9.2. hostfs as the root filesystem
+-----------------------------------
It's possible to boot from a directory hierarchy on the host using
hostfs rather than using the standard filesystem in a file.
To start, you need that hierarchy. The easiest way is to loop mount
- an existing root_fs file:
+ an existing root_fs file::
host# mount root_fs uml_root_dir -o loop
@@ -2166,15 +2136,15 @@
You need to change the filesystem type of / in etc/fstab to be
- 'hostfs', so that line looks like this:
+ 'hostfs', so that line looks like this::
- /dev/ubd/0 / hostfs defaults 1 1
+ /dev/ubd/0 / hostfs defaults 1 1
Then you need to chown to yourself all the files in that directory
- that are owned by root. This worked for me:
+ that are owned by root. This worked for me::
host# find . -uid 0 -exec chown jdike {} \;
@@ -2183,7 +2153,7 @@
Next, make sure that your UML kernel has hostfs compiled in, not as a
- module. Then run UML with the boot device pointing at that directory:
+ module. Then run UML with the boot device pointing at that directory::
ubd0=/path/to/uml/root/directory
@@ -2194,41 +2164,35 @@
UML should then boot as it does normally.
- 9.3. Building hostfs
+9.3. Building hostfs
+---------------------
If you need to build hostfs because it's not in your kernel, you have
two choices:
- o Compiling hostfs into the kernel:
+ - Compiling hostfs into the kernel:
Reconfigure the kernel and set the 'Host filesystem' option under
- o Compiling hostfs as a module:
+ - Compiling hostfs as a module:
Reconfigure the kernel and set the 'Host filesystem' option under
be in arch/um/fs/hostfs/hostfs.o. Install that in
- /lib/modules/`uname -r`/fs in the virtual machine, boot it up, and
+ ``/lib/modules/$(uname -r)/fs`` in the virtual machine, boot it up, and::
UML# insmod hostfs
+.. _The_Management_Console:
-
-
-
-
-
-
-
-
-
- 10. The Management Console
+10. The Management Console
+===========================
@@ -2240,15 +2204,15 @@
There are a number of things you can do with the mconsole interface:
- o get the kernel version
+ - get the kernel version
- o add and remove devices
+ - add and remove devices
- o halt or reboot the machine
+ - halt or reboot the machine
- o Send SysRq commands
+ - Send SysRq commands
- o Pause and resume the UML
+ - Pause and resume the UML
You need the mconsole client (uml_mconsole) which is present in CVS
@@ -2257,7 +2221,7 @@
You also need CONFIG_MCONSOLE (under 'General Setup') enabled in UML.
- When you boot UML, you'll see a line like:
+ When you boot UML, you'll see a line like::
mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole
@@ -2265,7 +2229,7 @@
- If you specify a unique machine id one the UML command line, i.e.
+ If you specify a unique machine id one the UML command line, i.e.::
umid=debian
@@ -2273,7 +2237,7 @@
- you'll see this
+ you'll see this::
mconsole initialized on /home/jdike/.uml/debian/mconsole
@@ -2282,7 +2246,7 @@
That file is the socket that uml_mconsole will use to communicate with
- UML. Run it with either the umid or the full path as its argument:
+ UML. Run it with either the umid or the full path as its argument::
host% uml_mconsole debian
@@ -2290,7 +2254,7 @@
- or
+ or::
host% uml_mconsole /home/jdike/.uml/debian/mconsole
@@ -2300,30 +2264,31 @@
You'll get a prompt, at which you can run one of these commands:
- o version
+ - version
- o halt
+ - halt
- o reboot
+ - reboot
- o config
+ - config
- o remove
+ - remove
- o sysrq
+ - sysrq
- o help
+ - help
- o cad
+ - cad
- o stop
+ - stop
- o go
+ - go
- 10.1. version
+10.1. version
+--------------
- This takes no arguments. It prints the UML version.
+ This takes no arguments. It prints the UML version::
(mconsole) version
@@ -2342,11 +2307,12 @@
- 10.2. halt and reboot
+10.2. halt and reboot
+----------------------
These take no arguments. They shut the machine down immediately, with
no syncing of disks and no clean shutdown of userspace. So, they are
- pretty close to crashing the machine.
+ pretty close to crashing the machine::
(mconsole) halt
@@ -2357,34 +2323,36 @@
- 10.3. config
+10.3. config
+-------------
"config" adds a new device to the virtual machine. Currently the ubd
and network drivers support this. It takes one argument, which is the
- device to add, with the same syntax as the kernel command line.
+ device to add, with the same syntax as the kernel command line::
- (mconsole)
- config ubd3=/home/jdike/incoming/roots/root_fs_debian22
+ (mconsole)
+ config ubd3=/home/jdike/incoming/roots/root_fs_debian22
- OK
- (mconsole) config eth1=mcast
- OK
+ OK
+ (mconsole) config eth1=mcast
+ OK
- 10.4. remove
+10.4. remove
+-------------
"remove" deletes a device from the system. Its argument is just the
name of the device to be removed. The device must be idle in whatever
sense the driver considers necessary. In the case of the ubd driver,
the removed block device must not be mounted, swapped on, or otherwise
- open, and in the case of the network driver, the device must be down.
+ open, and in the case of the network driver, the device must be down::
(mconsole) remove ubd3
@@ -2397,7 +2365,8 @@
- 10.5. sysrq
+10.5. sysrq
+------------
This takes one argument, which is a single letter. It calls the
generic kernel's SysRq driver, which does whatever is called for by
@@ -2407,19 +2376,21 @@
- 10.6. help
+10.6. help
+-----------
"help" returns a string listing the valid commands and what each one
does.
- 10.7. cad
+10.7. cad
+----------
This invokes the Ctl-Alt-Del action on init. What exactly this ends
up doing is up to /etc/inittab. Normally, it reboots the machine.
With UML, this is usually not desired, so if a halt would be better,
- then find the section of inittab that looks like this
+ then find the section of inittab that looks like this::
# What to do when CTRL-ALT-DEL is pressed.
@@ -2432,7 +2403,8 @@
- 10.8. stop
+10.8. stop
+-----------
This puts the UML in a loop reading mconsole requests until a 'go'
mconsole command is received. This is very useful for making backups
@@ -2448,7 +2420,8 @@
- 10.9. go
+10.9. go
+---------
This resumes a UML after being paused by a 'stop' command. Note that
when the UML has resumed, TCP connections may have timed out and if
@@ -2460,9 +2433,10 @@
+.. _Kernel_debugging:
-
- 11. Kernel debugging
+11. Kernel debugging
+=====================
Note: The interface that makes debugging, as described here, possible
@@ -2477,15 +2451,16 @@
In order to debug the kernel, you need build it from source. See
- ``Compiling the kernel and modules'' for information on doing that.
+ :ref:`Compiling_the_kernel_and_modules` for information on doing that.
Make sure that you enable CONFIG_DEBUGSYM and CONFIG_PT_PROXY during
- the config. These will compile the kernel with -g, and enable the
+ the config. These will compile the kernel with ``-g``, and enable the
ptrace proxy so that gdb works with UML, respectively.
- 11.1. Starting the kernel under gdb
+11.1. Starting the kernel under gdb
+------------------------------------
You can have the kernel running under the control of gdb from the
beginning by putting 'debug' on the command line. You will get an
@@ -2498,7 +2473,11 @@
There is a transcript of a debugging session here <debug-
session.html> , with breakpoints being set in the scheduler and in an
interrupt handler.
- 11.2. Examining sleeping processes
+
+
+11.2. Examining sleeping processes
+-----------------------------------
+
Not every bug is evident in the currently running process. Sometimes,
processes hang in the kernel when they shouldn't because they've
@@ -2516,7 +2495,7 @@
Now what you do is this:
- o detach from the current thread
+ - detach from the current thread::
(UML gdb) det
@@ -2525,7 +2504,7 @@
- o attach to the thread you are interested in
+ - attach to the thread you are interested in::
(UML gdb) att <host pid>
@@ -2534,7 +2513,7 @@
- o look at its stack and anything else of interest
+ - look at its stack and anything else of interest::
(UML gdb) bt
@@ -2545,18 +2524,14 @@
Note that you can't do anything at this point that requires that a
process execute, e.g. calling a function
- o when you're done looking at that process, reattach to the current
- thread and continue it
+ - when you're done looking at that process, reattach to the current
+ thread and continue it::
(UML gdb)
att 1
-
-
-
-
(UML gdb)
c
@@ -2569,12 +2544,13 @@
- 11.3. Running ddd on UML
+11.3. Running ddd on UML
+-------------------------
ddd works on UML, but requires a special kludge. The process goes
like this:
- o Start ddd
+ - Start ddd::
host% ddd linux
@@ -2583,14 +2559,14 @@
- o With ps, get the pid of the gdb that ddd started. You can ask the
+ - With ps, get the pid of the gdb that ddd started. You can ask the
gdb to tell you, but for some reason that confuses things and
causes a hang.
- o run UML with 'debug=parent gdb-pid=<pid>' added to the command line
+ - run UML with 'debug=parent gdb-pid=<pid>' added to the command line
- it will just sit there after you hit return
- o type 'att 1' to the ddd gdb and you will see something like
+ - type 'att 1' to the ddd gdb and you will see something like::
0xa013dc51 in __kill ()
@@ -2602,12 +2578,14 @@
- o At this point, type 'c', UML will boot up, and you can use ddd just
+ - At this point, type 'c', UML will boot up, and you can use ddd just
as you do on any other process.
- 11.4. Debugging modules
+11.4. Debugging modules
+------------------------
+
gdb has support for debugging code which is dynamically loaded into
the process. This support is what is needed to debug kernel modules
@@ -2629,7 +2607,8 @@
First, you must tell it where your modules are. There is a list in
- the script that looks like this:
+ the script that looks like this::
+
set MODULE_PATHS {
"fat" "/usr/src/uml/linux-2.4.18/fs/fat/fat.o"
"isofs" "/usr/src/uml/linux-2.4.18/fs/isofs/isofs.o"
@@ -2641,9 +2620,7 @@
You change that to list the names and paths of the modules that you
are going to debug. Then you run it from the toplevel directory of
- your UML pool and it basically tells you what to do:
-
-
+ your UML pool and it basically tells you what to do::
******** GDB pid is 21903 ********
@@ -2666,7 +2643,7 @@
After you run UML and it sits there doing nothing, you hit return at
- the 'att 1' and continue it:
+ the 'att 1' and continue it::
Attaching to program: /home/jdike/linux/2.4/um/./linux, process 1
@@ -2678,63 +2655,48 @@
At this point, you debug normally. When you insmod something, the
- expect magic will kick in and you'll see something like:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- *** Module hostfs loaded ***
- Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
- mod_user=0x8070e00) at module.c:349
- 349 char *name, *n_name, *name_tmp = NULL;
- (UML gdb) finish
- Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
- mod_user=0x8070e00) at module.c:349
- 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
- 411 else res = EXECUTE_SYSCALL(syscall, regs);
- Value returned is $1 = 0
- (UML gdb)
- p/x (int)module_list + module_list->size_of_struct
-
- $2 = 0xa9021054
- (UML gdb) symbol-file ./linux
- Load new symbol table from "./linux"? (y or n) y
- Reading symbols from ./linux...
- done.
- (UML gdb)
- add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
-
- add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
- .text_addr = 0xa9021054
- (y or n) y
-
- Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
- done.
- (UML gdb) p *module_list
- $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
- size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
- nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
- init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
- ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
- persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
- kallsyms_end = 0x0,
- archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
- archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
- kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
- >> Finished loading symbols for hostfs ...
+ expect magic will kick in and you'll see something like::
+
+
+ *** Module hostfs loaded ***
+ Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
+ mod_user=0x8070e00) at module.c:349
+ 349 char *name, *n_name, *name_tmp = NULL;
+ (UML gdb) finish
+ Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
+ mod_user=0x8070e00) at module.c:349
+ 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
+ 411 else res = EXECUTE_SYSCALL(syscall, regs);
+ Value returned is $1 = 0
+ (UML gdb)
+ p/x (int)module_list + module_list->size_of_struct
+
+ $2 = 0xa9021054
+ (UML gdb) symbol-file ./linux
+ Load new symbol table from "./linux"? (y or n) y
+ Reading symbols from ./linux...
+ done.
+ (UML gdb)
+ add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
+
+ add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
+ .text_addr = 0xa9021054
+ (y or n) y
+
+ Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
+ done.
+ (UML gdb) p *module_list
+ $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
+ size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
+ nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
+ init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
+ ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
+ persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
+ kallsyms_end = 0x0,
+ archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
+ archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
+ kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
+ >> Finished loading symbols for hostfs ...
@@ -2744,7 +2706,7 @@
Boot the kernel under the debugger and load the module with insmod or
- modprobe. With gdb, do:
+ modprobe. With gdb, do::
(UML gdb) p module_list
@@ -2758,12 +2720,12 @@
the name fields until find the module you want to debug. Take the
address of that structure, and add module.size_of_struct (which in
2.4.10 kernels is 96 (0x60)) to it. Gdb can make this hard addition
- for you :-):
+ for you :-)::
- (UML gdb)
- printf "%#x\n", (int)module_list module_list->size_of_struct
+ (UML gdb)
+ printf "%#x\n", (int)module_list module_list->size_of_struct
@@ -2771,7 +2733,7 @@
The offset from the module start occasionally changes (before 2.4.0,
it was module.size_of_struct + 4), so it's a good idea to check the
init and cleanup addresses once in a while, as describe below. Now
- do:
+ do::
(UML gdb)
@@ -2786,7 +2748,7 @@
If there's any doubt that you got the offset right, like breakpoints
appear not to work, or they're appearing in the wrong place, you can
check it by looking at the module structure. The init and cleanup
- fields should look like:
+ fields should look like::
init = 0x588066b0 <init_hostfs>, cleanup = 0x588066c0 <exit_hostfs>
@@ -2801,7 +2763,7 @@
When you want to load in a new version of the module, you need to get
gdb to forget about the old one. The only way I've found to do that
- is to tell gdb to forget about all symbols that it knows about:
+ is to tell gdb to forget about all symbols that it knows about::
(UML gdb) symbol-file
@@ -2809,7 +2771,7 @@
- Then reload the symbols from the kernel binary:
+ Then reload the symbols from the kernel binary::
(UML gdb) symbol-file /path/to/kernel
@@ -2823,17 +2785,19 @@
- 11.5. Attaching gdb to the kernel
+11.5. Attaching gdb to the kernel
+----------------------------------
If you don't have the kernel running under gdb, you can attach gdb to
it later by sending the tracing thread a SIGUSR1. The first line of
- the console output identifies its pid:
+ the console output identifies its pid::
+
tracing thread pid = 20093
- When you send it the signal:
+ When you send it the signal::
host% kill -USR1 20093
@@ -2845,7 +2809,7 @@
If you have the mconsole compiled into UML, then the mconsole client
- can be used to start gdb:
+ can be used to start gdb::
(mconsole) (mconsole) config gdb=xterm
@@ -2857,7 +2821,8 @@
- 11.6. Using alternate debuggers
+11.6. Using alternate debuggers
+--------------------------------
UML has support for attaching to an already running debugger rather
than starting gdb itself. This is present in CVS as of 17 Apr 2001.
@@ -2886,7 +2851,7 @@
An example of an alternate debugger is strace. You can strace the
actual kernel as follows:
- o Run the following in a shell
+ - Run the following in a shell::
host%
@@ -2894,13 +2859,13 @@
- o Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
+ - Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
by the previous command
- o Hit return in the shell, and UML will start running, and strace
+ - Hit return in the shell, and UML will start running, and strace
output will start accumulating in the output file.
- Note that this is different from running
+ Note that this is different from running::
host% strace ./linux
@@ -2917,95 +2882,57 @@
- 12. Kernel debugging examples
+12. Kernel debugging examples
+==============================
- 12.1. The case of the hung fsck
+12.1. The case of the hung fsck
+--------------------------------
When booting up the kernel, fsck failed, and dropped me into a shell
- to fix things up. I ran fsck -y, which hung:
+ to fix things up. I ran fsck -y, which hung::
+ Setting hostname uml [ OK ]
+ Checking root filesystem
+ /dev/fhd0 was not cleanly unmounted, check forced.
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
+ /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
+ (i.e., without -a or -p options)
+ [ FAILED ]
+ *** An error occurred during the file system check.
+ *** Dropping you to a shell; the system will reboot
+ *** when you leave the shell.
+ Give root password for maintenance
+ (or type Control-D for normal startup):
+ [root@uml /root]# fsck -y /dev/fhd0
+ fsck -y /dev/fhd0
+ Parallelizing fsck version 1.14 (9-Jan-1999)
+ e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
+ /dev/fhd0 contains a file system with errors, check forced.
+ Pass 1: Checking inodes, blocks, and sizes
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
+ Inode 19780, i_blocks is 1548, should be 540. Fix? yes
+ Pass 2: Checking directory structure
+ Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
+ Directory inode 11858, block 0, offset 0: directory corrupted
+ Salvage? yes
+ Missing '.' in directory inode 11858.
+ Fix? yes
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Setting hostname uml [ OK ]
- Checking root filesystem
- /dev/fhd0 was not cleanly unmounted, check forced.
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
-
- /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
- (i.e., without -a or -p options)
- [ FAILED ]
-
- *** An error occurred during the file system check.
- *** Dropping you to a shell; the system will reboot
- *** when you leave the shell.
- Give root password for maintenance
- (or type Control-D for normal startup):
-
- [root@uml /root]# fsck -y /dev/fhd0
- fsck -y /dev/fhd0
- Parallelizing fsck version 1.14 (9-Jan-1999)
- e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
- /dev/fhd0 contains a file system with errors, check forced.
- Pass 1: Checking inodes, blocks, and sizes
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
-
- Inode 19780, i_blocks is 1548, should be 540. Fix? yes
-
- Pass 2: Checking directory structure
- Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
-
- Directory inode 11858, block 0, offset 0: directory corrupted
- Salvage? yes
-
- Missing '.' in directory inode 11858.
- Fix? yes
-
- Missing '..' in directory inode 11858.
- Fix? yes
-
-
-
+ Missing '..' in directory inode 11858.
+ Fix? yes
The standard drill in this sort of situation is to fire up gdb on the
signal thread, which, in this case, was pid 1935. In another window,
- I run gdb and attach pid 1935.
-
-
+ I run gdb and attach pid 1935::
~/linux/2.3.26/um 1016: gdb linux
@@ -3022,11 +2949,7 @@
0x100756d9 in __wait4 ()
-
-
-
-
- Let's see what's currently running:
+ Let's see what's currently running::
@@ -3041,7 +2964,7 @@
reason and never woke up.
- Let's guess that the last process in the process list is fsck:
+ Let's guess that the last process in the process list is fsck::
@@ -3052,7 +2975,7 @@
- It is, so let's see what it thinks it's up to:
+ It is, so let's see what it thinks it's up to::
@@ -3068,8 +2991,6 @@
-
-
The interesting things here are the fact that its .thread.syscall.id
is __NR_write (see the big switch in arch/um/kernel/syscall_kern.c or
the defines in include/asm-um/arch/unistd.h), and that it never
@@ -3081,30 +3002,20 @@
The fact that it never returned from write means that its stack should
be fairly interesting. Its pid is 1980 (.thread.extern_pid). That
process is being ptraced by the signal thread, so it must be detached
- before gdb can attach it:
+ before gdb can attach it::
+ (gdb) call detach(1980)
-
-
-
-
-
-
- (gdb) call detach(1980)
-
- Program received signal SIGSEGV, Segmentation fault.
- <function called from gdb>
- The program being debugged stopped while in a function called from GDB.
- When the function (detach) is done executing, GDB will silently
- stop (instead of continuing to evaluate the expression containing
- the function call).
- (gdb) call detach(1980)
- $15 = 0
-
-
-
+ Program received signal SIGSEGV, Segmentation fault.
+ <function called from gdb>
+ The program being debugged stopped while in a function called from GDB.
+ When the function (detach) is done executing, GDB will silently
+ stop (instead of continuing to evaluate the expression containing
+ the function call).
+ (gdb) call detach(1980)
+ $15 = 0
The first detach segfaults for some reason, and the second one
@@ -3112,7 +3023,7 @@
Now I detach from the signal thread, attach to the fsck thread, and
- look at its stack:
+ look at its stack::
(gdb) det
@@ -3152,14 +3063,14 @@
- The interesting things here are :
+ The interesting things here are:
- o There are two segfaults on this stack (frames 9 and 14)
+ - There are two segfaults on this stack (frames 9 and 14)
- o The first faulting address (frame 11) is 0x50000800
+ - The first faulting address (frame 11) is 0x50000800::
- (gdb) p (void *)1342179328
- $16 = (void *) 0x50000800
+ (gdb) p (void *)1342179328
+ $16 = (void *) 0x50000800
@@ -3175,7 +3086,7 @@
However, the more immediate problem is that second segfault and I'm
going to concentrate on that. First, I want to see where the fault
- happened, so I have to go look at the sigcontent struct in frame 8:
+ happened, so I have to go look at the sigcontent struct in frame 8::
@@ -3211,7 +3122,7 @@
- That's not very useful, so I'll try a more manual method:
+ That's not very useful, so I'll try a more manual method::
(gdb) p *((struct sigcontext *) (&sig + 1))
@@ -3224,7 +3135,7 @@
- The ip is in handle_mm_fault:
+ The ip is in handle_mm_fault::
(gdb) p (void *)268480945
@@ -3236,7 +3147,7 @@
- Specifically, it's in pte_alloc:
+ Specifically, it's in pte_alloc::
(gdb) i line *$20
@@ -3249,7 +3160,7 @@
To find where in handle_mm_fault this is, I'll jump forward in the
- code until I see an address in that procedure:
+ code until I see an address in that procedure::
@@ -3286,21 +3197,21 @@
Something is apparently wrong with the page tables or vma_structs, so
- lets go back to frame 11 and have a look at them:
+ lets go back to frame 11 and have a look at them::
- #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
- 50 handle_mm_fault(current, vma, address, is_write);
- (gdb) call pgd_offset_proc(vma->vm_mm, address)
- $22 = (pgd_t *) 0x80a548c
+ #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
+ 50 handle_mm_fault(current, vma, address, is_write);
+ (gdb) call pgd_offset_proc(vma->vm_mm, address)
+ $22 = (pgd_t *) 0x80a548c
That's pretty bogus. Page tables aren't supposed to be in process
- text or data areas. Let's see what's in the vma:
+ text or data areas. Let's see what's in the vma::
(gdb) p *vma
@@ -3325,12 +3236,9 @@
-
-
This also pretty bogus. With all of the 0x80xxxxx and 0xaffffxxx
addresses, this is looking like a stack was plonked down on top of
- these structures. Maybe it's a stack overflow from the next page:
-
+ these structures. Maybe it's a stack overflow from the next page::
(gdb) p vma
@@ -3338,52 +3246,36 @@
-
-
That's towards the lower quarter of the page, so that would have to
- have been pretty heavy stack overflow:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- (gdb) x/100x $25
- 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
- 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
- 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
- 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
- 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
- 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
- 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
-
-
+ have been pretty heavy stack overflow::
+
+
+ (gdb) x/100x $25
+ 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
+ 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
+ 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
+ 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
+ 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
+ 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
+ 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
@@ -3399,65 +3291,53 @@
on will be somewhat clearer.
- 12.2. Episode 2: The case of the hung fsck
+12.2. Episode 2: The case of the hung fsck
+-------------------------------------------
After setting a trap in the SEGV handler for accesses to the signal
thread's stack, I reran the kernel.
- fsck hung again, this time by hitting the trap:
+ fsck hung again, this time by hitting the trap::
+ Setting hostname uml [ OK ]
+ Checking root filesystem
+ /dev/fhd0 contains a file system with errors, check forced.
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
+ /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
+ (i.e., without -a or -p options)
+ [ FAILED ]
+ *** An error occurred during the file system check.
+ *** Dropping you to a shell; the system will reboot
+ *** when you leave the shell.
+ Give root password for maintenance
+ (or type Control-D for normal startup):
+ [root@uml /root]# fsck -y /dev/fhd0
+ fsck -y /dev/fhd0
+ Parallelizing fsck version 1.14 (9-Jan-1999)
+ e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
+ /dev/fhd0 contains a file system with errors, check forced.
+ Pass 1: Checking inodes, blocks, and sizes
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
+ Pass 2: Checking directory structure
+ Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
+ Directory inode 11858, block 0, offset 0: directory corrupted
+ Salvage? yes
+ Missing '.' in directory inode 11858.
+ Fix? yes
+ Missing '..' in directory inode 11858.
+ Fix? yes
-
-
-
-
-
- Setting hostname uml [ OK ]
- Checking root filesystem
- /dev/fhd0 contains a file system with errors, check forced.
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
-
- /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
- (i.e., without -a or -p options)
- [ FAILED ]
-
- *** An error occurred during the file system check.
- *** Dropping you to a shell; the system will reboot
- *** when you leave the shell.
- Give root password for maintenance
- (or type Control-D for normal startup):
-
- [root@uml /root]# fsck -y /dev/fhd0
- fsck -y /dev/fhd0
- Parallelizing fsck version 1.14 (9-Jan-1999)
- e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
- /dev/fhd0 contains a file system with errors, check forced.
- Pass 1: Checking inodes, blocks, and sizes
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
-
- Pass 2: Checking directory structure
- Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
-
- Directory inode 11858, block 0, offset 0: directory corrupted
- Salvage? yes
-
- Missing '.' in directory inode 11858.
- Fix? yes
-
- Missing '..' in directory inode 11858.
- Fix? yes
-
- Untested (4127) [100fe44c]: trap_kern.c line 31
+ Untested (4127) [100fe44c]: trap_kern.c line 31
@@ -3465,7 +3345,7 @@
I need to get the signal thread to detach from pid 4127 so that I can
attach to it with gdb. This is done by sending it a SIGUSR1, which is
- caught by the signal thread, which detaches the process:
+ caught by the signal thread, which detaches the process::
kill -USR1 4127
@@ -3474,31 +3354,20 @@
- Now I can run gdb on it:
-
-
-
-
-
-
-
-
-
-
-
-
-
- ~/linux/2.3.26/um 1034: gdb linux
- GNU gdb 4.17.0.11 with Linux support
- Copyright 1998 Free Software Foundation, Inc.
- GDB is free software, covered by the GNU General Public License, and you are
- welcome to change it and/or distribute copies of it under certain conditions.
- Type "show copying" to see the conditions.
- There is absolutely no warranty for GDB. Type "show warranty" for details.
- This GDB was configured as "i386-redhat-linux"...
- (gdb) att 4127
- Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
- 0x10075891 in __libc_nanosleep ()
+ Now I can run gdb on it::
+
+
+ ~/linux/2.3.26/um 1034: gdb linux
+ GNU gdb 4.17.0.11 with Linux support
+ Copyright 1998 Free Software Foundation, Inc.
+ GDB is free software, covered by the GNU General Public License, and you are
+ welcome to change it and/or distribute copies of it under certain conditions.
+ Type "show copying" to see the conditions.
+ There is absolutely no warranty for GDB. Type "show warranty" for details.
+ This GDB was configured as "i386-redhat-linux"...
+ (gdb) att 4127
+ Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
+ 0x10075891 in __libc_nanosleep ()
@@ -3506,7 +3375,7 @@
The backtrace shows that it was in a write and that the fault address
(address in frame 3) is 0x50000800, which is right in the middle of
- the signal thread's stack page:
+ the signal thread's stack page::
(gdb) bt
@@ -3540,58 +3409,48 @@
-
-
Going up the stack to the segv_handler frame and looking at where in
the code the access happened shows that it happened near line 110 of
- block_dev.c:
-
-
-
-
-
-
-
-
-
- (gdb) up
- #1 0x1007584d in __sleep (seconds=1000000)
- at ../sysdeps/unix/sysv/linux/sleep.c:78
- ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
- (gdb)
- #2 0x1006ce9a in stop () at user_util.c:191
- 191 while(1) sleep(1000000);
- (gdb)
- #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
- 31 KERN_UNTESTED();
- (gdb)
- #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
- 174 segv(sc->cr2, sc->err & 2);
- (gdb) p *sc
- $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
- __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
- esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
- err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
- esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
- cr2 = 1342179328}
- (gdb) p (void *)268550834
- $2 = (void *) 0x1001c2b2
- (gdb) i sym $2
- block_write + 1090 in section .text
- (gdb) i line *$2
- Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
- starts at address 0x1001c2a1 <block_write+1073>
- and ends at 0x1001c2bf <block_write+1103>.
- (gdb) i line *0x1001c2c0
- Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
- and ends at 0x1001c2e3 <block_write+1139>.
-
-
+ block_dev.c::
+
+
+
+ (gdb) up
+ #1 0x1007584d in __sleep (seconds=1000000)
+ at ../sysdeps/unix/sysv/linux/sleep.c:78
+ ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
+ (gdb)
+ #2 0x1006ce9a in stop () at user_util.c:191
+ 191 while(1) sleep(1000000);
+ (gdb)
+ #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
+ 31 KERN_UNTESTED();
+ (gdb)
+ #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
+ 174 segv(sc->cr2, sc->err & 2);
+ (gdb) p *sc
+ $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
+ __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
+ esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
+ err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
+ esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
+ cr2 = 1342179328}
+ (gdb) p (void *)268550834
+ $2 = (void *) 0x1001c2b2
+ (gdb) i sym $2
+ block_write + 1090 in section .text
+ (gdb) i line *$2
+ Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
+ starts at address 0x1001c2a1 <block_write+1073>
+ and ends at 0x1001c2bf <block_write+1103>.
+ (gdb) i line *0x1001c2c0
+ Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
+ and ends at 0x1001c2e3 <block_write+1139>.
Looking at the source shows that the fault happened during a call to
- copy_from_user to copy the data into the kernel:
+ copy_from_user to copy the data into the kernel::
107 count -= chars;
@@ -3601,10 +3460,8 @@
-
-
p is the pointer which must contain 0x50000800, since buf contains
- 0x80b8800 (frame 8 above). It is defined as:
+ 0x80b8800 (frame 8 above). It is defined as::
p = offset + bh->b_data;
@@ -3615,24 +3472,22 @@
I need to figure out what bh is, and it just so happens that bh is
passed as an argument to mark_buffer_uptodate and mark_buffer_dirty a
- few lines later, so I do a little disassembly:
+ few lines later, so I do a little disassembly::
-
-
- (gdb) disas 0x1001c2bf 0x1001c2e0
- Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
- 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
- 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
- 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
- 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
- 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
- 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
- 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
- 0x1001c2d8 <block_write+1128>: pushl $0x0
- 0x1001c2da <block_write+1130>: pushl %edx
- 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
- End of assembler dump.
+ (gdb) disas 0x1001c2bf 0x1001c2e0
+ Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
+ 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
+ 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
+ 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
+ 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
+ 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
+ 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
+ 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
+ 0x1001c2d8 <block_write+1128>: pushl $0x0
+ 0x1001c2da <block_write+1130>: pushl %edx
+ 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
+ End of assembler dump.
@@ -3640,7 +3495,7 @@
At that point, bh is in %edx (address 0x1001c2da), which is calculated
at 0x1001c2c2 as %ebp + 0xfffffdd4, so I figure exactly what that is,
- taking %ebp from the sigcontext_struct above:
+ taking %ebp from the sigcontext_struct above::
(gdb) p (void *)1342631484
@@ -3657,7 +3512,7 @@
Now, I look at the structure to see what's in it, and particularly,
- what its b_data field contains:
+ what its b_data field contains::
(gdb) p *((struct buffer_head *)0x50100200)
@@ -3682,18 +3537,18 @@
The b_page field is a pointer to the page_struct representing the
0x50000000 page. Looking at it shows the kernel's idea of the state
- of that page:
+ of that page::
- (gdb) p *$13.b_page
- $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
- index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
- next = 0x50008460, prev = 0x50019350}, wait = {
- lock = <optimized out or zero length>, task_list = {next = 0x50004024,
- prev = 0x50004024}, __magic = 1342193708, __creator = 0},
- pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
- zone = 0x100c5160}
+ (gdb) p *$13.b_page
+ $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
+ index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
+ next = 0x50008460, prev = 0x50019350}, wait = {
+ lock = <optimized out or zero length>, task_list = {next = 0x50004024,
+ prev = 0x50004024}, __magic = 1342193708, __creator = 0},
+ pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
+ zone = 0x100c5160}
@@ -3702,7 +3557,7 @@
Some sanity-checking: the virtual field shows the "virtual" address of
this page, which in this kernel is the same as its "physical" address,
and the page_struct itself should be mem_map[0], since it represents
- the first page of memory:
+ the first page of memory::
@@ -3719,7 +3574,7 @@
Now to check out the page_struct itself. In particular, the flags
- field shows whether the page is considered free or not:
+ field shows whether the page is considered free or not::
(gdb) p (void *)132
@@ -3739,7 +3594,7 @@
In my setup_arch procedure, I have the following code which looks just
- fine:
+ fine::
@@ -3762,7 +3617,7 @@
Stepping into init_bootmem, and looking at bootmem_map before looking
- at what it contains shows the following:
+ at what it contains shows the following::
@@ -3788,18 +3643,20 @@
- 13. What to do when UML doesn't work
+13. What to do when UML doesn't work
+=====================================
- 13.1. Strange compilation errors when you build from source
+13.1. Strange compilation errors when you build from source
+------------------------------------------------------------
As of test11, it is necessary to have "ARCH=um" in the environment or
on the make command line for all steps in building UML, including
clean, distclean, or mrproper, config, menuconfig, or xconfig, dep,
and linux. If you forget for any of them, the i386 build seems to
- contaminate the UML build. If this happens, start from scratch with
+ contaminate the UML build. If this happens, start from scratch with::
host%
@@ -3811,7 +3668,7 @@
and repeat the build process with ARCH=um on all the steps.
- See ``Compiling the kernel and modules'' for more details.
+ See :ref:`Compiling_the_kernel_and_modules` for more details.
Another cause of strange compilation errors is building UML in
@@ -3824,11 +3681,11 @@
- 13.3. A variety of panics and hangs with /tmp on a reiserfs filesys-
- tem
+13.3. A variety of panics and hangs with /tmp on a reiserfs filesystem
+-----------------------------------------------------------------------
I saw this on reiserfs 3.5.21 and it seems to be fixed in 3.5.27.
- Panics preceded by
+ Panics preceded by::
Detaching pid nnnn
@@ -3854,17 +3711,19 @@
- 13.5. UML doesn't work when /tmp is an NFS filesystem
+13.5. UML doesn't work when /tmp is an NFS filesystem
+------------------------------------------------------
This seems to be a similar situation with the ReiserFS problem above.
Some versions of NFS seems not to handle mmap correctly, which UML
depends on. The workaround is have /tmp be a non-NFS directory.
- 13.6. UML hangs on boot when compiled with gprof support
+13.6. UML hangs on boot when compiled with gprof support
+---------------------------------------------------------
If you build UML with gprof support and, early in the boot, it does
- this
+ this::
kernel BUG at page_alloc.c:100!
@@ -3878,10 +3737,11 @@
- 13.7. syslogd dies with a SIGTERM on startup
+13.7. syslogd dies with a SIGTERM on startup
+---------------------------------------------
The exact boot error depends on the distribution that you're booting,
- but Debian produces this:
+ but Debian produces this::
/etc/rc2.d/S10sysklogd: line 49: 93 Terminated
@@ -3897,17 +3757,18 @@
- 13.8. TUN/TAP networking doesn't work on a 2.4 host
+13.8. TUN/TAP networking doesn't work on a 2.4 host
+----------------------------------------------------
There are a couple of problems which were
<http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
out"> by Tim Robinson <timro at trkr dot net>
- o It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
+ - It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
The fix is to upgrade to something more recent and then read the
next item.
- o If you see
+ - If you see::
File descriptor in bad state
@@ -3921,8 +3782,8 @@
- 13.9. You can network to the host but not to other machines on the
- net
+13.9. You can network to the host but not to other machines on the net
+=======================================================================
If you can connect to the host, and the host can connect to UML, but
you cannot connect to any other machines, then you may need to enable
@@ -3930,7 +3791,7 @@
using private IP addresses (192.168.x.x or 10.x.x.x) for host/UML
networking, rather than the public address space that your host is
connected to. UML does not enable IP Masquerading, so you will need
- to create a static rule to enable it:
+ to create a static rule to enable it::
host%
@@ -3948,7 +3809,7 @@
If you can reach the local net, but not the outside Internet, then
- that is usually a routing problem. The UML needs a default route:
+ that is usually a routing problem. The UML needs a default route::
UML#
@@ -3972,7 +3833,8 @@
- 13.10. I have no root and I want to scream
+13.10. I have no root and I want to scream
+===========================================
Thanks to Birgit Wahlich for telling me about this strange one. It
turns out that there's a limit of six environment variables on the
@@ -3987,14 +3849,16 @@
- 13.11. UML build conflict between ptrace.h and ucontext.h
+13.11. UML build conflict between ptrace.h and ucontext.h
+==========================================================
On some older systems, /usr/include/asm/ptrace.h and
/usr/include/sys/ucontext.h define the same names. So, when they're
included together, the defines from one completely mess up the parsing
- of the other, producing errors like:
+ of the other, producing errors like::
+
/usr/include/sys/ucontext.h:47: parse error before
- `10'
+ `10`
@@ -4007,7 +3871,8 @@
- 13.12. The UML BogoMips is exactly half the host's BogoMips
+13.12. The UML BogoMips is exactly half the host's BogoMips
+------------------------------------------------------------
On i386 kernels, there are two ways of running the loop that is used
to calculate the BogoMips rating, using the TSC if it's there or using
@@ -4019,15 +3884,17 @@
- 13.13. When you run UML, it immediately segfaults
+13.13. When you run UML, it immediately segfaults
+--------------------------------------------------
If the host is configured with the 2G/2G address space split, that's
- why. See ``UML on 2G/2G hosts'' for the details on getting UML to
+ why. See ref:`UML_on_2G/2G_hosts` for the details on getting UML to
run on your host.
- 13.14. xterms appear, then immediately disappear
+13.14. xterms appear, then immediately disappear
+-------------------------------------------------
If you're running an up to date kernel with an old release of
uml_utilities, the port-helper program will not work properly, so
@@ -4039,7 +3906,8 @@
- 13.15. Any other panic, hang, or strange behavior
+13.15. Any other panic, hang, or strange behavior
+--------------------------------------------------
If you're seeing truly strange behavior, such as hangs or panics that
happen in random places, or you try running the debugger to see what's
@@ -4057,9 +3925,13 @@
it and that a fix is imminent.
- If you want to be super-helpful, read ``Diagnosing Problems'' and
+ If you want to be super-helpful, read :ref:`Diagnosing_Problems` and
follow the instructions contained therein.
- 14. Diagnosing Problems
+
+.. _Diagnosing_Problems:
+
+14. Diagnosing Problems
+========================
If you get UML to crash, hang, or otherwise misbehave, you should
@@ -4074,21 +3946,22 @@
For any diagnosis, you're going to need to build a debugging kernel.
The binaries from this site aren't debuggable. If you haven't done
- this before, read about ``Compiling the kernel and modules'' and
- ``Kernel debugging'' UML first.
+ this before, read about :ref:`Compiling_the_kernel_and_modules` and
+ :ref:`Kernel_debugging` UML first.
- 14.1. Case 1 : Normal kernel panics
+14.1. Case 1 : Normal kernel panics
+------------------------------------
The most common case is for a normal thread to panic. To debug this,
you will need to run it under the debugger (add 'debug' to the command
line). An xterm will start up with gdb running inside it. Continue
- it when it stops in start_kernel and make it crash. Now ^C gdb and
+ it when it stops in start_kernel and make it crash. Now ``^C gdb`` and
If the panic was a "Kernel mode fault", then there will be a segv
frame on the stack and I'm going to want some more information. The
- stack might look something like this:
+ stack might look something like this::
(UML gdb) backtrace
@@ -4107,7 +3980,7 @@
I'm going to want to see the symbol and line information for the value
- of ip in the segv frame. In this case, you would do the following:
+ of ip in the segv frame. In this case, you would do the following::
(UML gdb) i sym 268849158
@@ -4115,7 +3988,7 @@
- and
+ and::
(UML gdb) i line *268849158
@@ -4128,7 +4001,8 @@
to get that information from the faulting ip.
- 14.2. Case 2 : Tracing thread panics
+14.2. Case 2 : Tracing thread panics
+-------------------------------------
The less common and more painful case is when the tracing thread
panics. In this case, the kernel debugger will be useless because it
@@ -4136,7 +4010,7 @@
do is get a backtrace from the tracing thread. This is done by
figuring out what its pid is, firing up gdb, and attaching it to that
pid. You can figure out the tracing thread pid by looking at the
- first line of the console output, which will look like this:
+ first line of the console output, which will look like this::
tracing thread pid = 15851
@@ -4145,7 +4019,7 @@
or by running ps on the host and finding the line that looks like
- this:
+ this::
jdike 15851 4.5 0.4 132568 1104 pts/0 S 21:34 0:05 ./linux [(tracing thread)]
@@ -4164,7 +4038,7 @@
14.3. Case 3 : Tracing thread panics caused by other threads
However, there are cases where the misbehavior of another thread
- caused the problem. The most common panic of this type is:
+ caused the problem. The most common panic of this type is::
wait_for_stop failed to wait for <pid> to stop with <signal number>
@@ -4177,7 +4051,7 @@
debugger is defunct and without some fancy footwork, another gdb can't
attach to it. So, this is how the fancy footwork goes:
- In a shell:
+ In a shell::
host% kill -STOP pid
@@ -4185,7 +4059,7 @@
- Run gdb on the tracing thread as described in case 2 and do:
+ Run gdb on the tracing thread as described in case 2 and do::
(host gdb) call detach(pid)
@@ -4193,7 +4067,7 @@
If you get a segfault, do it again. It always works the second time.
- Detach from the tracing thread and attach to that other thread:
+ Detach from the tracing thread and attach to that other thread::
(host gdb) detach
@@ -4209,7 +4083,7 @@
If gdb hangs when attaching to that process, go back to a shell and
- do:
+ do::
host%
@@ -4218,7 +4092,7 @@
- And then get the backtrace:
+ And then get the backtrace::
(host gdb) backtrace
@@ -4227,13 +4101,14 @@
- 14.4. Case 4 : Hangs
+14.4. Case 4 : Hangs
+---------------------
Hangs seem to be fairly rare, but they sometimes happen. When a hang
happens, we need a backtrace from the offending process. Run the
kernel debugger as described in case 1 and get a backtrace. If the
current process is not the idle thread, then send in the backtrace.
- You can tell that it's the idle thread if the stack looks like this:
+ You can tell that it's the idle thread if the stack looks like this::
#0 0x100b1401 in __libc_nanosleep ()
@@ -4257,7 +4132,8 @@
- 15. Thanks
+15. Thanks
+===========
A number of people have helped this project in various ways, and this
@@ -4274,20 +4150,21 @@
bookkeeping lapses and I forget about contributions.
- 15.1. Code and Documentation
+15.1. Code and Documentation
+-----------------------------
Rusty Russell <rusty at linuxcare.com.au> -
- o wrote the HOWTO <http://user-mode-
+ - wrote the HOWTO <http://user-mode-
linux.sourceforge.net/UserModeLinux-HOWTO.html>
- o prodded me into making this project official and putting it on
+ - prodded me into making this project official and putting it on
SourceForge
- o came up with the way cool UML logo <http://user-mode-
+ - came up with the way cool UML logo <http://user-mode-
linux.sourceforge.net/uml-small.png>
- o redid the config process
+ - redid the config process
Peter Moulder <reiter at netspace.net.au> - Fixed my config and build
@@ -4296,18 +4173,18 @@
Bill Stearns <wstearns at pobox.com> -
- o HOWTO updates
+ - HOWTO updates
- o lots of bug reports
+ - lots of bug reports
- o lots of testing
+ - lots of testing
- o dedicated a box (uml.ists.dartmouth.edu) to support UML development
+ - dedicated a box (uml.ists.dartmouth.edu) to support UML development
- o wrote the mkrootfs script, which allows bootable filesystems of
+ - wrote the mkrootfs script, which allows bootable filesystems of
RPM-based distributions to be cranked out
- o cranked out a large number of filesystems with said script
+ - cranked out a large number of filesystems with said script
Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
@@ -4375,176 +4252,180 @@
David Coulson <http://davidcoulson.net> -
- o Set up the usermodelinux.org <http://usermodelinux.org> site,
+ - Set up the usermodelinux.org <http://usermodelinux.org> site,
which is a great way of keeping the UML user community on top of
UML goings-on.
- o Site documentation and updates
+ - Site documentation and updates
- o Nifty little UML management daemon UMLd
+ - Nifty little UML management daemon UMLd
<http://uml.openconsultancy.com/umld/>
- o Lots of testing and bug reports
+ - Lots of testing and bug reports
- 15.2. Flushing out bugs
+15.2. Flushing out bugs
+------------------------
- o Yuri Pudgorodsky
+ - Yuri Pudgorodsky
- o Gerald Britton
+ - Gerald Britton
- o Ian Wehrman
+ - Ian Wehrman
- o Gord Lamb
+ - Gord Lamb
- o Eugene Koontz
+ - Eugene Koontz
- o John H. Hartman
+ - John H. Hartman
- o Anders Karlsson
+ - Anders Karlsson
- o Daniel Phillips
+ - Daniel Phillips
- o John Fremlin
+ - John Fremlin
- o Rainer Burgstaller
+ - Rainer Burgstaller
- o James Stevenson
+ - James Stevenson
- o Matt Clay
+ - Matt Clay
- o Cliff Jefferies
+ - Cliff Jefferies
- o Geoff Hoff
+ - Geoff Hoff
- o Lennert Buytenhek
+ - Lennert Buytenhek
- o Al Viro
+ - Al Viro
- o Frank Klingenhoefer
+ - Frank Klingenhoefer
- o Livio Baldini Soares
+ - Livio Baldini Soares
- o Jon Burgess
+ - Jon Burgess
- o Petru Paler
+ - Petru Paler
- o Paul
+ - Paul
- o Chris Reahard
+ - Chris Reahard
- o Sverker Nilsson
+ - Sverker Nilsson
- o Gong Su
+ - Gong Su
- o johan verrept
+ - johan verrept
- o Bjorn Eriksson
+ - Bjorn Eriksson
- o Lorenzo Allegrucci
+ - Lorenzo Allegrucci
- o Muli Ben-Yehuda
+ - Muli Ben-Yehuda
- o David Mansfield
+ - David Mansfield
- o Howard Goff
+ - Howard Goff
- o Mike Anderson
+ - Mike Anderson
- o John Byrne
+ - John Byrne
- o Sapan J. Batia
+ - Sapan J. Batia
- o Iris Huang
+ - Iris Huang
- o Jan Hudec
+ - Jan Hudec
- o Voluspa
+ - Voluspa
- 15.3. Buglets and clean-ups
+15.3. Buglets and clean-ups
+----------------------------
- o Dave Zarzycki
+ - Dave Zarzycki
- o Adam Lazur
+ - Adam Lazur
- o Boria Feigin
+ - Boria Feigin
- o Brian J. Murrell
+ - Brian J. Murrell
- o JS
+ - JS
- o Roman Zippel
+ - Roman Zippel
- o Wil Cooley
+ - Wil Cooley
- o Ayelet Shemesh
+ - Ayelet Shemesh
- o Will Dyson
+ - Will Dyson
- o Sverker Nilsson
+ - Sverker Nilsson
- o dvorak
+ - dvorak
- o v.naga srinivas
+ - v.naga srinivas
- o Shlomi Fish
+ - Shlomi Fish
- o Roger Binns
+ - Roger Binns
- o johan verrept
+ - johan verrept
- o MrChuoi
+ - MrChuoi
- o Peter Cleve
+ - Peter Cleve
- o Vincent Guffens
+ - Vincent Guffens
- o Nathan Scott
+ - Nathan Scott
- o Patrick Caulfield
+ - Patrick Caulfield
- o jbearce
+ - jbearce
- o Catalin Marinas
+ - Catalin Marinas
- o Shane Spencer
+ - Shane Spencer
- o Zou Min
+ - Zou Min
- o Ryan Boder
+ - Ryan Boder
- o Lorenzo Colitti
+ - Lorenzo Colitti
- o Gwendal Grignou
+ - Gwendal Grignou
- o Andre' Breiler
+ - Andre' Breiler
- o Tsutomu Yasuda
+ - Tsutomu Yasuda
- 15.4. Case Studies
+15.4. Case Studies
+-------------------
- o Jon Wright
+ - Jon Wright
- o William McEwan
+ - William McEwan
- o Michael Richardson
+ - Michael Richardson
- 15.5. Other contributions
+15.5. Other contributions
+--------------------------
Bill Carr <Bill.Carr at compaq.com> made the Red Hat mkrootfs script
@@ -4575,15 +4456,3 @@
server jailed inside UML. It's available from the download
<http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
Filesystems section.
-
-
-
-
-
-
-
-
-
-
-
-
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 02/27] docs: virt: convert UML documentation to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:57 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jonathan Corbet,
Jeff Dike, Richard Weinberger, Anton Ivanov, linux-doc, linux-um
Despite being an old document, it contains lots of information
that could still be useful.
The document has a nice style with makes easy to convert to
ReST. So, let's convert it to ReST.
This patch does:
- Use proper markups for titles;
- Mark and proper indent literal blocks;
- don't use an 'o' character for lists;
- other minor changes required for the doc to be parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/index.rst | 1 +
...odeLinux-HOWTO.txt => user_mode_linux.rst} | 1703 ++++++++---------
2 files changed, 787 insertions(+), 917 deletions(-)
rename Documentation/virt/uml/{UserModeLinux-HOWTO.txt => user_mode_linux.rst} (75%)
diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst
index 062ffb527043..0a8f7fda64ad 100644
--- a/Documentation/virt/index.rst
+++ b/Documentation/virt/index.rst
@@ -8,6 +8,7 @@ Linux Virtualization Support
:maxdepth: 2
kvm/index
+ uml/user_mode_linux
paravirt_ops
.. only:: html and subproject
diff --git a/Documentation/virt/uml/UserModeLinux-HOWTO.txt b/Documentation/virt/uml/user_mode_linux.rst
similarity index 75%
rename from Documentation/virt/uml/UserModeLinux-HOWTO.txt
rename to Documentation/virt/uml/user_mode_linux.rst
index 87b80f589e1c..98922008be23 100644
--- a/Documentation/virt/uml/UserModeLinux-HOWTO.txt
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -1,12 +1,15 @@
- User Mode Linux HOWTO
- User Mode Linux Core Team
- Mon Nov 18 14:16:16 EST 2002
+=====================
+User Mode Linux HOWTO
+=====================
- This document describes the use and abuse of Jeff Dike's User Mode
- Linux: a port of the Linux kernel as a normal Intel Linux process.
- ______________________________________________________________________
+:Author: User Mode Linux Core Team
+:Last-updated: Mon Nov 18 14:16:16 EST 2002
- Table of Contents
+This document describes the use and abuse of Jeff Dike's User Mode
+Linux: a port of the Linux kernel as a normal Intel Linux process.
+
+
+.. Table of Contents
1. Introduction
@@ -132,19 +135,19 @@
15.5 Other contributions
- ______________________________________________________________________
-
- 1. Introduction
+1. Introduction
+================
Welcome to User Mode Linux. It's going to be fun.
- 1.1. How is User Mode Linux Different?
+1.1. How is User Mode Linux Different?
+---------------------------------------
Normally, the Linux Kernel talks straight to your hardware (video
card, keyboard, hard drives, etc), and any programs which run ask the
- kernel to operate the hardware, like so:
+ kernel to operate the hardware, like so::
@@ -160,10 +163,10 @@
The User Mode Linux Kernel is different; instead of talking to the
- hardware, it talks to a `real' Linux kernel (called the `host kernel'
+ hardware, it talks to a `real` Linux kernel (called the `host kernel`
from now on), like any other program. Programs can then run inside
User-Mode Linux as if they were running under a normal kernel, like
- so:
+ so::
@@ -181,7 +184,8 @@
- 1.2. Why Would I Want User Mode Linux?
+1.2. Why Would I Want User Mode Linux?
+---------------------------------------
1. If User Mode Linux crashes, your host kernel is still fine.
@@ -204,14 +208,16 @@
+.. _Compiling_the_kernel_and_modules:
+2. Compiling the kernel and modules
+====================================
- 2. Compiling the kernel and modules
-
- 2.1. Compiling the kernel
+2.1. Compiling the kernel
+--------------------------
Compiling the user mode kernel is just like compiling any other
@@ -220,7 +226,6 @@
1. Download the latest UML patch from
-
the download page <http://user-mode-linux.sourceforge.net/
In this example, the file is uml-patch-2.4.0-prerelease.bz2.
@@ -230,57 +235,33 @@
such as:
ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
- <ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2>
- .
-
-
- 3. Make a directory and unpack the kernel into it.
+ 3. Make a directory and unpack the kernel into it::
host%
mkdir ~/uml
-
-
-
-
-
host%
cd ~/uml
-
-
-
-
-
host%
tar -xzvf linux-2.4.0-prerelease.tar.bz2
-
-
-
- 4. Apply the patch using
-
-
+ 4. Apply the patch using::
host%
cd ~/uml/linux
-
-
host%
bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
-
-
-
- 5. Run your favorite config; `make xconfig ARCH=um' is the most
- convenient. `make config ARCH=um' and 'make menuconfig ARCH=um'
+ 5. Run your favorite config; ``make xconfig ARCH=um`` is the most
+ convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um``
will work as well. The defaults will give you a useful kernel. If
you want to change something, go ahead, it probably won't hurt
anything.
@@ -288,13 +269,13 @@
Note: If the host is configured with a 2G/2G address space split
rather than the usual 3G/1G split, then the packaged UML binaries
- will not run. They will immediately segfault. See ``UML on 2G/2G
- hosts'' for the scoop on running UML on your system.
+ will not run. They will immediately segfault. See
+ :ref:`UML_on_2G/2G_hosts` for the scoop on running UML on your system.
- 6. Finish with `make linux ARCH=um': the result is a file called
- `linux' in the top directory of your source tree.
+ 6. Finish with ``make linux ARCH=um``: the result is a file called
+ ``linux`` in the top directory of your source tree.
Make sure that you don't build this kernel in /usr/src/linux. On some
distributions, /usr/include/asm is a link into this pool. The user-
@@ -310,7 +291,7 @@
corresponding directory in the appropriate kernel pool.
If you don't have the latest kernel pool, you can get the
- corresponding user-mode sources with
+ corresponding user-mode sources with::
host% cvs co -r v_2_3_x linux
@@ -322,10 +303,11 @@
bug fixes and enhancements that have gone into subsequent releases.
- 2.2. Compiling and installing kernel modules
+2.2. Compiling and installing kernel modules
+---------------------------------------------
UML modules are built in the same way as the native kernel (with the
- exception of the 'ARCH=um' that you always need for UML):
+ exception of the 'ARCH=um' that you always need for UML)::
host% make modules ARCH=um
@@ -337,12 +319,12 @@
the user-mode pool. Modules from the native kernel won't work.
You can install them by using ftp or something to copy them into the
- virtual machine and dropping them into /lib/modules/`uname -r`.
+ virtual machine and dropping them into ``/lib/modules/$(uname -r)``.
You can also get the kernel build process to install them as follows:
1. with the kernel not booted, mount the root filesystem in the top
- level of the kernel pool:
+ level of the kernel pool::
host% mount root_fs mnt -o loop
@@ -352,7 +334,7 @@
- 2. run
+ 2. run::
host%
@@ -363,7 +345,7 @@
- 3. unmount the filesystem
+ 3. unmount the filesystem::
host% umount mnt
@@ -386,22 +368,23 @@
- 2.3. Compiling and installing uml_utilities
+2.3. Compiling and installing uml_utilities
+--------------------------------------------
Many features of the UML kernel require a user-space helper program,
so a uml_utilities package is distributed separately from the kernel
patch which provides these helpers. Included within this is:
- o port-helper - Used by consoles which connect to xterms or ports
+ - port-helper - Used by consoles which connect to xterms or ports
- o tunctl - Configuration tool to create and delete tap devices
+ - tunctl - Configuration tool to create and delete tap devices
- o uml_net - Setuid binary for automatic tap device configuration
+ - uml_net - Setuid binary for automatic tap device configuration
- o uml_switch - User-space virtual switch required for daemon
+ - uml_switch - User-space virtual switch required for daemon
transport
- The uml_utilities tree is compiled with:
+ The uml_utilities tree is compiled with::
host#
@@ -423,19 +406,21 @@
- 3. Running UML and logging in
+3. Running UML and logging in
+==============================
- 3.1. Running UML
+3.1. Running UML
+-----------------
It runs on 2.2.15 or later, and all 2.4 kernels.
Booting UML is straightforward. Simply run 'linux': it will try to
- mount the file `root_fs' in the current directory. You do not need to
- run it as root. If your root filesystem is not named `root_fs', then
- you need to put a `ubd0=root_fs_whatever' switch on the linux command
+ mount the file ``root_fs`` in the current directory. You do not need to
+ run it as root. If your root filesystem is not named ``root_fs``, then
+ you need to put a ``ubd0=root_fs_whatever`` switch on the linux command
line.
@@ -447,14 +432,16 @@
The kernel will boot up and present you with a login prompt.
- Note: If the host is configured with a 2G/2G address space split
+Note:
+ If the host is configured with a 2G/2G address space split
rather than the usual 3G/1G split, then the packaged UML binaries will
- not run. They will immediately segfault. See ``UML on 2G/2G hosts''
+ not run. They will immediately segfault. See :ref:`UML_on_2G/2G_hosts`
for the scoop on running UML on your system.
- 3.2. Logging in
+3.2. Logging in
+----------------
@@ -468,22 +455,22 @@
There are a couple of other ways to log in:
- o On a virtual console
+ - On a virtual console
Each virtual console that is configured (i.e. the device exists in
/dev and /etc/inittab runs a getty on it) will come up in its own
- xterm. If you get tired of the xterms, read ``Setting up serial
- lines and consoles'' to see how to attach the consoles to
- something else, like host ptys.
+ xterm. If you get tired of the xterms, read
+ :ref:`setting_up_serial_lines_and_consoles` to see how to attach
+ the consoles to something else, like host ptys.
- o Over the serial line
+ - Over the serial line
- In the boot output, find a line that looks like:
+ In the boot output, find a line that looks like::
@@ -493,7 +480,7 @@
Attach your favorite terminal program to the corresponding tty. I.e.
- for minicom, the command would be
+ for minicom, the command would be::
host% minicom -o -p /dev/ttyp1
@@ -503,37 +490,41 @@
- o Over the net
+ - Over the net
If the network is running, then you can telnet to the virtual
- machine and log in to it. See ``Setting up the network'' to learn
+ machine and log in to it. See :ref:`Setting_up_the_network` to learn
about setting up a virtual network.
When you're done using it, run halt, and the kernel will bring itself
down and the process will exit.
- 3.3. Examples
+3.3. Examples
+--------------
Here are some examples of UML in action:
- o A login session <http://user-mode-linux.sourceforge.net/login.html>
+ - A login session <http://user-mode-linux.sourceforge.net/login.html>
- o A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+ - A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+.. _UML_on_2G/2G_hosts:
- 4. UML on 2G/2G hosts
+4. UML on 2G/2G hosts
+======================
- 4.1. Introduction
+4.1. Introduction
+------------------
Most Linux machines are configured so that the kernel occupies the
@@ -546,7 +537,8 @@
- 4.2. The problem
+4.2. The problem
+-----------------
The prebuilt UML binaries on this site will not run on 2G/2G hosts
@@ -558,13 +550,14 @@
- 4.3. The solution
+4.3. The solution
+------------------
The fix for this is to rebuild UML from source after enabling
CONFIG_HOST_2G_2G (under 'General Setup'). This will cause UML to
load itself in the top .5G of that smaller process address space,
- where it will run fine. See ``Compiling the kernel and modules'' if
+ where it will run fine. See :ref:`Compiling_the_kernel_and_modules` if
you need help building UML from source.
@@ -573,10 +566,11 @@
+.. _setting_up_serial_lines_and_consoles:
-
- 5. Setting up serial lines and consoles
+5. Setting up serial lines and consoles
+========================================
It is possible to attach UML serial lines and consoles to many types
@@ -584,22 +578,23 @@
You can attach them to host ptys, ttys, file descriptors, and ports.
- This allows you to do things like
+ This allows you to do things like:
- o have a UML console appear on an unused host console,
+ - have a UML console appear on an unused host console,
- o hook two virtual machines together by having one attach to a pty
+ - hook two virtual machines together by having one attach to a pty
and having the other attach to the corresponding tty
- o make a virtual machine accessible from the net by attaching a
+ - make a virtual machine accessible from the net by attaching a
console to a port on the host.
- The general format of the command line option is device=channel.
+ The general format of the command line option is ``device=channel``.
- 5.1. Specifying the device
+5.1. Specifying the device
+---------------------------
Devices are specified with "con" or "ssl" (console or serial line,
respectively), optionally with a device number if you are talking
@@ -613,7 +608,7 @@
A specific device name will override a less general "con=" or "ssl=".
So, for example, you can assign a pty to each of the serial lines
- except for the first two like this:
+ except for the first two like this::
ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1
@@ -626,13 +621,14 @@
- 5.2. Specifying the channel
+5.2. Specifying the channel
+----------------------------
There are a number of different types of channels to attach a UML
device to, each with a different way of specifying exactly what to
attach to.
- o pseudo-terminals - device=pty pts terminals - device=pts
+ - pseudo-terminals - device=pty pts terminals - device=pts
This will cause UML to allocate a free host pseudo-terminal for the
@@ -640,23 +636,23 @@
log. You access it by attaching a terminal program to the
corresponding tty:
- o screen /dev/pts/n
+ - screen /dev/pts/n
- o screen /dev/ttyxx
+ - screen /dev/ttyxx
- o minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
+ - minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
devices
- o kermit - start it up, 'open' the device, then 'connect'
+ - kermit - start it up, 'open' the device, then 'connect'
- o terminals - device=tty:tty device file
+ - terminals - device=tty:tty device file
- This will make UML attach the device to the specified tty (i.e
+ This will make UML attach the device to the specified tty (i.e::
con1=tty:/dev/tty3
@@ -672,7 +668,7 @@
- o xterms - device=xterm
+ - xterms - device=xterm
UML will run an xterm and the device will be attached to it.
@@ -681,12 +677,12 @@
- o Port - device=port:port number
+ - Port - device=port:port number
This will attach the UML devices to the specified host port.
Attaching console 1 to the host's port 9000 would be done like
- this:
+ this::
con1=port:9000
@@ -694,7 +690,7 @@
- Attaching all the serial lines to that port would be done similarly:
+ Attaching all the serial lines to that port would be done similarly::
ssl=port:9000
@@ -702,8 +698,8 @@
- You access these devices by telnetting to that port. Each active tel-
- net session gets a different device. If there are more telnets to a
+ You access these devices by telnetting to that port. Each active
+ telnet session gets a different device. If there are more telnets to a
port than UML devices attached to it, then the extra telnet sessions
will block until an existing telnet detaches, or until another device
becomes active (i.e. by being activated in /etc/inittab).
@@ -725,13 +721,13 @@
- o already-existing file descriptors - device=file descriptor
+ - already-existing file descriptors - device=file descriptor
If you set up a file descriptor on the UML command line, you can
attach a UML device to it. This is most commonly used to put the
main console back on stdin and stdout after assigning all the other
- consoles to something else:
+ consoles to something else::
con0=fd:0,fd:1 con=pts
@@ -743,7 +739,7 @@
- o Nothing - device=null
+ - Nothing - device=null
This allows the device to be opened, in contrast to 'none', but
@@ -754,7 +750,7 @@
- o None - device=none
+ - None - device=none
This causes the device to disappear.
@@ -762,7 +758,7 @@
You can also specify different input and output channels for a device
- by putting a comma between them:
+ by putting a comma between them::
ssl3=tty:/dev/tty2,xterm
@@ -785,14 +781,15 @@
- 5.3. Examples
+5.3. Examples
+--------------
There are a number of interesting things you can do with this
capability.
First, this is how you get rid of those bleeding console xterms by
- attaching them to host ptys:
+ attaching them to host ptys::
con=pty con0=fd:0,fd:1
@@ -802,7 +799,7 @@
This will make a UML console take over an unused host virtual console,
so that when you switch to it, you will see the UML login prompt
- rather than the host login prompt:
+ rather than the host login prompt::
con1=tty:/dev/tty6
@@ -813,7 +810,7 @@
You can attach two virtual machines together with what amounts to a
serial line as follows:
- Run one UML with a serial line attached to a pty -
+ Run one UML with a serial line attached to a pty::
ssl1=pty
@@ -825,7 +822,7 @@
that it got /dev/ptyp1).
Boot the other UML with a serial line attached to the corresponding
- tty -
+ tty::
ssl1=tty:/dev/ttyp1
@@ -838,7 +835,10 @@
prompt of the other virtual machine.
- 6. Setting up the network
+.. _setting_up_the_network:
+
+6. Setting up the network
+==========================
@@ -858,19 +858,19 @@
There are currently five transport types available for a UML virtual
machine to exchange packets with other hosts:
- o ethertap
+ - ethertap
- o TUN/TAP
+ - TUN/TAP
- o Multicast
+ - Multicast
- o a switch daemon
+ - a switch daemon
- o slip
+ - slip
- o slirp
+ - slirp
- o pcap
+ - pcap
The TUN/TAP, ethertap, slip, and slirp transports allow a UML
instance to exchange packets with the host. They may be directed
@@ -893,28 +893,28 @@
With so many host transports, which one should you use? Here's when
you should use each one:
- o ethertap - if you want access to the host networking and it is
+ - ethertap - if you want access to the host networking and it is
running 2.2
- o TUN/TAP - if you want access to the host networking and it is
+ - TUN/TAP - if you want access to the host networking and it is
running 2.4. Also, the TUN/TAP transport is able to use a
preconfigured device, allowing it to avoid using the setuid uml_net
helper, which is a security advantage.
- o Multicast - if you want a purely virtual network and you don't want
+ - Multicast - if you want a purely virtual network and you don't want
to set up anything but the UML
- o a switch daemon - if you want a purely virtual network and you
+ - a switch daemon - if you want a purely virtual network and you
don't mind running the daemon in order to get somewhat better
performance
- o slip - there is no particular reason to run the slip backend unless
+ - slip - there is no particular reason to run the slip backend unless
ethertap and TUN/TAP are just not available for some reason
- o slirp - if you don't have root access on the host to setup
+ - slirp - if you don't have root access on the host to setup
networking, or if you don't want to allocate an IP to your UML
- o pcap - not much use for actual network connectivity, but great for
+ - pcap - not much use for actual network connectivity, but great for
monitoring traffic on the host
Ethertap is available on 2.4 and works fine. TUN/TAP is preferred
@@ -926,7 +926,8 @@
exploit the helper's root privileges.
- 6.1. General setup
+6.1. General setup
+-------------------
First, you must have the virtual network enabled in your UML. If are
running a prebuilt kernel from this site, everything is already
@@ -938,7 +939,7 @@
The next step is to provide a network device to the virtual machine.
This is done by describing it on the kernel command line.
- The general format is
+ The general format is::
eth <n> = <transport> , <transport args>
@@ -947,7 +948,7 @@
For example, a virtual ethernet device may be attached to a host
- ethertap device as follows:
+ ethertap device as follows::
eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
@@ -978,7 +979,7 @@
You can also add devices to a UML and remove them at runtime. See the
- ``The Management Console'' page for details.
+ :ref:`The_Management_Console` page for details.
The sections below describe this in more detail.
@@ -995,7 +996,8 @@
- 6.2. Userspace daemons
+6.2. Userspace daemons
+-----------------------
You will likely need the setuid helper, or the switch daemon, or both.
They are both installed with the RPM and deb, so if you've installed
@@ -1011,7 +1013,8 @@
- 6.3. Specifying ethernet addresses
+6.3. Specifying ethernet addresses
+-----------------------------------
Below, you will see that the TUN/TAP, ethertap, and daemon interfaces
allow you to specify hardware addresses for the virtual ethernet
@@ -1023,21 +1026,21 @@
sufficient to guarantee a unique hardware address for the device. A
couple of exceptions are:
- o Another set of virtual ethernet devices are on the same network and
+ - Another set of virtual ethernet devices are on the same network and
they are assigned hardware addresses using a different scheme which
may conflict with the UML IP address-based scheme
- o You aren't going to use the device for IP networking, so you don't
+ - You aren't going to use the device for IP networking, so you don't
assign the device an IP address
If you let the driver provide the hardware address, you should make
sure that the device IP address is known before the interface is
- brought up. So, inside UML, this will guarantee that:
+ brought up. So, inside UML, this will guarantee that::
- UML#
- ifconfig eth0 192.168.0.250 up
+ UML#
+ ifconfig eth0 192.168.0.250 up
@@ -1049,13 +1052,14 @@
- 6.4. UML interface setup
+6.4. UML interface setup
+-------------------------
Once the network devices have been described on the command line, you
should boot UML and log in.
- The first thing to do is bring the interface up:
+ The first thing to do is bring the interface up::
UML# ifconfig ethn ip-address up
@@ -1067,7 +1071,7 @@
To reach the rest of the world, you should set a default route to the
- host:
+ host::
UML# route add default gw host ip
@@ -1075,7 +1079,7 @@
- Again, with host ip of 192.168.0.4:
+ Again, with host ip of 192.168.0.4::
UML# route add default gw 192.168.0.4
@@ -1097,29 +1101,25 @@
Note: If you can't communicate with other hosts on your physical
ethernet, it's probably because of a network route that's
automatically set up. If you run 'route -n' and see a route that
- looks like this:
+ looks like this::
- Destination Gateway Genmask Flags Metric Ref Use Iface
- 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
+ Destination Gateway Genmask Flags Metric Ref Use Iface
+ 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
with a mask that's not 255.255.255.255, then replace it with a route
- to your host:
+ to your host::
UML#
route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0
-
-
-
-
UML#
route add -host 192.168.0.4 dev eth0
@@ -1131,7 +1131,8 @@
- 6.5. Multicast
+6.5. Multicast
+---------------
The simplest way to set up a virtual network between multiple UMLs is
to use the mcast transport. This was written by Harald Welte and is
@@ -1142,7 +1143,7 @@
messages when you bring the device up inside UML.
- To use it, run two UMLs with
+ To use it, run two UMLs with::
eth0=mcast
@@ -1151,16 +1152,12 @@
on their command lines. Log in, configure the ethernet device in each
- machine with different IP addresses:
+ machine with different IP addresses::
UML1# ifconfig eth0 192.168.0.254
-
-
-
-
UML2# ifconfig eth0 192.168.0.253
@@ -1168,7 +1165,7 @@
and they should be able to talk to each other.
- The full set of command line options for this transport are
+ The full set of command line options for this transport are::
@@ -1186,7 +1183,7 @@
This is useful when your network does not support multicast, and
all network connections are simple point to point links.
- The full set of command line options for this transport are
+ The full set of command line options for this transport are::
ethn=ucast,ethernet address,remote address,listen port,remote port
@@ -1194,7 +1191,8 @@
- 6.6. TUN/TAP with the uml_net helper
+6.6. TUN/TAP with the uml_net helper
+-------------------------------------
TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the
host. The TUN/TAP backend has been in UML since 2.4.9-3um.
@@ -1216,7 +1214,7 @@
kernel or as the tun.o module.
The format of the command line switch to attach a device to a TUN/TAP
- device is
+ device is::
eth <n> =tuntap,,, <IP address>
@@ -1226,7 +1224,7 @@
For example, this argument will attach the UML's eth0 to the next
available tap device and assign an ethernet address to it based on its
- IP address
+ IP address::
eth0=tuntap,,,192.168.0.254
@@ -1247,10 +1245,10 @@
There are a couple potential problems with running the TUN/TAP
transport on a 2.4 host kernel
- o TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
+ - TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
kernel or use the ethertap transport.
- o With an upgraded kernel, TUN/TAP may fail with
+ - With an upgraded kernel, TUN/TAP may fail with::
File descriptor in bad state
@@ -1264,12 +1262,12 @@
kernel.
These were pointed out by Tim Robinson <timro at trkr dot net> in
- <http://www.geocrawler.com/> name="this uml-
- user post"> .
+ <http://www.geocrawler.com/> name="this uml-user post"> .
- 6.7. TUN/TAP with a preconfigured tap device
+6.7. TUN/TAP with a preconfigured tap device
+---------------------------------------------
If you prefer not to have UML use uml_net (which is somewhat
insecure), with UML 2.4.17-11, you can set up a TUN/TAP device
@@ -1277,8 +1275,8 @@
there is no need for root assistance. Setting up the device is done
as follows:
- o Create the device with tunctl (available from the UML utilities
- tarball)
+ - Create the device with tunctl (available from the UML utilities
+ tarball)::
@@ -1291,8 +1289,8 @@
where uid is the user id or username that UML will be run as. This
will tell you what device was created.
- o Configure the device IP (change IP addresses and device name to
- suit)
+ - Configure the device IP (change IP addresses and device name to
+ suit)::
@@ -1303,8 +1301,8 @@
- o Set up routing and arping if desired - this is my recipe, there are
- other ways of doing the same thing
+ - Set up routing and arping if desired - this is my recipe, there are
+ other ways of doing the same thing::
host#
@@ -1313,19 +1311,9 @@
host#
route add -host 192.168.0.253 dev tap0
-
-
-
-
-
host#
bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
-
-
-
-
-
host#
arp -Ds 192.168.0.253 eth0 pub
@@ -1338,76 +1326,43 @@
utility which reads the information from a config file and sets up
devices at boot time.
- o Rather than using up two IPs and ARPing for one of them, you can
+ - Rather than using up two IPs and ARPing for one of them, you can
also provide direct access to your LAN by the UML by using a
- bridge.
+ bridge::
host#
brctl addbr br0
-
-
-
-
host#
ifconfig eth0 0.0.0.0 promisc up
-
-
-
-
host#
ifconfig tap0 0.0.0.0 promisc up
-
-
-
-
host#
ifconfig br0 192.168.0.1 netmask 255.255.255.0 up
-
-
-
-
-
- host#
- brctl stp br0 off
-
-
-
-
+ host#
+ brctl stp br0 off
host#
brctl setfd br0 1
-
-
-
-
host#
brctl sethello br0 1
-
-
-
-
host#
brctl addif br0 eth0
-
-
-
-
host#
brctl addif br0 tap0
@@ -1417,12 +1372,12 @@
Note that 'br0' should be setup using ifconfig with the existing IP
address of eth0, as eth0 no longer has its own IP.
- o
+ -
Also, the /dev/net/tun device must be writable by the user running
UML in order for the UML to use the device that's been configured
- for it. The simplest thing to do is
+ for it. The simplest thing to do is::
host# chmod 666 /dev/net/tun
@@ -1438,14 +1393,14 @@
devices and chgrp /dev/net/tun to that group with mode 664 or 660.
- o Once the device is set up, run UML with 'eth0=tuntap,device name'
+ - Once the device is set up, run UML with 'eth0=tuntap,device name'
(i.e. 'eth0=tuntap,tap0') on the command line (or do it with the
mconsole config command).
- o Bring the eth device up in UML and you're in business.
+ - Bring the eth device up in UML and you're in business.
If you don't want that tap device any more, you can make it non-
- persistent with
+ persistent with::
host# tunctl -d tap device
@@ -1455,7 +1410,7 @@
Finally, tunctl has a -b (for brief mode) switch which causes it to
output only the name of the tap device it created. This makes it
- suitable for capture by a script:
+ suitable for capture by a script::
host# TAP=`tunctl -u 1000 -b`
@@ -1465,7 +1420,8 @@
- 6.8. Ethertap
+6.8. Ethertap
+--------------
Ethertap is the general mechanism on 2.2 for userspace processes to
exchange packets with the kernel.
@@ -1473,7 +1429,7 @@
To use this transport, you need to describe the virtual network device
- on the UML command line. The general format for this is
+ on the UML command line. The general format for this is::
eth <n> =ethertap, <device> , <ethernet address> , <tap IP address>
@@ -1481,7 +1437,7 @@
- So, the previous example
+ So, the previous example::
eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
@@ -1521,7 +1477,7 @@
If you want to set things up yourself, you need to make sure that the
appropriate /dev entry exists. If it doesn't, become root and create
- it as follows:
+ it as follows::
mknod /dev/tap <minor> c 36 <minor> + 16
@@ -1529,7 +1485,7 @@
- For example, this is how to create /dev/tap0:
+ For example, this is how to create /dev/tap0::
mknod /dev/tap0 c 36 0 + 16
@@ -1539,7 +1495,7 @@
You also need to make sure that the host kernel has ethertap support.
If ethertap is enabled as a module, you apparently need to insmod
- ethertap once for each ethertap device you want to enable. So,
+ ethertap once for each ethertap device you want to enable. So,::
host#
@@ -1549,7 +1505,7 @@
will give you the tap0 interface. To get the tap1 interface, you need
- to run
+ to run::
host#
@@ -1561,7 +1517,8 @@
- 6.9. The switch daemon
+6.9. The switch daemon
+-----------------------
Note: This is the daemon formerly known as uml_router, but which was
renamed so the network weenies of the world would stop growling at me.
@@ -1577,7 +1534,7 @@
sockets.
- If you want it to listen on a different pair of sockets, use
+ If you want it to listen on a different pair of sockets, use::
-unix control socket data socket
@@ -1586,7 +1543,7 @@
- If you want it to act as a hub rather than a switch, use
+ If you want it to act as a hub rather than a switch, use::
-hub
@@ -1596,7 +1553,7 @@
If you want the switch to be connected to host networking (allowing
- the umls to get access to the outside world through the host), use
+ the umls to get access to the outside world through the host), use::
-tap tap0
@@ -1610,7 +1567,7 @@
device than tap0, specify that instead of tap0.
- uml_switch can be backgrounded as follows
+ uml_switch can be backgrounded as follows::
host%
@@ -1623,7 +1580,7 @@
stdin for EOF. When it sees that, it exits.
- The general format of the kernel command line switch is
+ The general format of the kernel command line switch is::
@@ -1639,7 +1596,8 @@
how to communicate with the daemon. You should only specify them if
you told the daemon to use different sockets than the default. So, if
you ran the daemon with no arguments, running the UML on the same
- machine with
+ machine with::
+
eth0=daemon
@@ -1649,7 +1607,8 @@
- 6.10. Slip
+6.10. Slip
+-----------
Slip is another, less general, mechanism for a process to communicate
with the host networking. In contrast to the ethertap interface,
@@ -1658,7 +1617,7 @@
IP.
- The general format of the command line switch is
+ The general format of the command line switch is::
@@ -1681,7 +1640,8 @@
- 6.11. Slirp
+6.11. Slirp
+------------
slirp uses an external program, usually /usr/bin/slirp, to provide IP
only networking connectivity through the host. This is similar to IP
@@ -1691,7 +1651,7 @@
root access or setuid binaries on the host.
- The general format of the command line switch for slirp is:
+ The general format of the command line switch for slirp is::
@@ -1716,7 +1676,7 @@
The eth0 interface on UML should be set up with the IP 10.2.0.15,
although you can use anything as long as it is not used by a network
you will be connecting to. The default route on UML should be set to
- use
+ use::
UML#
@@ -1737,10 +1697,11 @@
- 6.12. pcap
+6.12. pcap
+-----------
The pcap transport is attached to a UML ethernet device on the command
- line or with uml_mconsole with the following syntax:
+ line or with uml_mconsole with the following syntax::
@@ -1762,7 +1723,7 @@
expression optimizer is used.
- Example:
+ Example::
@@ -1777,7 +1738,8 @@
- 6.13. Setting up the host yourself
+6.13. Setting up the host yourself
+-----------------------------------
If you don't specify an address for the host side of the ethertap or
slip device, UML won't do any setup on the host. So this is what is
@@ -1785,19 +1747,15 @@
192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your
own network):
- o The device needs to be configured with its IP address. Tap devices
+ - The device needs to be configured with its IP address. Tap devices
are also configured with an mtu of 1484. Slip devices are
configured with a point-to-point address pointing at the UML ip
- address.
+ address::
host# ifconfig tap0 arp mtu 1484 192.168.0.251 up
-
-
-
-
host#
ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up
@@ -1805,7 +1763,7 @@
- o If a tap device is being set up, a route is set to the UML IP.
+ - If a tap device is being set up, a route is set to the UML IP::
UML# route add -host 192.168.0.250 gw 192.168.0.251
@@ -1814,8 +1772,8 @@
- o To allow other hosts on your network to see the virtual machine,
- proxy arp is set up for it.
+ - To allow other hosts on your network to see the virtual machine,
+ proxy arp is set up for it::
host# arp -Ds 192.168.0.250 eth0 pub
@@ -1824,7 +1782,7 @@
- o Finally, the host is set up to route packets.
+ - Finally, the host is set up to route packets::
host# echo 1 > /proc/sys/net/ipv4/ip_forward
@@ -1838,12 +1796,14 @@
- 7. Sharing Filesystems between Virtual Machines
+7. Sharing Filesystems between Virtual Machines
+================================================
- 7.1. A warning
+7.1. A warning
+---------------
Don't attempt to share filesystems simply by booting two UMLs from the
same file. That's the same thing as booting two physical machines
@@ -1851,7 +1811,8 @@
- 7.2. Using layered block devices
+7.2. Using layered block devices
+---------------------------------
The way to share a filesystem between two virtual machines is to use
the copy-on-write (COW) layering capability of the ubd block driver.
@@ -1872,7 +1833,7 @@
To add a copy-on-write layer to an existing block device file, simply
- add the name of the COW file to the appropriate ubd switch:
+ add the name of the COW file to the appropriate ubd switch::
ubd0=root_fs_cow,root_fs_debian_22
@@ -1883,7 +1844,7 @@
where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is
the existing shared filesystem. The COW file need not exist. If it
doesn't, the driver will create and initialize it. Once the COW file
- has been initialized, it can be used on its own on the command line:
+ has been initialized, it can be used on its own on the command line::
ubd0=root_fs_cow
@@ -1896,14 +1857,16 @@
- 7.3. Note!
+7.3. Note!
+-----------
When checking the size of the COW file in order to see the gobs of
space that you're saving, make sure you use 'ls -ls' to see the actual
disk consumption rather than the length of the file. The COW file is
sparse, so the length will be very different from the disk usage.
Here is a 'ls -l' of a COW file and backing file from one boot and
- shutdown:
+ shutdown::
+
host% ls -l cow.debian debian2.2
-rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
-rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
@@ -1911,7 +1874,7 @@
- Doesn't look like much saved space, does it? Well, here's 'ls -ls':
+ Doesn't look like much saved space, does it? Well, here's 'ls -ls'::
host% ls -ls cow.debian debian2.2
@@ -1926,7 +1889,8 @@
- 7.4. Another warning
+7.4. Another warning
+---------------------
Once a filesystem is being used as a readonly backing file for a COW
file, do not boot directly from it or modify it in any way. Doing so
@@ -1952,7 +1916,8 @@
- 7.5. uml_moo : Merging a COW file with its backing file
+7.5. uml_moo : Merging a COW file with its backing file
+--------------------------------------------------------
Depending on how you use UML and COW devices, it may be advisable to
merge the changes in the COW file into the backing file every once in
@@ -1961,7 +1926,7 @@
- The utility that does this is uml_moo. Its usage is
+ The utility that does this is uml_moo. Its usage is::
host% uml_moo COW file new backing file
@@ -2001,7 +1966,8 @@
- 8. Creating filesystems
+8. Creating filesystems
+========================
You may want to create and mount new UML filesystems, either because
@@ -2015,13 +1981,14 @@
should be easy to translate to the filesystem of your choice.
- 8.1. Create the filesystem file
+8.1. Create the filesystem file
+================================
dd is your friend. All you need to do is tell dd to create an empty
file of the appropriate size. I usually make it sparse to save time
and to avoid allocating disk space until it's actually used. For
example, the following command will create a sparse 100 meg file full
- of zeroes.
+ of zeroes::
host%
@@ -2034,9 +2001,9 @@
8.2. Assign the file to a UML device
- Add an argument like the following to the UML command line:
+ Add an argument like the following to the UML command line::
- ubd4=new_filesystem
+ ubd4=new_filesystem
@@ -2053,7 +2020,7 @@
etc), then get them into UML by way of the net or hostfs.
- Make the new filesystem on the device assigned to the new file:
+ Make the new filesystem on the device assigned to the new file::
host# mkreiserfs /dev/ubd/4
@@ -2077,7 +2044,7 @@
- Now, mount it:
+ Now, mount it::
UML#
@@ -2096,7 +2063,8 @@
- 9. Host file access
+9. Host file access
+====================
If you want to access files on the host machine from inside UML, you
@@ -2112,10 +2080,11 @@
files contained in it just as you would on the host.
- 9.1. Using hostfs
+9.1. Using hostfs
+------------------
To begin with, make sure that hostfs is available inside the virtual
- machine with
+ machine with::
UML# cat /proc/filesystems
@@ -2127,7 +2096,7 @@
module and available inside the virtual machine, and insmod it.
- Now all you need to do is run mount:
+ Now all you need to do is run mount::
UML# mount none /mnt/host -t hostfs
@@ -2139,7 +2108,7 @@
If you don't want to mount the host root directory, then you can
- specify a subdirectory to mount with the -o switch to mount:
+ specify a subdirectory to mount with the -o switch to mount::
UML# mount none /mnt/home -t hostfs -o /home
@@ -2151,13 +2120,14 @@
- 9.2. hostfs as the root filesystem
+9.2. hostfs as the root filesystem
+-----------------------------------
It's possible to boot from a directory hierarchy on the host using
hostfs rather than using the standard filesystem in a file.
To start, you need that hierarchy. The easiest way is to loop mount
- an existing root_fs file:
+ an existing root_fs file::
host# mount root_fs uml_root_dir -o loop
@@ -2166,15 +2136,15 @@
You need to change the filesystem type of / in etc/fstab to be
- 'hostfs', so that line looks like this:
+ 'hostfs', so that line looks like this::
- /dev/ubd/0 / hostfs defaults 1 1
+ /dev/ubd/0 / hostfs defaults 1 1
Then you need to chown to yourself all the files in that directory
- that are owned by root. This worked for me:
+ that are owned by root. This worked for me::
host# find . -uid 0 -exec chown jdike {} \;
@@ -2183,7 +2153,7 @@
Next, make sure that your UML kernel has hostfs compiled in, not as a
- module. Then run UML with the boot device pointing at that directory:
+ module. Then run UML with the boot device pointing at that directory::
ubd0=/path/to/uml/root/directory
@@ -2194,41 +2164,35 @@
UML should then boot as it does normally.
- 9.3. Building hostfs
+9.3. Building hostfs
+---------------------
If you need to build hostfs because it's not in your kernel, you have
two choices:
- o Compiling hostfs into the kernel:
+ - Compiling hostfs into the kernel:
Reconfigure the kernel and set the 'Host filesystem' option under
- o Compiling hostfs as a module:
+ - Compiling hostfs as a module:
Reconfigure the kernel and set the 'Host filesystem' option under
be in arch/um/fs/hostfs/hostfs.o. Install that in
- /lib/modules/`uname -r`/fs in the virtual machine, boot it up, and
+ ``/lib/modules/$(uname -r)/fs`` in the virtual machine, boot it up, and::
UML# insmod hostfs
+.. _The_Management_Console:
-
-
-
-
-
-
-
-
-
- 10. The Management Console
+10. The Management Console
+===========================
@@ -2240,15 +2204,15 @@
There are a number of things you can do with the mconsole interface:
- o get the kernel version
+ - get the kernel version
- o add and remove devices
+ - add and remove devices
- o halt or reboot the machine
+ - halt or reboot the machine
- o Send SysRq commands
+ - Send SysRq commands
- o Pause and resume the UML
+ - Pause and resume the UML
You need the mconsole client (uml_mconsole) which is present in CVS
@@ -2257,7 +2221,7 @@
You also need CONFIG_MCONSOLE (under 'General Setup') enabled in UML.
- When you boot UML, you'll see a line like:
+ When you boot UML, you'll see a line like::
mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole
@@ -2265,7 +2229,7 @@
- If you specify a unique machine id one the UML command line, i.e.
+ If you specify a unique machine id one the UML command line, i.e.::
umid=debian
@@ -2273,7 +2237,7 @@
- you'll see this
+ you'll see this::
mconsole initialized on /home/jdike/.uml/debian/mconsole
@@ -2282,7 +2246,7 @@
That file is the socket that uml_mconsole will use to communicate with
- UML. Run it with either the umid or the full path as its argument:
+ UML. Run it with either the umid or the full path as its argument::
host% uml_mconsole debian
@@ -2290,7 +2254,7 @@
- or
+ or::
host% uml_mconsole /home/jdike/.uml/debian/mconsole
@@ -2300,30 +2264,31 @@
You'll get a prompt, at which you can run one of these commands:
- o version
+ - version
- o halt
+ - halt
- o reboot
+ - reboot
- o config
+ - config
- o remove
+ - remove
- o sysrq
+ - sysrq
- o help
+ - help
- o cad
+ - cad
- o stop
+ - stop
- o go
+ - go
- 10.1. version
+10.1. version
+--------------
- This takes no arguments. It prints the UML version.
+ This takes no arguments. It prints the UML version::
(mconsole) version
@@ -2342,11 +2307,12 @@
- 10.2. halt and reboot
+10.2. halt and reboot
+----------------------
These take no arguments. They shut the machine down immediately, with
no syncing of disks and no clean shutdown of userspace. So, they are
- pretty close to crashing the machine.
+ pretty close to crashing the machine::
(mconsole) halt
@@ -2357,34 +2323,36 @@
- 10.3. config
+10.3. config
+-------------
"config" adds a new device to the virtual machine. Currently the ubd
and network drivers support this. It takes one argument, which is the
- device to add, with the same syntax as the kernel command line.
+ device to add, with the same syntax as the kernel command line::
- (mconsole)
- config ubd3=/home/jdike/incoming/roots/root_fs_debian22
+ (mconsole)
+ config ubd3=/home/jdike/incoming/roots/root_fs_debian22
- OK
- (mconsole) config eth1=mcast
- OK
+ OK
+ (mconsole) config eth1=mcast
+ OK
- 10.4. remove
+10.4. remove
+-------------
"remove" deletes a device from the system. Its argument is just the
name of the device to be removed. The device must be idle in whatever
sense the driver considers necessary. In the case of the ubd driver,
the removed block device must not be mounted, swapped on, or otherwise
- open, and in the case of the network driver, the device must be down.
+ open, and in the case of the network driver, the device must be down::
(mconsole) remove ubd3
@@ -2397,7 +2365,8 @@
- 10.5. sysrq
+10.5. sysrq
+------------
This takes one argument, which is a single letter. It calls the
generic kernel's SysRq driver, which does whatever is called for by
@@ -2407,19 +2376,21 @@
- 10.6. help
+10.6. help
+-----------
"help" returns a string listing the valid commands and what each one
does.
- 10.7. cad
+10.7. cad
+----------
This invokes the Ctl-Alt-Del action on init. What exactly this ends
up doing is up to /etc/inittab. Normally, it reboots the machine.
With UML, this is usually not desired, so if a halt would be better,
- then find the section of inittab that looks like this
+ then find the section of inittab that looks like this::
# What to do when CTRL-ALT-DEL is pressed.
@@ -2432,7 +2403,8 @@
- 10.8. stop
+10.8. stop
+-----------
This puts the UML in a loop reading mconsole requests until a 'go'
mconsole command is received. This is very useful for making backups
@@ -2448,7 +2420,8 @@
- 10.9. go
+10.9. go
+---------
This resumes a UML after being paused by a 'stop' command. Note that
when the UML has resumed, TCP connections may have timed out and if
@@ -2460,9 +2433,10 @@
+.. _Kernel_debugging:
-
- 11. Kernel debugging
+11. Kernel debugging
+=====================
Note: The interface that makes debugging, as described here, possible
@@ -2477,15 +2451,16 @@
In order to debug the kernel, you need build it from source. See
- ``Compiling the kernel and modules'' for information on doing that.
+ :ref:`Compiling_the_kernel_and_modules` for information on doing that.
Make sure that you enable CONFIG_DEBUGSYM and CONFIG_PT_PROXY during
- the config. These will compile the kernel with -g, and enable the
+ the config. These will compile the kernel with ``-g``, and enable the
ptrace proxy so that gdb works with UML, respectively.
- 11.1. Starting the kernel under gdb
+11.1. Starting the kernel under gdb
+------------------------------------
You can have the kernel running under the control of gdb from the
beginning by putting 'debug' on the command line. You will get an
@@ -2498,7 +2473,11 @@
There is a transcript of a debugging session here <debug-
session.html> , with breakpoints being set in the scheduler and in an
interrupt handler.
- 11.2. Examining sleeping processes
+
+
+11.2. Examining sleeping processes
+-----------------------------------
+
Not every bug is evident in the currently running process. Sometimes,
processes hang in the kernel when they shouldn't because they've
@@ -2516,7 +2495,7 @@
Now what you do is this:
- o detach from the current thread
+ - detach from the current thread::
(UML gdb) det
@@ -2525,7 +2504,7 @@
- o attach to the thread you are interested in
+ - attach to the thread you are interested in::
(UML gdb) att <host pid>
@@ -2534,7 +2513,7 @@
- o look at its stack and anything else of interest
+ - look at its stack and anything else of interest::
(UML gdb) bt
@@ -2545,18 +2524,14 @@
Note that you can't do anything at this point that requires that a
process execute, e.g. calling a function
- o when you're done looking at that process, reattach to the current
- thread and continue it
+ - when you're done looking at that process, reattach to the current
+ thread and continue it::
(UML gdb)
att 1
-
-
-
-
(UML gdb)
c
@@ -2569,12 +2544,13 @@
- 11.3. Running ddd on UML
+11.3. Running ddd on UML
+-------------------------
ddd works on UML, but requires a special kludge. The process goes
like this:
- o Start ddd
+ - Start ddd::
host% ddd linux
@@ -2583,14 +2559,14 @@
- o With ps, get the pid of the gdb that ddd started. You can ask the
+ - With ps, get the pid of the gdb that ddd started. You can ask the
gdb to tell you, but for some reason that confuses things and
causes a hang.
- o run UML with 'debug=parent gdb-pid=<pid>' added to the command line
+ - run UML with 'debug=parent gdb-pid=<pid>' added to the command line
- it will just sit there after you hit return
- o type 'att 1' to the ddd gdb and you will see something like
+ - type 'att 1' to the ddd gdb and you will see something like::
0xa013dc51 in __kill ()
@@ -2602,12 +2578,14 @@
- o At this point, type 'c', UML will boot up, and you can use ddd just
+ - At this point, type 'c', UML will boot up, and you can use ddd just
as you do on any other process.
- 11.4. Debugging modules
+11.4. Debugging modules
+------------------------
+
gdb has support for debugging code which is dynamically loaded into
the process. This support is what is needed to debug kernel modules
@@ -2629,7 +2607,8 @@
First, you must tell it where your modules are. There is a list in
- the script that looks like this:
+ the script that looks like this::
+
set MODULE_PATHS {
"fat" "/usr/src/uml/linux-2.4.18/fs/fat/fat.o"
"isofs" "/usr/src/uml/linux-2.4.18/fs/isofs/isofs.o"
@@ -2641,9 +2620,7 @@
You change that to list the names and paths of the modules that you
are going to debug. Then you run it from the toplevel directory of
- your UML pool and it basically tells you what to do:
-
-
+ your UML pool and it basically tells you what to do::
******** GDB pid is 21903 ********
@@ -2666,7 +2643,7 @@
After you run UML and it sits there doing nothing, you hit return at
- the 'att 1' and continue it:
+ the 'att 1' and continue it::
Attaching to program: /home/jdike/linux/2.4/um/./linux, process 1
@@ -2678,63 +2655,48 @@
At this point, you debug normally. When you insmod something, the
- expect magic will kick in and you'll see something like:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- *** Module hostfs loaded ***
- Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
- mod_user=0x8070e00) at module.c:349
- 349 char *name, *n_name, *name_tmp = NULL;
- (UML gdb) finish
- Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
- mod_user=0x8070e00) at module.c:349
- 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
- 411 else res = EXECUTE_SYSCALL(syscall, regs);
- Value returned is $1 = 0
- (UML gdb)
- p/x (int)module_list + module_list->size_of_struct
-
- $2 = 0xa9021054
- (UML gdb) symbol-file ./linux
- Load new symbol table from "./linux"? (y or n) y
- Reading symbols from ./linux...
- done.
- (UML gdb)
- add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
-
- add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
- .text_addr = 0xa9021054
- (y or n) y
-
- Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
- done.
- (UML gdb) p *module_list
- $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
- size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
- nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
- init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
- ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
- persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
- kallsyms_end = 0x0,
- archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
- archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
- kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
- >> Finished loading symbols for hostfs ...
+ expect magic will kick in and you'll see something like::
+
+
+ *** Module hostfs loaded ***
+ Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
+ mod_user=0x8070e00) at module.c:349
+ 349 char *name, *n_name, *name_tmp = NULL;
+ (UML gdb) finish
+ Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
+ mod_user=0x8070e00) at module.c:349
+ 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
+ 411 else res = EXECUTE_SYSCALL(syscall, regs);
+ Value returned is $1 = 0
+ (UML gdb)
+ p/x (int)module_list + module_list->size_of_struct
+
+ $2 = 0xa9021054
+ (UML gdb) symbol-file ./linux
+ Load new symbol table from "./linux"? (y or n) y
+ Reading symbols from ./linux...
+ done.
+ (UML gdb)
+ add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
+
+ add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
+ .text_addr = 0xa9021054
+ (y or n) y
+
+ Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
+ done.
+ (UML gdb) p *module_list
+ $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
+ size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
+ nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
+ init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
+ ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
+ persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
+ kallsyms_end = 0x0,
+ archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
+ archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
+ kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
+ >> Finished loading symbols for hostfs ...
@@ -2744,7 +2706,7 @@
Boot the kernel under the debugger and load the module with insmod or
- modprobe. With gdb, do:
+ modprobe. With gdb, do::
(UML gdb) p module_list
@@ -2758,12 +2720,12 @@
the name fields until find the module you want to debug. Take the
address of that structure, and add module.size_of_struct (which in
2.4.10 kernels is 96 (0x60)) to it. Gdb can make this hard addition
- for you :-):
+ for you :-)::
- (UML gdb)
- printf "%#x\n", (int)module_list module_list->size_of_struct
+ (UML gdb)
+ printf "%#x\n", (int)module_list module_list->size_of_struct
@@ -2771,7 +2733,7 @@
The offset from the module start occasionally changes (before 2.4.0,
it was module.size_of_struct + 4), so it's a good idea to check the
init and cleanup addresses once in a while, as describe below. Now
- do:
+ do::
(UML gdb)
@@ -2786,7 +2748,7 @@
If there's any doubt that you got the offset right, like breakpoints
appear not to work, or they're appearing in the wrong place, you can
check it by looking at the module structure. The init and cleanup
- fields should look like:
+ fields should look like::
init = 0x588066b0 <init_hostfs>, cleanup = 0x588066c0 <exit_hostfs>
@@ -2801,7 +2763,7 @@
When you want to load in a new version of the module, you need to get
gdb to forget about the old one. The only way I've found to do that
- is to tell gdb to forget about all symbols that it knows about:
+ is to tell gdb to forget about all symbols that it knows about::
(UML gdb) symbol-file
@@ -2809,7 +2771,7 @@
- Then reload the symbols from the kernel binary:
+ Then reload the symbols from the kernel binary::
(UML gdb) symbol-file /path/to/kernel
@@ -2823,17 +2785,19 @@
- 11.5. Attaching gdb to the kernel
+11.5. Attaching gdb to the kernel
+----------------------------------
If you don't have the kernel running under gdb, you can attach gdb to
it later by sending the tracing thread a SIGUSR1. The first line of
- the console output identifies its pid:
+ the console output identifies its pid::
+
tracing thread pid = 20093
- When you send it the signal:
+ When you send it the signal::
host% kill -USR1 20093
@@ -2845,7 +2809,7 @@
If you have the mconsole compiled into UML, then the mconsole client
- can be used to start gdb:
+ can be used to start gdb::
(mconsole) (mconsole) config gdb=xterm
@@ -2857,7 +2821,8 @@
- 11.6. Using alternate debuggers
+11.6. Using alternate debuggers
+--------------------------------
UML has support for attaching to an already running debugger rather
than starting gdb itself. This is present in CVS as of 17 Apr 2001.
@@ -2886,7 +2851,7 @@
An example of an alternate debugger is strace. You can strace the
actual kernel as follows:
- o Run the following in a shell
+ - Run the following in a shell::
host%
@@ -2894,13 +2859,13 @@
- o Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
+ - Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
by the previous command
- o Hit return in the shell, and UML will start running, and strace
+ - Hit return in the shell, and UML will start running, and strace
output will start accumulating in the output file.
- Note that this is different from running
+ Note that this is different from running::
host% strace ./linux
@@ -2917,95 +2882,57 @@
- 12. Kernel debugging examples
+12. Kernel debugging examples
+==============================
- 12.1. The case of the hung fsck
+12.1. The case of the hung fsck
+--------------------------------
When booting up the kernel, fsck failed, and dropped me into a shell
- to fix things up. I ran fsck -y, which hung:
+ to fix things up. I ran fsck -y, which hung::
+ Setting hostname uml [ OK ]
+ Checking root filesystem
+ /dev/fhd0 was not cleanly unmounted, check forced.
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
+ /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
+ (i.e., without -a or -p options)
+ [ FAILED ]
+ *** An error occurred during the file system check.
+ *** Dropping you to a shell; the system will reboot
+ *** when you leave the shell.
+ Give root password for maintenance
+ (or type Control-D for normal startup):
+ [root@uml /root]# fsck -y /dev/fhd0
+ fsck -y /dev/fhd0
+ Parallelizing fsck version 1.14 (9-Jan-1999)
+ e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
+ /dev/fhd0 contains a file system with errors, check forced.
+ Pass 1: Checking inodes, blocks, and sizes
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
+ Inode 19780, i_blocks is 1548, should be 540. Fix? yes
+ Pass 2: Checking directory structure
+ Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
+ Directory inode 11858, block 0, offset 0: directory corrupted
+ Salvage? yes
+ Missing '.' in directory inode 11858.
+ Fix? yes
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Setting hostname uml [ OK ]
- Checking root filesystem
- /dev/fhd0 was not cleanly unmounted, check forced.
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
-
- /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
- (i.e., without -a or -p options)
- [ FAILED ]
-
- *** An error occurred during the file system check.
- *** Dropping you to a shell; the system will reboot
- *** when you leave the shell.
- Give root password for maintenance
- (or type Control-D for normal startup):
-
- [root@uml /root]# fsck -y /dev/fhd0
- fsck -y /dev/fhd0
- Parallelizing fsck version 1.14 (9-Jan-1999)
- e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
- /dev/fhd0 contains a file system with errors, check forced.
- Pass 1: Checking inodes, blocks, and sizes
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
-
- Inode 19780, i_blocks is 1548, should be 540. Fix? yes
-
- Pass 2: Checking directory structure
- Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
-
- Directory inode 11858, block 0, offset 0: directory corrupted
- Salvage? yes
-
- Missing '.' in directory inode 11858.
- Fix? yes
-
- Missing '..' in directory inode 11858.
- Fix? yes
-
-
-
+ Missing '..' in directory inode 11858.
+ Fix? yes
The standard drill in this sort of situation is to fire up gdb on the
signal thread, which, in this case, was pid 1935. In another window,
- I run gdb and attach pid 1935.
-
-
+ I run gdb and attach pid 1935::
~/linux/2.3.26/um 1016: gdb linux
@@ -3022,11 +2949,7 @@
0x100756d9 in __wait4 ()
-
-
-
-
- Let's see what's currently running:
+ Let's see what's currently running::
@@ -3041,7 +2964,7 @@
reason and never woke up.
- Let's guess that the last process in the process list is fsck:
+ Let's guess that the last process in the process list is fsck::
@@ -3052,7 +2975,7 @@
- It is, so let's see what it thinks it's up to:
+ It is, so let's see what it thinks it's up to::
@@ -3068,8 +2991,6 @@
-
-
The interesting things here are the fact that its .thread.syscall.id
is __NR_write (see the big switch in arch/um/kernel/syscall_kern.c or
the defines in include/asm-um/arch/unistd.h), and that it never
@@ -3081,30 +3002,20 @@
The fact that it never returned from write means that its stack should
be fairly interesting. Its pid is 1980 (.thread.extern_pid). That
process is being ptraced by the signal thread, so it must be detached
- before gdb can attach it:
+ before gdb can attach it::
+ (gdb) call detach(1980)
-
-
-
-
-
-
- (gdb) call detach(1980)
-
- Program received signal SIGSEGV, Segmentation fault.
- <function called from gdb>
- The program being debugged stopped while in a function called from GDB.
- When the function (detach) is done executing, GDB will silently
- stop (instead of continuing to evaluate the expression containing
- the function call).
- (gdb) call detach(1980)
- $15 = 0
-
-
-
+ Program received signal SIGSEGV, Segmentation fault.
+ <function called from gdb>
+ The program being debugged stopped while in a function called from GDB.
+ When the function (detach) is done executing, GDB will silently
+ stop (instead of continuing to evaluate the expression containing
+ the function call).
+ (gdb) call detach(1980)
+ $15 = 0
The first detach segfaults for some reason, and the second one
@@ -3112,7 +3023,7 @@
Now I detach from the signal thread, attach to the fsck thread, and
- look at its stack:
+ look at its stack::
(gdb) det
@@ -3152,14 +3063,14 @@
- The interesting things here are :
+ The interesting things here are:
- o There are two segfaults on this stack (frames 9 and 14)
+ - There are two segfaults on this stack (frames 9 and 14)
- o The first faulting address (frame 11) is 0x50000800
+ - The first faulting address (frame 11) is 0x50000800::
- (gdb) p (void *)1342179328
- $16 = (void *) 0x50000800
+ (gdb) p (void *)1342179328
+ $16 = (void *) 0x50000800
@@ -3175,7 +3086,7 @@
However, the more immediate problem is that second segfault and I'm
going to concentrate on that. First, I want to see where the fault
- happened, so I have to go look at the sigcontent struct in frame 8:
+ happened, so I have to go look at the sigcontent struct in frame 8::
@@ -3211,7 +3122,7 @@
- That's not very useful, so I'll try a more manual method:
+ That's not very useful, so I'll try a more manual method::
(gdb) p *((struct sigcontext *) (&sig + 1))
@@ -3224,7 +3135,7 @@
- The ip is in handle_mm_fault:
+ The ip is in handle_mm_fault::
(gdb) p (void *)268480945
@@ -3236,7 +3147,7 @@
- Specifically, it's in pte_alloc:
+ Specifically, it's in pte_alloc::
(gdb) i line *$20
@@ -3249,7 +3160,7 @@
To find where in handle_mm_fault this is, I'll jump forward in the
- code until I see an address in that procedure:
+ code until I see an address in that procedure::
@@ -3286,21 +3197,21 @@
Something is apparently wrong with the page tables or vma_structs, so
- lets go back to frame 11 and have a look at them:
+ lets go back to frame 11 and have a look at them::
- #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
- 50 handle_mm_fault(current, vma, address, is_write);
- (gdb) call pgd_offset_proc(vma->vm_mm, address)
- $22 = (pgd_t *) 0x80a548c
+ #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
+ 50 handle_mm_fault(current, vma, address, is_write);
+ (gdb) call pgd_offset_proc(vma->vm_mm, address)
+ $22 = (pgd_t *) 0x80a548c
That's pretty bogus. Page tables aren't supposed to be in process
- text or data areas. Let's see what's in the vma:
+ text or data areas. Let's see what's in the vma::
(gdb) p *vma
@@ -3325,12 +3236,9 @@
-
-
This also pretty bogus. With all of the 0x80xxxxx and 0xaffffxxx
addresses, this is looking like a stack was plonked down on top of
- these structures. Maybe it's a stack overflow from the next page:
-
+ these structures. Maybe it's a stack overflow from the next page::
(gdb) p vma
@@ -3338,52 +3246,36 @@
-
-
That's towards the lower quarter of the page, so that would have to
- have been pretty heavy stack overflow:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- (gdb) x/100x $25
- 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
- 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
- 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
- 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
- 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
- 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
- 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
-
-
+ have been pretty heavy stack overflow::
+
+
+ (gdb) x/100x $25
+ 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
+ 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
+ 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
+ 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
+ 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
+ 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
+ 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
@@ -3399,65 +3291,53 @@
on will be somewhat clearer.
- 12.2. Episode 2: The case of the hung fsck
+12.2. Episode 2: The case of the hung fsck
+-------------------------------------------
After setting a trap in the SEGV handler for accesses to the signal
thread's stack, I reran the kernel.
- fsck hung again, this time by hitting the trap:
+ fsck hung again, this time by hitting the trap::
+ Setting hostname uml [ OK ]
+ Checking root filesystem
+ /dev/fhd0 contains a file system with errors, check forced.
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
+ /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
+ (i.e., without -a or -p options)
+ [ FAILED ]
+ *** An error occurred during the file system check.
+ *** Dropping you to a shell; the system will reboot
+ *** when you leave the shell.
+ Give root password for maintenance
+ (or type Control-D for normal startup):
+ [root@uml /root]# fsck -y /dev/fhd0
+ fsck -y /dev/fhd0
+ Parallelizing fsck version 1.14 (9-Jan-1999)
+ e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
+ /dev/fhd0 contains a file system with errors, check forced.
+ Pass 1: Checking inodes, blocks, and sizes
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
+ Pass 2: Checking directory structure
+ Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
+ Directory inode 11858, block 0, offset 0: directory corrupted
+ Salvage? yes
+ Missing '.' in directory inode 11858.
+ Fix? yes
+ Missing '..' in directory inode 11858.
+ Fix? yes
-
-
-
-
-
- Setting hostname uml [ OK ]
- Checking root filesystem
- /dev/fhd0 contains a file system with errors, check forced.
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
-
- /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
- (i.e., without -a or -p options)
- [ FAILED ]
-
- *** An error occurred during the file system check.
- *** Dropping you to a shell; the system will reboot
- *** when you leave the shell.
- Give root password for maintenance
- (or type Control-D for normal startup):
-
- [root@uml /root]# fsck -y /dev/fhd0
- fsck -y /dev/fhd0
- Parallelizing fsck version 1.14 (9-Jan-1999)
- e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
- /dev/fhd0 contains a file system with errors, check forced.
- Pass 1: Checking inodes, blocks, and sizes
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
-
- Pass 2: Checking directory structure
- Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
-
- Directory inode 11858, block 0, offset 0: directory corrupted
- Salvage? yes
-
- Missing '.' in directory inode 11858.
- Fix? yes
-
- Missing '..' in directory inode 11858.
- Fix? yes
-
- Untested (4127) [100fe44c]: trap_kern.c line 31
+ Untested (4127) [100fe44c]: trap_kern.c line 31
@@ -3465,7 +3345,7 @@
I need to get the signal thread to detach from pid 4127 so that I can
attach to it with gdb. This is done by sending it a SIGUSR1, which is
- caught by the signal thread, which detaches the process:
+ caught by the signal thread, which detaches the process::
kill -USR1 4127
@@ -3474,31 +3354,20 @@
- Now I can run gdb on it:
-
-
-
-
-
-
-
-
-
-
-
-
-
- ~/linux/2.3.26/um 1034: gdb linux
- GNU gdb 4.17.0.11 with Linux support
- Copyright 1998 Free Software Foundation, Inc.
- GDB is free software, covered by the GNU General Public License, and you are
- welcome to change it and/or distribute copies of it under certain conditions.
- Type "show copying" to see the conditions.
- There is absolutely no warranty for GDB. Type "show warranty" for details.
- This GDB was configured as "i386-redhat-linux"...
- (gdb) att 4127
- Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
- 0x10075891 in __libc_nanosleep ()
+ Now I can run gdb on it::
+
+
+ ~/linux/2.3.26/um 1034: gdb linux
+ GNU gdb 4.17.0.11 with Linux support
+ Copyright 1998 Free Software Foundation, Inc.
+ GDB is free software, covered by the GNU General Public License, and you are
+ welcome to change it and/or distribute copies of it under certain conditions.
+ Type "show copying" to see the conditions.
+ There is absolutely no warranty for GDB. Type "show warranty" for details.
+ This GDB was configured as "i386-redhat-linux"...
+ (gdb) att 4127
+ Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
+ 0x10075891 in __libc_nanosleep ()
@@ -3506,7 +3375,7 @@
The backtrace shows that it was in a write and that the fault address
(address in frame 3) is 0x50000800, which is right in the middle of
- the signal thread's stack page:
+ the signal thread's stack page::
(gdb) bt
@@ -3540,58 +3409,48 @@
-
-
Going up the stack to the segv_handler frame and looking at where in
the code the access happened shows that it happened near line 110 of
- block_dev.c:
-
-
-
-
-
-
-
-
-
- (gdb) up
- #1 0x1007584d in __sleep (seconds=1000000)
- at ../sysdeps/unix/sysv/linux/sleep.c:78
- ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
- (gdb)
- #2 0x1006ce9a in stop () at user_util.c:191
- 191 while(1) sleep(1000000);
- (gdb)
- #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
- 31 KERN_UNTESTED();
- (gdb)
- #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
- 174 segv(sc->cr2, sc->err & 2);
- (gdb) p *sc
- $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
- __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
- esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
- err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
- esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
- cr2 = 1342179328}
- (gdb) p (void *)268550834
- $2 = (void *) 0x1001c2b2
- (gdb) i sym $2
- block_write + 1090 in section .text
- (gdb) i line *$2
- Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
- starts at address 0x1001c2a1 <block_write+1073>
- and ends at 0x1001c2bf <block_write+1103>.
- (gdb) i line *0x1001c2c0
- Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
- and ends at 0x1001c2e3 <block_write+1139>.
-
-
+ block_dev.c::
+
+
+
+ (gdb) up
+ #1 0x1007584d in __sleep (seconds=1000000)
+ at ../sysdeps/unix/sysv/linux/sleep.c:78
+ ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
+ (gdb)
+ #2 0x1006ce9a in stop () at user_util.c:191
+ 191 while(1) sleep(1000000);
+ (gdb)
+ #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
+ 31 KERN_UNTESTED();
+ (gdb)
+ #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
+ 174 segv(sc->cr2, sc->err & 2);
+ (gdb) p *sc
+ $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
+ __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
+ esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
+ err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
+ esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
+ cr2 = 1342179328}
+ (gdb) p (void *)268550834
+ $2 = (void *) 0x1001c2b2
+ (gdb) i sym $2
+ block_write + 1090 in section .text
+ (gdb) i line *$2
+ Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
+ starts at address 0x1001c2a1 <block_write+1073>
+ and ends at 0x1001c2bf <block_write+1103>.
+ (gdb) i line *0x1001c2c0
+ Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
+ and ends at 0x1001c2e3 <block_write+1139>.
Looking at the source shows that the fault happened during a call to
- copy_from_user to copy the data into the kernel:
+ copy_from_user to copy the data into the kernel::
107 count -= chars;
@@ -3601,10 +3460,8 @@
-
-
p is the pointer which must contain 0x50000800, since buf contains
- 0x80b8800 (frame 8 above). It is defined as:
+ 0x80b8800 (frame 8 above). It is defined as::
p = offset + bh->b_data;
@@ -3615,24 +3472,22 @@
I need to figure out what bh is, and it just so happens that bh is
passed as an argument to mark_buffer_uptodate and mark_buffer_dirty a
- few lines later, so I do a little disassembly:
+ few lines later, so I do a little disassembly::
-
-
- (gdb) disas 0x1001c2bf 0x1001c2e0
- Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
- 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
- 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
- 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
- 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
- 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
- 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
- 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
- 0x1001c2d8 <block_write+1128>: pushl $0x0
- 0x1001c2da <block_write+1130>: pushl %edx
- 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
- End of assembler dump.
+ (gdb) disas 0x1001c2bf 0x1001c2e0
+ Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
+ 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
+ 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
+ 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
+ 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
+ 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
+ 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
+ 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
+ 0x1001c2d8 <block_write+1128>: pushl $0x0
+ 0x1001c2da <block_write+1130>: pushl %edx
+ 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
+ End of assembler dump.
@@ -3640,7 +3495,7 @@
At that point, bh is in %edx (address 0x1001c2da), which is calculated
at 0x1001c2c2 as %ebp + 0xfffffdd4, so I figure exactly what that is,
- taking %ebp from the sigcontext_struct above:
+ taking %ebp from the sigcontext_struct above::
(gdb) p (void *)1342631484
@@ -3657,7 +3512,7 @@
Now, I look at the structure to see what's in it, and particularly,
- what its b_data field contains:
+ what its b_data field contains::
(gdb) p *((struct buffer_head *)0x50100200)
@@ -3682,18 +3537,18 @@
The b_page field is a pointer to the page_struct representing the
0x50000000 page. Looking at it shows the kernel's idea of the state
- of that page:
+ of that page::
- (gdb) p *$13.b_page
- $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
- index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
- next = 0x50008460, prev = 0x50019350}, wait = {
- lock = <optimized out or zero length>, task_list = {next = 0x50004024,
- prev = 0x50004024}, __magic = 1342193708, __creator = 0},
- pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
- zone = 0x100c5160}
+ (gdb) p *$13.b_page
+ $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
+ index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
+ next = 0x50008460, prev = 0x50019350}, wait = {
+ lock = <optimized out or zero length>, task_list = {next = 0x50004024,
+ prev = 0x50004024}, __magic = 1342193708, __creator = 0},
+ pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
+ zone = 0x100c5160}
@@ -3702,7 +3557,7 @@
Some sanity-checking: the virtual field shows the "virtual" address of
this page, which in this kernel is the same as its "physical" address,
and the page_struct itself should be mem_map[0], since it represents
- the first page of memory:
+ the first page of memory::
@@ -3719,7 +3574,7 @@
Now to check out the page_struct itself. In particular, the flags
- field shows whether the page is considered free or not:
+ field shows whether the page is considered free or not::
(gdb) p (void *)132
@@ -3739,7 +3594,7 @@
In my setup_arch procedure, I have the following code which looks just
- fine:
+ fine::
@@ -3762,7 +3617,7 @@
Stepping into init_bootmem, and looking at bootmem_map before looking
- at what it contains shows the following:
+ at what it contains shows the following::
@@ -3788,18 +3643,20 @@
- 13. What to do when UML doesn't work
+13. What to do when UML doesn't work
+=====================================
- 13.1. Strange compilation errors when you build from source
+13.1. Strange compilation errors when you build from source
+------------------------------------------------------------
As of test11, it is necessary to have "ARCH=um" in the environment or
on the make command line for all steps in building UML, including
clean, distclean, or mrproper, config, menuconfig, or xconfig, dep,
and linux. If you forget for any of them, the i386 build seems to
- contaminate the UML build. If this happens, start from scratch with
+ contaminate the UML build. If this happens, start from scratch with::
host%
@@ -3811,7 +3668,7 @@
and repeat the build process with ARCH=um on all the steps.
- See ``Compiling the kernel and modules'' for more details.
+ See :ref:`Compiling_the_kernel_and_modules` for more details.
Another cause of strange compilation errors is building UML in
@@ -3824,11 +3681,11 @@
- 13.3. A variety of panics and hangs with /tmp on a reiserfs filesys-
- tem
+13.3. A variety of panics and hangs with /tmp on a reiserfs filesystem
+-----------------------------------------------------------------------
I saw this on reiserfs 3.5.21 and it seems to be fixed in 3.5.27.
- Panics preceded by
+ Panics preceded by::
Detaching pid nnnn
@@ -3854,17 +3711,19 @@
- 13.5. UML doesn't work when /tmp is an NFS filesystem
+13.5. UML doesn't work when /tmp is an NFS filesystem
+------------------------------------------------------
This seems to be a similar situation with the ReiserFS problem above.
Some versions of NFS seems not to handle mmap correctly, which UML
depends on. The workaround is have /tmp be a non-NFS directory.
- 13.6. UML hangs on boot when compiled with gprof support
+13.6. UML hangs on boot when compiled with gprof support
+---------------------------------------------------------
If you build UML with gprof support and, early in the boot, it does
- this
+ this::
kernel BUG at page_alloc.c:100!
@@ -3878,10 +3737,11 @@
- 13.7. syslogd dies with a SIGTERM on startup
+13.7. syslogd dies with a SIGTERM on startup
+---------------------------------------------
The exact boot error depends on the distribution that you're booting,
- but Debian produces this:
+ but Debian produces this::
/etc/rc2.d/S10sysklogd: line 49: 93 Terminated
@@ -3897,17 +3757,18 @@
- 13.8. TUN/TAP networking doesn't work on a 2.4 host
+13.8. TUN/TAP networking doesn't work on a 2.4 host
+----------------------------------------------------
There are a couple of problems which were
<http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
out"> by Tim Robinson <timro at trkr dot net>
- o It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
+ - It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
The fix is to upgrade to something more recent and then read the
next item.
- o If you see
+ - If you see::
File descriptor in bad state
@@ -3921,8 +3782,8 @@
- 13.9. You can network to the host but not to other machines on the
- net
+13.9. You can network to the host but not to other machines on the net
+=======================================================================
If you can connect to the host, and the host can connect to UML, but
you cannot connect to any other machines, then you may need to enable
@@ -3930,7 +3791,7 @@
using private IP addresses (192.168.x.x or 10.x.x.x) for host/UML
networking, rather than the public address space that your host is
connected to. UML does not enable IP Masquerading, so you will need
- to create a static rule to enable it:
+ to create a static rule to enable it::
host%
@@ -3948,7 +3809,7 @@
If you can reach the local net, but not the outside Internet, then
- that is usually a routing problem. The UML needs a default route:
+ that is usually a routing problem. The UML needs a default route::
UML#
@@ -3972,7 +3833,8 @@
- 13.10. I have no root and I want to scream
+13.10. I have no root and I want to scream
+===========================================
Thanks to Birgit Wahlich for telling me about this strange one. It
turns out that there's a limit of six environment variables on the
@@ -3987,14 +3849,16 @@
- 13.11. UML build conflict between ptrace.h and ucontext.h
+13.11. UML build conflict between ptrace.h and ucontext.h
+==========================================================
On some older systems, /usr/include/asm/ptrace.h and
/usr/include/sys/ucontext.h define the same names. So, when they're
included together, the defines from one completely mess up the parsing
- of the other, producing errors like:
+ of the other, producing errors like::
+
/usr/include/sys/ucontext.h:47: parse error before
- `10'
+ `10`
@@ -4007,7 +3871,8 @@
- 13.12. The UML BogoMips is exactly half the host's BogoMips
+13.12. The UML BogoMips is exactly half the host's BogoMips
+------------------------------------------------------------
On i386 kernels, there are two ways of running the loop that is used
to calculate the BogoMips rating, using the TSC if it's there or using
@@ -4019,15 +3884,17 @@
- 13.13. When you run UML, it immediately segfaults
+13.13. When you run UML, it immediately segfaults
+--------------------------------------------------
If the host is configured with the 2G/2G address space split, that's
- why. See ``UML on 2G/2G hosts'' for the details on getting UML to
+ why. See ref:`UML_on_2G/2G_hosts` for the details on getting UML to
run on your host.
- 13.14. xterms appear, then immediately disappear
+13.14. xterms appear, then immediately disappear
+-------------------------------------------------
If you're running an up to date kernel with an old release of
uml_utilities, the port-helper program will not work properly, so
@@ -4039,7 +3906,8 @@
- 13.15. Any other panic, hang, or strange behavior
+13.15. Any other panic, hang, or strange behavior
+--------------------------------------------------
If you're seeing truly strange behavior, such as hangs or panics that
happen in random places, or you try running the debugger to see what's
@@ -4057,9 +3925,13 @@
it and that a fix is imminent.
- If you want to be super-helpful, read ``Diagnosing Problems'' and
+ If you want to be super-helpful, read :ref:`Diagnosing_Problems` and
follow the instructions contained therein.
- 14. Diagnosing Problems
+
+.. _Diagnosing_Problems:
+
+14. Diagnosing Problems
+========================
If you get UML to crash, hang, or otherwise misbehave, you should
@@ -4074,21 +3946,22 @@
For any diagnosis, you're going to need to build a debugging kernel.
The binaries from this site aren't debuggable. If you haven't done
- this before, read about ``Compiling the kernel and modules'' and
- ``Kernel debugging'' UML first.
+ this before, read about :ref:`Compiling_the_kernel_and_modules` and
+ :ref:`Kernel_debugging` UML first.
- 14.1. Case 1 : Normal kernel panics
+14.1. Case 1 : Normal kernel panics
+------------------------------------
The most common case is for a normal thread to panic. To debug this,
you will need to run it under the debugger (add 'debug' to the command
line). An xterm will start up with gdb running inside it. Continue
- it when it stops in start_kernel and make it crash. Now ^C gdb and
+ it when it stops in start_kernel and make it crash. Now ``^C gdb`` and
If the panic was a "Kernel mode fault", then there will be a segv
frame on the stack and I'm going to want some more information. The
- stack might look something like this:
+ stack might look something like this::
(UML gdb) backtrace
@@ -4107,7 +3980,7 @@
I'm going to want to see the symbol and line information for the value
- of ip in the segv frame. In this case, you would do the following:
+ of ip in the segv frame. In this case, you would do the following::
(UML gdb) i sym 268849158
@@ -4115,7 +3988,7 @@
- and
+ and::
(UML gdb) i line *268849158
@@ -4128,7 +4001,8 @@
to get that information from the faulting ip.
- 14.2. Case 2 : Tracing thread panics
+14.2. Case 2 : Tracing thread panics
+-------------------------------------
The less common and more painful case is when the tracing thread
panics. In this case, the kernel debugger will be useless because it
@@ -4136,7 +4010,7 @@
do is get a backtrace from the tracing thread. This is done by
figuring out what its pid is, firing up gdb, and attaching it to that
pid. You can figure out the tracing thread pid by looking at the
- first line of the console output, which will look like this:
+ first line of the console output, which will look like this::
tracing thread pid = 15851
@@ -4145,7 +4019,7 @@
or by running ps on the host and finding the line that looks like
- this:
+ this::
jdike 15851 4.5 0.4 132568 1104 pts/0 S 21:34 0:05 ./linux [(tracing thread)]
@@ -4164,7 +4038,7 @@
14.3. Case 3 : Tracing thread panics caused by other threads
However, there are cases where the misbehavior of another thread
- caused the problem. The most common panic of this type is:
+ caused the problem. The most common panic of this type is::
wait_for_stop failed to wait for <pid> to stop with <signal number>
@@ -4177,7 +4051,7 @@
debugger is defunct and without some fancy footwork, another gdb can't
attach to it. So, this is how the fancy footwork goes:
- In a shell:
+ In a shell::
host% kill -STOP pid
@@ -4185,7 +4059,7 @@
- Run gdb on the tracing thread as described in case 2 and do:
+ Run gdb on the tracing thread as described in case 2 and do::
(host gdb) call detach(pid)
@@ -4193,7 +4067,7 @@
If you get a segfault, do it again. It always works the second time.
- Detach from the tracing thread and attach to that other thread:
+ Detach from the tracing thread and attach to that other thread::
(host gdb) detach
@@ -4209,7 +4083,7 @@
If gdb hangs when attaching to that process, go back to a shell and
- do:
+ do::
host%
@@ -4218,7 +4092,7 @@
- And then get the backtrace:
+ And then get the backtrace::
(host gdb) backtrace
@@ -4227,13 +4101,14 @@
- 14.4. Case 4 : Hangs
+14.4. Case 4 : Hangs
+---------------------
Hangs seem to be fairly rare, but they sometimes happen. When a hang
happens, we need a backtrace from the offending process. Run the
kernel debugger as described in case 1 and get a backtrace. If the
current process is not the idle thread, then send in the backtrace.
- You can tell that it's the idle thread if the stack looks like this:
+ You can tell that it's the idle thread if the stack looks like this::
#0 0x100b1401 in __libc_nanosleep ()
@@ -4257,7 +4132,8 @@
- 15. Thanks
+15. Thanks
+===========
A number of people have helped this project in various ways, and this
@@ -4274,20 +4150,21 @@
bookkeeping lapses and I forget about contributions.
- 15.1. Code and Documentation
+15.1. Code and Documentation
+-----------------------------
Rusty Russell <rusty at linuxcare.com.au> -
- o wrote the HOWTO <http://user-mode-
+ - wrote the HOWTO <http://user-mode-
linux.sourceforge.net/UserModeLinux-HOWTO.html>
- o prodded me into making this project official and putting it on
+ - prodded me into making this project official and putting it on
SourceForge
- o came up with the way cool UML logo <http://user-mode-
+ - came up with the way cool UML logo <http://user-mode-
linux.sourceforge.net/uml-small.png>
- o redid the config process
+ - redid the config process
Peter Moulder <reiter at netspace.net.au> - Fixed my config and build
@@ -4296,18 +4173,18 @@
Bill Stearns <wstearns at pobox.com> -
- o HOWTO updates
+ - HOWTO updates
- o lots of bug reports
+ - lots of bug reports
- o lots of testing
+ - lots of testing
- o dedicated a box (uml.ists.dartmouth.edu) to support UML development
+ - dedicated a box (uml.ists.dartmouth.edu) to support UML development
- o wrote the mkrootfs script, which allows bootable filesystems of
+ - wrote the mkrootfs script, which allows bootable filesystems of
RPM-based distributions to be cranked out
- o cranked out a large number of filesystems with said script
+ - cranked out a large number of filesystems with said script
Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
@@ -4375,176 +4252,180 @@
David Coulson <http://davidcoulson.net> -
- o Set up the usermodelinux.org <http://usermodelinux.org> site,
+ - Set up the usermodelinux.org <http://usermodelinux.org> site,
which is a great way of keeping the UML user community on top of
UML goings-on.
- o Site documentation and updates
+ - Site documentation and updates
- o Nifty little UML management daemon UMLd
+ - Nifty little UML management daemon UMLd
<http://uml.openconsultancy.com/umld/>
- o Lots of testing and bug reports
+ - Lots of testing and bug reports
- 15.2. Flushing out bugs
+15.2. Flushing out bugs
+------------------------
- o Yuri Pudgorodsky
+ - Yuri Pudgorodsky
- o Gerald Britton
+ - Gerald Britton
- o Ian Wehrman
+ - Ian Wehrman
- o Gord Lamb
+ - Gord Lamb
- o Eugene Koontz
+ - Eugene Koontz
- o John H. Hartman
+ - John H. Hartman
- o Anders Karlsson
+ - Anders Karlsson
- o Daniel Phillips
+ - Daniel Phillips
- o John Fremlin
+ - John Fremlin
- o Rainer Burgstaller
+ - Rainer Burgstaller
- o James Stevenson
+ - James Stevenson
- o Matt Clay
+ - Matt Clay
- o Cliff Jefferies
+ - Cliff Jefferies
- o Geoff Hoff
+ - Geoff Hoff
- o Lennert Buytenhek
+ - Lennert Buytenhek
- o Al Viro
+ - Al Viro
- o Frank Klingenhoefer
+ - Frank Klingenhoefer
- o Livio Baldini Soares
+ - Livio Baldini Soares
- o Jon Burgess
+ - Jon Burgess
- o Petru Paler
+ - Petru Paler
- o Paul
+ - Paul
- o Chris Reahard
+ - Chris Reahard
- o Sverker Nilsson
+ - Sverker Nilsson
- o Gong Su
+ - Gong Su
- o johan verrept
+ - johan verrept
- o Bjorn Eriksson
+ - Bjorn Eriksson
- o Lorenzo Allegrucci
+ - Lorenzo Allegrucci
- o Muli Ben-Yehuda
+ - Muli Ben-Yehuda
- o David Mansfield
+ - David Mansfield
- o Howard Goff
+ - Howard Goff
- o Mike Anderson
+ - Mike Anderson
- o John Byrne
+ - John Byrne
- o Sapan J. Batia
+ - Sapan J. Batia
- o Iris Huang
+ - Iris Huang
- o Jan Hudec
+ - Jan Hudec
- o Voluspa
+ - Voluspa
- 15.3. Buglets and clean-ups
+15.3. Buglets and clean-ups
+----------------------------
- o Dave Zarzycki
+ - Dave Zarzycki
- o Adam Lazur
+ - Adam Lazur
- o Boria Feigin
+ - Boria Feigin
- o Brian J. Murrell
+ - Brian J. Murrell
- o JS
+ - JS
- o Roman Zippel
+ - Roman Zippel
- o Wil Cooley
+ - Wil Cooley
- o Ayelet Shemesh
+ - Ayelet Shemesh
- o Will Dyson
+ - Will Dyson
- o Sverker Nilsson
+ - Sverker Nilsson
- o dvorak
+ - dvorak
- o v.naga srinivas
+ - v.naga srinivas
- o Shlomi Fish
+ - Shlomi Fish
- o Roger Binns
+ - Roger Binns
- o johan verrept
+ - johan verrept
- o MrChuoi
+ - MrChuoi
- o Peter Cleve
+ - Peter Cleve
- o Vincent Guffens
+ - Vincent Guffens
- o Nathan Scott
+ - Nathan Scott
- o Patrick Caulfield
+ - Patrick Caulfield
- o jbearce
+ - jbearce
- o Catalin Marinas
+ - Catalin Marinas
- o Shane Spencer
+ - Shane Spencer
- o Zou Min
+ - Zou Min
- o Ryan Boder
+ - Ryan Boder
- o Lorenzo Colitti
+ - Lorenzo Colitti
- o Gwendal Grignou
+ - Gwendal Grignou
- o Andre' Breiler
+ - Andre' Breiler
- o Tsutomu Yasuda
+ - Tsutomu Yasuda
- 15.4. Case Studies
+15.4. Case Studies
+-------------------
- o Jon Wright
+ - Jon Wright
- o William McEwan
+ - William McEwan
- o Michael Richardson
+ - Michael Richardson
- 15.5. Other contributions
+15.5. Other contributions
+--------------------------
Bill Carr <Bill.Carr at compaq.com> made the Red Hat mkrootfs script
@@ -4575,15 +4456,3 @@
server jailed inside UML. It's available from the download
<http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
Filesystems section.
-
-
-
-
-
-
-
-
-
-
-
-
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 02/27] docs: virt: convert UML documentation to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Jonathan Corbet, Mauro Carvalho Chehab, Richard Weinberger,
Jeff Dike, linux-doc, linux-um, Mauro Carvalho Chehab,
Anton Ivanov
Despite being an old document, it contains lots of information
that could still be useful.
The document has a nice style with makes easy to convert to
ReST. So, let's convert it to ReST.
This patch does:
- Use proper markups for titles;
- Mark and proper indent literal blocks;
- don't use an 'o' character for lists;
- other minor changes required for the doc to be parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/index.rst | 1 +
...odeLinux-HOWTO.txt => user_mode_linux.rst} | 1703 ++++++++---------
2 files changed, 787 insertions(+), 917 deletions(-)
rename Documentation/virt/uml/{UserModeLinux-HOWTO.txt => user_mode_linux.rst} (75%)
diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst
index 062ffb527043..0a8f7fda64ad 100644
--- a/Documentation/virt/index.rst
+++ b/Documentation/virt/index.rst
@@ -8,6 +8,7 @@ Linux Virtualization Support
:maxdepth: 2
kvm/index
+ uml/user_mode_linux
paravirt_ops
.. only:: html and subproject
diff --git a/Documentation/virt/uml/UserModeLinux-HOWTO.txt b/Documentation/virt/uml/user_mode_linux.rst
similarity index 75%
rename from Documentation/virt/uml/UserModeLinux-HOWTO.txt
rename to Documentation/virt/uml/user_mode_linux.rst
index 87b80f589e1c..98922008be23 100644
--- a/Documentation/virt/uml/UserModeLinux-HOWTO.txt
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -1,12 +1,15 @@
- User Mode Linux HOWTO
- User Mode Linux Core Team
- Mon Nov 18 14:16:16 EST 2002
+=====================
+User Mode Linux HOWTO
+=====================
- This document describes the use and abuse of Jeff Dike's User Mode
- Linux: a port of the Linux kernel as a normal Intel Linux process.
- ______________________________________________________________________
+:Author: User Mode Linux Core Team
+:Last-updated: Mon Nov 18 14:16:16 EST 2002
- Table of Contents
+This document describes the use and abuse of Jeff Dike's User Mode
+Linux: a port of the Linux kernel as a normal Intel Linux process.
+
+
+.. Table of Contents
1. Introduction
@@ -132,19 +135,19 @@
15.5 Other contributions
- ______________________________________________________________________
-
- 1. Introduction
+1. Introduction
+================
Welcome to User Mode Linux. It's going to be fun.
- 1.1. How is User Mode Linux Different?
+1.1. How is User Mode Linux Different?
+---------------------------------------
Normally, the Linux Kernel talks straight to your hardware (video
card, keyboard, hard drives, etc), and any programs which run ask the
- kernel to operate the hardware, like so:
+ kernel to operate the hardware, like so::
@@ -160,10 +163,10 @@
The User Mode Linux Kernel is different; instead of talking to the
- hardware, it talks to a `real' Linux kernel (called the `host kernel'
+ hardware, it talks to a `real` Linux kernel (called the `host kernel`
from now on), like any other program. Programs can then run inside
User-Mode Linux as if they were running under a normal kernel, like
- so:
+ so::
@@ -181,7 +184,8 @@
- 1.2. Why Would I Want User Mode Linux?
+1.2. Why Would I Want User Mode Linux?
+---------------------------------------
1. If User Mode Linux crashes, your host kernel is still fine.
@@ -204,14 +208,16 @@
+.. _Compiling_the_kernel_and_modules:
+2. Compiling the kernel and modules
+====================================
- 2. Compiling the kernel and modules
-
- 2.1. Compiling the kernel
+2.1. Compiling the kernel
+--------------------------
Compiling the user mode kernel is just like compiling any other
@@ -220,7 +226,6 @@
1. Download the latest UML patch from
-
the download page <http://user-mode-linux.sourceforge.net/
In this example, the file is uml-patch-2.4.0-prerelease.bz2.
@@ -230,57 +235,33 @@
such as:
ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
- <ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2>
- .
-
-
- 3. Make a directory and unpack the kernel into it.
+ 3. Make a directory and unpack the kernel into it::
host%
mkdir ~/uml
-
-
-
-
-
host%
cd ~/uml
-
-
-
-
-
host%
tar -xzvf linux-2.4.0-prerelease.tar.bz2
-
-
-
- 4. Apply the patch using
-
-
+ 4. Apply the patch using::
host%
cd ~/uml/linux
-
-
host%
bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
-
-
-
- 5. Run your favorite config; `make xconfig ARCH=um' is the most
- convenient. `make config ARCH=um' and 'make menuconfig ARCH=um'
+ 5. Run your favorite config; ``make xconfig ARCH=um`` is the most
+ convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um``
will work as well. The defaults will give you a useful kernel. If
you want to change something, go ahead, it probably won't hurt
anything.
@@ -288,13 +269,13 @@
Note: If the host is configured with a 2G/2G address space split
rather than the usual 3G/1G split, then the packaged UML binaries
- will not run. They will immediately segfault. See ``UML on 2G/2G
- hosts'' for the scoop on running UML on your system.
+ will not run. They will immediately segfault. See
+ :ref:`UML_on_2G/2G_hosts` for the scoop on running UML on your system.
- 6. Finish with `make linux ARCH=um': the result is a file called
- `linux' in the top directory of your source tree.
+ 6. Finish with ``make linux ARCH=um``: the result is a file called
+ ``linux`` in the top directory of your source tree.
Make sure that you don't build this kernel in /usr/src/linux. On some
distributions, /usr/include/asm is a link into this pool. The user-
@@ -310,7 +291,7 @@
corresponding directory in the appropriate kernel pool.
If you don't have the latest kernel pool, you can get the
- corresponding user-mode sources with
+ corresponding user-mode sources with::
host% cvs co -r v_2_3_x linux
@@ -322,10 +303,11 @@
bug fixes and enhancements that have gone into subsequent releases.
- 2.2. Compiling and installing kernel modules
+2.2. Compiling and installing kernel modules
+---------------------------------------------
UML modules are built in the same way as the native kernel (with the
- exception of the 'ARCH=um' that you always need for UML):
+ exception of the 'ARCH=um' that you always need for UML)::
host% make modules ARCH=um
@@ -337,12 +319,12 @@
the user-mode pool. Modules from the native kernel won't work.
You can install them by using ftp or something to copy them into the
- virtual machine and dropping them into /lib/modules/`uname -r`.
+ virtual machine and dropping them into ``/lib/modules/$(uname -r)``.
You can also get the kernel build process to install them as follows:
1. with the kernel not booted, mount the root filesystem in the top
- level of the kernel pool:
+ level of the kernel pool::
host% mount root_fs mnt -o loop
@@ -352,7 +334,7 @@
- 2. run
+ 2. run::
host%
@@ -363,7 +345,7 @@
- 3. unmount the filesystem
+ 3. unmount the filesystem::
host% umount mnt
@@ -386,22 +368,23 @@
- 2.3. Compiling and installing uml_utilities
+2.3. Compiling and installing uml_utilities
+--------------------------------------------
Many features of the UML kernel require a user-space helper program,
so a uml_utilities package is distributed separately from the kernel
patch which provides these helpers. Included within this is:
- o port-helper - Used by consoles which connect to xterms or ports
+ - port-helper - Used by consoles which connect to xterms or ports
- o tunctl - Configuration tool to create and delete tap devices
+ - tunctl - Configuration tool to create and delete tap devices
- o uml_net - Setuid binary for automatic tap device configuration
+ - uml_net - Setuid binary for automatic tap device configuration
- o uml_switch - User-space virtual switch required for daemon
+ - uml_switch - User-space virtual switch required for daemon
transport
- The uml_utilities tree is compiled with:
+ The uml_utilities tree is compiled with::
host#
@@ -423,19 +406,21 @@
- 3. Running UML and logging in
+3. Running UML and logging in
+==============================
- 3.1. Running UML
+3.1. Running UML
+-----------------
It runs on 2.2.15 or later, and all 2.4 kernels.
Booting UML is straightforward. Simply run 'linux': it will try to
- mount the file `root_fs' in the current directory. You do not need to
- run it as root. If your root filesystem is not named `root_fs', then
- you need to put a `ubd0=root_fs_whatever' switch on the linux command
+ mount the file ``root_fs`` in the current directory. You do not need to
+ run it as root. If your root filesystem is not named ``root_fs``, then
+ you need to put a ``ubd0=root_fs_whatever`` switch on the linux command
line.
@@ -447,14 +432,16 @@
The kernel will boot up and present you with a login prompt.
- Note: If the host is configured with a 2G/2G address space split
+Note:
+ If the host is configured with a 2G/2G address space split
rather than the usual 3G/1G split, then the packaged UML binaries will
- not run. They will immediately segfault. See ``UML on 2G/2G hosts''
+ not run. They will immediately segfault. See :ref:`UML_on_2G/2G_hosts`
for the scoop on running UML on your system.
- 3.2. Logging in
+3.2. Logging in
+----------------
@@ -468,22 +455,22 @@
There are a couple of other ways to log in:
- o On a virtual console
+ - On a virtual console
Each virtual console that is configured (i.e. the device exists in
/dev and /etc/inittab runs a getty on it) will come up in its own
- xterm. If you get tired of the xterms, read ``Setting up serial
- lines and consoles'' to see how to attach the consoles to
- something else, like host ptys.
+ xterm. If you get tired of the xterms, read
+ :ref:`setting_up_serial_lines_and_consoles` to see how to attach
+ the consoles to something else, like host ptys.
- o Over the serial line
+ - Over the serial line
- In the boot output, find a line that looks like:
+ In the boot output, find a line that looks like::
@@ -493,7 +480,7 @@
Attach your favorite terminal program to the corresponding tty. I.e.
- for minicom, the command would be
+ for minicom, the command would be::
host% minicom -o -p /dev/ttyp1
@@ -503,37 +490,41 @@
- o Over the net
+ - Over the net
If the network is running, then you can telnet to the virtual
- machine and log in to it. See ``Setting up the network'' to learn
+ machine and log in to it. See :ref:`Setting_up_the_network` to learn
about setting up a virtual network.
When you're done using it, run halt, and the kernel will bring itself
down and the process will exit.
- 3.3. Examples
+3.3. Examples
+--------------
Here are some examples of UML in action:
- o A login session <http://user-mode-linux.sourceforge.net/login.html>
+ - A login session <http://user-mode-linux.sourceforge.net/login.html>
- o A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+ - A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+.. _UML_on_2G/2G_hosts:
- 4. UML on 2G/2G hosts
+4. UML on 2G/2G hosts
+======================
- 4.1. Introduction
+4.1. Introduction
+------------------
Most Linux machines are configured so that the kernel occupies the
@@ -546,7 +537,8 @@
- 4.2. The problem
+4.2. The problem
+-----------------
The prebuilt UML binaries on this site will not run on 2G/2G hosts
@@ -558,13 +550,14 @@
- 4.3. The solution
+4.3. The solution
+------------------
The fix for this is to rebuild UML from source after enabling
CONFIG_HOST_2G_2G (under 'General Setup'). This will cause UML to
load itself in the top .5G of that smaller process address space,
- where it will run fine. See ``Compiling the kernel and modules'' if
+ where it will run fine. See :ref:`Compiling_the_kernel_and_modules` if
you need help building UML from source.
@@ -573,10 +566,11 @@
+.. _setting_up_serial_lines_and_consoles:
-
- 5. Setting up serial lines and consoles
+5. Setting up serial lines and consoles
+========================================
It is possible to attach UML serial lines and consoles to many types
@@ -584,22 +578,23 @@
You can attach them to host ptys, ttys, file descriptors, and ports.
- This allows you to do things like
+ This allows you to do things like:
- o have a UML console appear on an unused host console,
+ - have a UML console appear on an unused host console,
- o hook two virtual machines together by having one attach to a pty
+ - hook two virtual machines together by having one attach to a pty
and having the other attach to the corresponding tty
- o make a virtual machine accessible from the net by attaching a
+ - make a virtual machine accessible from the net by attaching a
console to a port on the host.
- The general format of the command line option is device=channel.
+ The general format of the command line option is ``device=channel``.
- 5.1. Specifying the device
+5.1. Specifying the device
+---------------------------
Devices are specified with "con" or "ssl" (console or serial line,
respectively), optionally with a device number if you are talking
@@ -613,7 +608,7 @@
A specific device name will override a less general "con=" or "ssl=".
So, for example, you can assign a pty to each of the serial lines
- except for the first two like this:
+ except for the first two like this::
ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1
@@ -626,13 +621,14 @@
- 5.2. Specifying the channel
+5.2. Specifying the channel
+----------------------------
There are a number of different types of channels to attach a UML
device to, each with a different way of specifying exactly what to
attach to.
- o pseudo-terminals - device=pty pts terminals - device=pts
+ - pseudo-terminals - device=pty pts terminals - device=pts
This will cause UML to allocate a free host pseudo-terminal for the
@@ -640,23 +636,23 @@
log. You access it by attaching a terminal program to the
corresponding tty:
- o screen /dev/pts/n
+ - screen /dev/pts/n
- o screen /dev/ttyxx
+ - screen /dev/ttyxx
- o minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
+ - minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
devices
- o kermit - start it up, 'open' the device, then 'connect'
+ - kermit - start it up, 'open' the device, then 'connect'
- o terminals - device=tty:tty device file
+ - terminals - device=tty:tty device file
- This will make UML attach the device to the specified tty (i.e
+ This will make UML attach the device to the specified tty (i.e::
con1=tty:/dev/tty3
@@ -672,7 +668,7 @@
- o xterms - device=xterm
+ - xterms - device=xterm
UML will run an xterm and the device will be attached to it.
@@ -681,12 +677,12 @@
- o Port - device=port:port number
+ - Port - device=port:port number
This will attach the UML devices to the specified host port.
Attaching console 1 to the host's port 9000 would be done like
- this:
+ this::
con1=port:9000
@@ -694,7 +690,7 @@
- Attaching all the serial lines to that port would be done similarly:
+ Attaching all the serial lines to that port would be done similarly::
ssl=port:9000
@@ -702,8 +698,8 @@
- You access these devices by telnetting to that port. Each active tel-
- net session gets a different device. If there are more telnets to a
+ You access these devices by telnetting to that port. Each active
+ telnet session gets a different device. If there are more telnets to a
port than UML devices attached to it, then the extra telnet sessions
will block until an existing telnet detaches, or until another device
becomes active (i.e. by being activated in /etc/inittab).
@@ -725,13 +721,13 @@
- o already-existing file descriptors - device=file descriptor
+ - already-existing file descriptors - device=file descriptor
If you set up a file descriptor on the UML command line, you can
attach a UML device to it. This is most commonly used to put the
main console back on stdin and stdout after assigning all the other
- consoles to something else:
+ consoles to something else::
con0=fd:0,fd:1 con=pts
@@ -743,7 +739,7 @@
- o Nothing - device=null
+ - Nothing - device=null
This allows the device to be opened, in contrast to 'none', but
@@ -754,7 +750,7 @@
- o None - device=none
+ - None - device=none
This causes the device to disappear.
@@ -762,7 +758,7 @@
You can also specify different input and output channels for a device
- by putting a comma between them:
+ by putting a comma between them::
ssl3=tty:/dev/tty2,xterm
@@ -785,14 +781,15 @@
- 5.3. Examples
+5.3. Examples
+--------------
There are a number of interesting things you can do with this
capability.
First, this is how you get rid of those bleeding console xterms by
- attaching them to host ptys:
+ attaching them to host ptys::
con=pty con0=fd:0,fd:1
@@ -802,7 +799,7 @@
This will make a UML console take over an unused host virtual console,
so that when you switch to it, you will see the UML login prompt
- rather than the host login prompt:
+ rather than the host login prompt::
con1=tty:/dev/tty6
@@ -813,7 +810,7 @@
You can attach two virtual machines together with what amounts to a
serial line as follows:
- Run one UML with a serial line attached to a pty -
+ Run one UML with a serial line attached to a pty::
ssl1=pty
@@ -825,7 +822,7 @@
that it got /dev/ptyp1).
Boot the other UML with a serial line attached to the corresponding
- tty -
+ tty::
ssl1=tty:/dev/ttyp1
@@ -838,7 +835,10 @@
prompt of the other virtual machine.
- 6. Setting up the network
+.. _setting_up_the_network:
+
+6. Setting up the network
+==========================
@@ -858,19 +858,19 @@
There are currently five transport types available for a UML virtual
machine to exchange packets with other hosts:
- o ethertap
+ - ethertap
- o TUN/TAP
+ - TUN/TAP
- o Multicast
+ - Multicast
- o a switch daemon
+ - a switch daemon
- o slip
+ - slip
- o slirp
+ - slirp
- o pcap
+ - pcap
The TUN/TAP, ethertap, slip, and slirp transports allow a UML
instance to exchange packets with the host. They may be directed
@@ -893,28 +893,28 @@
With so many host transports, which one should you use? Here's when
you should use each one:
- o ethertap - if you want access to the host networking and it is
+ - ethertap - if you want access to the host networking and it is
running 2.2
- o TUN/TAP - if you want access to the host networking and it is
+ - TUN/TAP - if you want access to the host networking and it is
running 2.4. Also, the TUN/TAP transport is able to use a
preconfigured device, allowing it to avoid using the setuid uml_net
helper, which is a security advantage.
- o Multicast - if you want a purely virtual network and you don't want
+ - Multicast - if you want a purely virtual network and you don't want
to set up anything but the UML
- o a switch daemon - if you want a purely virtual network and you
+ - a switch daemon - if you want a purely virtual network and you
don't mind running the daemon in order to get somewhat better
performance
- o slip - there is no particular reason to run the slip backend unless
+ - slip - there is no particular reason to run the slip backend unless
ethertap and TUN/TAP are just not available for some reason
- o slirp - if you don't have root access on the host to setup
+ - slirp - if you don't have root access on the host to setup
networking, or if you don't want to allocate an IP to your UML
- o pcap - not much use for actual network connectivity, but great for
+ - pcap - not much use for actual network connectivity, but great for
monitoring traffic on the host
Ethertap is available on 2.4 and works fine. TUN/TAP is preferred
@@ -926,7 +926,8 @@
exploit the helper's root privileges.
- 6.1. General setup
+6.1. General setup
+-------------------
First, you must have the virtual network enabled in your UML. If are
running a prebuilt kernel from this site, everything is already
@@ -938,7 +939,7 @@
The next step is to provide a network device to the virtual machine.
This is done by describing it on the kernel command line.
- The general format is
+ The general format is::
eth <n> = <transport> , <transport args>
@@ -947,7 +948,7 @@
For example, a virtual ethernet device may be attached to a host
- ethertap device as follows:
+ ethertap device as follows::
eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
@@ -978,7 +979,7 @@
You can also add devices to a UML and remove them at runtime. See the
- ``The Management Console'' page for details.
+ :ref:`The_Management_Console` page for details.
The sections below describe this in more detail.
@@ -995,7 +996,8 @@
- 6.2. Userspace daemons
+6.2. Userspace daemons
+-----------------------
You will likely need the setuid helper, or the switch daemon, or both.
They are both installed with the RPM and deb, so if you've installed
@@ -1011,7 +1013,8 @@
- 6.3. Specifying ethernet addresses
+6.3. Specifying ethernet addresses
+-----------------------------------
Below, you will see that the TUN/TAP, ethertap, and daemon interfaces
allow you to specify hardware addresses for the virtual ethernet
@@ -1023,21 +1026,21 @@
sufficient to guarantee a unique hardware address for the device. A
couple of exceptions are:
- o Another set of virtual ethernet devices are on the same network and
+ - Another set of virtual ethernet devices are on the same network and
they are assigned hardware addresses using a different scheme which
may conflict with the UML IP address-based scheme
- o You aren't going to use the device for IP networking, so you don't
+ - You aren't going to use the device for IP networking, so you don't
assign the device an IP address
If you let the driver provide the hardware address, you should make
sure that the device IP address is known before the interface is
- brought up. So, inside UML, this will guarantee that:
+ brought up. So, inside UML, this will guarantee that::
- UML#
- ifconfig eth0 192.168.0.250 up
+ UML#
+ ifconfig eth0 192.168.0.250 up
@@ -1049,13 +1052,14 @@
- 6.4. UML interface setup
+6.4. UML interface setup
+-------------------------
Once the network devices have been described on the command line, you
should boot UML and log in.
- The first thing to do is bring the interface up:
+ The first thing to do is bring the interface up::
UML# ifconfig ethn ip-address up
@@ -1067,7 +1071,7 @@
To reach the rest of the world, you should set a default route to the
- host:
+ host::
UML# route add default gw host ip
@@ -1075,7 +1079,7 @@
- Again, with host ip of 192.168.0.4:
+ Again, with host ip of 192.168.0.4::
UML# route add default gw 192.168.0.4
@@ -1097,29 +1101,25 @@
Note: If you can't communicate with other hosts on your physical
ethernet, it's probably because of a network route that's
automatically set up. If you run 'route -n' and see a route that
- looks like this:
+ looks like this::
- Destination Gateway Genmask Flags Metric Ref Use Iface
- 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
+ Destination Gateway Genmask Flags Metric Ref Use Iface
+ 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
with a mask that's not 255.255.255.255, then replace it with a route
- to your host:
+ to your host::
UML#
route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0
-
-
-
-
UML#
route add -host 192.168.0.4 dev eth0
@@ -1131,7 +1131,8 @@
- 6.5. Multicast
+6.5. Multicast
+---------------
The simplest way to set up a virtual network between multiple UMLs is
to use the mcast transport. This was written by Harald Welte and is
@@ -1142,7 +1143,7 @@
messages when you bring the device up inside UML.
- To use it, run two UMLs with
+ To use it, run two UMLs with::
eth0=mcast
@@ -1151,16 +1152,12 @@
on their command lines. Log in, configure the ethernet device in each
- machine with different IP addresses:
+ machine with different IP addresses::
UML1# ifconfig eth0 192.168.0.254
-
-
-
-
UML2# ifconfig eth0 192.168.0.253
@@ -1168,7 +1165,7 @@
and they should be able to talk to each other.
- The full set of command line options for this transport are
+ The full set of command line options for this transport are::
@@ -1186,7 +1183,7 @@
This is useful when your network does not support multicast, and
all network connections are simple point to point links.
- The full set of command line options for this transport are
+ The full set of command line options for this transport are::
ethn=ucast,ethernet address,remote address,listen port,remote port
@@ -1194,7 +1191,8 @@
- 6.6. TUN/TAP with the uml_net helper
+6.6. TUN/TAP with the uml_net helper
+-------------------------------------
TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the
host. The TUN/TAP backend has been in UML since 2.4.9-3um.
@@ -1216,7 +1214,7 @@
kernel or as the tun.o module.
The format of the command line switch to attach a device to a TUN/TAP
- device is
+ device is::
eth <n> =tuntap,,, <IP address>
@@ -1226,7 +1224,7 @@
For example, this argument will attach the UML's eth0 to the next
available tap device and assign an ethernet address to it based on its
- IP address
+ IP address::
eth0=tuntap,,,192.168.0.254
@@ -1247,10 +1245,10 @@
There are a couple potential problems with running the TUN/TAP
transport on a 2.4 host kernel
- o TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
+ - TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
kernel or use the ethertap transport.
- o With an upgraded kernel, TUN/TAP may fail with
+ - With an upgraded kernel, TUN/TAP may fail with::
File descriptor in bad state
@@ -1264,12 +1262,12 @@
kernel.
These were pointed out by Tim Robinson <timro at trkr dot net> in
- <http://www.geocrawler.com/> name="this uml-
- user post"> .
+ <http://www.geocrawler.com/> name="this uml-user post"> .
- 6.7. TUN/TAP with a preconfigured tap device
+6.7. TUN/TAP with a preconfigured tap device
+---------------------------------------------
If you prefer not to have UML use uml_net (which is somewhat
insecure), with UML 2.4.17-11, you can set up a TUN/TAP device
@@ -1277,8 +1275,8 @@
there is no need for root assistance. Setting up the device is done
as follows:
- o Create the device with tunctl (available from the UML utilities
- tarball)
+ - Create the device with tunctl (available from the UML utilities
+ tarball)::
@@ -1291,8 +1289,8 @@
where uid is the user id or username that UML will be run as. This
will tell you what device was created.
- o Configure the device IP (change IP addresses and device name to
- suit)
+ - Configure the device IP (change IP addresses and device name to
+ suit)::
@@ -1303,8 +1301,8 @@
- o Set up routing and arping if desired - this is my recipe, there are
- other ways of doing the same thing
+ - Set up routing and arping if desired - this is my recipe, there are
+ other ways of doing the same thing::
host#
@@ -1313,19 +1311,9 @@
host#
route add -host 192.168.0.253 dev tap0
-
-
-
-
-
host#
bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
-
-
-
-
-
host#
arp -Ds 192.168.0.253 eth0 pub
@@ -1338,76 +1326,43 @@
utility which reads the information from a config file and sets up
devices at boot time.
- o Rather than using up two IPs and ARPing for one of them, you can
+ - Rather than using up two IPs and ARPing for one of them, you can
also provide direct access to your LAN by the UML by using a
- bridge.
+ bridge::
host#
brctl addbr br0
-
-
-
-
host#
ifconfig eth0 0.0.0.0 promisc up
-
-
-
-
host#
ifconfig tap0 0.0.0.0 promisc up
-
-
-
-
host#
ifconfig br0 192.168.0.1 netmask 255.255.255.0 up
-
-
-
-
-
- host#
- brctl stp br0 off
-
-
-
-
+ host#
+ brctl stp br0 off
host#
brctl setfd br0 1
-
-
-
-
host#
brctl sethello br0 1
-
-
-
-
host#
brctl addif br0 eth0
-
-
-
-
host#
brctl addif br0 tap0
@@ -1417,12 +1372,12 @@
Note that 'br0' should be setup using ifconfig with the existing IP
address of eth0, as eth0 no longer has its own IP.
- o
+ -
Also, the /dev/net/tun device must be writable by the user running
UML in order for the UML to use the device that's been configured
- for it. The simplest thing to do is
+ for it. The simplest thing to do is::
host# chmod 666 /dev/net/tun
@@ -1438,14 +1393,14 @@
devices and chgrp /dev/net/tun to that group with mode 664 or 660.
- o Once the device is set up, run UML with 'eth0=tuntap,device name'
+ - Once the device is set up, run UML with 'eth0=tuntap,device name'
(i.e. 'eth0=tuntap,tap0') on the command line (or do it with the
mconsole config command).
- o Bring the eth device up in UML and you're in business.
+ - Bring the eth device up in UML and you're in business.
If you don't want that tap device any more, you can make it non-
- persistent with
+ persistent with::
host# tunctl -d tap device
@@ -1455,7 +1410,7 @@
Finally, tunctl has a -b (for brief mode) switch which causes it to
output only the name of the tap device it created. This makes it
- suitable for capture by a script:
+ suitable for capture by a script::
host# TAP=`tunctl -u 1000 -b`
@@ -1465,7 +1420,8 @@
- 6.8. Ethertap
+6.8. Ethertap
+--------------
Ethertap is the general mechanism on 2.2 for userspace processes to
exchange packets with the kernel.
@@ -1473,7 +1429,7 @@
To use this transport, you need to describe the virtual network device
- on the UML command line. The general format for this is
+ on the UML command line. The general format for this is::
eth <n> =ethertap, <device> , <ethernet address> , <tap IP address>
@@ -1481,7 +1437,7 @@
- So, the previous example
+ So, the previous example::
eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
@@ -1521,7 +1477,7 @@
If you want to set things up yourself, you need to make sure that the
appropriate /dev entry exists. If it doesn't, become root and create
- it as follows:
+ it as follows::
mknod /dev/tap <minor> c 36 <minor> + 16
@@ -1529,7 +1485,7 @@
- For example, this is how to create /dev/tap0:
+ For example, this is how to create /dev/tap0::
mknod /dev/tap0 c 36 0 + 16
@@ -1539,7 +1495,7 @@
You also need to make sure that the host kernel has ethertap support.
If ethertap is enabled as a module, you apparently need to insmod
- ethertap once for each ethertap device you want to enable. So,
+ ethertap once for each ethertap device you want to enable. So,::
host#
@@ -1549,7 +1505,7 @@
will give you the tap0 interface. To get the tap1 interface, you need
- to run
+ to run::
host#
@@ -1561,7 +1517,8 @@
- 6.9. The switch daemon
+6.9. The switch daemon
+-----------------------
Note: This is the daemon formerly known as uml_router, but which was
renamed so the network weenies of the world would stop growling at me.
@@ -1577,7 +1534,7 @@
sockets.
- If you want it to listen on a different pair of sockets, use
+ If you want it to listen on a different pair of sockets, use::
-unix control socket data socket
@@ -1586,7 +1543,7 @@
- If you want it to act as a hub rather than a switch, use
+ If you want it to act as a hub rather than a switch, use::
-hub
@@ -1596,7 +1553,7 @@
If you want the switch to be connected to host networking (allowing
- the umls to get access to the outside world through the host), use
+ the umls to get access to the outside world through the host), use::
-tap tap0
@@ -1610,7 +1567,7 @@
device than tap0, specify that instead of tap0.
- uml_switch can be backgrounded as follows
+ uml_switch can be backgrounded as follows::
host%
@@ -1623,7 +1580,7 @@
stdin for EOF. When it sees that, it exits.
- The general format of the kernel command line switch is
+ The general format of the kernel command line switch is::
@@ -1639,7 +1596,8 @@
how to communicate with the daemon. You should only specify them if
you told the daemon to use different sockets than the default. So, if
you ran the daemon with no arguments, running the UML on the same
- machine with
+ machine with::
+
eth0=daemon
@@ -1649,7 +1607,8 @@
- 6.10. Slip
+6.10. Slip
+-----------
Slip is another, less general, mechanism for a process to communicate
with the host networking. In contrast to the ethertap interface,
@@ -1658,7 +1617,7 @@
IP.
- The general format of the command line switch is
+ The general format of the command line switch is::
@@ -1681,7 +1640,8 @@
- 6.11. Slirp
+6.11. Slirp
+------------
slirp uses an external program, usually /usr/bin/slirp, to provide IP
only networking connectivity through the host. This is similar to IP
@@ -1691,7 +1651,7 @@
root access or setuid binaries on the host.
- The general format of the command line switch for slirp is:
+ The general format of the command line switch for slirp is::
@@ -1716,7 +1676,7 @@
The eth0 interface on UML should be set up with the IP 10.2.0.15,
although you can use anything as long as it is not used by a network
you will be connecting to. The default route on UML should be set to
- use
+ use::
UML#
@@ -1737,10 +1697,11 @@
- 6.12. pcap
+6.12. pcap
+-----------
The pcap transport is attached to a UML ethernet device on the command
- line or with uml_mconsole with the following syntax:
+ line or with uml_mconsole with the following syntax::
@@ -1762,7 +1723,7 @@
expression optimizer is used.
- Example:
+ Example::
@@ -1777,7 +1738,8 @@
- 6.13. Setting up the host yourself
+6.13. Setting up the host yourself
+-----------------------------------
If you don't specify an address for the host side of the ethertap or
slip device, UML won't do any setup on the host. So this is what is
@@ -1785,19 +1747,15 @@
192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your
own network):
- o The device needs to be configured with its IP address. Tap devices
+ - The device needs to be configured with its IP address. Tap devices
are also configured with an mtu of 1484. Slip devices are
configured with a point-to-point address pointing at the UML ip
- address.
+ address::
host# ifconfig tap0 arp mtu 1484 192.168.0.251 up
-
-
-
-
host#
ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up
@@ -1805,7 +1763,7 @@
- o If a tap device is being set up, a route is set to the UML IP.
+ - If a tap device is being set up, a route is set to the UML IP::
UML# route add -host 192.168.0.250 gw 192.168.0.251
@@ -1814,8 +1772,8 @@
- o To allow other hosts on your network to see the virtual machine,
- proxy arp is set up for it.
+ - To allow other hosts on your network to see the virtual machine,
+ proxy arp is set up for it::
host# arp -Ds 192.168.0.250 eth0 pub
@@ -1824,7 +1782,7 @@
- o Finally, the host is set up to route packets.
+ - Finally, the host is set up to route packets::
host# echo 1 > /proc/sys/net/ipv4/ip_forward
@@ -1838,12 +1796,14 @@
- 7. Sharing Filesystems between Virtual Machines
+7. Sharing Filesystems between Virtual Machines
+================================================
- 7.1. A warning
+7.1. A warning
+---------------
Don't attempt to share filesystems simply by booting two UMLs from the
same file. That's the same thing as booting two physical machines
@@ -1851,7 +1811,8 @@
- 7.2. Using layered block devices
+7.2. Using layered block devices
+---------------------------------
The way to share a filesystem between two virtual machines is to use
the copy-on-write (COW) layering capability of the ubd block driver.
@@ -1872,7 +1833,7 @@
To add a copy-on-write layer to an existing block device file, simply
- add the name of the COW file to the appropriate ubd switch:
+ add the name of the COW file to the appropriate ubd switch::
ubd0=root_fs_cow,root_fs_debian_22
@@ -1883,7 +1844,7 @@
where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is
the existing shared filesystem. The COW file need not exist. If it
doesn't, the driver will create and initialize it. Once the COW file
- has been initialized, it can be used on its own on the command line:
+ has been initialized, it can be used on its own on the command line::
ubd0=root_fs_cow
@@ -1896,14 +1857,16 @@
- 7.3. Note!
+7.3. Note!
+-----------
When checking the size of the COW file in order to see the gobs of
space that you're saving, make sure you use 'ls -ls' to see the actual
disk consumption rather than the length of the file. The COW file is
sparse, so the length will be very different from the disk usage.
Here is a 'ls -l' of a COW file and backing file from one boot and
- shutdown:
+ shutdown::
+
host% ls -l cow.debian debian2.2
-rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
-rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
@@ -1911,7 +1874,7 @@
- Doesn't look like much saved space, does it? Well, here's 'ls -ls':
+ Doesn't look like much saved space, does it? Well, here's 'ls -ls'::
host% ls -ls cow.debian debian2.2
@@ -1926,7 +1889,8 @@
- 7.4. Another warning
+7.4. Another warning
+---------------------
Once a filesystem is being used as a readonly backing file for a COW
file, do not boot directly from it or modify it in any way. Doing so
@@ -1952,7 +1916,8 @@
- 7.5. uml_moo : Merging a COW file with its backing file
+7.5. uml_moo : Merging a COW file with its backing file
+--------------------------------------------------------
Depending on how you use UML and COW devices, it may be advisable to
merge the changes in the COW file into the backing file every once in
@@ -1961,7 +1926,7 @@
- The utility that does this is uml_moo. Its usage is
+ The utility that does this is uml_moo. Its usage is::
host% uml_moo COW file new backing file
@@ -2001,7 +1966,8 @@
- 8. Creating filesystems
+8. Creating filesystems
+========================
You may want to create and mount new UML filesystems, either because
@@ -2015,13 +1981,14 @@
should be easy to translate to the filesystem of your choice.
- 8.1. Create the filesystem file
+8.1. Create the filesystem file
+================================
dd is your friend. All you need to do is tell dd to create an empty
file of the appropriate size. I usually make it sparse to save time
and to avoid allocating disk space until it's actually used. For
example, the following command will create a sparse 100 meg file full
- of zeroes.
+ of zeroes::
host%
@@ -2034,9 +2001,9 @@
8.2. Assign the file to a UML device
- Add an argument like the following to the UML command line:
+ Add an argument like the following to the UML command line::
- ubd4=new_filesystem
+ ubd4=new_filesystem
@@ -2053,7 +2020,7 @@
etc), then get them into UML by way of the net or hostfs.
- Make the new filesystem on the device assigned to the new file:
+ Make the new filesystem on the device assigned to the new file::
host# mkreiserfs /dev/ubd/4
@@ -2077,7 +2044,7 @@
- Now, mount it:
+ Now, mount it::
UML#
@@ -2096,7 +2063,8 @@
- 9. Host file access
+9. Host file access
+====================
If you want to access files on the host machine from inside UML, you
@@ -2112,10 +2080,11 @@
files contained in it just as you would on the host.
- 9.1. Using hostfs
+9.1. Using hostfs
+------------------
To begin with, make sure that hostfs is available inside the virtual
- machine with
+ machine with::
UML# cat /proc/filesystems
@@ -2127,7 +2096,7 @@
module and available inside the virtual machine, and insmod it.
- Now all you need to do is run mount:
+ Now all you need to do is run mount::
UML# mount none /mnt/host -t hostfs
@@ -2139,7 +2108,7 @@
If you don't want to mount the host root directory, then you can
- specify a subdirectory to mount with the -o switch to mount:
+ specify a subdirectory to mount with the -o switch to mount::
UML# mount none /mnt/home -t hostfs -o /home
@@ -2151,13 +2120,14 @@
- 9.2. hostfs as the root filesystem
+9.2. hostfs as the root filesystem
+-----------------------------------
It's possible to boot from a directory hierarchy on the host using
hostfs rather than using the standard filesystem in a file.
To start, you need that hierarchy. The easiest way is to loop mount
- an existing root_fs file:
+ an existing root_fs file::
host# mount root_fs uml_root_dir -o loop
@@ -2166,15 +2136,15 @@
You need to change the filesystem type of / in etc/fstab to be
- 'hostfs', so that line looks like this:
+ 'hostfs', so that line looks like this::
- /dev/ubd/0 / hostfs defaults 1 1
+ /dev/ubd/0 / hostfs defaults 1 1
Then you need to chown to yourself all the files in that directory
- that are owned by root. This worked for me:
+ that are owned by root. This worked for me::
host# find . -uid 0 -exec chown jdike {} \;
@@ -2183,7 +2153,7 @@
Next, make sure that your UML kernel has hostfs compiled in, not as a
- module. Then run UML with the boot device pointing at that directory:
+ module. Then run UML with the boot device pointing at that directory::
ubd0=/path/to/uml/root/directory
@@ -2194,41 +2164,35 @@
UML should then boot as it does normally.
- 9.3. Building hostfs
+9.3. Building hostfs
+---------------------
If you need to build hostfs because it's not in your kernel, you have
two choices:
- o Compiling hostfs into the kernel:
+ - Compiling hostfs into the kernel:
Reconfigure the kernel and set the 'Host filesystem' option under
- o Compiling hostfs as a module:
+ - Compiling hostfs as a module:
Reconfigure the kernel and set the 'Host filesystem' option under
be in arch/um/fs/hostfs/hostfs.o. Install that in
- /lib/modules/`uname -r`/fs in the virtual machine, boot it up, and
+ ``/lib/modules/$(uname -r)/fs`` in the virtual machine, boot it up, and::
UML# insmod hostfs
+.. _The_Management_Console:
-
-
-
-
-
-
-
-
-
- 10. The Management Console
+10. The Management Console
+===========================
@@ -2240,15 +2204,15 @@
There are a number of things you can do with the mconsole interface:
- o get the kernel version
+ - get the kernel version
- o add and remove devices
+ - add and remove devices
- o halt or reboot the machine
+ - halt or reboot the machine
- o Send SysRq commands
+ - Send SysRq commands
- o Pause and resume the UML
+ - Pause and resume the UML
You need the mconsole client (uml_mconsole) which is present in CVS
@@ -2257,7 +2221,7 @@
You also need CONFIG_MCONSOLE (under 'General Setup') enabled in UML.
- When you boot UML, you'll see a line like:
+ When you boot UML, you'll see a line like::
mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole
@@ -2265,7 +2229,7 @@
- If you specify a unique machine id one the UML command line, i.e.
+ If you specify a unique machine id one the UML command line, i.e.::
umid=debian
@@ -2273,7 +2237,7 @@
- you'll see this
+ you'll see this::
mconsole initialized on /home/jdike/.uml/debian/mconsole
@@ -2282,7 +2246,7 @@
That file is the socket that uml_mconsole will use to communicate with
- UML. Run it with either the umid or the full path as its argument:
+ UML. Run it with either the umid or the full path as its argument::
host% uml_mconsole debian
@@ -2290,7 +2254,7 @@
- or
+ or::
host% uml_mconsole /home/jdike/.uml/debian/mconsole
@@ -2300,30 +2264,31 @@
You'll get a prompt, at which you can run one of these commands:
- o version
+ - version
- o halt
+ - halt
- o reboot
+ - reboot
- o config
+ - config
- o remove
+ - remove
- o sysrq
+ - sysrq
- o help
+ - help
- o cad
+ - cad
- o stop
+ - stop
- o go
+ - go
- 10.1. version
+10.1. version
+--------------
- This takes no arguments. It prints the UML version.
+ This takes no arguments. It prints the UML version::
(mconsole) version
@@ -2342,11 +2307,12 @@
- 10.2. halt and reboot
+10.2. halt and reboot
+----------------------
These take no arguments. They shut the machine down immediately, with
no syncing of disks and no clean shutdown of userspace. So, they are
- pretty close to crashing the machine.
+ pretty close to crashing the machine::
(mconsole) halt
@@ -2357,34 +2323,36 @@
- 10.3. config
+10.3. config
+-------------
"config" adds a new device to the virtual machine. Currently the ubd
and network drivers support this. It takes one argument, which is the
- device to add, with the same syntax as the kernel command line.
+ device to add, with the same syntax as the kernel command line::
- (mconsole)
- config ubd3=/home/jdike/incoming/roots/root_fs_debian22
+ (mconsole)
+ config ubd3=/home/jdike/incoming/roots/root_fs_debian22
- OK
- (mconsole) config eth1=mcast
- OK
+ OK
+ (mconsole) config eth1=mcast
+ OK
- 10.4. remove
+10.4. remove
+-------------
"remove" deletes a device from the system. Its argument is just the
name of the device to be removed. The device must be idle in whatever
sense the driver considers necessary. In the case of the ubd driver,
the removed block device must not be mounted, swapped on, or otherwise
- open, and in the case of the network driver, the device must be down.
+ open, and in the case of the network driver, the device must be down::
(mconsole) remove ubd3
@@ -2397,7 +2365,8 @@
- 10.5. sysrq
+10.5. sysrq
+------------
This takes one argument, which is a single letter. It calls the
generic kernel's SysRq driver, which does whatever is called for by
@@ -2407,19 +2376,21 @@
- 10.6. help
+10.6. help
+-----------
"help" returns a string listing the valid commands and what each one
does.
- 10.7. cad
+10.7. cad
+----------
This invokes the Ctl-Alt-Del action on init. What exactly this ends
up doing is up to /etc/inittab. Normally, it reboots the machine.
With UML, this is usually not desired, so if a halt would be better,
- then find the section of inittab that looks like this
+ then find the section of inittab that looks like this::
# What to do when CTRL-ALT-DEL is pressed.
@@ -2432,7 +2403,8 @@
- 10.8. stop
+10.8. stop
+-----------
This puts the UML in a loop reading mconsole requests until a 'go'
mconsole command is received. This is very useful for making backups
@@ -2448,7 +2420,8 @@
- 10.9. go
+10.9. go
+---------
This resumes a UML after being paused by a 'stop' command. Note that
when the UML has resumed, TCP connections may have timed out and if
@@ -2460,9 +2433,10 @@
+.. _Kernel_debugging:
-
- 11. Kernel debugging
+11. Kernel debugging
+=====================
Note: The interface that makes debugging, as described here, possible
@@ -2477,15 +2451,16 @@
In order to debug the kernel, you need build it from source. See
- ``Compiling the kernel and modules'' for information on doing that.
+ :ref:`Compiling_the_kernel_and_modules` for information on doing that.
Make sure that you enable CONFIG_DEBUGSYM and CONFIG_PT_PROXY during
- the config. These will compile the kernel with -g, and enable the
+ the config. These will compile the kernel with ``-g``, and enable the
ptrace proxy so that gdb works with UML, respectively.
- 11.1. Starting the kernel under gdb
+11.1. Starting the kernel under gdb
+------------------------------------
You can have the kernel running under the control of gdb from the
beginning by putting 'debug' on the command line. You will get an
@@ -2498,7 +2473,11 @@
There is a transcript of a debugging session here <debug-
session.html> , with breakpoints being set in the scheduler and in an
interrupt handler.
- 11.2. Examining sleeping processes
+
+
+11.2. Examining sleeping processes
+-----------------------------------
+
Not every bug is evident in the currently running process. Sometimes,
processes hang in the kernel when they shouldn't because they've
@@ -2516,7 +2495,7 @@
Now what you do is this:
- o detach from the current thread
+ - detach from the current thread::
(UML gdb) det
@@ -2525,7 +2504,7 @@
- o attach to the thread you are interested in
+ - attach to the thread you are interested in::
(UML gdb) att <host pid>
@@ -2534,7 +2513,7 @@
- o look at its stack and anything else of interest
+ - look at its stack and anything else of interest::
(UML gdb) bt
@@ -2545,18 +2524,14 @@
Note that you can't do anything at this point that requires that a
process execute, e.g. calling a function
- o when you're done looking at that process, reattach to the current
- thread and continue it
+ - when you're done looking at that process, reattach to the current
+ thread and continue it::
(UML gdb)
att 1
-
-
-
-
(UML gdb)
c
@@ -2569,12 +2544,13 @@
- 11.3. Running ddd on UML
+11.3. Running ddd on UML
+-------------------------
ddd works on UML, but requires a special kludge. The process goes
like this:
- o Start ddd
+ - Start ddd::
host% ddd linux
@@ -2583,14 +2559,14 @@
- o With ps, get the pid of the gdb that ddd started. You can ask the
+ - With ps, get the pid of the gdb that ddd started. You can ask the
gdb to tell you, but for some reason that confuses things and
causes a hang.
- o run UML with 'debug=parent gdb-pid=<pid>' added to the command line
+ - run UML with 'debug=parent gdb-pid=<pid>' added to the command line
- it will just sit there after you hit return
- o type 'att 1' to the ddd gdb and you will see something like
+ - type 'att 1' to the ddd gdb and you will see something like::
0xa013dc51 in __kill ()
@@ -2602,12 +2578,14 @@
- o At this point, type 'c', UML will boot up, and you can use ddd just
+ - At this point, type 'c', UML will boot up, and you can use ddd just
as you do on any other process.
- 11.4. Debugging modules
+11.4. Debugging modules
+------------------------
+
gdb has support for debugging code which is dynamically loaded into
the process. This support is what is needed to debug kernel modules
@@ -2629,7 +2607,8 @@
First, you must tell it where your modules are. There is a list in
- the script that looks like this:
+ the script that looks like this::
+
set MODULE_PATHS {
"fat" "/usr/src/uml/linux-2.4.18/fs/fat/fat.o"
"isofs" "/usr/src/uml/linux-2.4.18/fs/isofs/isofs.o"
@@ -2641,9 +2620,7 @@
You change that to list the names and paths of the modules that you
are going to debug. Then you run it from the toplevel directory of
- your UML pool and it basically tells you what to do:
-
-
+ your UML pool and it basically tells you what to do::
******** GDB pid is 21903 ********
@@ -2666,7 +2643,7 @@
After you run UML and it sits there doing nothing, you hit return at
- the 'att 1' and continue it:
+ the 'att 1' and continue it::
Attaching to program: /home/jdike/linux/2.4/um/./linux, process 1
@@ -2678,63 +2655,48 @@
At this point, you debug normally. When you insmod something, the
- expect magic will kick in and you'll see something like:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- *** Module hostfs loaded ***
- Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
- mod_user=0x8070e00) at module.c:349
- 349 char *name, *n_name, *name_tmp = NULL;
- (UML gdb) finish
- Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
- mod_user=0x8070e00) at module.c:349
- 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
- 411 else res = EXECUTE_SYSCALL(syscall, regs);
- Value returned is $1 = 0
- (UML gdb)
- p/x (int)module_list + module_list->size_of_struct
-
- $2 = 0xa9021054
- (UML gdb) symbol-file ./linux
- Load new symbol table from "./linux"? (y or n) y
- Reading symbols from ./linux...
- done.
- (UML gdb)
- add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
-
- add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
- .text_addr = 0xa9021054
- (y or n) y
-
- Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
- done.
- (UML gdb) p *module_list
- $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
- size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
- nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
- init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
- ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
- persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
- kallsyms_end = 0x0,
- archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
- archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
- kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
- >> Finished loading symbols for hostfs ...
+ expect magic will kick in and you'll see something like::
+
+
+ *** Module hostfs loaded ***
+ Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
+ mod_user=0x8070e00) at module.c:349
+ 349 char *name, *n_name, *name_tmp = NULL;
+ (UML gdb) finish
+ Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
+ mod_user=0x8070e00) at module.c:349
+ 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
+ 411 else res = EXECUTE_SYSCALL(syscall, regs);
+ Value returned is $1 = 0
+ (UML gdb)
+ p/x (int)module_list + module_list->size_of_struct
+
+ $2 = 0xa9021054
+ (UML gdb) symbol-file ./linux
+ Load new symbol table from "./linux"? (y or n) y
+ Reading symbols from ./linux...
+ done.
+ (UML gdb)
+ add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
+
+ add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
+ .text_addr = 0xa9021054
+ (y or n) y
+
+ Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
+ done.
+ (UML gdb) p *module_list
+ $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
+ size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
+ nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
+ init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
+ ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
+ persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
+ kallsyms_end = 0x0,
+ archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
+ archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
+ kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
+ >> Finished loading symbols for hostfs ...
@@ -2744,7 +2706,7 @@
Boot the kernel under the debugger and load the module with insmod or
- modprobe. With gdb, do:
+ modprobe. With gdb, do::
(UML gdb) p module_list
@@ -2758,12 +2720,12 @@
the name fields until find the module you want to debug. Take the
address of that structure, and add module.size_of_struct (which in
2.4.10 kernels is 96 (0x60)) to it. Gdb can make this hard addition
- for you :-):
+ for you :-)::
- (UML gdb)
- printf "%#x\n", (int)module_list module_list->size_of_struct
+ (UML gdb)
+ printf "%#x\n", (int)module_list module_list->size_of_struct
@@ -2771,7 +2733,7 @@
The offset from the module start occasionally changes (before 2.4.0,
it was module.size_of_struct + 4), so it's a good idea to check the
init and cleanup addresses once in a while, as describe below. Now
- do:
+ do::
(UML gdb)
@@ -2786,7 +2748,7 @@
If there's any doubt that you got the offset right, like breakpoints
appear not to work, or they're appearing in the wrong place, you can
check it by looking at the module structure. The init and cleanup
- fields should look like:
+ fields should look like::
init = 0x588066b0 <init_hostfs>, cleanup = 0x588066c0 <exit_hostfs>
@@ -2801,7 +2763,7 @@
When you want to load in a new version of the module, you need to get
gdb to forget about the old one. The only way I've found to do that
- is to tell gdb to forget about all symbols that it knows about:
+ is to tell gdb to forget about all symbols that it knows about::
(UML gdb) symbol-file
@@ -2809,7 +2771,7 @@
- Then reload the symbols from the kernel binary:
+ Then reload the symbols from the kernel binary::
(UML gdb) symbol-file /path/to/kernel
@@ -2823,17 +2785,19 @@
- 11.5. Attaching gdb to the kernel
+11.5. Attaching gdb to the kernel
+----------------------------------
If you don't have the kernel running under gdb, you can attach gdb to
it later by sending the tracing thread a SIGUSR1. The first line of
- the console output identifies its pid:
+ the console output identifies its pid::
+
tracing thread pid = 20093
- When you send it the signal:
+ When you send it the signal::
host% kill -USR1 20093
@@ -2845,7 +2809,7 @@
If you have the mconsole compiled into UML, then the mconsole client
- can be used to start gdb:
+ can be used to start gdb::
(mconsole) (mconsole) config gdb=xterm
@@ -2857,7 +2821,8 @@
- 11.6. Using alternate debuggers
+11.6. Using alternate debuggers
+--------------------------------
UML has support for attaching to an already running debugger rather
than starting gdb itself. This is present in CVS as of 17 Apr 2001.
@@ -2886,7 +2851,7 @@
An example of an alternate debugger is strace. You can strace the
actual kernel as follows:
- o Run the following in a shell
+ - Run the following in a shell::
host%
@@ -2894,13 +2859,13 @@
- o Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
+ - Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
by the previous command
- o Hit return in the shell, and UML will start running, and strace
+ - Hit return in the shell, and UML will start running, and strace
output will start accumulating in the output file.
- Note that this is different from running
+ Note that this is different from running::
host% strace ./linux
@@ -2917,95 +2882,57 @@
- 12. Kernel debugging examples
+12. Kernel debugging examples
+==============================
- 12.1. The case of the hung fsck
+12.1. The case of the hung fsck
+--------------------------------
When booting up the kernel, fsck failed, and dropped me into a shell
- to fix things up. I ran fsck -y, which hung:
+ to fix things up. I ran fsck -y, which hung::
+ Setting hostname uml [ OK ]
+ Checking root filesystem
+ /dev/fhd0 was not cleanly unmounted, check forced.
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
+ /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
+ (i.e., without -a or -p options)
+ [ FAILED ]
+ *** An error occurred during the file system check.
+ *** Dropping you to a shell; the system will reboot
+ *** when you leave the shell.
+ Give root password for maintenance
+ (or type Control-D for normal startup):
+ [root@uml /root]# fsck -y /dev/fhd0
+ fsck -y /dev/fhd0
+ Parallelizing fsck version 1.14 (9-Jan-1999)
+ e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
+ /dev/fhd0 contains a file system with errors, check forced.
+ Pass 1: Checking inodes, blocks, and sizes
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
+ Inode 19780, i_blocks is 1548, should be 540. Fix? yes
+ Pass 2: Checking directory structure
+ Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
+ Directory inode 11858, block 0, offset 0: directory corrupted
+ Salvage? yes
+ Missing '.' in directory inode 11858.
+ Fix? yes
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Setting hostname uml [ OK ]
- Checking root filesystem
- /dev/fhd0 was not cleanly unmounted, check forced.
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
-
- /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
- (i.e., without -a or -p options)
- [ FAILED ]
-
- *** An error occurred during the file system check.
- *** Dropping you to a shell; the system will reboot
- *** when you leave the shell.
- Give root password for maintenance
- (or type Control-D for normal startup):
-
- [root@uml /root]# fsck -y /dev/fhd0
- fsck -y /dev/fhd0
- Parallelizing fsck version 1.14 (9-Jan-1999)
- e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
- /dev/fhd0 contains a file system with errors, check forced.
- Pass 1: Checking inodes, blocks, and sizes
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
-
- Inode 19780, i_blocks is 1548, should be 540. Fix? yes
-
- Pass 2: Checking directory structure
- Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
-
- Directory inode 11858, block 0, offset 0: directory corrupted
- Salvage? yes
-
- Missing '.' in directory inode 11858.
- Fix? yes
-
- Missing '..' in directory inode 11858.
- Fix? yes
-
-
-
+ Missing '..' in directory inode 11858.
+ Fix? yes
The standard drill in this sort of situation is to fire up gdb on the
signal thread, which, in this case, was pid 1935. In another window,
- I run gdb and attach pid 1935.
-
-
+ I run gdb and attach pid 1935::
~/linux/2.3.26/um 1016: gdb linux
@@ -3022,11 +2949,7 @@
0x100756d9 in __wait4 ()
-
-
-
-
- Let's see what's currently running:
+ Let's see what's currently running::
@@ -3041,7 +2964,7 @@
reason and never woke up.
- Let's guess that the last process in the process list is fsck:
+ Let's guess that the last process in the process list is fsck::
@@ -3052,7 +2975,7 @@
- It is, so let's see what it thinks it's up to:
+ It is, so let's see what it thinks it's up to::
@@ -3068,8 +2991,6 @@
-
-
The interesting things here are the fact that its .thread.syscall.id
is __NR_write (see the big switch in arch/um/kernel/syscall_kern.c or
the defines in include/asm-um/arch/unistd.h), and that it never
@@ -3081,30 +3002,20 @@
The fact that it never returned from write means that its stack should
be fairly interesting. Its pid is 1980 (.thread.extern_pid). That
process is being ptraced by the signal thread, so it must be detached
- before gdb can attach it:
+ before gdb can attach it::
+ (gdb) call detach(1980)
-
-
-
-
-
-
- (gdb) call detach(1980)
-
- Program received signal SIGSEGV, Segmentation fault.
- <function called from gdb>
- The program being debugged stopped while in a function called from GDB.
- When the function (detach) is done executing, GDB will silently
- stop (instead of continuing to evaluate the expression containing
- the function call).
- (gdb) call detach(1980)
- $15 = 0
-
-
-
+ Program received signal SIGSEGV, Segmentation fault.
+ <function called from gdb>
+ The program being debugged stopped while in a function called from GDB.
+ When the function (detach) is done executing, GDB will silently
+ stop (instead of continuing to evaluate the expression containing
+ the function call).
+ (gdb) call detach(1980)
+ $15 = 0
The first detach segfaults for some reason, and the second one
@@ -3112,7 +3023,7 @@
Now I detach from the signal thread, attach to the fsck thread, and
- look at its stack:
+ look at its stack::
(gdb) det
@@ -3152,14 +3063,14 @@
- The interesting things here are :
+ The interesting things here are:
- o There are two segfaults on this stack (frames 9 and 14)
+ - There are two segfaults on this stack (frames 9 and 14)
- o The first faulting address (frame 11) is 0x50000800
+ - The first faulting address (frame 11) is 0x50000800::
- (gdb) p (void *)1342179328
- $16 = (void *) 0x50000800
+ (gdb) p (void *)1342179328
+ $16 = (void *) 0x50000800
@@ -3175,7 +3086,7 @@
However, the more immediate problem is that second segfault and I'm
going to concentrate on that. First, I want to see where the fault
- happened, so I have to go look at the sigcontent struct in frame 8:
+ happened, so I have to go look at the sigcontent struct in frame 8::
@@ -3211,7 +3122,7 @@
- That's not very useful, so I'll try a more manual method:
+ That's not very useful, so I'll try a more manual method::
(gdb) p *((struct sigcontext *) (&sig + 1))
@@ -3224,7 +3135,7 @@
- The ip is in handle_mm_fault:
+ The ip is in handle_mm_fault::
(gdb) p (void *)268480945
@@ -3236,7 +3147,7 @@
- Specifically, it's in pte_alloc:
+ Specifically, it's in pte_alloc::
(gdb) i line *$20
@@ -3249,7 +3160,7 @@
To find where in handle_mm_fault this is, I'll jump forward in the
- code until I see an address in that procedure:
+ code until I see an address in that procedure::
@@ -3286,21 +3197,21 @@
Something is apparently wrong with the page tables or vma_structs, so
- lets go back to frame 11 and have a look at them:
+ lets go back to frame 11 and have a look at them::
- #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
- 50 handle_mm_fault(current, vma, address, is_write);
- (gdb) call pgd_offset_proc(vma->vm_mm, address)
- $22 = (pgd_t *) 0x80a548c
+ #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
+ 50 handle_mm_fault(current, vma, address, is_write);
+ (gdb) call pgd_offset_proc(vma->vm_mm, address)
+ $22 = (pgd_t *) 0x80a548c
That's pretty bogus. Page tables aren't supposed to be in process
- text or data areas. Let's see what's in the vma:
+ text or data areas. Let's see what's in the vma::
(gdb) p *vma
@@ -3325,12 +3236,9 @@
-
-
This also pretty bogus. With all of the 0x80xxxxx and 0xaffffxxx
addresses, this is looking like a stack was plonked down on top of
- these structures. Maybe it's a stack overflow from the next page:
-
+ these structures. Maybe it's a stack overflow from the next page::
(gdb) p vma
@@ -3338,52 +3246,36 @@
-
-
That's towards the lower quarter of the page, so that would have to
- have been pretty heavy stack overflow:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- (gdb) x/100x $25
- 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
- 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
- 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
- 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
- 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
- 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
- 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
-
-
+ have been pretty heavy stack overflow::
+
+
+ (gdb) x/100x $25
+ 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
+ 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
+ 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
+ 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
+ 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
+ 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
+ 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
@@ -3399,65 +3291,53 @@
on will be somewhat clearer.
- 12.2. Episode 2: The case of the hung fsck
+12.2. Episode 2: The case of the hung fsck
+-------------------------------------------
After setting a trap in the SEGV handler for accesses to the signal
thread's stack, I reran the kernel.
- fsck hung again, this time by hitting the trap:
+ fsck hung again, this time by hitting the trap::
+ Setting hostname uml [ OK ]
+ Checking root filesystem
+ /dev/fhd0 contains a file system with errors, check forced.
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
+ /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
+ (i.e., without -a or -p options)
+ [ FAILED ]
+ *** An error occurred during the file system check.
+ *** Dropping you to a shell; the system will reboot
+ *** when you leave the shell.
+ Give root password for maintenance
+ (or type Control-D for normal startup):
+ [root@uml /root]# fsck -y /dev/fhd0
+ fsck -y /dev/fhd0
+ Parallelizing fsck version 1.14 (9-Jan-1999)
+ e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
+ /dev/fhd0 contains a file system with errors, check forced.
+ Pass 1: Checking inodes, blocks, and sizes
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
+ Pass 2: Checking directory structure
+ Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
+ Directory inode 11858, block 0, offset 0: directory corrupted
+ Salvage? yes
+ Missing '.' in directory inode 11858.
+ Fix? yes
+ Missing '..' in directory inode 11858.
+ Fix? yes
-
-
-
-
-
- Setting hostname uml [ OK ]
- Checking root filesystem
- /dev/fhd0 contains a file system with errors, check forced.
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
-
- /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
- (i.e., without -a or -p options)
- [ FAILED ]
-
- *** An error occurred during the file system check.
- *** Dropping you to a shell; the system will reboot
- *** when you leave the shell.
- Give root password for maintenance
- (or type Control-D for normal startup):
-
- [root@uml /root]# fsck -y /dev/fhd0
- fsck -y /dev/fhd0
- Parallelizing fsck version 1.14 (9-Jan-1999)
- e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
- /dev/fhd0 contains a file system with errors, check forced.
- Pass 1: Checking inodes, blocks, and sizes
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
-
- Pass 2: Checking directory structure
- Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
-
- Directory inode 11858, block 0, offset 0: directory corrupted
- Salvage? yes
-
- Missing '.' in directory inode 11858.
- Fix? yes
-
- Missing '..' in directory inode 11858.
- Fix? yes
-
- Untested (4127) [100fe44c]: trap_kern.c line 31
+ Untested (4127) [100fe44c]: trap_kern.c line 31
@@ -3465,7 +3345,7 @@
I need to get the signal thread to detach from pid 4127 so that I can
attach to it with gdb. This is done by sending it a SIGUSR1, which is
- caught by the signal thread, which detaches the process:
+ caught by the signal thread, which detaches the process::
kill -USR1 4127
@@ -3474,31 +3354,20 @@
- Now I can run gdb on it:
-
-
-
-
-
-
-
-
-
-
-
-
-
- ~/linux/2.3.26/um 1034: gdb linux
- GNU gdb 4.17.0.11 with Linux support
- Copyright 1998 Free Software Foundation, Inc.
- GDB is free software, covered by the GNU General Public License, and you are
- welcome to change it and/or distribute copies of it under certain conditions.
- Type "show copying" to see the conditions.
- There is absolutely no warranty for GDB. Type "show warranty" for details.
- This GDB was configured as "i386-redhat-linux"...
- (gdb) att 4127
- Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
- 0x10075891 in __libc_nanosleep ()
+ Now I can run gdb on it::
+
+
+ ~/linux/2.3.26/um 1034: gdb linux
+ GNU gdb 4.17.0.11 with Linux support
+ Copyright 1998 Free Software Foundation, Inc.
+ GDB is free software, covered by the GNU General Public License, and you are
+ welcome to change it and/or distribute copies of it under certain conditions.
+ Type "show copying" to see the conditions.
+ There is absolutely no warranty for GDB. Type "show warranty" for details.
+ This GDB was configured as "i386-redhat-linux"...
+ (gdb) att 4127
+ Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
+ 0x10075891 in __libc_nanosleep ()
@@ -3506,7 +3375,7 @@
The backtrace shows that it was in a write and that the fault address
(address in frame 3) is 0x50000800, which is right in the middle of
- the signal thread's stack page:
+ the signal thread's stack page::
(gdb) bt
@@ -3540,58 +3409,48 @@
-
-
Going up the stack to the segv_handler frame and looking at where in
the code the access happened shows that it happened near line 110 of
- block_dev.c:
-
-
-
-
-
-
-
-
-
- (gdb) up
- #1 0x1007584d in __sleep (seconds=1000000)
- at ../sysdeps/unix/sysv/linux/sleep.c:78
- ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
- (gdb)
- #2 0x1006ce9a in stop () at user_util.c:191
- 191 while(1) sleep(1000000);
- (gdb)
- #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
- 31 KERN_UNTESTED();
- (gdb)
- #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
- 174 segv(sc->cr2, sc->err & 2);
- (gdb) p *sc
- $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
- __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
- esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
- err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
- esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
- cr2 = 1342179328}
- (gdb) p (void *)268550834
- $2 = (void *) 0x1001c2b2
- (gdb) i sym $2
- block_write + 1090 in section .text
- (gdb) i line *$2
- Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
- starts at address 0x1001c2a1 <block_write+1073>
- and ends at 0x1001c2bf <block_write+1103>.
- (gdb) i line *0x1001c2c0
- Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
- and ends at 0x1001c2e3 <block_write+1139>.
-
-
+ block_dev.c::
+
+
+
+ (gdb) up
+ #1 0x1007584d in __sleep (seconds=1000000)
+ at ../sysdeps/unix/sysv/linux/sleep.c:78
+ ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
+ (gdb)
+ #2 0x1006ce9a in stop () at user_util.c:191
+ 191 while(1) sleep(1000000);
+ (gdb)
+ #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
+ 31 KERN_UNTESTED();
+ (gdb)
+ #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
+ 174 segv(sc->cr2, sc->err & 2);
+ (gdb) p *sc
+ $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
+ __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
+ esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
+ err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
+ esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
+ cr2 = 1342179328}
+ (gdb) p (void *)268550834
+ $2 = (void *) 0x1001c2b2
+ (gdb) i sym $2
+ block_write + 1090 in section .text
+ (gdb) i line *$2
+ Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
+ starts at address 0x1001c2a1 <block_write+1073>
+ and ends at 0x1001c2bf <block_write+1103>.
+ (gdb) i line *0x1001c2c0
+ Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
+ and ends at 0x1001c2e3 <block_write+1139>.
Looking at the source shows that the fault happened during a call to
- copy_from_user to copy the data into the kernel:
+ copy_from_user to copy the data into the kernel::
107 count -= chars;
@@ -3601,10 +3460,8 @@
-
-
p is the pointer which must contain 0x50000800, since buf contains
- 0x80b8800 (frame 8 above). It is defined as:
+ 0x80b8800 (frame 8 above). It is defined as::
p = offset + bh->b_data;
@@ -3615,24 +3472,22 @@
I need to figure out what bh is, and it just so happens that bh is
passed as an argument to mark_buffer_uptodate and mark_buffer_dirty a
- few lines later, so I do a little disassembly:
+ few lines later, so I do a little disassembly::
-
-
- (gdb) disas 0x1001c2bf 0x1001c2e0
- Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
- 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
- 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
- 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
- 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
- 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
- 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
- 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
- 0x1001c2d8 <block_write+1128>: pushl $0x0
- 0x1001c2da <block_write+1130>: pushl %edx
- 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
- End of assembler dump.
+ (gdb) disas 0x1001c2bf 0x1001c2e0
+ Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
+ 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
+ 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
+ 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
+ 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
+ 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
+ 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
+ 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
+ 0x1001c2d8 <block_write+1128>: pushl $0x0
+ 0x1001c2da <block_write+1130>: pushl %edx
+ 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
+ End of assembler dump.
@@ -3640,7 +3495,7 @@
At that point, bh is in %edx (address 0x1001c2da), which is calculated
at 0x1001c2c2 as %ebp + 0xfffffdd4, so I figure exactly what that is,
- taking %ebp from the sigcontext_struct above:
+ taking %ebp from the sigcontext_struct above::
(gdb) p (void *)1342631484
@@ -3657,7 +3512,7 @@
Now, I look at the structure to see what's in it, and particularly,
- what its b_data field contains:
+ what its b_data field contains::
(gdb) p *((struct buffer_head *)0x50100200)
@@ -3682,18 +3537,18 @@
The b_page field is a pointer to the page_struct representing the
0x50000000 page. Looking at it shows the kernel's idea of the state
- of that page:
+ of that page::
- (gdb) p *$13.b_page
- $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
- index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
- next = 0x50008460, prev = 0x50019350}, wait = {
- lock = <optimized out or zero length>, task_list = {next = 0x50004024,
- prev = 0x50004024}, __magic = 1342193708, __creator = 0},
- pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
- zone = 0x100c5160}
+ (gdb) p *$13.b_page
+ $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
+ index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
+ next = 0x50008460, prev = 0x50019350}, wait = {
+ lock = <optimized out or zero length>, task_list = {next = 0x50004024,
+ prev = 0x50004024}, __magic = 1342193708, __creator = 0},
+ pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
+ zone = 0x100c5160}
@@ -3702,7 +3557,7 @@
Some sanity-checking: the virtual field shows the "virtual" address of
this page, which in this kernel is the same as its "physical" address,
and the page_struct itself should be mem_map[0], since it represents
- the first page of memory:
+ the first page of memory::
@@ -3719,7 +3574,7 @@
Now to check out the page_struct itself. In particular, the flags
- field shows whether the page is considered free or not:
+ field shows whether the page is considered free or not::
(gdb) p (void *)132
@@ -3739,7 +3594,7 @@
In my setup_arch procedure, I have the following code which looks just
- fine:
+ fine::
@@ -3762,7 +3617,7 @@
Stepping into init_bootmem, and looking at bootmem_map before looking
- at what it contains shows the following:
+ at what it contains shows the following::
@@ -3788,18 +3643,20 @@
- 13. What to do when UML doesn't work
+13. What to do when UML doesn't work
+=====================================
- 13.1. Strange compilation errors when you build from source
+13.1. Strange compilation errors when you build from source
+------------------------------------------------------------
As of test11, it is necessary to have "ARCH=um" in the environment or
on the make command line for all steps in building UML, including
clean, distclean, or mrproper, config, menuconfig, or xconfig, dep,
and linux. If you forget for any of them, the i386 build seems to
- contaminate the UML build. If this happens, start from scratch with
+ contaminate the UML build. If this happens, start from scratch with::
host%
@@ -3811,7 +3668,7 @@
and repeat the build process with ARCH=um on all the steps.
- See ``Compiling the kernel and modules'' for more details.
+ See :ref:`Compiling_the_kernel_and_modules` for more details.
Another cause of strange compilation errors is building UML in
@@ -3824,11 +3681,11 @@
- 13.3. A variety of panics and hangs with /tmp on a reiserfs filesys-
- tem
+13.3. A variety of panics and hangs with /tmp on a reiserfs filesystem
+-----------------------------------------------------------------------
I saw this on reiserfs 3.5.21 and it seems to be fixed in 3.5.27.
- Panics preceded by
+ Panics preceded by::
Detaching pid nnnn
@@ -3854,17 +3711,19 @@
- 13.5. UML doesn't work when /tmp is an NFS filesystem
+13.5. UML doesn't work when /tmp is an NFS filesystem
+------------------------------------------------------
This seems to be a similar situation with the ReiserFS problem above.
Some versions of NFS seems not to handle mmap correctly, which UML
depends on. The workaround is have /tmp be a non-NFS directory.
- 13.6. UML hangs on boot when compiled with gprof support
+13.6. UML hangs on boot when compiled with gprof support
+---------------------------------------------------------
If you build UML with gprof support and, early in the boot, it does
- this
+ this::
kernel BUG at page_alloc.c:100!
@@ -3878,10 +3737,11 @@
- 13.7. syslogd dies with a SIGTERM on startup
+13.7. syslogd dies with a SIGTERM on startup
+---------------------------------------------
The exact boot error depends on the distribution that you're booting,
- but Debian produces this:
+ but Debian produces this::
/etc/rc2.d/S10sysklogd: line 49: 93 Terminated
@@ -3897,17 +3757,18 @@
- 13.8. TUN/TAP networking doesn't work on a 2.4 host
+13.8. TUN/TAP networking doesn't work on a 2.4 host
+----------------------------------------------------
There are a couple of problems which were
<http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
out"> by Tim Robinson <timro at trkr dot net>
- o It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
+ - It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
The fix is to upgrade to something more recent and then read the
next item.
- o If you see
+ - If you see::
File descriptor in bad state
@@ -3921,8 +3782,8 @@
- 13.9. You can network to the host but not to other machines on the
- net
+13.9. You can network to the host but not to other machines on the net
+=======================================================================
If you can connect to the host, and the host can connect to UML, but
you cannot connect to any other machines, then you may need to enable
@@ -3930,7 +3791,7 @@
using private IP addresses (192.168.x.x or 10.x.x.x) for host/UML
networking, rather than the public address space that your host is
connected to. UML does not enable IP Masquerading, so you will need
- to create a static rule to enable it:
+ to create a static rule to enable it::
host%
@@ -3948,7 +3809,7 @@
If you can reach the local net, but not the outside Internet, then
- that is usually a routing problem. The UML needs a default route:
+ that is usually a routing problem. The UML needs a default route::
UML#
@@ -3972,7 +3833,8 @@
- 13.10. I have no root and I want to scream
+13.10. I have no root and I want to scream
+===========================================
Thanks to Birgit Wahlich for telling me about this strange one. It
turns out that there's a limit of six environment variables on the
@@ -3987,14 +3849,16 @@
- 13.11. UML build conflict between ptrace.h and ucontext.h
+13.11. UML build conflict between ptrace.h and ucontext.h
+==========================================================
On some older systems, /usr/include/asm/ptrace.h and
/usr/include/sys/ucontext.h define the same names. So, when they're
included together, the defines from one completely mess up the parsing
- of the other, producing errors like:
+ of the other, producing errors like::
+
/usr/include/sys/ucontext.h:47: parse error before
- `10'
+ `10`
@@ -4007,7 +3871,8 @@
- 13.12. The UML BogoMips is exactly half the host's BogoMips
+13.12. The UML BogoMips is exactly half the host's BogoMips
+------------------------------------------------------------
On i386 kernels, there are two ways of running the loop that is used
to calculate the BogoMips rating, using the TSC if it's there or using
@@ -4019,15 +3884,17 @@
- 13.13. When you run UML, it immediately segfaults
+13.13. When you run UML, it immediately segfaults
+--------------------------------------------------
If the host is configured with the 2G/2G address space split, that's
- why. See ``UML on 2G/2G hosts'' for the details on getting UML to
+ why. See ref:`UML_on_2G/2G_hosts` for the details on getting UML to
run on your host.
- 13.14. xterms appear, then immediately disappear
+13.14. xterms appear, then immediately disappear
+-------------------------------------------------
If you're running an up to date kernel with an old release of
uml_utilities, the port-helper program will not work properly, so
@@ -4039,7 +3906,8 @@
- 13.15. Any other panic, hang, or strange behavior
+13.15. Any other panic, hang, or strange behavior
+--------------------------------------------------
If you're seeing truly strange behavior, such as hangs or panics that
happen in random places, or you try running the debugger to see what's
@@ -4057,9 +3925,13 @@
it and that a fix is imminent.
- If you want to be super-helpful, read ``Diagnosing Problems'' and
+ If you want to be super-helpful, read :ref:`Diagnosing_Problems` and
follow the instructions contained therein.
- 14. Diagnosing Problems
+
+.. _Diagnosing_Problems:
+
+14. Diagnosing Problems
+========================
If you get UML to crash, hang, or otherwise misbehave, you should
@@ -4074,21 +3946,22 @@
For any diagnosis, you're going to need to build a debugging kernel.
The binaries from this site aren't debuggable. If you haven't done
- this before, read about ``Compiling the kernel and modules'' and
- ``Kernel debugging'' UML first.
+ this before, read about :ref:`Compiling_the_kernel_and_modules` and
+ :ref:`Kernel_debugging` UML first.
- 14.1. Case 1 : Normal kernel panics
+14.1. Case 1 : Normal kernel panics
+------------------------------------
The most common case is for a normal thread to panic. To debug this,
you will need to run it under the debugger (add 'debug' to the command
line). An xterm will start up with gdb running inside it. Continue
- it when it stops in start_kernel and make it crash. Now ^C gdb and
+ it when it stops in start_kernel and make it crash. Now ``^C gdb`` and
If the panic was a "Kernel mode fault", then there will be a segv
frame on the stack and I'm going to want some more information. The
- stack might look something like this:
+ stack might look something like this::
(UML gdb) backtrace
@@ -4107,7 +3980,7 @@
I'm going to want to see the symbol and line information for the value
- of ip in the segv frame. In this case, you would do the following:
+ of ip in the segv frame. In this case, you would do the following::
(UML gdb) i sym 268849158
@@ -4115,7 +3988,7 @@
- and
+ and::
(UML gdb) i line *268849158
@@ -4128,7 +4001,8 @@
to get that information from the faulting ip.
- 14.2. Case 2 : Tracing thread panics
+14.2. Case 2 : Tracing thread panics
+-------------------------------------
The less common and more painful case is when the tracing thread
panics. In this case, the kernel debugger will be useless because it
@@ -4136,7 +4010,7 @@
do is get a backtrace from the tracing thread. This is done by
figuring out what its pid is, firing up gdb, and attaching it to that
pid. You can figure out the tracing thread pid by looking at the
- first line of the console output, which will look like this:
+ first line of the console output, which will look like this::
tracing thread pid = 15851
@@ -4145,7 +4019,7 @@
or by running ps on the host and finding the line that looks like
- this:
+ this::
jdike 15851 4.5 0.4 132568 1104 pts/0 S 21:34 0:05 ./linux [(tracing thread)]
@@ -4164,7 +4038,7 @@
14.3. Case 3 : Tracing thread panics caused by other threads
However, there are cases where the misbehavior of another thread
- caused the problem. The most common panic of this type is:
+ caused the problem. The most common panic of this type is::
wait_for_stop failed to wait for <pid> to stop with <signal number>
@@ -4177,7 +4051,7 @@
debugger is defunct and without some fancy footwork, another gdb can't
attach to it. So, this is how the fancy footwork goes:
- In a shell:
+ In a shell::
host% kill -STOP pid
@@ -4185,7 +4059,7 @@
- Run gdb on the tracing thread as described in case 2 and do:
+ Run gdb on the tracing thread as described in case 2 and do::
(host gdb) call detach(pid)
@@ -4193,7 +4067,7 @@
If you get a segfault, do it again. It always works the second time.
- Detach from the tracing thread and attach to that other thread:
+ Detach from the tracing thread and attach to that other thread::
(host gdb) detach
@@ -4209,7 +4083,7 @@
If gdb hangs when attaching to that process, go back to a shell and
- do:
+ do::
host%
@@ -4218,7 +4092,7 @@
- And then get the backtrace:
+ And then get the backtrace::
(host gdb) backtrace
@@ -4227,13 +4101,14 @@
- 14.4. Case 4 : Hangs
+14.4. Case 4 : Hangs
+---------------------
Hangs seem to be fairly rare, but they sometimes happen. When a hang
happens, we need a backtrace from the offending process. Run the
kernel debugger as described in case 1 and get a backtrace. If the
current process is not the idle thread, then send in the backtrace.
- You can tell that it's the idle thread if the stack looks like this:
+ You can tell that it's the idle thread if the stack looks like this::
#0 0x100b1401 in __libc_nanosleep ()
@@ -4257,7 +4132,8 @@
- 15. Thanks
+15. Thanks
+===========
A number of people have helped this project in various ways, and this
@@ -4274,20 +4150,21 @@
bookkeeping lapses and I forget about contributions.
- 15.1. Code and Documentation
+15.1. Code and Documentation
+-----------------------------
Rusty Russell <rusty at linuxcare.com.au> -
- o wrote the HOWTO <http://user-mode-
+ - wrote the HOWTO <http://user-mode-
linux.sourceforge.net/UserModeLinux-HOWTO.html>
- o prodded me into making this project official and putting it on
+ - prodded me into making this project official and putting it on
SourceForge
- o came up with the way cool UML logo <http://user-mode-
+ - came up with the way cool UML logo <http://user-mode-
linux.sourceforge.net/uml-small.png>
- o redid the config process
+ - redid the config process
Peter Moulder <reiter at netspace.net.au> - Fixed my config and build
@@ -4296,18 +4173,18 @@
Bill Stearns <wstearns at pobox.com> -
- o HOWTO updates
+ - HOWTO updates
- o lots of bug reports
+ - lots of bug reports
- o lots of testing
+ - lots of testing
- o dedicated a box (uml.ists.dartmouth.edu) to support UML development
+ - dedicated a box (uml.ists.dartmouth.edu) to support UML development
- o wrote the mkrootfs script, which allows bootable filesystems of
+ - wrote the mkrootfs script, which allows bootable filesystems of
RPM-based distributions to be cranked out
- o cranked out a large number of filesystems with said script
+ - cranked out a large number of filesystems with said script
Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
@@ -4375,176 +4252,180 @@
David Coulson <http://davidcoulson.net> -
- o Set up the usermodelinux.org <http://usermodelinux.org> site,
+ - Set up the usermodelinux.org <http://usermodelinux.org> site,
which is a great way of keeping the UML user community on top of
UML goings-on.
- o Site documentation and updates
+ - Site documentation and updates
- o Nifty little UML management daemon UMLd
+ - Nifty little UML management daemon UMLd
<http://uml.openconsultancy.com/umld/>
- o Lots of testing and bug reports
+ - Lots of testing and bug reports
- 15.2. Flushing out bugs
+15.2. Flushing out bugs
+------------------------
- o Yuri Pudgorodsky
+ - Yuri Pudgorodsky
- o Gerald Britton
+ - Gerald Britton
- o Ian Wehrman
+ - Ian Wehrman
- o Gord Lamb
+ - Gord Lamb
- o Eugene Koontz
+ - Eugene Koontz
- o John H. Hartman
+ - John H. Hartman
- o Anders Karlsson
+ - Anders Karlsson
- o Daniel Phillips
+ - Daniel Phillips
- o John Fremlin
+ - John Fremlin
- o Rainer Burgstaller
+ - Rainer Burgstaller
- o James Stevenson
+ - James Stevenson
- o Matt Clay
+ - Matt Clay
- o Cliff Jefferies
+ - Cliff Jefferies
- o Geoff Hoff
+ - Geoff Hoff
- o Lennert Buytenhek
+ - Lennert Buytenhek
- o Al Viro
+ - Al Viro
- o Frank Klingenhoefer
+ - Frank Klingenhoefer
- o Livio Baldini Soares
+ - Livio Baldini Soares
- o Jon Burgess
+ - Jon Burgess
- o Petru Paler
+ - Petru Paler
- o Paul
+ - Paul
- o Chris Reahard
+ - Chris Reahard
- o Sverker Nilsson
+ - Sverker Nilsson
- o Gong Su
+ - Gong Su
- o johan verrept
+ - johan verrept
- o Bjorn Eriksson
+ - Bjorn Eriksson
- o Lorenzo Allegrucci
+ - Lorenzo Allegrucci
- o Muli Ben-Yehuda
+ - Muli Ben-Yehuda
- o David Mansfield
+ - David Mansfield
- o Howard Goff
+ - Howard Goff
- o Mike Anderson
+ - Mike Anderson
- o John Byrne
+ - John Byrne
- o Sapan J. Batia
+ - Sapan J. Batia
- o Iris Huang
+ - Iris Huang
- o Jan Hudec
+ - Jan Hudec
- o Voluspa
+ - Voluspa
- 15.3. Buglets and clean-ups
+15.3. Buglets and clean-ups
+----------------------------
- o Dave Zarzycki
+ - Dave Zarzycki
- o Adam Lazur
+ - Adam Lazur
- o Boria Feigin
+ - Boria Feigin
- o Brian J. Murrell
+ - Brian J. Murrell
- o JS
+ - JS
- o Roman Zippel
+ - Roman Zippel
- o Wil Cooley
+ - Wil Cooley
- o Ayelet Shemesh
+ - Ayelet Shemesh
- o Will Dyson
+ - Will Dyson
- o Sverker Nilsson
+ - Sverker Nilsson
- o dvorak
+ - dvorak
- o v.naga srinivas
+ - v.naga srinivas
- o Shlomi Fish
+ - Shlomi Fish
- o Roger Binns
+ - Roger Binns
- o johan verrept
+ - johan verrept
- o MrChuoi
+ - MrChuoi
- o Peter Cleve
+ - Peter Cleve
- o Vincent Guffens
+ - Vincent Guffens
- o Nathan Scott
+ - Nathan Scott
- o Patrick Caulfield
+ - Patrick Caulfield
- o jbearce
+ - jbearce
- o Catalin Marinas
+ - Catalin Marinas
- o Shane Spencer
+ - Shane Spencer
- o Zou Min
+ - Zou Min
- o Ryan Boder
+ - Ryan Boder
- o Lorenzo Colitti
+ - Lorenzo Colitti
- o Gwendal Grignou
+ - Gwendal Grignou
- o Andre' Breiler
+ - Andre' Breiler
- o Tsutomu Yasuda
+ - Tsutomu Yasuda
- 15.4. Case Studies
+15.4. Case Studies
+-------------------
- o Jon Wright
+ - Jon Wright
- o William McEwan
+ - William McEwan
- o Michael Richardson
+ - Michael Richardson
- 15.5. Other contributions
+15.5. Other contributions
+--------------------------
Bill Carr <Bill.Carr at compaq.com> made the Red Hat mkrootfs script
@@ -4575,15 +4456,3 @@
server jailed inside UML. It's available from the download
<http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
Filesystems section.
-
-
-
-
-
-
-
-
-
-
-
-
--
2.24.1
_______________________________________________
linux-um mailing list
linux-um@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-um
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 02/27] docs: virt: convert UML documentation to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jonathan Corbet,
Jeff Dike, Richard Weinberger, Anton Ivanov, linux-doc, linux-um
Despite being an old document, it contains lots of information
that could still be useful.
The document has a nice style with makes easy to convert to
ReST. So, let's convert it to ReST.
This patch does:
- Use proper markups for titles;
- Mark and proper indent literal blocks;
- don't use an 'o' character for lists;
- other minor changes required for the doc to be parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/index.rst | 1 +
...odeLinux-HOWTO.txt => user_mode_linux.rst} | 1703 ++++++++---------
2 files changed, 787 insertions(+), 917 deletions(-)
rename Documentation/virt/uml/{UserModeLinux-HOWTO.txt => user_mode_linux.rst} (75%)
diff --git a/Documentation/virt/index.rst b/Documentation/virt/index.rst
index 062ffb527043..0a8f7fda64ad 100644
--- a/Documentation/virt/index.rst
+++ b/Documentation/virt/index.rst
@@ -8,6 +8,7 @@ Linux Virtualization Support
:maxdepth: 2
kvm/index
+ uml/user_mode_linux
paravirt_ops
.. only:: html and subproject
diff --git a/Documentation/virt/uml/UserModeLinux-HOWTO.txt b/Documentation/virt/uml/user_mode_linux.rst
similarity index 75%
rename from Documentation/virt/uml/UserModeLinux-HOWTO.txt
rename to Documentation/virt/uml/user_mode_linux.rst
index 87b80f589e1c..98922008be23 100644
--- a/Documentation/virt/uml/UserModeLinux-HOWTO.txt
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -1,12 +1,15 @@
- User Mode Linux HOWTO
- User Mode Linux Core Team
- Mon Nov 18 14:16:16 EST 2002
+=====================
+User Mode Linux HOWTO
+=====================
- This document describes the use and abuse of Jeff Dike's User Mode
- Linux: a port of the Linux kernel as a normal Intel Linux process.
- ______________________________________________________________________
+:Author: User Mode Linux Core Team
+:Last-updated: Mon Nov 18 14:16:16 EST 2002
- Table of Contents
+This document describes the use and abuse of Jeff Dike's User Mode
+Linux: a port of the Linux kernel as a normal Intel Linux process.
+
+
+.. Table of Contents
1. Introduction
@@ -132,19 +135,19 @@
15.5 Other contributions
- ______________________________________________________________________
-
- 1. Introduction
+1. Introduction
+================
Welcome to User Mode Linux. It's going to be fun.
- 1.1. How is User Mode Linux Different?
+1.1. How is User Mode Linux Different?
+---------------------------------------
Normally, the Linux Kernel talks straight to your hardware (video
card, keyboard, hard drives, etc), and any programs which run ask the
- kernel to operate the hardware, like so:
+ kernel to operate the hardware, like so::
@@ -160,10 +163,10 @@
The User Mode Linux Kernel is different; instead of talking to the
- hardware, it talks to a `real' Linux kernel (called the `host kernel'
+ hardware, it talks to a `real` Linux kernel (called the `host kernel`
from now on), like any other program. Programs can then run inside
User-Mode Linux as if they were running under a normal kernel, like
- so:
+ so::
@@ -181,7 +184,8 @@
- 1.2. Why Would I Want User Mode Linux?
+1.2. Why Would I Want User Mode Linux?
+---------------------------------------
1. If User Mode Linux crashes, your host kernel is still fine.
@@ -204,14 +208,16 @@
+.. _Compiling_the_kernel_and_modules:
+2. Compiling the kernel and modules
+====================================
- 2. Compiling the kernel and modules
-
- 2.1. Compiling the kernel
+2.1. Compiling the kernel
+--------------------------
Compiling the user mode kernel is just like compiling any other
@@ -220,7 +226,6 @@
1. Download the latest UML patch from
-
the download page <http://user-mode-linux.sourceforge.net/
In this example, the file is uml-patch-2.4.0-prerelease.bz2.
@@ -230,57 +235,33 @@
such as:
ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
- <ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2>
- .
-
-
- 3. Make a directory and unpack the kernel into it.
+ 3. Make a directory and unpack the kernel into it::
host%
mkdir ~/uml
-
-
-
-
-
host%
cd ~/uml
-
-
-
-
-
host%
tar -xzvf linux-2.4.0-prerelease.tar.bz2
-
-
-
- 4. Apply the patch using
-
-
+ 4. Apply the patch using::
host%
cd ~/uml/linux
-
-
host%
bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
-
-
-
- 5. Run your favorite config; `make xconfig ARCH=um' is the most
- convenient. `make config ARCH=um' and 'make menuconfig ARCH=um'
+ 5. Run your favorite config; ``make xconfig ARCH=um`` is the most
+ convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um``
will work as well. The defaults will give you a useful kernel. If
you want to change something, go ahead, it probably won't hurt
anything.
@@ -288,13 +269,13 @@
Note: If the host is configured with a 2G/2G address space split
rather than the usual 3G/1G split, then the packaged UML binaries
- will not run. They will immediately segfault. See ``UML on 2G/2G
- hosts'' for the scoop on running UML on your system.
+ will not run. They will immediately segfault. See
+ :ref:`UML_on_2G/2G_hosts` for the scoop on running UML on your system.
- 6. Finish with `make linux ARCH=um': the result is a file called
- `linux' in the top directory of your source tree.
+ 6. Finish with ``make linux ARCH=um``: the result is a file called
+ ``linux`` in the top directory of your source tree.
Make sure that you don't build this kernel in /usr/src/linux. On some
distributions, /usr/include/asm is a link into this pool. The user-
@@ -310,7 +291,7 @@
corresponding directory in the appropriate kernel pool.
If you don't have the latest kernel pool, you can get the
- corresponding user-mode sources with
+ corresponding user-mode sources with::
host% cvs co -r v_2_3_x linux
@@ -322,10 +303,11 @@
bug fixes and enhancements that have gone into subsequent releases.
- 2.2. Compiling and installing kernel modules
+2.2. Compiling and installing kernel modules
+---------------------------------------------
UML modules are built in the same way as the native kernel (with the
- exception of the 'ARCH=um' that you always need for UML):
+ exception of the 'ARCH=um' that you always need for UML)::
host% make modules ARCH=um
@@ -337,12 +319,12 @@
the user-mode pool. Modules from the native kernel won't work.
You can install them by using ftp or something to copy them into the
- virtual machine and dropping them into /lib/modules/`uname -r`.
+ virtual machine and dropping them into ``/lib/modules/$(uname -r)``.
You can also get the kernel build process to install them as follows:
1. with the kernel not booted, mount the root filesystem in the top
- level of the kernel pool:
+ level of the kernel pool::
host% mount root_fs mnt -o loop
@@ -352,7 +334,7 @@
- 2. run
+ 2. run::
host%
@@ -363,7 +345,7 @@
- 3. unmount the filesystem
+ 3. unmount the filesystem::
host% umount mnt
@@ -386,22 +368,23 @@
- 2.3. Compiling and installing uml_utilities
+2.3. Compiling and installing uml_utilities
+--------------------------------------------
Many features of the UML kernel require a user-space helper program,
so a uml_utilities package is distributed separately from the kernel
patch which provides these helpers. Included within this is:
- o port-helper - Used by consoles which connect to xterms or ports
+ - port-helper - Used by consoles which connect to xterms or ports
- o tunctl - Configuration tool to create and delete tap devices
+ - tunctl - Configuration tool to create and delete tap devices
- o uml_net - Setuid binary for automatic tap device configuration
+ - uml_net - Setuid binary for automatic tap device configuration
- o uml_switch - User-space virtual switch required for daemon
+ - uml_switch - User-space virtual switch required for daemon
transport
- The uml_utilities tree is compiled with:
+ The uml_utilities tree is compiled with::
host#
@@ -423,19 +406,21 @@
- 3. Running UML and logging in
+3. Running UML and logging in
+==============================
- 3.1. Running UML
+3.1. Running UML
+-----------------
It runs on 2.2.15 or later, and all 2.4 kernels.
Booting UML is straightforward. Simply run 'linux': it will try to
- mount the file `root_fs' in the current directory. You do not need to
- run it as root. If your root filesystem is not named `root_fs', then
- you need to put a `ubd0=root_fs_whatever' switch on the linux command
+ mount the file ``root_fs`` in the current directory. You do not need to
+ run it as root. If your root filesystem is not named ``root_fs``, then
+ you need to put a ``ubd0=root_fs_whatever`` switch on the linux command
line.
@@ -447,14 +432,16 @@
The kernel will boot up and present you with a login prompt.
- Note: If the host is configured with a 2G/2G address space split
+Note:
+ If the host is configured with a 2G/2G address space split
rather than the usual 3G/1G split, then the packaged UML binaries will
- not run. They will immediately segfault. See ``UML on 2G/2G hosts''
+ not run. They will immediately segfault. See :ref:`UML_on_2G/2G_hosts`
for the scoop on running UML on your system.
- 3.2. Logging in
+3.2. Logging in
+----------------
@@ -468,22 +455,22 @@
There are a couple of other ways to log in:
- o On a virtual console
+ - On a virtual console
Each virtual console that is configured (i.e. the device exists in
/dev and /etc/inittab runs a getty on it) will come up in its own
- xterm. If you get tired of the xterms, read ``Setting up serial
- lines and consoles'' to see how to attach the consoles to
- something else, like host ptys.
+ xterm. If you get tired of the xterms, read
+ :ref:`setting_up_serial_lines_and_consoles` to see how to attach
+ the consoles to something else, like host ptys.
- o Over the serial line
+ - Over the serial line
- In the boot output, find a line that looks like:
+ In the boot output, find a line that looks like::
@@ -493,7 +480,7 @@
Attach your favorite terminal program to the corresponding tty. I.e.
- for minicom, the command would be
+ for minicom, the command would be::
host% minicom -o -p /dev/ttyp1
@@ -503,37 +490,41 @@
- o Over the net
+ - Over the net
If the network is running, then you can telnet to the virtual
- machine and log in to it. See ``Setting up the network'' to learn
+ machine and log in to it. See :ref:`Setting_up_the_network` to learn
about setting up a virtual network.
When you're done using it, run halt, and the kernel will bring itself
down and the process will exit.
- 3.3. Examples
+3.3. Examples
+--------------
Here are some examples of UML in action:
- o A login session <http://user-mode-linux.sourceforge.net/login.html>
+ - A login session <http://user-mode-linux.sourceforge.net/login.html>
- o A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+ - A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+.. _UML_on_2G/2G_hosts:
- 4. UML on 2G/2G hosts
+4. UML on 2G/2G hosts
+======================
- 4.1. Introduction
+4.1. Introduction
+------------------
Most Linux machines are configured so that the kernel occupies the
@@ -546,7 +537,8 @@
- 4.2. The problem
+4.2. The problem
+-----------------
The prebuilt UML binaries on this site will not run on 2G/2G hosts
@@ -558,13 +550,14 @@
- 4.3. The solution
+4.3. The solution
+------------------
The fix for this is to rebuild UML from source after enabling
CONFIG_HOST_2G_2G (under 'General Setup'). This will cause UML to
load itself in the top .5G of that smaller process address space,
- where it will run fine. See ``Compiling the kernel and modules'' if
+ where it will run fine. See :ref:`Compiling_the_kernel_and_modules` if
you need help building UML from source.
@@ -573,10 +566,11 @@
+.. _setting_up_serial_lines_and_consoles:
-
- 5. Setting up serial lines and consoles
+5. Setting up serial lines and consoles
+========================================
It is possible to attach UML serial lines and consoles to many types
@@ -584,22 +578,23 @@
You can attach them to host ptys, ttys, file descriptors, and ports.
- This allows you to do things like
+ This allows you to do things like:
- o have a UML console appear on an unused host console,
+ - have a UML console appear on an unused host console,
- o hook two virtual machines together by having one attach to a pty
+ - hook two virtual machines together by having one attach to a pty
and having the other attach to the corresponding tty
- o make a virtual machine accessible from the net by attaching a
+ - make a virtual machine accessible from the net by attaching a
console to a port on the host.
- The general format of the command line option is device=channel.
+ The general format of the command line option is ``device=channel``.
- 5.1. Specifying the device
+5.1. Specifying the device
+---------------------------
Devices are specified with "con" or "ssl" (console or serial line,
respectively), optionally with a device number if you are talking
@@ -613,7 +608,7 @@
A specific device name will override a less general "con=" or "ssl=".
So, for example, you can assign a pty to each of the serial lines
- except for the first two like this:
+ except for the first two like this::
ssl=pty ssl0=tty:/dev/tty0 ssl1=tty:/dev/tty1
@@ -626,13 +621,14 @@
- 5.2. Specifying the channel
+5.2. Specifying the channel
+----------------------------
There are a number of different types of channels to attach a UML
device to, each with a different way of specifying exactly what to
attach to.
- o pseudo-terminals - device=pty pts terminals - device=pts
+ - pseudo-terminals - device=pty pts terminals - device=pts
This will cause UML to allocate a free host pseudo-terminal for the
@@ -640,23 +636,23 @@
log. You access it by attaching a terminal program to the
corresponding tty:
- o screen /dev/pts/n
+ - screen /dev/pts/n
- o screen /dev/ttyxx
+ - screen /dev/ttyxx
- o minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
+ - minicom -o -p /dev/ttyxx - minicom seems not able to handle pts
devices
- o kermit - start it up, 'open' the device, then 'connect'
+ - kermit - start it up, 'open' the device, then 'connect'
- o terminals - device=tty:tty device file
+ - terminals - device=tty:tty device file
- This will make UML attach the device to the specified tty (i.e
+ This will make UML attach the device to the specified tty (i.e::
con1=tty:/dev/tty3
@@ -672,7 +668,7 @@
- o xterms - device=xterm
+ - xterms - device=xterm
UML will run an xterm and the device will be attached to it.
@@ -681,12 +677,12 @@
- o Port - device=port:port number
+ - Port - device=port:port number
This will attach the UML devices to the specified host port.
Attaching console 1 to the host's port 9000 would be done like
- this:
+ this::
con1=port:9000
@@ -694,7 +690,7 @@
- Attaching all the serial lines to that port would be done similarly:
+ Attaching all the serial lines to that port would be done similarly::
ssl=port:9000
@@ -702,8 +698,8 @@
- You access these devices by telnetting to that port. Each active tel-
- net session gets a different device. If there are more telnets to a
+ You access these devices by telnetting to that port. Each active
+ telnet session gets a different device. If there are more telnets to a
port than UML devices attached to it, then the extra telnet sessions
will block until an existing telnet detaches, or until another device
becomes active (i.e. by being activated in /etc/inittab).
@@ -725,13 +721,13 @@
- o already-existing file descriptors - device=file descriptor
+ - already-existing file descriptors - device=file descriptor
If you set up a file descriptor on the UML command line, you can
attach a UML device to it. This is most commonly used to put the
main console back on stdin and stdout after assigning all the other
- consoles to something else:
+ consoles to something else::
con0=fd:0,fd:1 con=pts
@@ -743,7 +739,7 @@
- o Nothing - device=null
+ - Nothing - device=null
This allows the device to be opened, in contrast to 'none', but
@@ -754,7 +750,7 @@
- o None - device=none
+ - None - device=none
This causes the device to disappear.
@@ -762,7 +758,7 @@
You can also specify different input and output channels for a device
- by putting a comma between them:
+ by putting a comma between them::
ssl3=tty:/dev/tty2,xterm
@@ -785,14 +781,15 @@
- 5.3. Examples
+5.3. Examples
+--------------
There are a number of interesting things you can do with this
capability.
First, this is how you get rid of those bleeding console xterms by
- attaching them to host ptys:
+ attaching them to host ptys::
con=pty con0=fd:0,fd:1
@@ -802,7 +799,7 @@
This will make a UML console take over an unused host virtual console,
so that when you switch to it, you will see the UML login prompt
- rather than the host login prompt:
+ rather than the host login prompt::
con1=tty:/dev/tty6
@@ -813,7 +810,7 @@
You can attach two virtual machines together with what amounts to a
serial line as follows:
- Run one UML with a serial line attached to a pty -
+ Run one UML with a serial line attached to a pty::
ssl1=pty
@@ -825,7 +822,7 @@
that it got /dev/ptyp1).
Boot the other UML with a serial line attached to the corresponding
- tty -
+ tty::
ssl1=tty:/dev/ttyp1
@@ -838,7 +835,10 @@
prompt of the other virtual machine.
- 6. Setting up the network
+.. _setting_up_the_network:
+
+6. Setting up the network
+==========================
@@ -858,19 +858,19 @@
There are currently five transport types available for a UML virtual
machine to exchange packets with other hosts:
- o ethertap
+ - ethertap
- o TUN/TAP
+ - TUN/TAP
- o Multicast
+ - Multicast
- o a switch daemon
+ - a switch daemon
- o slip
+ - slip
- o slirp
+ - slirp
- o pcap
+ - pcap
The TUN/TAP, ethertap, slip, and slirp transports allow a UML
instance to exchange packets with the host. They may be directed
@@ -893,28 +893,28 @@
With so many host transports, which one should you use? Here's when
you should use each one:
- o ethertap - if you want access to the host networking and it is
+ - ethertap - if you want access to the host networking and it is
running 2.2
- o TUN/TAP - if you want access to the host networking and it is
+ - TUN/TAP - if you want access to the host networking and it is
running 2.4. Also, the TUN/TAP transport is able to use a
preconfigured device, allowing it to avoid using the setuid uml_net
helper, which is a security advantage.
- o Multicast - if you want a purely virtual network and you don't want
+ - Multicast - if you want a purely virtual network and you don't want
to set up anything but the UML
- o a switch daemon - if you want a purely virtual network and you
+ - a switch daemon - if you want a purely virtual network and you
don't mind running the daemon in order to get somewhat better
performance
- o slip - there is no particular reason to run the slip backend unless
+ - slip - there is no particular reason to run the slip backend unless
ethertap and TUN/TAP are just not available for some reason
- o slirp - if you don't have root access on the host to setup
+ - slirp - if you don't have root access on the host to setup
networking, or if you don't want to allocate an IP to your UML
- o pcap - not much use for actual network connectivity, but great for
+ - pcap - not much use for actual network connectivity, but great for
monitoring traffic on the host
Ethertap is available on 2.4 and works fine. TUN/TAP is preferred
@@ -926,7 +926,8 @@
exploit the helper's root privileges.
- 6.1. General setup
+6.1. General setup
+-------------------
First, you must have the virtual network enabled in your UML. If are
running a prebuilt kernel from this site, everything is already
@@ -938,7 +939,7 @@
The next step is to provide a network device to the virtual machine.
This is done by describing it on the kernel command line.
- The general format is
+ The general format is::
eth <n> = <transport> , <transport args>
@@ -947,7 +948,7 @@
For example, a virtual ethernet device may be attached to a host
- ethertap device as follows:
+ ethertap device as follows::
eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
@@ -978,7 +979,7 @@
You can also add devices to a UML and remove them at runtime. See the
- ``The Management Console'' page for details.
+ :ref:`The_Management_Console` page for details.
The sections below describe this in more detail.
@@ -995,7 +996,8 @@
- 6.2. Userspace daemons
+6.2. Userspace daemons
+-----------------------
You will likely need the setuid helper, or the switch daemon, or both.
They are both installed with the RPM and deb, so if you've installed
@@ -1011,7 +1013,8 @@
- 6.3. Specifying ethernet addresses
+6.3. Specifying ethernet addresses
+-----------------------------------
Below, you will see that the TUN/TAP, ethertap, and daemon interfaces
allow you to specify hardware addresses for the virtual ethernet
@@ -1023,21 +1026,21 @@
sufficient to guarantee a unique hardware address for the device. A
couple of exceptions are:
- o Another set of virtual ethernet devices are on the same network and
+ - Another set of virtual ethernet devices are on the same network and
they are assigned hardware addresses using a different scheme which
may conflict with the UML IP address-based scheme
- o You aren't going to use the device for IP networking, so you don't
+ - You aren't going to use the device for IP networking, so you don't
assign the device an IP address
If you let the driver provide the hardware address, you should make
sure that the device IP address is known before the interface is
- brought up. So, inside UML, this will guarantee that:
+ brought up. So, inside UML, this will guarantee that::
- UML#
- ifconfig eth0 192.168.0.250 up
+ UML#
+ ifconfig eth0 192.168.0.250 up
@@ -1049,13 +1052,14 @@
- 6.4. UML interface setup
+6.4. UML interface setup
+-------------------------
Once the network devices have been described on the command line, you
should boot UML and log in.
- The first thing to do is bring the interface up:
+ The first thing to do is bring the interface up::
UML# ifconfig ethn ip-address up
@@ -1067,7 +1071,7 @@
To reach the rest of the world, you should set a default route to the
- host:
+ host::
UML# route add default gw host ip
@@ -1075,7 +1079,7 @@
- Again, with host ip of 192.168.0.4:
+ Again, with host ip of 192.168.0.4::
UML# route add default gw 192.168.0.4
@@ -1097,29 +1101,25 @@
Note: If you can't communicate with other hosts on your physical
ethernet, it's probably because of a network route that's
automatically set up. If you run 'route -n' and see a route that
- looks like this:
+ looks like this::
- Destination Gateway Genmask Flags Metric Ref Use Iface
- 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
+ Destination Gateway Genmask Flags Metric Ref Use Iface
+ 192.168.0.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0
with a mask that's not 255.255.255.255, then replace it with a route
- to your host:
+ to your host::
UML#
route del -net 192.168.0.0 dev eth0 netmask 255.255.255.0
-
-
-
-
UML#
route add -host 192.168.0.4 dev eth0
@@ -1131,7 +1131,8 @@
- 6.5. Multicast
+6.5. Multicast
+---------------
The simplest way to set up a virtual network between multiple UMLs is
to use the mcast transport. This was written by Harald Welte and is
@@ -1142,7 +1143,7 @@
messages when you bring the device up inside UML.
- To use it, run two UMLs with
+ To use it, run two UMLs with::
eth0=mcast
@@ -1151,16 +1152,12 @@
on their command lines. Log in, configure the ethernet device in each
- machine with different IP addresses:
+ machine with different IP addresses::
UML1# ifconfig eth0 192.168.0.254
-
-
-
-
UML2# ifconfig eth0 192.168.0.253
@@ -1168,7 +1165,7 @@
and they should be able to talk to each other.
- The full set of command line options for this transport are
+ The full set of command line options for this transport are::
@@ -1186,7 +1183,7 @@
This is useful when your network does not support multicast, and
all network connections are simple point to point links.
- The full set of command line options for this transport are
+ The full set of command line options for this transport are::
ethn=ucast,ethernet address,remote address,listen port,remote port
@@ -1194,7 +1191,8 @@
- 6.6. TUN/TAP with the uml_net helper
+6.6. TUN/TAP with the uml_net helper
+-------------------------------------
TUN/TAP is the preferred mechanism on 2.4 to exchange packets with the
host. The TUN/TAP backend has been in UML since 2.4.9-3um.
@@ -1216,7 +1214,7 @@
kernel or as the tun.o module.
The format of the command line switch to attach a device to a TUN/TAP
- device is
+ device is::
eth <n> =tuntap,,, <IP address>
@@ -1226,7 +1224,7 @@
For example, this argument will attach the UML's eth0 to the next
available tap device and assign an ethernet address to it based on its
- IP address
+ IP address::
eth0=tuntap,,,192.168.0.254
@@ -1247,10 +1245,10 @@
There are a couple potential problems with running the TUN/TAP
transport on a 2.4 host kernel
- o TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
+ - TUN/TAP seems not to work on 2.4.3 and earlier. Upgrade the host
kernel or use the ethertap transport.
- o With an upgraded kernel, TUN/TAP may fail with
+ - With an upgraded kernel, TUN/TAP may fail with::
File descriptor in bad state
@@ -1264,12 +1262,12 @@
kernel.
These were pointed out by Tim Robinson <timro at trkr dot net> in
- <http://www.geocrawler.com/> name="this uml-
- user post"> .
+ <http://www.geocrawler.com/> name="this uml-user post"> .
- 6.7. TUN/TAP with a preconfigured tap device
+6.7. TUN/TAP with a preconfigured tap device
+---------------------------------------------
If you prefer not to have UML use uml_net (which is somewhat
insecure), with UML 2.4.17-11, you can set up a TUN/TAP device
@@ -1277,8 +1275,8 @@
there is no need for root assistance. Setting up the device is done
as follows:
- o Create the device with tunctl (available from the UML utilities
- tarball)
+ - Create the device with tunctl (available from the UML utilities
+ tarball)::
@@ -1291,8 +1289,8 @@
where uid is the user id or username that UML will be run as. This
will tell you what device was created.
- o Configure the device IP (change IP addresses and device name to
- suit)
+ - Configure the device IP (change IP addresses and device name to
+ suit)::
@@ -1303,8 +1301,8 @@
- o Set up routing and arping if desired - this is my recipe, there are
- other ways of doing the same thing
+ - Set up routing and arping if desired - this is my recipe, there are
+ other ways of doing the same thing::
host#
@@ -1313,19 +1311,9 @@
host#
route add -host 192.168.0.253 dev tap0
-
-
-
-
-
host#
bash -c 'echo 1 > /proc/sys/net/ipv4/conf/tap0/proxy_arp'
-
-
-
-
-
host#
arp -Ds 192.168.0.253 eth0 pub
@@ -1338,76 +1326,43 @@
utility which reads the information from a config file and sets up
devices at boot time.
- o Rather than using up two IPs and ARPing for one of them, you can
+ - Rather than using up two IPs and ARPing for one of them, you can
also provide direct access to your LAN by the UML by using a
- bridge.
+ bridge::
host#
brctl addbr br0
-
-
-
-
host#
ifconfig eth0 0.0.0.0 promisc up
-
-
-
-
host#
ifconfig tap0 0.0.0.0 promisc up
-
-
-
-
host#
ifconfig br0 192.168.0.1 netmask 255.255.255.0 up
-
-
-
-
-
- host#
- brctl stp br0 off
-
-
-
-
+ host#
+ brctl stp br0 off
host#
brctl setfd br0 1
-
-
-
-
host#
brctl sethello br0 1
-
-
-
-
host#
brctl addif br0 eth0
-
-
-
-
host#
brctl addif br0 tap0
@@ -1417,12 +1372,12 @@
Note that 'br0' should be setup using ifconfig with the existing IP
address of eth0, as eth0 no longer has its own IP.
- o
+ -
Also, the /dev/net/tun device must be writable by the user running
UML in order for the UML to use the device that's been configured
- for it. The simplest thing to do is
+ for it. The simplest thing to do is::
host# chmod 666 /dev/net/tun
@@ -1438,14 +1393,14 @@
devices and chgrp /dev/net/tun to that group with mode 664 or 660.
- o Once the device is set up, run UML with 'eth0=tuntap,device name'
+ - Once the device is set up, run UML with 'eth0=tuntap,device name'
(i.e. 'eth0=tuntap,tap0') on the command line (or do it with the
mconsole config command).
- o Bring the eth device up in UML and you're in business.
+ - Bring the eth device up in UML and you're in business.
If you don't want that tap device any more, you can make it non-
- persistent with
+ persistent with::
host# tunctl -d tap device
@@ -1455,7 +1410,7 @@
Finally, tunctl has a -b (for brief mode) switch which causes it to
output only the name of the tap device it created. This makes it
- suitable for capture by a script:
+ suitable for capture by a script::
host# TAP=`tunctl -u 1000 -b`
@@ -1465,7 +1420,8 @@
- 6.8. Ethertap
+6.8. Ethertap
+--------------
Ethertap is the general mechanism on 2.2 for userspace processes to
exchange packets with the kernel.
@@ -1473,7 +1429,7 @@
To use this transport, you need to describe the virtual network device
- on the UML command line. The general format for this is
+ on the UML command line. The general format for this is::
eth <n> =ethertap, <device> , <ethernet address> , <tap IP address>
@@ -1481,7 +1437,7 @@
- So, the previous example
+ So, the previous example::
eth0=ethertap,tap0,fe:fd:0:0:0:1,192.168.0.254
@@ -1521,7 +1477,7 @@
If you want to set things up yourself, you need to make sure that the
appropriate /dev entry exists. If it doesn't, become root and create
- it as follows:
+ it as follows::
mknod /dev/tap <minor> c 36 <minor> + 16
@@ -1529,7 +1485,7 @@
- For example, this is how to create /dev/tap0:
+ For example, this is how to create /dev/tap0::
mknod /dev/tap0 c 36 0 + 16
@@ -1539,7 +1495,7 @@
You also need to make sure that the host kernel has ethertap support.
If ethertap is enabled as a module, you apparently need to insmod
- ethertap once for each ethertap device you want to enable. So,
+ ethertap once for each ethertap device you want to enable. So,::
host#
@@ -1549,7 +1505,7 @@
will give you the tap0 interface. To get the tap1 interface, you need
- to run
+ to run::
host#
@@ -1561,7 +1517,8 @@
- 6.9. The switch daemon
+6.9. The switch daemon
+-----------------------
Note: This is the daemon formerly known as uml_router, but which was
renamed so the network weenies of the world would stop growling at me.
@@ -1577,7 +1534,7 @@
sockets.
- If you want it to listen on a different pair of sockets, use
+ If you want it to listen on a different pair of sockets, use::
-unix control socket data socket
@@ -1586,7 +1543,7 @@
- If you want it to act as a hub rather than a switch, use
+ If you want it to act as a hub rather than a switch, use::
-hub
@@ -1596,7 +1553,7 @@
If you want the switch to be connected to host networking (allowing
- the umls to get access to the outside world through the host), use
+ the umls to get access to the outside world through the host), use::
-tap tap0
@@ -1610,7 +1567,7 @@
device than tap0, specify that instead of tap0.
- uml_switch can be backgrounded as follows
+ uml_switch can be backgrounded as follows::
host%
@@ -1623,7 +1580,7 @@
stdin for EOF. When it sees that, it exits.
- The general format of the kernel command line switch is
+ The general format of the kernel command line switch is::
@@ -1639,7 +1596,8 @@
how to communicate with the daemon. You should only specify them if
you told the daemon to use different sockets than the default. So, if
you ran the daemon with no arguments, running the UML on the same
- machine with
+ machine with::
+
eth0=daemon
@@ -1649,7 +1607,8 @@
- 6.10. Slip
+6.10. Slip
+-----------
Slip is another, less general, mechanism for a process to communicate
with the host networking. In contrast to the ethertap interface,
@@ -1658,7 +1617,7 @@
IP.
- The general format of the command line switch is
+ The general format of the command line switch is::
@@ -1681,7 +1640,8 @@
- 6.11. Slirp
+6.11. Slirp
+------------
slirp uses an external program, usually /usr/bin/slirp, to provide IP
only networking connectivity through the host. This is similar to IP
@@ -1691,7 +1651,7 @@
root access or setuid binaries on the host.
- The general format of the command line switch for slirp is:
+ The general format of the command line switch for slirp is::
@@ -1716,7 +1676,7 @@
The eth0 interface on UML should be set up with the IP 10.2.0.15,
although you can use anything as long as it is not used by a network
you will be connecting to. The default route on UML should be set to
- use
+ use::
UML#
@@ -1737,10 +1697,11 @@
- 6.12. pcap
+6.12. pcap
+-----------
The pcap transport is attached to a UML ethernet device on the command
- line or with uml_mconsole with the following syntax:
+ line or with uml_mconsole with the following syntax::
@@ -1762,7 +1723,7 @@
expression optimizer is used.
- Example:
+ Example::
@@ -1777,7 +1738,8 @@
- 6.13. Setting up the host yourself
+6.13. Setting up the host yourself
+-----------------------------------
If you don't specify an address for the host side of the ethertap or
slip device, UML won't do any setup on the host. So this is what is
@@ -1785,19 +1747,15 @@
192.168.0.251 and a UML-side IP of 192.168.0.250 - adjust to suit your
own network):
- o The device needs to be configured with its IP address. Tap devices
+ - The device needs to be configured with its IP address. Tap devices
are also configured with an mtu of 1484. Slip devices are
configured with a point-to-point address pointing at the UML ip
- address.
+ address::
host# ifconfig tap0 arp mtu 1484 192.168.0.251 up
-
-
-
-
host#
ifconfig sl0 192.168.0.251 pointopoint 192.168.0.250 up
@@ -1805,7 +1763,7 @@
- o If a tap device is being set up, a route is set to the UML IP.
+ - If a tap device is being set up, a route is set to the UML IP::
UML# route add -host 192.168.0.250 gw 192.168.0.251
@@ -1814,8 +1772,8 @@
- o To allow other hosts on your network to see the virtual machine,
- proxy arp is set up for it.
+ - To allow other hosts on your network to see the virtual machine,
+ proxy arp is set up for it::
host# arp -Ds 192.168.0.250 eth0 pub
@@ -1824,7 +1782,7 @@
- o Finally, the host is set up to route packets.
+ - Finally, the host is set up to route packets::
host# echo 1 > /proc/sys/net/ipv4/ip_forward
@@ -1838,12 +1796,14 @@
- 7. Sharing Filesystems between Virtual Machines
+7. Sharing Filesystems between Virtual Machines
+================================================
- 7.1. A warning
+7.1. A warning
+---------------
Don't attempt to share filesystems simply by booting two UMLs from the
same file. That's the same thing as booting two physical machines
@@ -1851,7 +1811,8 @@
- 7.2. Using layered block devices
+7.2. Using layered block devices
+---------------------------------
The way to share a filesystem between two virtual machines is to use
the copy-on-write (COW) layering capability of the ubd block driver.
@@ -1872,7 +1833,7 @@
To add a copy-on-write layer to an existing block device file, simply
- add the name of the COW file to the appropriate ubd switch:
+ add the name of the COW file to the appropriate ubd switch::
ubd0=root_fs_cow,root_fs_debian_22
@@ -1883,7 +1844,7 @@
where 'root_fs_cow' is the private COW file and 'root_fs_debian_22' is
the existing shared filesystem. The COW file need not exist. If it
doesn't, the driver will create and initialize it. Once the COW file
- has been initialized, it can be used on its own on the command line:
+ has been initialized, it can be used on its own on the command line::
ubd0=root_fs_cow
@@ -1896,14 +1857,16 @@
- 7.3. Note!
+7.3. Note!
+-----------
When checking the size of the COW file in order to see the gobs of
space that you're saving, make sure you use 'ls -ls' to see the actual
disk consumption rather than the length of the file. The COW file is
sparse, so the length will be very different from the disk usage.
Here is a 'ls -l' of a COW file and backing file from one boot and
- shutdown:
+ shutdown::
+
host% ls -l cow.debian debian2.2
-rw-r--r-- 1 jdike jdike 492504064 Aug 6 21:16 cow.debian
-rwxrw-rw- 1 jdike jdike 537919488 Aug 6 20:42 debian2.2
@@ -1911,7 +1874,7 @@
- Doesn't look like much saved space, does it? Well, here's 'ls -ls':
+ Doesn't look like much saved space, does it? Well, here's 'ls -ls'::
host% ls -ls cow.debian debian2.2
@@ -1926,7 +1889,8 @@
- 7.4. Another warning
+7.4. Another warning
+---------------------
Once a filesystem is being used as a readonly backing file for a COW
file, do not boot directly from it or modify it in any way. Doing so
@@ -1952,7 +1916,8 @@
- 7.5. uml_moo : Merging a COW file with its backing file
+7.5. uml_moo : Merging a COW file with its backing file
+--------------------------------------------------------
Depending on how you use UML and COW devices, it may be advisable to
merge the changes in the COW file into the backing file every once in
@@ -1961,7 +1926,7 @@
- The utility that does this is uml_moo. Its usage is
+ The utility that does this is uml_moo. Its usage is::
host% uml_moo COW file new backing file
@@ -2001,7 +1966,8 @@
- 8. Creating filesystems
+8. Creating filesystems
+========================
You may want to create and mount new UML filesystems, either because
@@ -2015,13 +1981,14 @@
should be easy to translate to the filesystem of your choice.
- 8.1. Create the filesystem file
+8.1. Create the filesystem file
+================================
dd is your friend. All you need to do is tell dd to create an empty
file of the appropriate size. I usually make it sparse to save time
and to avoid allocating disk space until it's actually used. For
example, the following command will create a sparse 100 meg file full
- of zeroes.
+ of zeroes::
host%
@@ -2034,9 +2001,9 @@
8.2. Assign the file to a UML device
- Add an argument like the following to the UML command line:
+ Add an argument like the following to the UML command line::
- ubd4=new_filesystem
+ ubd4=new_filesystem
@@ -2053,7 +2020,7 @@
etc), then get them into UML by way of the net or hostfs.
- Make the new filesystem on the device assigned to the new file:
+ Make the new filesystem on the device assigned to the new file::
host# mkreiserfs /dev/ubd/4
@@ -2077,7 +2044,7 @@
- Now, mount it:
+ Now, mount it::
UML#
@@ -2096,7 +2063,8 @@
- 9. Host file access
+9. Host file access
+====================
If you want to access files on the host machine from inside UML, you
@@ -2112,10 +2080,11 @@
files contained in it just as you would on the host.
- 9.1. Using hostfs
+9.1. Using hostfs
+------------------
To begin with, make sure that hostfs is available inside the virtual
- machine with
+ machine with::
UML# cat /proc/filesystems
@@ -2127,7 +2096,7 @@
module and available inside the virtual machine, and insmod it.
- Now all you need to do is run mount:
+ Now all you need to do is run mount::
UML# mount none /mnt/host -t hostfs
@@ -2139,7 +2108,7 @@
If you don't want to mount the host root directory, then you can
- specify a subdirectory to mount with the -o switch to mount:
+ specify a subdirectory to mount with the -o switch to mount::
UML# mount none /mnt/home -t hostfs -o /home
@@ -2151,13 +2120,14 @@
- 9.2. hostfs as the root filesystem
+9.2. hostfs as the root filesystem
+-----------------------------------
It's possible to boot from a directory hierarchy on the host using
hostfs rather than using the standard filesystem in a file.
To start, you need that hierarchy. The easiest way is to loop mount
- an existing root_fs file:
+ an existing root_fs file::
host# mount root_fs uml_root_dir -o loop
@@ -2166,15 +2136,15 @@
You need to change the filesystem type of / in etc/fstab to be
- 'hostfs', so that line looks like this:
+ 'hostfs', so that line looks like this::
- /dev/ubd/0 / hostfs defaults 1 1
+ /dev/ubd/0 / hostfs defaults 1 1
Then you need to chown to yourself all the files in that directory
- that are owned by root. This worked for me:
+ that are owned by root. This worked for me::
host# find . -uid 0 -exec chown jdike {} \;
@@ -2183,7 +2153,7 @@
Next, make sure that your UML kernel has hostfs compiled in, not as a
- module. Then run UML with the boot device pointing at that directory:
+ module. Then run UML with the boot device pointing at that directory::
ubd0=/path/to/uml/root/directory
@@ -2194,41 +2164,35 @@
UML should then boot as it does normally.
- 9.3. Building hostfs
+9.3. Building hostfs
+---------------------
If you need to build hostfs because it's not in your kernel, you have
two choices:
- o Compiling hostfs into the kernel:
+ - Compiling hostfs into the kernel:
Reconfigure the kernel and set the 'Host filesystem' option under
- o Compiling hostfs as a module:
+ - Compiling hostfs as a module:
Reconfigure the kernel and set the 'Host filesystem' option under
be in arch/um/fs/hostfs/hostfs.o. Install that in
- /lib/modules/`uname -r`/fs in the virtual machine, boot it up, and
+ ``/lib/modules/$(uname -r)/fs`` in the virtual machine, boot it up, and::
UML# insmod hostfs
+.. _The_Management_Console:
-
-
-
-
-
-
-
-
-
- 10. The Management Console
+10. The Management Console
+===========================
@@ -2240,15 +2204,15 @@
There are a number of things you can do with the mconsole interface:
- o get the kernel version
+ - get the kernel version
- o add and remove devices
+ - add and remove devices
- o halt or reboot the machine
+ - halt or reboot the machine
- o Send SysRq commands
+ - Send SysRq commands
- o Pause and resume the UML
+ - Pause and resume the UML
You need the mconsole client (uml_mconsole) which is present in CVS
@@ -2257,7 +2221,7 @@
You also need CONFIG_MCONSOLE (under 'General Setup') enabled in UML.
- When you boot UML, you'll see a line like:
+ When you boot UML, you'll see a line like::
mconsole initialized on /home/jdike/.uml/umlNJ32yL/mconsole
@@ -2265,7 +2229,7 @@
- If you specify a unique machine id one the UML command line, i.e.
+ If you specify a unique machine id one the UML command line, i.e.::
umid=debian
@@ -2273,7 +2237,7 @@
- you'll see this
+ you'll see this::
mconsole initialized on /home/jdike/.uml/debian/mconsole
@@ -2282,7 +2246,7 @@
That file is the socket that uml_mconsole will use to communicate with
- UML. Run it with either the umid or the full path as its argument:
+ UML. Run it with either the umid or the full path as its argument::
host% uml_mconsole debian
@@ -2290,7 +2254,7 @@
- or
+ or::
host% uml_mconsole /home/jdike/.uml/debian/mconsole
@@ -2300,30 +2264,31 @@
You'll get a prompt, at which you can run one of these commands:
- o version
+ - version
- o halt
+ - halt
- o reboot
+ - reboot
- o config
+ - config
- o remove
+ - remove
- o sysrq
+ - sysrq
- o help
+ - help
- o cad
+ - cad
- o stop
+ - stop
- o go
+ - go
- 10.1. version
+10.1. version
+--------------
- This takes no arguments. It prints the UML version.
+ This takes no arguments. It prints the UML version::
(mconsole) version
@@ -2342,11 +2307,12 @@
- 10.2. halt and reboot
+10.2. halt and reboot
+----------------------
These take no arguments. They shut the machine down immediately, with
no syncing of disks and no clean shutdown of userspace. So, they are
- pretty close to crashing the machine.
+ pretty close to crashing the machine::
(mconsole) halt
@@ -2357,34 +2323,36 @@
- 10.3. config
+10.3. config
+-------------
"config" adds a new device to the virtual machine. Currently the ubd
and network drivers support this. It takes one argument, which is the
- device to add, with the same syntax as the kernel command line.
+ device to add, with the same syntax as the kernel command line::
- (mconsole)
- config ubd3=/home/jdike/incoming/roots/root_fs_debian22
+ (mconsole)
+ config ubd3=/home/jdike/incoming/roots/root_fs_debian22
- OK
- (mconsole) config eth1=mcast
- OK
+ OK
+ (mconsole) config eth1=mcast
+ OK
- 10.4. remove
+10.4. remove
+-------------
"remove" deletes a device from the system. Its argument is just the
name of the device to be removed. The device must be idle in whatever
sense the driver considers necessary. In the case of the ubd driver,
the removed block device must not be mounted, swapped on, or otherwise
- open, and in the case of the network driver, the device must be down.
+ open, and in the case of the network driver, the device must be down::
(mconsole) remove ubd3
@@ -2397,7 +2365,8 @@
- 10.5. sysrq
+10.5. sysrq
+------------
This takes one argument, which is a single letter. It calls the
generic kernel's SysRq driver, which does whatever is called for by
@@ -2407,19 +2376,21 @@
- 10.6. help
+10.6. help
+-----------
"help" returns a string listing the valid commands and what each one
does.
- 10.7. cad
+10.7. cad
+----------
This invokes the Ctl-Alt-Del action on init. What exactly this ends
up doing is up to /etc/inittab. Normally, it reboots the machine.
With UML, this is usually not desired, so if a halt would be better,
- then find the section of inittab that looks like this
+ then find the section of inittab that looks like this::
# What to do when CTRL-ALT-DEL is pressed.
@@ -2432,7 +2403,8 @@
- 10.8. stop
+10.8. stop
+-----------
This puts the UML in a loop reading mconsole requests until a 'go'
mconsole command is received. This is very useful for making backups
@@ -2448,7 +2420,8 @@
- 10.9. go
+10.9. go
+---------
This resumes a UML after being paused by a 'stop' command. Note that
when the UML has resumed, TCP connections may have timed out and if
@@ -2460,9 +2433,10 @@
+.. _Kernel_debugging:
-
- 11. Kernel debugging
+11. Kernel debugging
+=====================
Note: The interface that makes debugging, as described here, possible
@@ -2477,15 +2451,16 @@
In order to debug the kernel, you need build it from source. See
- ``Compiling the kernel and modules'' for information on doing that.
+ :ref:`Compiling_the_kernel_and_modules` for information on doing that.
Make sure that you enable CONFIG_DEBUGSYM and CONFIG_PT_PROXY during
- the config. These will compile the kernel with -g, and enable the
+ the config. These will compile the kernel with ``-g``, and enable the
ptrace proxy so that gdb works with UML, respectively.
- 11.1. Starting the kernel under gdb
+11.1. Starting the kernel under gdb
+------------------------------------
You can have the kernel running under the control of gdb from the
beginning by putting 'debug' on the command line. You will get an
@@ -2498,7 +2473,11 @@
There is a transcript of a debugging session here <debug-
session.html> , with breakpoints being set in the scheduler and in an
interrupt handler.
- 11.2. Examining sleeping processes
+
+
+11.2. Examining sleeping processes
+-----------------------------------
+
Not every bug is evident in the currently running process. Sometimes,
processes hang in the kernel when they shouldn't because they've
@@ -2516,7 +2495,7 @@
Now what you do is this:
- o detach from the current thread
+ - detach from the current thread::
(UML gdb) det
@@ -2525,7 +2504,7 @@
- o attach to the thread you are interested in
+ - attach to the thread you are interested in::
(UML gdb) att <host pid>
@@ -2534,7 +2513,7 @@
- o look at its stack and anything else of interest
+ - look at its stack and anything else of interest::
(UML gdb) bt
@@ -2545,18 +2524,14 @@
Note that you can't do anything at this point that requires that a
process execute, e.g. calling a function
- o when you're done looking at that process, reattach to the current
- thread and continue it
+ - when you're done looking at that process, reattach to the current
+ thread and continue it::
(UML gdb)
att 1
-
-
-
-
(UML gdb)
c
@@ -2569,12 +2544,13 @@
- 11.3. Running ddd on UML
+11.3. Running ddd on UML
+-------------------------
ddd works on UML, but requires a special kludge. The process goes
like this:
- o Start ddd
+ - Start ddd::
host% ddd linux
@@ -2583,14 +2559,14 @@
- o With ps, get the pid of the gdb that ddd started. You can ask the
+ - With ps, get the pid of the gdb that ddd started. You can ask the
gdb to tell you, but for some reason that confuses things and
causes a hang.
- o run UML with 'debug=parent gdb-pid=<pid>' added to the command line
+ - run UML with 'debug=parent gdb-pid=<pid>' added to the command line
- it will just sit there after you hit return
- o type 'att 1' to the ddd gdb and you will see something like
+ - type 'att 1' to the ddd gdb and you will see something like::
0xa013dc51 in __kill ()
@@ -2602,12 +2578,14 @@
- o At this point, type 'c', UML will boot up, and you can use ddd just
+ - At this point, type 'c', UML will boot up, and you can use ddd just
as you do on any other process.
- 11.4. Debugging modules
+11.4. Debugging modules
+------------------------
+
gdb has support for debugging code which is dynamically loaded into
the process. This support is what is needed to debug kernel modules
@@ -2629,7 +2607,8 @@
First, you must tell it where your modules are. There is a list in
- the script that looks like this:
+ the script that looks like this::
+
set MODULE_PATHS {
"fat" "/usr/src/uml/linux-2.4.18/fs/fat/fat.o"
"isofs" "/usr/src/uml/linux-2.4.18/fs/isofs/isofs.o"
@@ -2641,9 +2620,7 @@
You change that to list the names and paths of the modules that you
are going to debug. Then you run it from the toplevel directory of
- your UML pool and it basically tells you what to do:
-
-
+ your UML pool and it basically tells you what to do::
******** GDB pid is 21903 ********
@@ -2666,7 +2643,7 @@
After you run UML and it sits there doing nothing, you hit return at
- the 'att 1' and continue it:
+ the 'att 1' and continue it::
Attaching to program: /home/jdike/linux/2.4/um/./linux, process 1
@@ -2678,63 +2655,48 @@
At this point, you debug normally. When you insmod something, the
- expect magic will kick in and you'll see something like:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- *** Module hostfs loaded ***
- Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
- mod_user=0x8070e00) at module.c:349
- 349 char *name, *n_name, *name_tmp = NULL;
- (UML gdb) finish
- Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
- mod_user=0x8070e00) at module.c:349
- 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
- 411 else res = EXECUTE_SYSCALL(syscall, regs);
- Value returned is $1 = 0
- (UML gdb)
- p/x (int)module_list + module_list->size_of_struct
-
- $2 = 0xa9021054
- (UML gdb) symbol-file ./linux
- Load new symbol table from "./linux"? (y or n) y
- Reading symbols from ./linux...
- done.
- (UML gdb)
- add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
-
- add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
- .text_addr = 0xa9021054
- (y or n) y
-
- Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
- done.
- (UML gdb) p *module_list
- $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
- size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
- nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
- init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
- ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
- persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
- kallsyms_end = 0x0,
- archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
- archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
- kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
- >> Finished loading symbols for hostfs ...
+ expect magic will kick in and you'll see something like::
+
+
+ *** Module hostfs loaded ***
+ Breakpoint 1, sys_init_module (name_user=0x805abb0 "hostfs",
+ mod_user=0x8070e00) at module.c:349
+ 349 char *name, *n_name, *name_tmp = NULL;
+ (UML gdb) finish
+ Run till exit from #0 sys_init_module (name_user=0x805abb0 "hostfs",
+ mod_user=0x8070e00) at module.c:349
+ 0xa00e2e23 in execute_syscall (r=0xa8140284) at syscall_kern.c:411
+ 411 else res = EXECUTE_SYSCALL(syscall, regs);
+ Value returned is $1 = 0
+ (UML gdb)
+ p/x (int)module_list + module_list->size_of_struct
+
+ $2 = 0xa9021054
+ (UML gdb) symbol-file ./linux
+ Load new symbol table from "./linux"? (y or n) y
+ Reading symbols from ./linux...
+ done.
+ (UML gdb)
+ add-symbol-file /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o 0xa9021054
+
+ add symbol table from file "/home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o" at
+ .text_addr = 0xa9021054
+ (y or n) y
+
+ Reading symbols from /home/jdike/linux/2.4/um/arch/um/fs/hostfs/hostfs.o...
+ done.
+ (UML gdb) p *module_list
+ $1 = {size_of_struct = 84, next = 0xa0178720, name = 0xa9022de0 "hostfs",
+ size = 9016, uc = {usecount = {counter = 0}, pad = 0}, flags = 1,
+ nsyms = 57, ndeps = 0, syms = 0xa9023170, deps = 0x0, refs = 0x0,
+ init = 0xa90221f0 <init_hostfs>, cleanup = 0xa902222c <exit_hostfs>,
+ ex_table_start = 0x0, ex_table_end = 0x0, persist_start = 0x0,
+ persist_end = 0x0, can_unload = 0, runsize = 0, kallsyms_start = 0x0,
+ kallsyms_end = 0x0,
+ archdata_start = 0x1b855 <Address 0x1b855 out of bounds>,
+ archdata_end = 0xe5890000 <Address 0xe5890000 out of bounds>,
+ kernel_data = 0xf689c35d <Address 0xf689c35d out of bounds>}
+ >> Finished loading symbols for hostfs ...
@@ -2744,7 +2706,7 @@
Boot the kernel under the debugger and load the module with insmod or
- modprobe. With gdb, do:
+ modprobe. With gdb, do::
(UML gdb) p module_list
@@ -2758,12 +2720,12 @@
the name fields until find the module you want to debug. Take the
address of that structure, and add module.size_of_struct (which in
2.4.10 kernels is 96 (0x60)) to it. Gdb can make this hard addition
- for you :-):
+ for you :-)::
- (UML gdb)
- printf "%#x\n", (int)module_list module_list->size_of_struct
+ (UML gdb)
+ printf "%#x\n", (int)module_list module_list->size_of_struct
@@ -2771,7 +2733,7 @@
The offset from the module start occasionally changes (before 2.4.0,
it was module.size_of_struct + 4), so it's a good idea to check the
init and cleanup addresses once in a while, as describe below. Now
- do:
+ do::
(UML gdb)
@@ -2786,7 +2748,7 @@
If there's any doubt that you got the offset right, like breakpoints
appear not to work, or they're appearing in the wrong place, you can
check it by looking at the module structure. The init and cleanup
- fields should look like:
+ fields should look like::
init = 0x588066b0 <init_hostfs>, cleanup = 0x588066c0 <exit_hostfs>
@@ -2801,7 +2763,7 @@
When you want to load in a new version of the module, you need to get
gdb to forget about the old one. The only way I've found to do that
- is to tell gdb to forget about all symbols that it knows about:
+ is to tell gdb to forget about all symbols that it knows about::
(UML gdb) symbol-file
@@ -2809,7 +2771,7 @@
- Then reload the symbols from the kernel binary:
+ Then reload the symbols from the kernel binary::
(UML gdb) symbol-file /path/to/kernel
@@ -2823,17 +2785,19 @@
- 11.5. Attaching gdb to the kernel
+11.5. Attaching gdb to the kernel
+----------------------------------
If you don't have the kernel running under gdb, you can attach gdb to
it later by sending the tracing thread a SIGUSR1. The first line of
- the console output identifies its pid:
+ the console output identifies its pid::
+
tracing thread pid = 20093
- When you send it the signal:
+ When you send it the signal::
host% kill -USR1 20093
@@ -2845,7 +2809,7 @@
If you have the mconsole compiled into UML, then the mconsole client
- can be used to start gdb:
+ can be used to start gdb::
(mconsole) (mconsole) config gdb=xterm
@@ -2857,7 +2821,8 @@
- 11.6. Using alternate debuggers
+11.6. Using alternate debuggers
+--------------------------------
UML has support for attaching to an already running debugger rather
than starting gdb itself. This is present in CVS as of 17 Apr 2001.
@@ -2886,7 +2851,7 @@
An example of an alternate debugger is strace. You can strace the
actual kernel as follows:
- o Run the following in a shell
+ - Run the following in a shell::
host%
@@ -2894,13 +2859,13 @@
- o Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
+ - Run UML with 'debug' and 'gdb-pid=<pid>' with the pid printed out
by the previous command
- o Hit return in the shell, and UML will start running, and strace
+ - Hit return in the shell, and UML will start running, and strace
output will start accumulating in the output file.
- Note that this is different from running
+ Note that this is different from running::
host% strace ./linux
@@ -2917,95 +2882,57 @@
- 12. Kernel debugging examples
+12. Kernel debugging examples
+==============================
- 12.1. The case of the hung fsck
+12.1. The case of the hung fsck
+--------------------------------
When booting up the kernel, fsck failed, and dropped me into a shell
- to fix things up. I ran fsck -y, which hung:
+ to fix things up. I ran fsck -y, which hung::
+ Setting hostname uml [ OK ]
+ Checking root filesystem
+ /dev/fhd0 was not cleanly unmounted, check forced.
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
+ /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
+ (i.e., without -a or -p options)
+ [ FAILED ]
+ *** An error occurred during the file system check.
+ *** Dropping you to a shell; the system will reboot
+ *** when you leave the shell.
+ Give root password for maintenance
+ (or type Control-D for normal startup):
+ [root@uml /root]# fsck -y /dev/fhd0
+ fsck -y /dev/fhd0
+ Parallelizing fsck version 1.14 (9-Jan-1999)
+ e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
+ /dev/fhd0 contains a file system with errors, check forced.
+ Pass 1: Checking inodes, blocks, and sizes
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
+ Inode 19780, i_blocks is 1548, should be 540. Fix? yes
+ Pass 2: Checking directory structure
+ Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
+ Directory inode 11858, block 0, offset 0: directory corrupted
+ Salvage? yes
+ Missing '.' in directory inode 11858.
+ Fix? yes
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Setting hostname uml [ OK ]
- Checking root filesystem
- /dev/fhd0 was not cleanly unmounted, check forced.
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
-
- /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
- (i.e., without -a or -p options)
- [ FAILED ]
-
- *** An error occurred during the file system check.
- *** Dropping you to a shell; the system will reboot
- *** when you leave the shell.
- Give root password for maintenance
- (or type Control-D for normal startup):
-
- [root@uml /root]# fsck -y /dev/fhd0
- fsck -y /dev/fhd0
- Parallelizing fsck version 1.14 (9-Jan-1999)
- e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
- /dev/fhd0 contains a file system with errors, check forced.
- Pass 1: Checking inodes, blocks, and sizes
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
-
- Inode 19780, i_blocks is 1548, should be 540. Fix? yes
-
- Pass 2: Checking directory structure
- Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
-
- Directory inode 11858, block 0, offset 0: directory corrupted
- Salvage? yes
-
- Missing '.' in directory inode 11858.
- Fix? yes
-
- Missing '..' in directory inode 11858.
- Fix? yes
-
-
-
+ Missing '..' in directory inode 11858.
+ Fix? yes
The standard drill in this sort of situation is to fire up gdb on the
signal thread, which, in this case, was pid 1935. In another window,
- I run gdb and attach pid 1935.
-
-
+ I run gdb and attach pid 1935::
~/linux/2.3.26/um 1016: gdb linux
@@ -3022,11 +2949,7 @@
0x100756d9 in __wait4 ()
-
-
-
-
- Let's see what's currently running:
+ Let's see what's currently running::
@@ -3041,7 +2964,7 @@
reason and never woke up.
- Let's guess that the last process in the process list is fsck:
+ Let's guess that the last process in the process list is fsck::
@@ -3052,7 +2975,7 @@
- It is, so let's see what it thinks it's up to:
+ It is, so let's see what it thinks it's up to::
@@ -3068,8 +2991,6 @@
-
-
The interesting things here are the fact that its .thread.syscall.id
is __NR_write (see the big switch in arch/um/kernel/syscall_kern.c or
the defines in include/asm-um/arch/unistd.h), and that it never
@@ -3081,30 +3002,20 @@
The fact that it never returned from write means that its stack should
be fairly interesting. Its pid is 1980 (.thread.extern_pid). That
process is being ptraced by the signal thread, so it must be detached
- before gdb can attach it:
+ before gdb can attach it::
+ (gdb) call detach(1980)
-
-
-
-
-
-
- (gdb) call detach(1980)
-
- Program received signal SIGSEGV, Segmentation fault.
- <function called from gdb>
- The program being debugged stopped while in a function called from GDB.
- When the function (detach) is done executing, GDB will silently
- stop (instead of continuing to evaluate the expression containing
- the function call).
- (gdb) call detach(1980)
- $15 = 0
-
-
-
+ Program received signal SIGSEGV, Segmentation fault.
+ <function called from gdb>
+ The program being debugged stopped while in a function called from GDB.
+ When the function (detach) is done executing, GDB will silently
+ stop (instead of continuing to evaluate the expression containing
+ the function call).
+ (gdb) call detach(1980)
+ $15 = 0
The first detach segfaults for some reason, and the second one
@@ -3112,7 +3023,7 @@
Now I detach from the signal thread, attach to the fsck thread, and
- look at its stack:
+ look at its stack::
(gdb) det
@@ -3152,14 +3063,14 @@
- The interesting things here are :
+ The interesting things here are:
- o There are two segfaults on this stack (frames 9 and 14)
+ - There are two segfaults on this stack (frames 9 and 14)
- o The first faulting address (frame 11) is 0x50000800
+ - The first faulting address (frame 11) is 0x50000800::
- (gdb) p (void *)1342179328
- $16 = (void *) 0x50000800
+ (gdb) p (void *)1342179328
+ $16 = (void *) 0x50000800
@@ -3175,7 +3086,7 @@
However, the more immediate problem is that second segfault and I'm
going to concentrate on that. First, I want to see where the fault
- happened, so I have to go look at the sigcontent struct in frame 8:
+ happened, so I have to go look at the sigcontent struct in frame 8::
@@ -3211,7 +3122,7 @@
- That's not very useful, so I'll try a more manual method:
+ That's not very useful, so I'll try a more manual method::
(gdb) p *((struct sigcontext *) (&sig + 1))
@@ -3224,7 +3135,7 @@
- The ip is in handle_mm_fault:
+ The ip is in handle_mm_fault::
(gdb) p (void *)268480945
@@ -3236,7 +3147,7 @@
- Specifically, it's in pte_alloc:
+ Specifically, it's in pte_alloc::
(gdb) i line *$20
@@ -3249,7 +3160,7 @@
To find where in handle_mm_fault this is, I'll jump forward in the
- code until I see an address in that procedure:
+ code until I see an address in that procedure::
@@ -3286,21 +3197,21 @@
Something is apparently wrong with the page tables or vma_structs, so
- lets go back to frame 11 and have a look at them:
+ lets go back to frame 11 and have a look at them::
- #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
- 50 handle_mm_fault(current, vma, address, is_write);
- (gdb) call pgd_offset_proc(vma->vm_mm, address)
- $22 = (pgd_t *) 0x80a548c
+ #11 0x1006c0aa in segv (address=1342179328, is_write=2) at trap_kern.c:50
+ 50 handle_mm_fault(current, vma, address, is_write);
+ (gdb) call pgd_offset_proc(vma->vm_mm, address)
+ $22 = (pgd_t *) 0x80a548c
That's pretty bogus. Page tables aren't supposed to be in process
- text or data areas. Let's see what's in the vma:
+ text or data areas. Let's see what's in the vma::
(gdb) p *vma
@@ -3325,12 +3236,9 @@
-
-
This also pretty bogus. With all of the 0x80xxxxx and 0xaffffxxx
addresses, this is looking like a stack was plonked down on top of
- these structures. Maybe it's a stack overflow from the next page:
-
+ these structures. Maybe it's a stack overflow from the next page::
(gdb) p vma
@@ -3338,52 +3246,36 @@
-
-
That's towards the lower quarter of the page, so that would have to
- have been pretty heavy stack overflow:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- (gdb) x/100x $25
- 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
- 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
- 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
- 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
- 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
- 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
- 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
- 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
-
-
+ have been pretty heavy stack overflow::
+
+
+ (gdb) x/100x $25
+ 0x507d2434: 0x507d2434 0x00000000 0x08048000 0x080a4f8c
+ 0x507d2444: 0x00000000 0x080a79e0 0x080a8c94 0x080d1000
+ 0x507d2454: 0xaffffdb0 0xaffffe63 0xaffffe7a 0xaffffe7a
+ 0x507d2464: 0xafffffec 0x00000062 0x0000008a 0x00000000
+ 0x507d2474: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2484: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2494: 0x00000000 0x00000000 0x507d2fe0 0x00000000
+ 0x507d24a4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24b4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24c4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24d4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24e4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d24f4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2504: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2514: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2524: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2534: 0x00000000 0x00000000 0x507d25dc 0x00000000
+ 0x507d2544: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2554: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2564: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2574: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2584: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d2594: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d25a4: 0x00000000 0x00000000 0x00000000 0x00000000
+ 0x507d25b4: 0x00000000 0x00000000 0x00000000 0x00000000
@@ -3399,65 +3291,53 @@
on will be somewhat clearer.
- 12.2. Episode 2: The case of the hung fsck
+12.2. Episode 2: The case of the hung fsck
+-------------------------------------------
After setting a trap in the SEGV handler for accesses to the signal
thread's stack, I reran the kernel.
- fsck hung again, this time by hitting the trap:
+ fsck hung again, this time by hitting the trap::
+ Setting hostname uml [ OK ]
+ Checking root filesystem
+ /dev/fhd0 contains a file system with errors, check forced.
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
+ /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
+ (i.e., without -a or -p options)
+ [ FAILED ]
+ *** An error occurred during the file system check.
+ *** Dropping you to a shell; the system will reboot
+ *** when you leave the shell.
+ Give root password for maintenance
+ (or type Control-D for normal startup):
+ [root@uml /root]# fsck -y /dev/fhd0
+ fsck -y /dev/fhd0
+ Parallelizing fsck version 1.14 (9-Jan-1999)
+ e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
+ /dev/fhd0 contains a file system with errors, check forced.
+ Pass 1: Checking inodes, blocks, and sizes
+ Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
+ Pass 2: Checking directory structure
+ Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
+ Directory inode 11858, block 0, offset 0: directory corrupted
+ Salvage? yes
+ Missing '.' in directory inode 11858.
+ Fix? yes
+ Missing '..' in directory inode 11858.
+ Fix? yes
-
-
-
-
-
- Setting hostname uml [ OK ]
- Checking root filesystem
- /dev/fhd0 contains a file system with errors, check forced.
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780.
-
- /dev/fhd0: UNEXPECTED INCONSISTENCY; RUN fsck MANUALLY.
- (i.e., without -a or -p options)
- [ FAILED ]
-
- *** An error occurred during the file system check.
- *** Dropping you to a shell; the system will reboot
- *** when you leave the shell.
- Give root password for maintenance
- (or type Control-D for normal startup):
-
- [root@uml /root]# fsck -y /dev/fhd0
- fsck -y /dev/fhd0
- Parallelizing fsck version 1.14 (9-Jan-1999)
- e2fsck 1.14, 9-Jan-1999 for EXT2 FS 0.5b, 95/08/09
- /dev/fhd0 contains a file system with errors, check forced.
- Pass 1: Checking inodes, blocks, and sizes
- Error reading block 86894 (Attempt to read block from filesystem resulted in short read) while reading indirect blocks of inode 19780. Ignore error? yes
-
- Pass 2: Checking directory structure
- Error reading block 49405 (Attempt to read block from filesystem resulted in short read). Ignore error? yes
-
- Directory inode 11858, block 0, offset 0: directory corrupted
- Salvage? yes
-
- Missing '.' in directory inode 11858.
- Fix? yes
-
- Missing '..' in directory inode 11858.
- Fix? yes
-
- Untested (4127) [100fe44c]: trap_kern.c line 31
+ Untested (4127) [100fe44c]: trap_kern.c line 31
@@ -3465,7 +3345,7 @@
I need to get the signal thread to detach from pid 4127 so that I can
attach to it with gdb. This is done by sending it a SIGUSR1, which is
- caught by the signal thread, which detaches the process:
+ caught by the signal thread, which detaches the process::
kill -USR1 4127
@@ -3474,31 +3354,20 @@
- Now I can run gdb on it:
-
-
-
-
-
-
-
-
-
-
-
-
-
- ~/linux/2.3.26/um 1034: gdb linux
- GNU gdb 4.17.0.11 with Linux support
- Copyright 1998 Free Software Foundation, Inc.
- GDB is free software, covered by the GNU General Public License, and you are
- welcome to change it and/or distribute copies of it under certain conditions.
- Type "show copying" to see the conditions.
- There is absolutely no warranty for GDB. Type "show warranty" for details.
- This GDB was configured as "i386-redhat-linux"...
- (gdb) att 4127
- Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
- 0x10075891 in __libc_nanosleep ()
+ Now I can run gdb on it::
+
+
+ ~/linux/2.3.26/um 1034: gdb linux
+ GNU gdb 4.17.0.11 with Linux support
+ Copyright 1998 Free Software Foundation, Inc.
+ GDB is free software, covered by the GNU General Public License, and you are
+ welcome to change it and/or distribute copies of it under certain conditions.
+ Type "show copying" to see the conditions.
+ There is absolutely no warranty for GDB. Type "show warranty" for details.
+ This GDB was configured as "i386-redhat-linux"...
+ (gdb) att 4127
+ Attaching to program `/home/dike/linux/2.3.26/um/linux', Pid 4127
+ 0x10075891 in __libc_nanosleep ()
@@ -3506,7 +3375,7 @@
The backtrace shows that it was in a write and that the fault address
(address in frame 3) is 0x50000800, which is right in the middle of
- the signal thread's stack page:
+ the signal thread's stack page::
(gdb) bt
@@ -3540,58 +3409,48 @@
-
-
Going up the stack to the segv_handler frame and looking at where in
the code the access happened shows that it happened near line 110 of
- block_dev.c:
-
-
-
-
-
-
-
-
-
- (gdb) up
- #1 0x1007584d in __sleep (seconds=1000000)
- at ../sysdeps/unix/sysv/linux/sleep.c:78
- ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
- (gdb)
- #2 0x1006ce9a in stop () at user_util.c:191
- 191 while(1) sleep(1000000);
- (gdb)
- #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
- 31 KERN_UNTESTED();
- (gdb)
- #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
- 174 segv(sc->cr2, sc->err & 2);
- (gdb) p *sc
- $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
- __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
- esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
- err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
- esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
- cr2 = 1342179328}
- (gdb) p (void *)268550834
- $2 = (void *) 0x1001c2b2
- (gdb) i sym $2
- block_write + 1090 in section .text
- (gdb) i line *$2
- Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
- starts at address 0x1001c2a1 <block_write+1073>
- and ends at 0x1001c2bf <block_write+1103>.
- (gdb) i line *0x1001c2c0
- Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
- and ends at 0x1001c2e3 <block_write+1139>.
-
-
+ block_dev.c::
+
+
+
+ (gdb) up
+ #1 0x1007584d in __sleep (seconds=1000000)
+ at ../sysdeps/unix/sysv/linux/sleep.c:78
+ ../sysdeps/unix/sysv/linux/sleep.c:78: No such file or directory.
+ (gdb)
+ #2 0x1006ce9a in stop () at user_util.c:191
+ 191 while(1) sleep(1000000);
+ (gdb)
+ #3 0x1006bf88 in segv (address=1342179328, is_write=2) at trap_kern.c:31
+ 31 KERN_UNTESTED();
+ (gdb)
+ #4 0x1006c628 in segv_handler (sc=0x5006eaf8) at trap_user.c:174
+ 174 segv(sc->cr2, sc->err & 2);
+ (gdb) p *sc
+ $1 = {gs = 0, __gsh = 0, fs = 0, __fsh = 0, es = 43, __esh = 0, ds = 43,
+ __dsh = 0, edi = 1342179328, esi = 134973440, ebp = 1342631484,
+ esp = 1342630864, ebx = 256, edx = 0, ecx = 256, eax = 1024, trapno = 14,
+ err = 6, eip = 268550834, cs = 35, __csh = 0, eflags = 66070,
+ esp_at_signal = 1342630864, ss = 43, __ssh = 0, fpstate = 0x0, oldmask = 0,
+ cr2 = 1342179328}
+ (gdb) p (void *)268550834
+ $2 = (void *) 0x1001c2b2
+ (gdb) i sym $2
+ block_write + 1090 in section .text
+ (gdb) i line *$2
+ Line 209 of "/home/dike/linux/2.3.26/um/include/asm/arch/string.h"
+ starts at address 0x1001c2a1 <block_write+1073>
+ and ends at 0x1001c2bf <block_write+1103>.
+ (gdb) i line *0x1001c2c0
+ Line 110 of "block_dev.c" starts at address 0x1001c2bf <block_write+1103>
+ and ends at 0x1001c2e3 <block_write+1139>.
Looking at the source shows that the fault happened during a call to
- copy_from_user to copy the data into the kernel:
+ copy_from_user to copy the data into the kernel::
107 count -= chars;
@@ -3601,10 +3460,8 @@
-
-
p is the pointer which must contain 0x50000800, since buf contains
- 0x80b8800 (frame 8 above). It is defined as:
+ 0x80b8800 (frame 8 above). It is defined as::
p = offset + bh->b_data;
@@ -3615,24 +3472,22 @@
I need to figure out what bh is, and it just so happens that bh is
passed as an argument to mark_buffer_uptodate and mark_buffer_dirty a
- few lines later, so I do a little disassembly:
+ few lines later, so I do a little disassembly::
-
-
- (gdb) disas 0x1001c2bf 0x1001c2e0
- Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
- 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
- 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
- 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
- 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
- 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
- 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
- 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
- 0x1001c2d8 <block_write+1128>: pushl $0x0
- 0x1001c2da <block_write+1130>: pushl %edx
- 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
- End of assembler dump.
+ (gdb) disas 0x1001c2bf 0x1001c2e0
+ Dump of assembler code from 0x1001c2bf to 0x1001c2d0:
+ 0x1001c2bf <block_write+1103>: addl %eax,0xc(%ebp)
+ 0x1001c2c2 <block_write+1106>: movl 0xfffffdd4(%ebp),%edx
+ 0x1001c2c8 <block_write+1112>: btsl $0x0,0x18(%edx)
+ 0x1001c2cd <block_write+1117>: btsl $0x1,0x18(%edx)
+ 0x1001c2d2 <block_write+1122>: sbbl %ecx,%ecx
+ 0x1001c2d4 <block_write+1124>: testl %ecx,%ecx
+ 0x1001c2d6 <block_write+1126>: jne 0x1001c2e3 <block_write+1139>
+ 0x1001c2d8 <block_write+1128>: pushl $0x0
+ 0x1001c2da <block_write+1130>: pushl %edx
+ 0x1001c2db <block_write+1131>: call 0x1001819c <__mark_buffer_dirty>
+ End of assembler dump.
@@ -3640,7 +3495,7 @@
At that point, bh is in %edx (address 0x1001c2da), which is calculated
at 0x1001c2c2 as %ebp + 0xfffffdd4, so I figure exactly what that is,
- taking %ebp from the sigcontext_struct above:
+ taking %ebp from the sigcontext_struct above::
(gdb) p (void *)1342631484
@@ -3657,7 +3512,7 @@
Now, I look at the structure to see what's in it, and particularly,
- what its b_data field contains:
+ what its b_data field contains::
(gdb) p *((struct buffer_head *)0x50100200)
@@ -3682,18 +3537,18 @@
The b_page field is a pointer to the page_struct representing the
0x50000000 page. Looking at it shows the kernel's idea of the state
- of that page:
+ of that page::
- (gdb) p *$13.b_page
- $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
- index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
- next = 0x50008460, prev = 0x50019350}, wait = {
- lock = <optimized out or zero length>, task_list = {next = 0x50004024,
- prev = 0x50004024}, __magic = 1342193708, __creator = 0},
- pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
- zone = 0x100c5160}
+ (gdb) p *$13.b_page
+ $17 = {list = {next = 0x50004a5c, prev = 0x100c5174}, mapping = 0x0,
+ index = 0, next_hash = 0x0, count = {counter = 1}, flags = 132, lru = {
+ next = 0x50008460, prev = 0x50019350}, wait = {
+ lock = <optimized out or zero length>, task_list = {next = 0x50004024,
+ prev = 0x50004024}, __magic = 1342193708, __creator = 0},
+ pprev_hash = 0x0, buffers = 0x501002c0, virtual = 1342177280,
+ zone = 0x100c5160}
@@ -3702,7 +3557,7 @@
Some sanity-checking: the virtual field shows the "virtual" address of
this page, which in this kernel is the same as its "physical" address,
and the page_struct itself should be mem_map[0], since it represents
- the first page of memory:
+ the first page of memory::
@@ -3719,7 +3574,7 @@
Now to check out the page_struct itself. In particular, the flags
- field shows whether the page is considered free or not:
+ field shows whether the page is considered free or not::
(gdb) p (void *)132
@@ -3739,7 +3594,7 @@
In my setup_arch procedure, I have the following code which looks just
- fine:
+ fine::
@@ -3762,7 +3617,7 @@
Stepping into init_bootmem, and looking at bootmem_map before looking
- at what it contains shows the following:
+ at what it contains shows the following::
@@ -3788,18 +3643,20 @@
- 13. What to do when UML doesn't work
+13. What to do when UML doesn't work
+=====================================
- 13.1. Strange compilation errors when you build from source
+13.1. Strange compilation errors when you build from source
+------------------------------------------------------------
As of test11, it is necessary to have "ARCH=um" in the environment or
on the make command line for all steps in building UML, including
clean, distclean, or mrproper, config, menuconfig, or xconfig, dep,
and linux. If you forget for any of them, the i386 build seems to
- contaminate the UML build. If this happens, start from scratch with
+ contaminate the UML build. If this happens, start from scratch with::
host%
@@ -3811,7 +3668,7 @@
and repeat the build process with ARCH=um on all the steps.
- See ``Compiling the kernel and modules'' for more details.
+ See :ref:`Compiling_the_kernel_and_modules` for more details.
Another cause of strange compilation errors is building UML in
@@ -3824,11 +3681,11 @@
- 13.3. A variety of panics and hangs with /tmp on a reiserfs filesys-
- tem
+13.3. A variety of panics and hangs with /tmp on a reiserfs filesystem
+-----------------------------------------------------------------------
I saw this on reiserfs 3.5.21 and it seems to be fixed in 3.5.27.
- Panics preceded by
+ Panics preceded by::
Detaching pid nnnn
@@ -3854,17 +3711,19 @@
- 13.5. UML doesn't work when /tmp is an NFS filesystem
+13.5. UML doesn't work when /tmp is an NFS filesystem
+------------------------------------------------------
This seems to be a similar situation with the ReiserFS problem above.
Some versions of NFS seems not to handle mmap correctly, which UML
depends on. The workaround is have /tmp be a non-NFS directory.
- 13.6. UML hangs on boot when compiled with gprof support
+13.6. UML hangs on boot when compiled with gprof support
+---------------------------------------------------------
If you build UML with gprof support and, early in the boot, it does
- this
+ this::
kernel BUG at page_alloc.c:100!
@@ -3878,10 +3737,11 @@
- 13.7. syslogd dies with a SIGTERM on startup
+13.7. syslogd dies with a SIGTERM on startup
+---------------------------------------------
The exact boot error depends on the distribution that you're booting,
- but Debian produces this:
+ but Debian produces this::
/etc/rc2.d/S10sysklogd: line 49: 93 Terminated
@@ -3897,17 +3757,18 @@
- 13.8. TUN/TAP networking doesn't work on a 2.4 host
+13.8. TUN/TAP networking doesn't work on a 2.4 host
+----------------------------------------------------
There are a couple of problems which were
<http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
out"> by Tim Robinson <timro at trkr dot net>
- o It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
+ - It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
The fix is to upgrade to something more recent and then read the
next item.
- o If you see
+ - If you see::
File descriptor in bad state
@@ -3921,8 +3782,8 @@
- 13.9. You can network to the host but not to other machines on the
- net
+13.9. You can network to the host but not to other machines on the net
+=======================================================================
If you can connect to the host, and the host can connect to UML, but
you cannot connect to any other machines, then you may need to enable
@@ -3930,7 +3791,7 @@
using private IP addresses (192.168.x.x or 10.x.x.x) for host/UML
networking, rather than the public address space that your host is
connected to. UML does not enable IP Masquerading, so you will need
- to create a static rule to enable it:
+ to create a static rule to enable it::
host%
@@ -3948,7 +3809,7 @@
If you can reach the local net, but not the outside Internet, then
- that is usually a routing problem. The UML needs a default route:
+ that is usually a routing problem. The UML needs a default route::
UML#
@@ -3972,7 +3833,8 @@
- 13.10. I have no root and I want to scream
+13.10. I have no root and I want to scream
+===========================================
Thanks to Birgit Wahlich for telling me about this strange one. It
turns out that there's a limit of six environment variables on the
@@ -3987,14 +3849,16 @@
- 13.11. UML build conflict between ptrace.h and ucontext.h
+13.11. UML build conflict between ptrace.h and ucontext.h
+==========================================================
On some older systems, /usr/include/asm/ptrace.h and
/usr/include/sys/ucontext.h define the same names. So, when they're
included together, the defines from one completely mess up the parsing
- of the other, producing errors like:
+ of the other, producing errors like::
+
/usr/include/sys/ucontext.h:47: parse error before
- `10'
+ `10`
@@ -4007,7 +3871,8 @@
- 13.12. The UML BogoMips is exactly half the host's BogoMips
+13.12. The UML BogoMips is exactly half the host's BogoMips
+------------------------------------------------------------
On i386 kernels, there are two ways of running the loop that is used
to calculate the BogoMips rating, using the TSC if it's there or using
@@ -4019,15 +3884,17 @@
- 13.13. When you run UML, it immediately segfaults
+13.13. When you run UML, it immediately segfaults
+--------------------------------------------------
If the host is configured with the 2G/2G address space split, that's
- why. See ``UML on 2G/2G hosts'' for the details on getting UML to
+ why. See ref:`UML_on_2G/2G_hosts` for the details on getting UML to
run on your host.
- 13.14. xterms appear, then immediately disappear
+13.14. xterms appear, then immediately disappear
+-------------------------------------------------
If you're running an up to date kernel with an old release of
uml_utilities, the port-helper program will not work properly, so
@@ -4039,7 +3906,8 @@
- 13.15. Any other panic, hang, or strange behavior
+13.15. Any other panic, hang, or strange behavior
+--------------------------------------------------
If you're seeing truly strange behavior, such as hangs or panics that
happen in random places, or you try running the debugger to see what's
@@ -4057,9 +3925,13 @@
it and that a fix is imminent.
- If you want to be super-helpful, read ``Diagnosing Problems'' and
+ If you want to be super-helpful, read :ref:`Diagnosing_Problems` and
follow the instructions contained therein.
- 14. Diagnosing Problems
+
+.. _Diagnosing_Problems:
+
+14. Diagnosing Problems
+========================
If you get UML to crash, hang, or otherwise misbehave, you should
@@ -4074,21 +3946,22 @@
For any diagnosis, you're going to need to build a debugging kernel.
The binaries from this site aren't debuggable. If you haven't done
- this before, read about ``Compiling the kernel and modules'' and
- ``Kernel debugging'' UML first.
+ this before, read about :ref:`Compiling_the_kernel_and_modules` and
+ :ref:`Kernel_debugging` UML first.
- 14.1. Case 1 : Normal kernel panics
+14.1. Case 1 : Normal kernel panics
+------------------------------------
The most common case is for a normal thread to panic. To debug this,
you will need to run it under the debugger (add 'debug' to the command
line). An xterm will start up with gdb running inside it. Continue
- it when it stops in start_kernel and make it crash. Now ^C gdb and
+ it when it stops in start_kernel and make it crash. Now ``^C gdb`` and
If the panic was a "Kernel mode fault", then there will be a segv
frame on the stack and I'm going to want some more information. The
- stack might look something like this:
+ stack might look something like this::
(UML gdb) backtrace
@@ -4107,7 +3980,7 @@
I'm going to want to see the symbol and line information for the value
- of ip in the segv frame. In this case, you would do the following:
+ of ip in the segv frame. In this case, you would do the following::
(UML gdb) i sym 268849158
@@ -4115,7 +3988,7 @@
- and
+ and::
(UML gdb) i line *268849158
@@ -4128,7 +4001,8 @@
to get that information from the faulting ip.
- 14.2. Case 2 : Tracing thread panics
+14.2. Case 2 : Tracing thread panics
+-------------------------------------
The less common and more painful case is when the tracing thread
panics. In this case, the kernel debugger will be useless because it
@@ -4136,7 +4010,7 @@
do is get a backtrace from the tracing thread. This is done by
figuring out what its pid is, firing up gdb, and attaching it to that
pid. You can figure out the tracing thread pid by looking at the
- first line of the console output, which will look like this:
+ first line of the console output, which will look like this::
tracing thread pid = 15851
@@ -4145,7 +4019,7 @@
or by running ps on the host and finding the line that looks like
- this:
+ this::
jdike 15851 4.5 0.4 132568 1104 pts/0 S 21:34 0:05 ./linux [(tracing thread)]
@@ -4164,7 +4038,7 @@
14.3. Case 3 : Tracing thread panics caused by other threads
However, there are cases where the misbehavior of another thread
- caused the problem. The most common panic of this type is:
+ caused the problem. The most common panic of this type is::
wait_for_stop failed to wait for <pid> to stop with <signal number>
@@ -4177,7 +4051,7 @@
debugger is defunct and without some fancy footwork, another gdb can't
attach to it. So, this is how the fancy footwork goes:
- In a shell:
+ In a shell::
host% kill -STOP pid
@@ -4185,7 +4059,7 @@
- Run gdb on the tracing thread as described in case 2 and do:
+ Run gdb on the tracing thread as described in case 2 and do::
(host gdb) call detach(pid)
@@ -4193,7 +4067,7 @@
If you get a segfault, do it again. It always works the second time.
- Detach from the tracing thread and attach to that other thread:
+ Detach from the tracing thread and attach to that other thread::
(host gdb) detach
@@ -4209,7 +4083,7 @@
If gdb hangs when attaching to that process, go back to a shell and
- do:
+ do::
host%
@@ -4218,7 +4092,7 @@
- And then get the backtrace:
+ And then get the backtrace::
(host gdb) backtrace
@@ -4227,13 +4101,14 @@
- 14.4. Case 4 : Hangs
+14.4. Case 4 : Hangs
+---------------------
Hangs seem to be fairly rare, but they sometimes happen. When a hang
happens, we need a backtrace from the offending process. Run the
kernel debugger as described in case 1 and get a backtrace. If the
current process is not the idle thread, then send in the backtrace.
- You can tell that it's the idle thread if the stack looks like this:
+ You can tell that it's the idle thread if the stack looks like this::
#0 0x100b1401 in __libc_nanosleep ()
@@ -4257,7 +4132,8 @@
- 15. Thanks
+15. Thanks
+===========
A number of people have helped this project in various ways, and this
@@ -4274,20 +4150,21 @@
bookkeeping lapses and I forget about contributions.
- 15.1. Code and Documentation
+15.1. Code and Documentation
+-----------------------------
Rusty Russell <rusty at linuxcare.com.au> -
- o wrote the HOWTO <http://user-mode-
+ - wrote the HOWTO <http://user-mode-
linux.sourceforge.net/UserModeLinux-HOWTO.html>
- o prodded me into making this project official and putting it on
+ - prodded me into making this project official and putting it on
SourceForge
- o came up with the way cool UML logo <http://user-mode-
+ - came up with the way cool UML logo <http://user-mode-
linux.sourceforge.net/uml-small.png>
- o redid the config process
+ - redid the config process
Peter Moulder <reiter at netspace.net.au> - Fixed my config and build
@@ -4296,18 +4173,18 @@
Bill Stearns <wstearns at pobox.com> -
- o HOWTO updates
+ - HOWTO updates
- o lots of bug reports
+ - lots of bug reports
- o lots of testing
+ - lots of testing
- o dedicated a box (uml.ists.dartmouth.edu) to support UML development
+ - dedicated a box (uml.ists.dartmouth.edu) to support UML development
- o wrote the mkrootfs script, which allows bootable filesystems of
+ - wrote the mkrootfs script, which allows bootable filesystems of
RPM-based distributions to be cranked out
- o cranked out a large number of filesystems with said script
+ - cranked out a large number of filesystems with said script
Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
@@ -4375,176 +4252,180 @@
David Coulson <http://davidcoulson.net> -
- o Set up the usermodelinux.org <http://usermodelinux.org> site,
+ - Set up the usermodelinux.org <http://usermodelinux.org> site,
which is a great way of keeping the UML user community on top of
UML goings-on.
- o Site documentation and updates
+ - Site documentation and updates
- o Nifty little UML management daemon UMLd
+ - Nifty little UML management daemon UMLd
<http://uml.openconsultancy.com/umld/>
- o Lots of testing and bug reports
+ - Lots of testing and bug reports
- 15.2. Flushing out bugs
+15.2. Flushing out bugs
+------------------------
- o Yuri Pudgorodsky
+ - Yuri Pudgorodsky
- o Gerald Britton
+ - Gerald Britton
- o Ian Wehrman
+ - Ian Wehrman
- o Gord Lamb
+ - Gord Lamb
- o Eugene Koontz
+ - Eugene Koontz
- o John H. Hartman
+ - John H. Hartman
- o Anders Karlsson
+ - Anders Karlsson
- o Daniel Phillips
+ - Daniel Phillips
- o John Fremlin
+ - John Fremlin
- o Rainer Burgstaller
+ - Rainer Burgstaller
- o James Stevenson
+ - James Stevenson
- o Matt Clay
+ - Matt Clay
- o Cliff Jefferies
+ - Cliff Jefferies
- o Geoff Hoff
+ - Geoff Hoff
- o Lennert Buytenhek
+ - Lennert Buytenhek
- o Al Viro
+ - Al Viro
- o Frank Klingenhoefer
+ - Frank Klingenhoefer
- o Livio Baldini Soares
+ - Livio Baldini Soares
- o Jon Burgess
+ - Jon Burgess
- o Petru Paler
+ - Petru Paler
- o Paul
+ - Paul
- o Chris Reahard
+ - Chris Reahard
- o Sverker Nilsson
+ - Sverker Nilsson
- o Gong Su
+ - Gong Su
- o johan verrept
+ - johan verrept
- o Bjorn Eriksson
+ - Bjorn Eriksson
- o Lorenzo Allegrucci
+ - Lorenzo Allegrucci
- o Muli Ben-Yehuda
+ - Muli Ben-Yehuda
- o David Mansfield
+ - David Mansfield
- o Howard Goff
+ - Howard Goff
- o Mike Anderson
+ - Mike Anderson
- o John Byrne
+ - John Byrne
- o Sapan J. Batia
+ - Sapan J. Batia
- o Iris Huang
+ - Iris Huang
- o Jan Hudec
+ - Jan Hudec
- o Voluspa
+ - Voluspa
- 15.3. Buglets and clean-ups
+15.3. Buglets and clean-ups
+----------------------------
- o Dave Zarzycki
+ - Dave Zarzycki
- o Adam Lazur
+ - Adam Lazur
- o Boria Feigin
+ - Boria Feigin
- o Brian J. Murrell
+ - Brian J. Murrell
- o JS
+ - JS
- o Roman Zippel
+ - Roman Zippel
- o Wil Cooley
+ - Wil Cooley
- o Ayelet Shemesh
+ - Ayelet Shemesh
- o Will Dyson
+ - Will Dyson
- o Sverker Nilsson
+ - Sverker Nilsson
- o dvorak
+ - dvorak
- o v.naga srinivas
+ - v.naga srinivas
- o Shlomi Fish
+ - Shlomi Fish
- o Roger Binns
+ - Roger Binns
- o johan verrept
+ - johan verrept
- o MrChuoi
+ - MrChuoi
- o Peter Cleve
+ - Peter Cleve
- o Vincent Guffens
+ - Vincent Guffens
- o Nathan Scott
+ - Nathan Scott
- o Patrick Caulfield
+ - Patrick Caulfield
- o jbearce
+ - jbearce
- o Catalin Marinas
+ - Catalin Marinas
- o Shane Spencer
+ - Shane Spencer
- o Zou Min
+ - Zou Min
- o Ryan Boder
+ - Ryan Boder
- o Lorenzo Colitti
+ - Lorenzo Colitti
- o Gwendal Grignou
+ - Gwendal Grignou
- o Andre' Breiler
+ - Andre' Breiler
- o Tsutomu Yasuda
+ - Tsutomu Yasuda
- 15.4. Case Studies
+15.4. Case Studies
+-------------------
- o Jon Wright
+ - Jon Wright
- o William McEwan
+ - William McEwan
- o Michael Richardson
+ - Michael Richardson
- 15.5. Other contributions
+15.5. Other contributions
+--------------------------
Bill Carr <Bill.Carr at compaq.com> made the Red Hat mkrootfs script
@@ -4575,15 +4456,3 @@
server jailed inside UML. It's available from the download
<http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
Filesystems section.
-
-
-
-
-
-
-
-
-
-
-
-
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 03/27] docs: virt: user_mode_linux.rst: update compiling instructions
2020-01-28 14:00 ` Mauro Carvalho Chehab
(?)
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:57 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jeff Dike,
Richard Weinberger, Anton Ivanov, Jonathan Corbet, linux-um,
linux-doc
Instead of pointing for a pre-2.4 and a seaparate patch,
update it to match current upstream, as UML was merged
a long time ago.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/uml/user_mode_linux.rst | 62 ++++------------------
1 file changed, 9 insertions(+), 53 deletions(-)
diff --git a/Documentation/virt/uml/user_mode_linux.rst b/Documentation/virt/uml/user_mode_linux.rst
index 98922008be23..a96d29243964 100644
--- a/Documentation/virt/uml/user_mode_linux.rst
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -3,7 +3,7 @@ User Mode Linux HOWTO
=====================
:Author: User Mode Linux Core Team
-:Last-updated: Mon Nov 18 14:16:16 EST 2002
+:Last-updated: Sat Jan 25 16:07:55 CET 2020
This document describes the use and abuse of Jeff Dike's User Mode
Linux: a port of the Linux kernel as a normal Intel Linux process.
@@ -221,23 +221,15 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
Compiling the user mode kernel is just like compiling any other
- kernel. Let's go through the steps, using 2.4.0-prerelease (current
- as of this writing) as an example:
+ kernel.
- 1. Download the latest UML patch from
- the download page <http://user-mode-linux.sourceforge.net/
-
- In this example, the file is uml-patch-2.4.0-prerelease.bz2.
-
-
- 2. Download the matching kernel from your favourite kernel mirror,
+ 1. Download the latest kernel from your favourite kernel mirror,
such as:
- ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
+ https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.4.14.tar.xz
-
- 3. Make a directory and unpack the kernel into it::
+ 2. Make a directory and unpack the kernel into it::
host%
mkdir ~/uml
@@ -246,21 +238,10 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
cd ~/uml
host%
- tar -xzvf linux-2.4.0-prerelease.tar.bz2
+ tar xvf linux-5.4.14.tar.xz
-
- 4. Apply the patch using::
-
- host%
- cd ~/uml/linux
-
- host%
- bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
-
-
-
- 5. Run your favorite config; ``make xconfig ARCH=um`` is the most
+ 3. Run your favorite config; ``make xconfig ARCH=um`` is the most
convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um``
will work as well. The defaults will give you a useful kernel. If
you want to change something, go ahead, it probably won't hurt
@@ -274,34 +255,9 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
- 6. Finish with ``make linux ARCH=um``: the result is a file called
+ 4. Finish with ``make linux ARCH=um``: the result is a file called
``linux`` in the top directory of your source tree.
- Make sure that you don't build this kernel in /usr/src/linux. On some
- distributions, /usr/include/asm is a link into this pool. The user-
- mode build changes the other end of that link, and things that include
- <asm/anything.h> stop compiling.
-
- The sources are also available from cvs at the project's cvs page,
- which has directions on getting the sources. You can also browse the
- CVS pool from there.
-
- If you get the CVS sources, you will have to check them out into an
- empty directory. You will then have to copy each file into the
- corresponding directory in the appropriate kernel pool.
-
- If you don't have the latest kernel pool, you can get the
- corresponding user-mode sources with::
-
-
- host% cvs co -r v_2_3_x linux
-
-
-
-
- where 'x' is the version in your pool. Note that you will not get the
- bug fixes and enhancements that have gone into subsequent releases.
-
2.2. Compiling and installing kernel modules
---------------------------------------------
@@ -414,7 +370,7 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
3.1. Running UML
-----------------
- It runs on 2.2.15 or later, and all 2.4 kernels.
+ It runs on 2.2.15 or later, and all kernel versions since 2.4.
Booting UML is straightforward. Simply run 'linux': it will try to
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 03/27] docs: virt: user_mode_linux.rst: update compiling instructions
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:57 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jeff Dike,
Richard Weinberger, Anton Ivanov, Jonathan Corbet, linux-um,
linux-doc
Instead of pointing for a pre-2.4 and a seaparate patch,
update it to match current upstream, as UML was merged
a long time ago.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/uml/user_mode_linux.rst | 62 ++++------------------
1 file changed, 9 insertions(+), 53 deletions(-)
diff --git a/Documentation/virt/uml/user_mode_linux.rst b/Documentation/virt/uml/user_mode_linux.rst
index 98922008be23..a96d29243964 100644
--- a/Documentation/virt/uml/user_mode_linux.rst
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -3,7 +3,7 @@ User Mode Linux HOWTO
=====================
:Author: User Mode Linux Core Team
-:Last-updated: Mon Nov 18 14:16:16 EST 2002
+:Last-updated: Sat Jan 25 16:07:55 CET 2020
This document describes the use and abuse of Jeff Dike's User Mode
Linux: a port of the Linux kernel as a normal Intel Linux process.
@@ -221,23 +221,15 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
Compiling the user mode kernel is just like compiling any other
- kernel. Let's go through the steps, using 2.4.0-prerelease (current
- as of this writing) as an example:
+ kernel.
- 1. Download the latest UML patch from
- the download page <http://user-mode-linux.sourceforge.net/
-
- In this example, the file is uml-patch-2.4.0-prerelease.bz2.
-
-
- 2. Download the matching kernel from your favourite kernel mirror,
+ 1. Download the latest kernel from your favourite kernel mirror,
such as:
- ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
+ https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.4.14.tar.xz
-
- 3. Make a directory and unpack the kernel into it::
+ 2. Make a directory and unpack the kernel into it::
host%
mkdir ~/uml
@@ -246,21 +238,10 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
cd ~/uml
host%
- tar -xzvf linux-2.4.0-prerelease.tar.bz2
+ tar xvf linux-5.4.14.tar.xz
-
- 4. Apply the patch using::
-
- host%
- cd ~/uml/linux
-
- host%
- bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
-
-
-
- 5. Run your favorite config; ``make xconfig ARCH=um`` is the most
+ 3. Run your favorite config; ``make xconfig ARCH=um`` is the most
convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um``
will work as well. The defaults will give you a useful kernel. If
you want to change something, go ahead, it probably won't hurt
@@ -274,34 +255,9 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
- 6. Finish with ``make linux ARCH=um``: the result is a file called
+ 4. Finish with ``make linux ARCH=um``: the result is a file called
``linux`` in the top directory of your source tree.
- Make sure that you don't build this kernel in /usr/src/linux. On some
- distributions, /usr/include/asm is a link into this pool. The user-
- mode build changes the other end of that link, and things that include
- <asm/anything.h> stop compiling.
-
- The sources are also available from cvs at the project's cvs page,
- which has directions on getting the sources. You can also browse the
- CVS pool from there.
-
- If you get the CVS sources, you will have to check them out into an
- empty directory. You will then have to copy each file into the
- corresponding directory in the appropriate kernel pool.
-
- If you don't have the latest kernel pool, you can get the
- corresponding user-mode sources with::
-
-
- host% cvs co -r v_2_3_x linux
-
-
-
-
- where 'x' is the version in your pool. Note that you will not get the
- bug fixes and enhancements that have gone into subsequent releases.
-
2.2. Compiling and installing kernel modules
---------------------------------------------
@@ -414,7 +370,7 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
3.1. Running UML
-----------------
- It runs on 2.2.15 or later, and all 2.4 kernels.
+ It runs on 2.2.15 or later, and all kernel versions since 2.4.
Booting UML is straightforward. Simply run 'linux': it will try to
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 03/27] docs: virt: user_mode_linux.rst: update compiling instructions
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Jonathan Corbet, Mauro Carvalho Chehab, Richard Weinberger,
Jeff Dike, linux-doc, linux-um, Mauro Carvalho Chehab,
Anton Ivanov
Instead of pointing for a pre-2.4 and a seaparate patch,
update it to match current upstream, as UML was merged
a long time ago.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/uml/user_mode_linux.rst | 62 ++++------------------
1 file changed, 9 insertions(+), 53 deletions(-)
diff --git a/Documentation/virt/uml/user_mode_linux.rst b/Documentation/virt/uml/user_mode_linux.rst
index 98922008be23..a96d29243964 100644
--- a/Documentation/virt/uml/user_mode_linux.rst
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -3,7 +3,7 @@ User Mode Linux HOWTO
=====================
:Author: User Mode Linux Core Team
-:Last-updated: Mon Nov 18 14:16:16 EST 2002
+:Last-updated: Sat Jan 25 16:07:55 CET 2020
This document describes the use and abuse of Jeff Dike's User Mode
Linux: a port of the Linux kernel as a normal Intel Linux process.
@@ -221,23 +221,15 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
Compiling the user mode kernel is just like compiling any other
- kernel. Let's go through the steps, using 2.4.0-prerelease (current
- as of this writing) as an example:
+ kernel.
- 1. Download the latest UML patch from
- the download page <http://user-mode-linux.sourceforge.net/
-
- In this example, the file is uml-patch-2.4.0-prerelease.bz2.
-
-
- 2. Download the matching kernel from your favourite kernel mirror,
+ 1. Download the latest kernel from your favourite kernel mirror,
such as:
- ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
+ https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.4.14.tar.xz
-
- 3. Make a directory and unpack the kernel into it::
+ 2. Make a directory and unpack the kernel into it::
host%
mkdir ~/uml
@@ -246,21 +238,10 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
cd ~/uml
host%
- tar -xzvf linux-2.4.0-prerelease.tar.bz2
+ tar xvf linux-5.4.14.tar.xz
-
- 4. Apply the patch using::
-
- host%
- cd ~/uml/linux
-
- host%
- bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
-
-
-
- 5. Run your favorite config; ``make xconfig ARCH=um`` is the most
+ 3. Run your favorite config; ``make xconfig ARCH=um`` is the most
convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um``
will work as well. The defaults will give you a useful kernel. If
you want to change something, go ahead, it probably won't hurt
@@ -274,34 +255,9 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
- 6. Finish with ``make linux ARCH=um``: the result is a file called
+ 4. Finish with ``make linux ARCH=um``: the result is a file called
``linux`` in the top directory of your source tree.
- Make sure that you don't build this kernel in /usr/src/linux. On some
- distributions, /usr/include/asm is a link into this pool. The user-
- mode build changes the other end of that link, and things that include
- <asm/anything.h> stop compiling.
-
- The sources are also available from cvs at the project's cvs page,
- which has directions on getting the sources. You can also browse the
- CVS pool from there.
-
- If you get the CVS sources, you will have to check them out into an
- empty directory. You will then have to copy each file into the
- corresponding directory in the appropriate kernel pool.
-
- If you don't have the latest kernel pool, you can get the
- corresponding user-mode sources with::
-
-
- host% cvs co -r v_2_3_x linux
-
-
-
-
- where 'x' is the version in your pool. Note that you will not get the
- bug fixes and enhancements that have gone into subsequent releases.
-
2.2. Compiling and installing kernel modules
---------------------------------------------
@@ -414,7 +370,7 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
3.1. Running UML
-----------------
- It runs on 2.2.15 or later, and all 2.4 kernels.
+ It runs on 2.2.15 or later, and all kernel versions since 2.4.
Booting UML is straightforward. Simply run 'linux': it will try to
--
2.24.1
_______________________________________________
linux-um mailing list
linux-um@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-um
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 03/27] docs: virt: user_mode_linux.rst: update compiling instructions
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jeff Dike,
Richard Weinberger, Anton Ivanov, Jonathan Corbet, linux-um,
linux-doc
Instead of pointing for a pre-2.4 and a seaparate patch,
update it to match current upstream, as UML was merged
a long time ago.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/uml/user_mode_linux.rst | 62 ++++------------------
1 file changed, 9 insertions(+), 53 deletions(-)
diff --git a/Documentation/virt/uml/user_mode_linux.rst b/Documentation/virt/uml/user_mode_linux.rst
index 98922008be23..a96d29243964 100644
--- a/Documentation/virt/uml/user_mode_linux.rst
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -3,7 +3,7 @@ User Mode Linux HOWTO
=====================
:Author: User Mode Linux Core Team
-:Last-updated: Mon Nov 18 14:16:16 EST 2002
+:Last-updated: Sat Jan 25 16:07:55 CET 2020
This document describes the use and abuse of Jeff Dike's User Mode
Linux: a port of the Linux kernel as a normal Intel Linux process.
@@ -221,23 +221,15 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
Compiling the user mode kernel is just like compiling any other
- kernel. Let's go through the steps, using 2.4.0-prerelease (current
- as of this writing) as an example:
+ kernel.
- 1. Download the latest UML patch from
- the download page <http://user-mode-linux.sourceforge.net/
-
- In this example, the file is uml-patch-2.4.0-prerelease.bz2.
-
-
- 2. Download the matching kernel from your favourite kernel mirror,
+ 1. Download the latest kernel from your favourite kernel mirror,
such as:
- ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
+ https://mirrors.edge.kernel.org/pub/linux/kernel/v5.x/linux-5.4.14.tar.xz
-
- 3. Make a directory and unpack the kernel into it::
+ 2. Make a directory and unpack the kernel into it::
host%
mkdir ~/uml
@@ -246,21 +238,10 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
cd ~/uml
host%
- tar -xzvf linux-2.4.0-prerelease.tar.bz2
+ tar xvf linux-5.4.14.tar.xz
-
- 4. Apply the patch using::
-
- host%
- cd ~/uml/linux
-
- host%
- bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
-
-
-
- 5. Run your favorite config; ``make xconfig ARCH=um`` is the most
+ 3. Run your favorite config; ``make xconfig ARCH=um`` is the most
convenient. ``make config ARCH=um`` and ``make menuconfig ARCH=um``
will work as well. The defaults will give you a useful kernel. If
you want to change something, go ahead, it probably won't hurt
@@ -274,34 +255,9 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
- 6. Finish with ``make linux ARCH=um``: the result is a file called
+ 4. Finish with ``make linux ARCH=um``: the result is a file called
``linux`` in the top directory of your source tree.
- Make sure that you don't build this kernel in /usr/src/linux. On some
- distributions, /usr/include/asm is a link into this pool. The user-
- mode build changes the other end of that link, and things that include
- <asm/anything.h> stop compiling.
-
- The sources are also available from cvs at the project's cvs page,
- which has directions on getting the sources. You can also browse the
- CVS pool from there.
-
- If you get the CVS sources, you will have to check them out into an
- empty directory. You will then have to copy each file into the
- corresponding directory in the appropriate kernel pool.
-
- If you don't have the latest kernel pool, you can get the
- corresponding user-mode sources with::
-
-
- host% cvs co -r v_2_3_x linux
-
-
-
-
- where 'x' is the version in your pool. Note that you will not get the
- bug fixes and enhancements that have gone into subsequent releases.
-
2.2. Compiling and installing kernel modules
---------------------------------------------
@@ -414,7 +370,7 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
3.1. Running UML
-----------------
- It runs on 2.2.15 or later, and all 2.4 kernels.
+ It runs on 2.2.15 or later, and all kernel versions since 2.4.
Booting UML is straightforward. Simply run 'linux': it will try to
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 04/27] docs: virt: user_mode_linux.rst: fix URL references
2020-01-28 14:00 ` Mauro Carvalho Chehab
(?)
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jeff Dike,
Richard Weinberger, Anton Ivanov, Jonathan Corbet, linux-um,
linux-doc
Several URLs are pointing to outdated places.
Update the references for the URLs whose contents still exists,
removing the others.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/uml/user_mode_linux.rst | 71 +++++++++-------------
1 file changed, 29 insertions(+), 42 deletions(-)
diff --git a/Documentation/virt/uml/user_mode_linux.rst b/Documentation/virt/uml/user_mode_linux.rst
index a96d29243964..d6844fb89b46 100644
--- a/Documentation/virt/uml/user_mode_linux.rst
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -319,7 +319,7 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
as modules, especially filesystems and network protocols and filters,
so most symbols which need to be exported probably already are.
However, if you do find symbols that need exporting, let us
- <http://user-mode-linux.sourceforge.net/> know, and
+ know at http://user-mode-linux.sourceforge.net/, and
they'll be "taken care of".
@@ -381,9 +381,9 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
You will need a filesystem to boot UML from. There are a number
- available for download from here <http://user-mode-
- linux.sourceforge.net/> . There are also several tools
- <http://user-mode-linux.sourceforge.net/> which can be
+ available for download from http://user-mode-linux.sourceforge.net.
+ There are also several tools at
+ http://user-mode-linux.sourceforge.net/ which can be
used to generate UML-compatible filesystem images from media.
The kernel will boot up and present you with a login prompt.
@@ -462,10 +462,9 @@ Note:
Here are some examples of UML in action:
- - A login session <http://user-mode-linux.sourceforge.net/login.html>
-
- - A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+ - A login session http://user-mode-linux.sourceforge.net/old/login.html
+ - A virtual network http://user-mode-linux.sourceforge.net/old/net.html
@@ -1130,11 +1129,6 @@ Note:
-
- Harald's original README is here <http://user-mode-linux.source-
- forge.net/> and explains these in detail, as well as
- some other issues.
-
There is also a related point-to-point only "ucast" transport.
This is useful when your network does not support multicast, and
all network connections are simple point to point links.
@@ -1217,8 +1211,7 @@ Note:
make sure that /usr/src/linux points to the headers for the running
kernel.
- These were pointed out by Tim Robinson <timro at trkr dot net> in
- <http://www.geocrawler.com/> name="this uml-user post"> .
+ These were pointed out by Tim Robinson <timro at trkr dot net> in the past.
@@ -1912,8 +1905,8 @@ Note:
uml_moo is installed with the UML deb and RPM. If you didn't install
UML from one of those packages, you can also get it from the UML
- utilities <http://user-mode-linux.sourceforge.net/
- utilities> tar file in tools/moo.
+ utilities http://user-mode-linux.sourceforge.net/utilities tar file
+ in tools/moo.
@@ -3707,18 +3700,15 @@ Note:
This is a syslogd bug. There's a race between a parent process
- installing a signal handler and its child sending the signal. See
- this uml-devel post <http://www.geocrawler.com/lists/3/Source-
- Forge/709/0/6612801> for the details.
+ installing a signal handler and its child sending the signal.
13.8. TUN/TAP networking doesn't work on a 2.4 host
----------------------------------------------------
- There are a couple of problems which were
- <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
- out"> by Tim Robinson <timro at trkr dot net>
+ There are a couple of problems which were reported by
+ Tim Robinson <timro at trkr dot net>
- It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
The fix is to upgrade to something more recent and then read the
@@ -3761,7 +3751,7 @@ Note:
Documentation on IP Masquerading, and SNAT, can be found at
- www.netfilter.org <http://www.netfilter.org> .
+ http://www.netfilter.org.
If you can reach the local net, but not the outside Internet, then
@@ -4111,14 +4101,14 @@ Note:
Rusty Russell <rusty at linuxcare.com.au> -
- - wrote the HOWTO <http://user-mode-
- linux.sourceforge.net/UserModeLinux-HOWTO.html>
+ - wrote the HOWTO
+ http://user-mode-linux.sourceforge.net/old/UserModeLinux-HOWTO.html
- prodded me into making this project official and putting it on
SourceForge
- - came up with the way cool UML logo <http://user-mode-
- linux.sourceforge.net/uml-small.png>
+ - came up with the way cool UML logo
+ http://user-mode-linux.sourceforge.net/uml-small.png
- redid the config process
@@ -4146,17 +4136,15 @@ Note:
Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
and associated usermode tools
- Lars Brinkhoff <http://lars.nocrew.org/> - Contributed the ptrace
- proxy from his own project <http://a386.nocrew.org/> to allow easier
- kernel debugging
+ Lars Brinkhoff http://lars.nocrew.org/ - Contributed the ptrace
+ proxy from his own project to allow easier kernel debugging
Andrea Arcangeli <andrea at suse.de> - Redid some of the early boot
code so that it would work on machines with Large File Support
- Chris Emerson <http://www.chiark.greenend.org.uk/~cemerson/> - Did
- the first UML port to Linux/ppc
+ Chris Emerson - Did the first UML port to Linux/ppc
Harald Welte <laforge at gnumonks.org> - Wrote the multicast
@@ -4171,7 +4159,7 @@ Note:
wrote the iomem emulation support
- Henrik Nordstrom <http://hem.passagen.se/hno/> - Provided a variety
+ Henrik Nordstrom http://hem.passagen.se/hno/ - Provided a variety
of patches, fixes, and clues
@@ -4206,16 +4194,15 @@ Note:
submitted patches for the slip transport and lots of other things.
- David Coulson <http://davidcoulson.net> -
+ David Coulson http://davidcoulson.net -
- - Set up the usermodelinux.org <http://usermodelinux.org> site,
+ - Set up the http://usermodelinux.org site,
which is a great way of keeping the UML user community on top of
UML goings-on.
- Site documentation and updates
- Nifty little UML management daemon UMLd
- <http://uml.openconsultancy.com/umld/>
- Lots of testing and bug reports
@@ -4388,12 +4375,12 @@ Note:
work with RH 6.2.
Michael Jennings <mikejen at hevanet.com> sent in some material which
- is now gracing the top of the index page <http://user-mode-
- linux.sourceforge.net/> of this site.
+ is now gracing the top of the index page
+ http://user-mode-linux.sourceforge.net/ of this site.
- SGI <http://www.sgi.com> (and more specifically Ralf Baechle <ralf at
- uni-koblenz.de> ) gave me an account on oss.sgi.com
- <http://www.oss.sgi.com> . The bandwidth there made it possible to
+ SGI (and more specifically Ralf Baechle <ralf at
+ uni-koblenz.de> ) gave me an account on oss.sgi.com.
+ The bandwidth there made it possible to
produce most of the filesystems available on the project download
page.
@@ -4410,5 +4397,5 @@ Note:
Chris Reahard built a specialized root filesystem for running a DNS
server jailed inside UML. It's available from the download
- <http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
+ http://user-mode-linux.sourceforge.net/old/dl-sf.html page in the Jail
Filesystems section.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 04/27] docs: virt: user_mode_linux.rst: fix URL references
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jeff Dike,
Richard Weinberger, Anton Ivanov, Jonathan Corbet, linux-um,
linux-doc
Several URLs are pointing to outdated places.
Update the references for the URLs whose contents still exists,
removing the others.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/uml/user_mode_linux.rst | 71 +++++++++-------------
1 file changed, 29 insertions(+), 42 deletions(-)
diff --git a/Documentation/virt/uml/user_mode_linux.rst b/Documentation/virt/uml/user_mode_linux.rst
index a96d29243964..d6844fb89b46 100644
--- a/Documentation/virt/uml/user_mode_linux.rst
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -319,7 +319,7 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
as modules, especially filesystems and network protocols and filters,
so most symbols which need to be exported probably already are.
However, if you do find symbols that need exporting, let us
- <http://user-mode-linux.sourceforge.net/> know, and
+ know at http://user-mode-linux.sourceforge.net/, and
they'll be "taken care of".
@@ -381,9 +381,9 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
You will need a filesystem to boot UML from. There are a number
- available for download from here <http://user-mode-
- linux.sourceforge.net/> . There are also several tools
- <http://user-mode-linux.sourceforge.net/> which can be
+ available for download from http://user-mode-linux.sourceforge.net.
+ There are also several tools at
+ http://user-mode-linux.sourceforge.net/ which can be
used to generate UML-compatible filesystem images from media.
The kernel will boot up and present you with a login prompt.
@@ -462,10 +462,9 @@ Note:
Here are some examples of UML in action:
- - A login session <http://user-mode-linux.sourceforge.net/login.html>
-
- - A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+ - A login session http://user-mode-linux.sourceforge.net/old/login.html
+ - A virtual network http://user-mode-linux.sourceforge.net/old/net.html
@@ -1130,11 +1129,6 @@ Note:
-
- Harald's original README is here <http://user-mode-linux.source-
- forge.net/> and explains these in detail, as well as
- some other issues.
-
There is also a related point-to-point only "ucast" transport.
This is useful when your network does not support multicast, and
all network connections are simple point to point links.
@@ -1217,8 +1211,7 @@ Note:
make sure that /usr/src/linux points to the headers for the running
kernel.
- These were pointed out by Tim Robinson <timro at trkr dot net> in
- <http://www.geocrawler.com/> name="this uml-user post"> .
+ These were pointed out by Tim Robinson <timro at trkr dot net> in the past.
@@ -1912,8 +1905,8 @@ Note:
uml_moo is installed with the UML deb and RPM. If you didn't install
UML from one of those packages, you can also get it from the UML
- utilities <http://user-mode-linux.sourceforge.net/
- utilities> tar file in tools/moo.
+ utilities http://user-mode-linux.sourceforge.net/utilities tar file
+ in tools/moo.
@@ -3707,18 +3700,15 @@ Note:
This is a syslogd bug. There's a race between a parent process
- installing a signal handler and its child sending the signal. See
- this uml-devel post <http://www.geocrawler.com/lists/3/Source-
- Forge/709/0/6612801> for the details.
+ installing a signal handler and its child sending the signal.
13.8. TUN/TAP networking doesn't work on a 2.4 host
----------------------------------------------------
- There are a couple of problems which were
- <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
- out"> by Tim Robinson <timro at trkr dot net>
+ There are a couple of problems which were reported by
+ Tim Robinson <timro at trkr dot net>
- It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
The fix is to upgrade to something more recent and then read the
@@ -3761,7 +3751,7 @@ Note:
Documentation on IP Masquerading, and SNAT, can be found at
- www.netfilter.org <http://www.netfilter.org> .
+ http://www.netfilter.org.
If you can reach the local net, but not the outside Internet, then
@@ -4111,14 +4101,14 @@ Note:
Rusty Russell <rusty at linuxcare.com.au> -
- - wrote the HOWTO <http://user-mode-
- linux.sourceforge.net/UserModeLinux-HOWTO.html>
+ - wrote the HOWTO
+ http://user-mode-linux.sourceforge.net/old/UserModeLinux-HOWTO.html
- prodded me into making this project official and putting it on
SourceForge
- - came up with the way cool UML logo <http://user-mode-
- linux.sourceforge.net/uml-small.png>
+ - came up with the way cool UML logo
+ http://user-mode-linux.sourceforge.net/uml-small.png
- redid the config process
@@ -4146,17 +4136,15 @@ Note:
Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
and associated usermode tools
- Lars Brinkhoff <http://lars.nocrew.org/> - Contributed the ptrace
- proxy from his own project <http://a386.nocrew.org/> to allow easier
- kernel debugging
+ Lars Brinkhoff http://lars.nocrew.org/ - Contributed the ptrace
+ proxy from his own project to allow easier kernel debugging
Andrea Arcangeli <andrea at suse.de> - Redid some of the early boot
code so that it would work on machines with Large File Support
- Chris Emerson <http://www.chiark.greenend.org.uk/~cemerson/> - Did
- the first UML port to Linux/ppc
+ Chris Emerson - Did the first UML port to Linux/ppc
Harald Welte <laforge at gnumonks.org> - Wrote the multicast
@@ -4171,7 +4159,7 @@ Note:
wrote the iomem emulation support
- Henrik Nordstrom <http://hem.passagen.se/hno/> - Provided a variety
+ Henrik Nordstrom http://hem.passagen.se/hno/ - Provided a variety
of patches, fixes, and clues
@@ -4206,16 +4194,15 @@ Note:
submitted patches for the slip transport and lots of other things.
- David Coulson <http://davidcoulson.net> -
+ David Coulson http://davidcoulson.net -
- - Set up the usermodelinux.org <http://usermodelinux.org> site,
+ - Set up the http://usermodelinux.org site,
which is a great way of keeping the UML user community on top of
UML goings-on.
- Site documentation and updates
- Nifty little UML management daemon UMLd
- <http://uml.openconsultancy.com/umld/>
- Lots of testing and bug reports
@@ -4388,12 +4375,12 @@ Note:
work with RH 6.2.
Michael Jennings <mikejen at hevanet.com> sent in some material which
- is now gracing the top of the index page <http://user-mode-
- linux.sourceforge.net/> of this site.
+ is now gracing the top of the index page
+ http://user-mode-linux.sourceforge.net/ of this site.
- SGI <http://www.sgi.com> (and more specifically Ralf Baechle <ralf at
- uni-koblenz.de> ) gave me an account on oss.sgi.com
- <http://www.oss.sgi.com> . The bandwidth there made it possible to
+ SGI (and more specifically Ralf Baechle <ralf at
+ uni-koblenz.de> ) gave me an account on oss.sgi.com.
+ The bandwidth there made it possible to
produce most of the filesystems available on the project download
page.
@@ -4410,5 +4397,5 @@ Note:
Chris Reahard built a specialized root filesystem for running a DNS
server jailed inside UML. It's available from the download
- <http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
+ http://user-mode-linux.sourceforge.net/old/dl-sf.html page in the Jail
Filesystems section.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 04/27] docs: virt: user_mode_linux.rst: fix URL references
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Jonathan Corbet, Mauro Carvalho Chehab, Richard Weinberger,
Jeff Dike, linux-doc, linux-um, Mauro Carvalho Chehab,
Anton Ivanov
Several URLs are pointing to outdated places.
Update the references for the URLs whose contents still exists,
removing the others.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/uml/user_mode_linux.rst | 71 +++++++++-------------
1 file changed, 29 insertions(+), 42 deletions(-)
diff --git a/Documentation/virt/uml/user_mode_linux.rst b/Documentation/virt/uml/user_mode_linux.rst
index a96d29243964..d6844fb89b46 100644
--- a/Documentation/virt/uml/user_mode_linux.rst
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -319,7 +319,7 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
as modules, especially filesystems and network protocols and filters,
so most symbols which need to be exported probably already are.
However, if you do find symbols that need exporting, let us
- <http://user-mode-linux.sourceforge.net/> know, and
+ know at http://user-mode-linux.sourceforge.net/, and
they'll be "taken care of".
@@ -381,9 +381,9 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
You will need a filesystem to boot UML from. There are a number
- available for download from here <http://user-mode-
- linux.sourceforge.net/> . There are also several tools
- <http://user-mode-linux.sourceforge.net/> which can be
+ available for download from http://user-mode-linux.sourceforge.net.
+ There are also several tools at
+ http://user-mode-linux.sourceforge.net/ which can be
used to generate UML-compatible filesystem images from media.
The kernel will boot up and present you with a login prompt.
@@ -462,10 +462,9 @@ Note:
Here are some examples of UML in action:
- - A login session <http://user-mode-linux.sourceforge.net/login.html>
-
- - A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+ - A login session http://user-mode-linux.sourceforge.net/old/login.html
+ - A virtual network http://user-mode-linux.sourceforge.net/old/net.html
@@ -1130,11 +1129,6 @@ Note:
-
- Harald's original README is here <http://user-mode-linux.source-
- forge.net/> and explains these in detail, as well as
- some other issues.
-
There is also a related point-to-point only "ucast" transport.
This is useful when your network does not support multicast, and
all network connections are simple point to point links.
@@ -1217,8 +1211,7 @@ Note:
make sure that /usr/src/linux points to the headers for the running
kernel.
- These were pointed out by Tim Robinson <timro at trkr dot net> in
- <http://www.geocrawler.com/> name="this uml-user post"> .
+ These were pointed out by Tim Robinson <timro at trkr dot net> in the past.
@@ -1912,8 +1905,8 @@ Note:
uml_moo is installed with the UML deb and RPM. If you didn't install
UML from one of those packages, you can also get it from the UML
- utilities <http://user-mode-linux.sourceforge.net/
- utilities> tar file in tools/moo.
+ utilities http://user-mode-linux.sourceforge.net/utilities tar file
+ in tools/moo.
@@ -3707,18 +3700,15 @@ Note:
This is a syslogd bug. There's a race between a parent process
- installing a signal handler and its child sending the signal. See
- this uml-devel post <http://www.geocrawler.com/lists/3/Source-
- Forge/709/0/6612801> for the details.
+ installing a signal handler and its child sending the signal.
13.8. TUN/TAP networking doesn't work on a 2.4 host
----------------------------------------------------
- There are a couple of problems which were
- <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
- out"> by Tim Robinson <timro at trkr dot net>
+ There are a couple of problems which were reported by
+ Tim Robinson <timro at trkr dot net>
- It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
The fix is to upgrade to something more recent and then read the
@@ -3761,7 +3751,7 @@ Note:
Documentation on IP Masquerading, and SNAT, can be found at
- www.netfilter.org <http://www.netfilter.org> .
+ http://www.netfilter.org.
If you can reach the local net, but not the outside Internet, then
@@ -4111,14 +4101,14 @@ Note:
Rusty Russell <rusty at linuxcare.com.au> -
- - wrote the HOWTO <http://user-mode-
- linux.sourceforge.net/UserModeLinux-HOWTO.html>
+ - wrote the HOWTO
+ http://user-mode-linux.sourceforge.net/old/UserModeLinux-HOWTO.html
- prodded me into making this project official and putting it on
SourceForge
- - came up with the way cool UML logo <http://user-mode-
- linux.sourceforge.net/uml-small.png>
+ - came up with the way cool UML logo
+ http://user-mode-linux.sourceforge.net/uml-small.png
- redid the config process
@@ -4146,17 +4136,15 @@ Note:
Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
and associated usermode tools
- Lars Brinkhoff <http://lars.nocrew.org/> - Contributed the ptrace
- proxy from his own project <http://a386.nocrew.org/> to allow easier
- kernel debugging
+ Lars Brinkhoff http://lars.nocrew.org/ - Contributed the ptrace
+ proxy from his own project to allow easier kernel debugging
Andrea Arcangeli <andrea at suse.de> - Redid some of the early boot
code so that it would work on machines with Large File Support
- Chris Emerson <http://www.chiark.greenend.org.uk/~cemerson/> - Did
- the first UML port to Linux/ppc
+ Chris Emerson - Did the first UML port to Linux/ppc
Harald Welte <laforge at gnumonks.org> - Wrote the multicast
@@ -4171,7 +4159,7 @@ Note:
wrote the iomem emulation support
- Henrik Nordstrom <http://hem.passagen.se/hno/> - Provided a variety
+ Henrik Nordstrom http://hem.passagen.se/hno/ - Provided a variety
of patches, fixes, and clues
@@ -4206,16 +4194,15 @@ Note:
submitted patches for the slip transport and lots of other things.
- David Coulson <http://davidcoulson.net> -
+ David Coulson http://davidcoulson.net -
- - Set up the usermodelinux.org <http://usermodelinux.org> site,
+ - Set up the http://usermodelinux.org site,
which is a great way of keeping the UML user community on top of
UML goings-on.
- Site documentation and updates
- Nifty little UML management daemon UMLd
- <http://uml.openconsultancy.com/umld/>
- Lots of testing and bug reports
@@ -4388,12 +4375,12 @@ Note:
work with RH 6.2.
Michael Jennings <mikejen at hevanet.com> sent in some material which
- is now gracing the top of the index page <http://user-mode-
- linux.sourceforge.net/> of this site.
+ is now gracing the top of the index page
+ http://user-mode-linux.sourceforge.net/ of this site.
- SGI <http://www.sgi.com> (and more specifically Ralf Baechle <ralf at
- uni-koblenz.de> ) gave me an account on oss.sgi.com
- <http://www.oss.sgi.com> . The bandwidth there made it possible to
+ SGI (and more specifically Ralf Baechle <ralf at
+ uni-koblenz.de> ) gave me an account on oss.sgi.com.
+ The bandwidth there made it possible to
produce most of the filesystems available on the project download
page.
@@ -4410,5 +4397,5 @@ Note:
Chris Reahard built a specialized root filesystem for running a DNS
server jailed inside UML. It's available from the download
- <http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
+ http://user-mode-linux.sourceforge.net/old/dl-sf.html page in the Jail
Filesystems section.
--
2.24.1
_______________________________________________
linux-um mailing list
linux-um@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-um
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 04/27] docs: virt: user_mode_linux.rst: fix URL references
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Jeff Dike,
Richard Weinberger, Anton Ivanov, Jonathan Corbet, linux-um,
linux-doc
Several URLs are pointing to outdated places.
Update the references for the URLs whose contents still exists,
removing the others.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/virt/uml/user_mode_linux.rst | 71 +++++++++-------------
1 file changed, 29 insertions(+), 42 deletions(-)
diff --git a/Documentation/virt/uml/user_mode_linux.rst b/Documentation/virt/uml/user_mode_linux.rst
index a96d29243964..d6844fb89b46 100644
--- a/Documentation/virt/uml/user_mode_linux.rst
+++ b/Documentation/virt/uml/user_mode_linux.rst
@@ -319,7 +319,7 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
as modules, especially filesystems and network protocols and filters,
so most symbols which need to be exported probably already are.
However, if you do find symbols that need exporting, let us
- <http://user-mode-linux.sourceforge.net/> know, and
+ know at http://user-mode-linux.sourceforge.net/, and
they'll be "taken care of".
@@ -381,9 +381,9 @@ Linux: a port of the Linux kernel as a normal Intel Linux process.
You will need a filesystem to boot UML from. There are a number
- available for download from here <http://user-mode-
- linux.sourceforge.net/> . There are also several tools
- <http://user-mode-linux.sourceforge.net/> which can be
+ available for download from http://user-mode-linux.sourceforge.net.
+ There are also several tools at
+ http://user-mode-linux.sourceforge.net/ which can be
used to generate UML-compatible filesystem images from media.
The kernel will boot up and present you with a login prompt.
@@ -462,10 +462,9 @@ Note:
Here are some examples of UML in action:
- - A login session <http://user-mode-linux.sourceforge.net/login.html>
-
- - A virtual network <http://user-mode-linux.sourceforge.net/net.html>
+ - A login session http://user-mode-linux.sourceforge.net/old/login.html
+ - A virtual network http://user-mode-linux.sourceforge.net/old/net.html
@@ -1130,11 +1129,6 @@ Note:
-
- Harald's original README is here <http://user-mode-linux.source-
- forge.net/> and explains these in detail, as well as
- some other issues.
-
There is also a related point-to-point only "ucast" transport.
This is useful when your network does not support multicast, and
all network connections are simple point to point links.
@@ -1217,8 +1211,7 @@ Note:
make sure that /usr/src/linux points to the headers for the running
kernel.
- These were pointed out by Tim Robinson <timro at trkr dot net> in
- <http://www.geocrawler.com/> name="this uml-user post"> .
+ These were pointed out by Tim Robinson <timro at trkr dot net> in the past.
@@ -1912,8 +1905,8 @@ Note:
uml_moo is installed with the UML deb and RPM. If you didn't install
UML from one of those packages, you can also get it from the UML
- utilities <http://user-mode-linux.sourceforge.net/
- utilities> tar file in tools/moo.
+ utilities http://user-mode-linux.sourceforge.net/utilities tar file
+ in tools/moo.
@@ -3707,18 +3700,15 @@ Note:
This is a syslogd bug. There's a race between a parent process
- installing a signal handler and its child sending the signal. See
- this uml-devel post <http://www.geocrawler.com/lists/3/Source-
- Forge/709/0/6612801> for the details.
+ installing a signal handler and its child sending the signal.
13.8. TUN/TAP networking doesn't work on a 2.4 host
----------------------------------------------------
- There are a couple of problems which were
- <http://www.geocrawler.com/lists/3/SourceForge/597/0/> name="pointed
- out"> by Tim Robinson <timro at trkr dot net>
+ There are a couple of problems which were reported by
+ Tim Robinson <timro at trkr dot net>
- It doesn't work on hosts running 2.4.7 (or thereabouts) or earlier.
The fix is to upgrade to something more recent and then read the
@@ -3761,7 +3751,7 @@ Note:
Documentation on IP Masquerading, and SNAT, can be found at
- www.netfilter.org <http://www.netfilter.org> .
+ http://www.netfilter.org.
If you can reach the local net, but not the outside Internet, then
@@ -4111,14 +4101,14 @@ Note:
Rusty Russell <rusty at linuxcare.com.au> -
- - wrote the HOWTO <http://user-mode-
- linux.sourceforge.net/UserModeLinux-HOWTO.html>
+ - wrote the HOWTO
+ http://user-mode-linux.sourceforge.net/old/UserModeLinux-HOWTO.html
- prodded me into making this project official and putting it on
SourceForge
- - came up with the way cool UML logo <http://user-mode-
- linux.sourceforge.net/uml-small.png>
+ - came up with the way cool UML logo
+ http://user-mode-linux.sourceforge.net/uml-small.png
- redid the config process
@@ -4146,17 +4136,15 @@ Note:
Jim Leu <jleu at mindspring.com> - Wrote the virtual ethernet driver
and associated usermode tools
- Lars Brinkhoff <http://lars.nocrew.org/> - Contributed the ptrace
- proxy from his own project <http://a386.nocrew.org/> to allow easier
- kernel debugging
+ Lars Brinkhoff http://lars.nocrew.org/ - Contributed the ptrace
+ proxy from his own project to allow easier kernel debugging
Andrea Arcangeli <andrea at suse.de> - Redid some of the early boot
code so that it would work on machines with Large File Support
- Chris Emerson <http://www.chiark.greenend.org.uk/~cemerson/> - Did
- the first UML port to Linux/ppc
+ Chris Emerson - Did the first UML port to Linux/ppc
Harald Welte <laforge at gnumonks.org> - Wrote the multicast
@@ -4171,7 +4159,7 @@ Note:
wrote the iomem emulation support
- Henrik Nordstrom <http://hem.passagen.se/hno/> - Provided a variety
+ Henrik Nordstrom http://hem.passagen.se/hno/ - Provided a variety
of patches, fixes, and clues
@@ -4206,16 +4194,15 @@ Note:
submitted patches for the slip transport and lots of other things.
- David Coulson <http://davidcoulson.net> -
+ David Coulson http://davidcoulson.net -
- - Set up the usermodelinux.org <http://usermodelinux.org> site,
+ - Set up the http://usermodelinux.org site,
which is a great way of keeping the UML user community on top of
UML goings-on.
- Site documentation and updates
- Nifty little UML management daemon UMLd
- <http://uml.openconsultancy.com/umld/>
- Lots of testing and bug reports
@@ -4388,12 +4375,12 @@ Note:
work with RH 6.2.
Michael Jennings <mikejen at hevanet.com> sent in some material which
- is now gracing the top of the index page <http://user-mode-
- linux.sourceforge.net/> of this site.
+ is now gracing the top of the index page
+ http://user-mode-linux.sourceforge.net/ of this site.
- SGI <http://www.sgi.com> (and more specifically Ralf Baechle <ralf at
- uni-koblenz.de> ) gave me an account on oss.sgi.com
- <http://www.oss.sgi.com> . The bandwidth there made it possible to
+ SGI (and more specifically Ralf Baechle <ralf at
+ uni-koblenz.de> ) gave me an account on oss.sgi.com.
+ The bandwidth there made it possible to
produce most of the filesystems available on the project download
page.
@@ -4410,5 +4397,5 @@ Note:
Chris Reahard built a specialized root filesystem for running a DNS
server jailed inside UML. It's available from the download
- <http://user-mode-linux.sourceforge.net/dl-sf.html> page in the Jail
+ http://user-mode-linux.sourceforge.net/old/dl-sf.html page in the Jail
Filesystems section.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 05/27] docs: virt: convert halt-polling.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../{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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 05/27] docs: virt: convert halt-polling.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../{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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 05/27] docs: virt: convert halt-polling.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../{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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 06/27] docs: virt: Convert msr.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use document title markup;
- Convert tables;
- Add blank lines and adjust indentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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 <glommer@redhat.com>, Red Hat Inc, 2010
-=====================================================
+=================
+KVM-specific MSRs
+=================
+
+:Author: Glauber Costa <glommer@redhat.com>, 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.
-
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 06/27] docs: virt: Convert msr.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use document title markup;
- Convert tables;
- Add blank lines and adjust indentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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 <glommer@redhat.com>, Red Hat Inc, 2010
-=====================================================
+=================
+KVM-specific MSRs
+=================
+
+:Author: Glauber Costa <glommer@redhat.com>, 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.
-
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 06/27] docs: virt: Convert msr.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use document title markup;
- Convert tables;
- Add blank lines and adjust indentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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 <glommer@redhat.com>, Red Hat Inc, 2010
-=====================================================
+=================
+KVM-specific MSRs
+=================
+
+:Author: Glauber Costa <glommer@redhat.com>, 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.
-
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 07/27] docs: kvm: devices/arm-vgic-its.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../{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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 07/27] docs: kvm: devices/arm-vgic-its.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../{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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 07/27] docs: kvm: devices/arm-vgic-its.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../{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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 08/27] docs: kvm: devices/arm-vgit-v3.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use title markups;
- change indent to match ReST syntax;
- use proper table markups;
- use literal block markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../{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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 08/27] docs: kvm: devices/arm-vgit-v3.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use title markups;
- change indent to match ReST syntax;
- use proper table markups;
- use literal block markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../{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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 08/27] docs: kvm: devices/arm-vgit-v3.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use title markups;
- change indent to match ReST syntax;
- use proper table markups;
- use literal block markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../{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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 09/27] docs: kvm: convert devices/arm-vgit.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use title markups;
- change indent to match ReST syntax;
- use proper table markups;
- use literal block markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 09/27] docs: kvm: convert devices/arm-vgit.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use title markups;
- change indent to match ReST syntax;
- use proper table markups;
- use literal block markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 09/27] docs: kvm: convert devices/arm-vgit.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use title markups;
- change indent to match ReST syntax;
- use proper table markups;
- use literal block markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 10/27] docs: kvm: convert devices/mpic.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 10/27] docs: kvm: convert devices/mpic.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 10/27] docs: kvm: convert devices/mpic.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 11/27] docs: kvm: convert devices/s390_flic.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 11/27] docs: kvm: convert devices/s390_flic.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 11/27] docs: kvm: convert devices/s390_flic.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* Re: [PATCH 11/27] docs: kvm: convert devices/s390_flic.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
(?)
@ 2020-01-28 18:11 ` Cornelia Huck
-1 siblings, 0 replies; 64+ messages in thread
From: Cornelia Huck @ 2020-01-28 18:11 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
On Tue, 28 Jan 2020 14:58:07 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> - 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 <mchehab+huawei@kernel.org>
> ---
> 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%)
Looks sane to me.
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
^ permalink raw reply [flat|nested] 64+ messages in thread* Re: [PATCH 11/27] docs: kvm: convert devices/s390_flic.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
(?)
(?)
@ 2020-01-28 18:13 ` Cornelia Huck
2020-01-28 20:38 ` Mauro Carvalho Chehab
-1 siblings, 1 reply; 64+ messages in thread
From: Cornelia Huck @ 2020-01-28 18:13 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
On Tue, 28 Jan 2020 15:00:12 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> - 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 <mchehab+huawei@kernel.org>
> ---
> 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%)
Duplicate... old files?
^ permalink raw reply [flat|nested] 64+ messages in thread* Re: [PATCH 11/27] docs: kvm: convert devices/s390_flic.txt to ReST
2020-01-28 18:13 ` Cornelia Huck
@ 2020-01-28 20:38 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 20:38 UTC (permalink / raw)
To: Cornelia Huck
Cc: Linux Media Mailing List, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
Em Tue, 28 Jan 2020 19:13:48 +0100
Cornelia Huck <cohuck@redhat.com> escreveu:
> On Tue, 28 Jan 2020 15:00:12 +0100
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>
> > - 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 <mchehab+huawei@kernel.org>
> > ---
> > 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%)
>
> Duplicate... old files?
It is duplicated. Sorry for that. I'm using an old notebook with a bad
internet connection. I ended by sending the same patch series twice,
as it sounded that the first attempt failed due to some errors I got
from git send-email.
Regards,
Mauro
^ permalink raw reply [flat|nested] 64+ messages in thread
* [PATCH 12/27] docs: kvm: convert devices/vcpu.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 12/27] docs: kvm: convert devices/vcpu.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 13/27] docs: kvm: convert devices/vcpu.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use standard title markup;
- adjust lists;
- 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/{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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 13/27] docs: kvm: convert devices/vcpu.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use standard title markup;
- adjust lists;
- 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/{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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 13/27] docs: kvm: convert devices/vcpu.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Use standard title markup;
- adjust lists;
- 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/{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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 14/27] docs: kvm: convert devices/vm.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 14/27] docs: kvm: convert devices/vm.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 14/27] docs: kvm: convert devices/vm.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 15/27] docs: kvm: convert devices/xics.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 15/27] docs: kvm: convert devices/xics.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 15/27] docs: kvm: convert devices/xics.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 16/27] docs: kvm: convert devices/xive.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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} | 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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 16/27] docs: kvm: convert devices/xive.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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} | 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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 16/27] docs: kvm: convert devices/xive.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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} | 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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 17/27] docs: kvm: Convert api.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
convert api.txt document to ReST format while trying to keep
its format as close as possible with the authors intent, and
avoid adding uneeded markups.
- 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 <mchehab+huawei@kernel.org>
---
Documentation/virt/kvm/{api.txt => api.rst} | 3343 +++++++++++--------
Documentation/virt/kvm/index.rst | 1 +
2 files changed, 1959 insertions(+), 1385 deletions(-)
rename Documentation/virt/kvm/{api.txt => api.rst} (71%)
diff --git a/Documentation/virt/kvm/api.txt b/Documentation/virt/kvm/api.rst
similarity index 71%
rename from Documentation/virt/kvm/api.txt
rename to Documentation/virt/kvm/api.rst
index ebb37b34dcfc..c6e1bb3ae0c6 100644
--- a/Documentation/virt/kvm/api.txt
+++ b/Documentation/virt/kvm/api.rst
@@ -1,8 +1,9 @@
+===================================================================
The Definitive KVM (Kernel-based Virtual Machine) API Documentation
===================================================================
1. General description
-----------------------
+======================
The kvm API is a set of ioctls that are issued to control various aspects
of a virtual machine. The ioctls belong to the following classes:
@@ -33,7 +34,7 @@ of a virtual machine. The ioctls belong to the following classes:
was used to create the VM.
2. File descriptors
--------------------
+===================
The kvm API is centered around file descriptors. An initial
open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
@@ -70,7 +71,7 @@ the VM is shut down.
3. Extensions
--------------
+=============
As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
incompatible change are allowed. However, there is an extension
@@ -84,13 +85,14 @@ set of ioctls is available for application use.
4. API description
-------------------
+==================
This section describes ioctls that can be used to control kvm guests.
For each ioctl, the following information is provided along with a
description:
- Capability: which KVM extension provides this ioctl. Can be 'basic',
+ Capability:
+ which KVM extension provides this ioctl. Can be 'basic',
which means that is will be provided by any kernel that supports
API version 12 (see section 4.1), a KVM_CAP_xyz constant, which
means availability needs to be checked with KVM_CHECK_EXTENSION
@@ -99,24 +101,29 @@ description:
availability: for kernels that don't support the ioctl,
the ioctl returns -ENOTTY.
- Architectures: which instruction set architectures provide this ioctl.
+ Architectures:
+ which instruction set architectures provide this ioctl.
x86 includes both i386 and x86_64.
- Type: system, vm, or vcpu.
+ Type:
+ system, vm, or vcpu.
- Parameters: what parameters are accepted by the ioctl.
+ Parameters:
+ what parameters are accepted by the ioctl.
- Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
+ Returns:
+ the return value. General error numbers (EBADF, ENOMEM, EINVAL)
are not detailed, but errors with specific meanings are.
4.1 KVM_GET_API_VERSION
+-----------------------
-Capability: basic
-Architectures: all
-Type: system ioctl
-Parameters: none
-Returns: the constant KVM_API_VERSION (=12)
+:Capability: basic
+:Architectures: all
+:Type: system ioctl
+:Parameters: none
+:Returns: the constant KVM_API_VERSION (=12)
This identifies the API version as the stable kvm API. It is not
expected that this number will change. However, Linux 2.6.20 and
@@ -127,12 +134,13 @@ described as 'basic' will be available.
4.2 KVM_CREATE_VM
+-----------------
-Capability: basic
-Architectures: all
-Type: system ioctl
-Parameters: machine type identifier (KVM_VM_*)
-Returns: a VM fd that can be used to control the new virtual machine.
+:Capability: basic
+:Architectures: all
+:Type: system ioctl
+:Parameters: machine type identifier (KVM_VM_*)
+:Returns: a VM fd that can be used to control the new virtual machine.
The new VM has no virtual cpus and no memory.
You probably want to use 0 as machine type.
@@ -155,17 +163,17 @@ identifier, where IPA_Bits is the maximum width of any physical
address used by the VM. The IPA_Bits is encoded in bits[7-0] of the
machine type identifier.
-e.g, to configure a guest to use 48bit physical address size :
+e.g, to configure a guest to use 48bit physical address size::
vm_fd = ioctl(dev_fd, KVM_CREATE_VM, KVM_VM_TYPE_ARM_IPA_SIZE(48));
-The requested size (IPA_Bits) must be :
- 0 - Implies default size, 40bits (for backward compatibility)
+The requested size (IPA_Bits) must be:
- or
-
- N - Implies N bits, where N is a positive integer such that,
+ == =========================================================
+ 0 Implies default size, 40bits (for backward compatibility)
+ N Implies N bits, where N is a positive integer such that,
32 <= N <= Host_IPA_Limit
+ == =========================================================
Host_IPA_Limit is the maximum possible value for IPA_Bits on the host and
is dependent on the CPU capability and the kernel configuration. The limit can
@@ -179,21 +187,28 @@ host physical address translations).
4.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST
+----------------------------------------------------------
+
+:Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST
+:Architectures: x86
+:Type: system ioctl
+:Parameters: struct kvm_msr_list (in/out)
+:Returns: 0 on success; -1 on error
-Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST
-Architectures: x86
-Type: system ioctl
-Parameters: struct kvm_msr_list (in/out)
-Returns: 0 on success; -1 on error
Errors:
- EFAULT: the msr index list cannot be read from or written to
- E2BIG: the msr index list is to be to fit in the array specified by
+
+ ====== ============================================================
+ EFAULT the msr index list cannot be read from or written to
+ E2BIG the msr index list is to be to fit in the array specified by
the user.
+ ====== ============================================================
-struct kvm_msr_list {
+::
+
+ struct kvm_msr_list {
__u32 nmsrs; /* number of msrs in entries */
__u32 indices[0];
-};
+ };
The user fills in the size of the indices array in nmsrs, and in return
kvm adjusts nmsrs to reflect the actual number of msrs and fills in the
@@ -214,12 +229,13 @@ otherwise.
4.4 KVM_CHECK_EXTENSION
+-----------------------
-Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl
-Architectures: all
-Type: system ioctl, vm ioctl
-Parameters: extension identifier (KVM_CAP_*)
-Returns: 0 if unsupported; 1 (or some other positive integer) if supported
+:Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl
+:Architectures: all
+:Type: system ioctl, vm ioctl
+:Parameters: extension identifier (KVM_CAP_*)
+:Returns: 0 if unsupported; 1 (or some other positive integer) if supported
The API allows the application to query about extensions to the core
kvm API. Userspace passes an extension identifier (an integer) and
@@ -232,12 +248,13 @@ It is thus encouraged to use the vm ioctl to query for capabilities (available
with KVM_CAP_CHECK_EXTENSION_VM on the vm fd)
4.5 KVM_GET_VCPU_MMAP_SIZE
+--------------------------
-Capability: basic
-Architectures: all
-Type: system ioctl
-Parameters: none
-Returns: size of vcpu mmap area, in bytes
+:Capability: basic
+:Architectures: all
+:Type: system ioctl
+:Parameters: none
+:Returns: size of vcpu mmap area, in bytes
The KVM_RUN ioctl (cf.) communicates with userspace via a shared
memory region. This ioctl returns the size of that region. See the
@@ -245,23 +262,25 @@ KVM_RUN documentation for details.
4.6 KVM_SET_MEMORY_REGION
+-------------------------
-Capability: basic
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_memory_region (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_memory_region (in)
+:Returns: 0 on success, -1 on error
This ioctl is obsolete and has been removed.
4.7 KVM_CREATE_VCPU
+-------------------
-Capability: basic
-Architectures: all
-Type: vm ioctl
-Parameters: vcpu id (apic id on x86)
-Returns: vcpu fd on success, -1 on error
+:Capability: basic
+:Architectures: all
+:Type: vm ioctl
+:Parameters: vcpu id (apic id on x86)
+:Returns: vcpu fd on success, -1 on error
This API adds a vcpu to a virtual machine. No more than max_vcpus may be added.
The vcpu id is an integer in the range [0, max_vcpu_id).
@@ -302,22 +321,25 @@ cpu's hardware control block.
4.8 KVM_GET_DIRTY_LOG (vm ioctl)
+--------------------------------
-Capability: basic
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_dirty_log (in/out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_dirty_log (in/out)
+:Returns: 0 on success, -1 on error
-/* for KVM_GET_DIRTY_LOG */
-struct kvm_dirty_log {
+::
+
+ /* for KVM_GET_DIRTY_LOG */
+ struct kvm_dirty_log {
__u32 slot;
__u32 padding;
union {
void __user *dirty_bitmap; /* one bit per page */
__u64 padding;
};
-};
+ };
Given a memory slot, return a bitmap containing any pages dirtied
since the last call to this ioctl. Bit 0 is the first page in the
@@ -334,25 +356,31 @@ KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is enabled. For more information,
see the description of the capability.
4.9 KVM_SET_MEMORY_ALIAS
+------------------------
-Capability: basic
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_memory_alias (in)
-Returns: 0 (success), -1 (error)
+:Capability: basic
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_memory_alias (in)
+:Returns: 0 (success), -1 (error)
This ioctl is obsolete and has been removed.
4.10 KVM_RUN
+------------
+
+:Capability: basic
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: none
+:Returns: 0 on success, -1 on error
-Capability: basic
-Architectures: all
-Type: vcpu ioctl
-Parameters: none
-Returns: 0 on success, -1 on error
Errors:
- EINTR: an unmasked signal is pending
+
+ ===== =============================
+ EINTR an unmasked signal is pending
+ ===== =============================
This ioctl is used to run a guest virtual cpu. While there are no
explicit parameters, there is an implicit parameter block that can be
@@ -362,42 +390,46 @@ kvm_run' (see below).
4.11 KVM_GET_REGS
+-----------------
-Capability: basic
-Architectures: all except ARM, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_regs (out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all except ARM, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_regs (out)
+:Returns: 0 on success, -1 on error
Reads the general purpose registers from the vcpu.
-/* x86 */
-struct kvm_regs {
+::
+
+ /* x86 */
+ struct kvm_regs {
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
__u64 rax, rbx, rcx, rdx;
__u64 rsi, rdi, rsp, rbp;
__u64 r8, r9, r10, r11;
__u64 r12, r13, r14, r15;
__u64 rip, rflags;
-};
+ };
-/* mips */
-struct kvm_regs {
+ /* mips */
+ struct kvm_regs {
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
__u64 gpr[32];
__u64 hi;
__u64 lo;
__u64 pc;
-};
+ };
4.12 KVM_SET_REGS
+-----------------
-Capability: basic
-Architectures: all except ARM, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_regs (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all except ARM, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_regs (in)
+:Returns: 0 on success, -1 on error
Writes the general purpose registers into the vcpu.
@@ -405,17 +437,20 @@ See KVM_GET_REGS for the data structure.
4.13 KVM_GET_SREGS
+------------------
-Capability: basic
-Architectures: x86, ppc
-Type: vcpu ioctl
-Parameters: struct kvm_sregs (out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86, ppc
+:Type: vcpu ioctl
+:Parameters: struct kvm_sregs (out)
+:Returns: 0 on success, -1 on error
Reads special registers from the vcpu.
-/* x86 */
-struct kvm_sregs {
+::
+
+ /* x86 */
+ struct kvm_sregs {
struct kvm_segment cs, ds, es, fs, gs, ss;
struct kvm_segment tr, ldt;
struct kvm_dtable gdt, idt;
@@ -423,9 +458,9 @@ struct kvm_sregs {
__u64 efer;
__u64 apic_base;
__u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
-};
+ };
-/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */
+ /* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */
interrupt_bitmap is a bitmap of pending external interrupts. At most
one bit may be set. This interrupt has been acknowledged by the APIC
@@ -433,29 +468,33 @@ but not yet injected into the cpu core.
4.14 KVM_SET_SREGS
+------------------
-Capability: basic
-Architectures: x86, ppc
-Type: vcpu ioctl
-Parameters: struct kvm_sregs (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86, ppc
+:Type: vcpu ioctl
+:Parameters: struct kvm_sregs (in)
+:Returns: 0 on success, -1 on error
Writes special registers into the vcpu. See KVM_GET_SREGS for the
data structures.
4.15 KVM_TRANSLATE
+------------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_translation (in/out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_translation (in/out)
+:Returns: 0 on success, -1 on error
Translates a virtual address according to the vcpu's current address
translation mode.
-struct kvm_translation {
+::
+
+ struct kvm_translation {
/* in */
__u64 linear_address;
@@ -465,59 +504,68 @@ struct kvm_translation {
__u8 writeable;
__u8 usermode;
__u8 pad[5];
-};
+ };
4.16 KVM_INTERRUPT
+------------------
-Capability: basic
-Architectures: x86, ppc, mips
-Type: vcpu ioctl
-Parameters: struct kvm_interrupt (in)
-Returns: 0 on success, negative on failure.
+:Capability: basic
+:Architectures: x86, ppc, mips
+:Type: vcpu ioctl
+:Parameters: struct kvm_interrupt (in)
+:Returns: 0 on success, negative on failure.
Queues a hardware interrupt vector to be injected.
-/* for KVM_INTERRUPT */
-struct kvm_interrupt {
+::
+
+ /* for KVM_INTERRUPT */
+ struct kvm_interrupt {
/* in */
__u32 irq;
-};
+ };
X86:
+^^^^
-Returns: 0 on success,
- -EEXIST if an interrupt is already enqueued
- -EINVAL the the irq number is invalid
- -ENXIO if the PIC is in the kernel
- -EFAULT if the pointer is invalid
+:Returns:
+
+ ========= ===================================
+ 0 on success,
+ -EEXIST if an interrupt is already enqueued
+ -EINVAL the the irq number is invalid
+ -ENXIO if the PIC is in the kernel
+ -EFAULT if the pointer is invalid
+ ========= ===================================
Note 'irq' is an interrupt vector, not an interrupt pin or line. This
ioctl is useful if the in-kernel PIC is not used.
PPC:
+^^^^
Queues an external interrupt to be injected. This ioctl is overleaded
with 3 different irq values:
a) KVM_INTERRUPT_SET
- This injects an edge type external interrupt into the guest once it's ready
- to receive interrupts. When injected, the interrupt is done.
+ This injects an edge type external interrupt into the guest once it's ready
+ to receive interrupts. When injected, the interrupt is done.
b) KVM_INTERRUPT_UNSET
- This unsets any pending interrupt.
+ This unsets any pending interrupt.
- Only available with KVM_CAP_PPC_UNSET_IRQ.
+ Only available with KVM_CAP_PPC_UNSET_IRQ.
c) KVM_INTERRUPT_SET_LEVEL
- This injects a level type external interrupt into the guest context. The
- interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
- is triggered.
+ This injects a level type external interrupt into the guest context. The
+ interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
+ is triggered.
- Only available with KVM_CAP_PPC_IRQ_LEVEL.
+ Only available with KVM_CAP_PPC_IRQ_LEVEL.
Note that any value for 'irq' other than the ones stated above is invalid
and incurs unexpected behavior.
@@ -525,6 +573,7 @@ and incurs unexpected behavior.
This is an asynchronous vcpu ioctl and can be invoked from any thread.
MIPS:
+^^^^^
Queues an external interrupt to be injected into the virtual CPU. A negative
interrupt number dequeues the interrupt.
@@ -533,24 +582,26 @@ This is an asynchronous vcpu ioctl and can be invoked from any thread.
4.17 KVM_DEBUG_GUEST
+--------------------
-Capability: basic
-Architectures: none
-Type: vcpu ioctl
-Parameters: none)
-Returns: -1 on error
+:Capability: basic
+:Architectures: none
+:Type: vcpu ioctl
+:Parameters: none)
+:Returns: -1 on error
Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead.
4.18 KVM_GET_MSRS
+-----------------
-Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system)
-Architectures: x86
-Type: system ioctl, vcpu ioctl
-Parameters: struct kvm_msrs (in/out)
-Returns: number of msrs successfully returned;
- -1 on error
+:Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system)
+:Architectures: x86
+:Type: system ioctl, vcpu ioctl
+:Parameters: struct kvm_msrs (in/out)
+:Returns: number of msrs successfully returned;
+ -1 on error
When used as a system ioctl:
Reads the values of MSR-based features that are available for the VM. This
@@ -562,18 +613,20 @@ When used as a vcpu ioctl:
Reads model-specific registers from the vcpu. Supported msr indices can
be obtained using KVM_GET_MSR_INDEX_LIST in a system ioctl.
-struct kvm_msrs {
+::
+
+ struct kvm_msrs {
__u32 nmsrs; /* number of msrs in entries */
__u32 pad;
struct kvm_msr_entry entries[0];
-};
+ };
-struct kvm_msr_entry {
+ struct kvm_msr_entry {
__u32 index;
__u32 reserved;
__u64 data;
-};
+ };
Application code should set the 'nmsrs' member (which indicates the
size of the entries array) and the 'index' member of each array entry.
@@ -581,12 +634,13 @@ kvm will fill in the 'data' member.
4.19 KVM_SET_MSRS
+-----------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_msrs (in)
-Returns: number of msrs successfully set (see below), -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_msrs (in)
+:Returns: number of msrs successfully set (see below), -1 on error
Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
data structures.
@@ -602,41 +656,44 @@ MSRs that have been set successfully.
4.20 KVM_SET_CPUID
+------------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_cpuid (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_cpuid (in)
+:Returns: 0 on success, -1 on error
Defines the vcpu responses to the cpuid instruction. Applications
should use the KVM_SET_CPUID2 ioctl if available.
+::
-struct kvm_cpuid_entry {
+ struct kvm_cpuid_entry {
__u32 function;
__u32 eax;
__u32 ebx;
__u32 ecx;
__u32 edx;
__u32 padding;
-};
+ };
-/* for KVM_SET_CPUID */
-struct kvm_cpuid {
+ /* for KVM_SET_CPUID */
+ struct kvm_cpuid {
__u32 nent;
__u32 padding;
struct kvm_cpuid_entry entries[0];
-};
+ };
4.21 KVM_SET_SIGNAL_MASK
+------------------------
-Capability: basic
-Architectures: all
-Type: vcpu ioctl
-Parameters: struct kvm_signal_mask (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: struct kvm_signal_mask (in)
+:Returns: 0 on success, -1 on error
Defines which signals are blocked during execution of KVM_RUN. This
signal mask temporarily overrides the threads signal mask. Any
@@ -646,25 +703,30 @@ their traditional behaviour) will cause KVM_RUN to return with -EINTR.
Note the signal will only be delivered if not blocked by the original
signal mask.
-/* for KVM_SET_SIGNAL_MASK */
-struct kvm_signal_mask {
+::
+
+ /* for KVM_SET_SIGNAL_MASK */
+ struct kvm_signal_mask {
__u32 len;
__u8 sigset[0];
-};
+ };
4.22 KVM_GET_FPU
+----------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_fpu (out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_fpu (out)
+:Returns: 0 on success, -1 on error
Reads the floating point state from the vcpu.
-/* for KVM_GET_FPU and KVM_SET_FPU */
-struct kvm_fpu {
+::
+
+ /* for KVM_GET_FPU and KVM_SET_FPU */
+ struct kvm_fpu {
__u8 fpr[8][16];
__u16 fcw;
__u16 fsw;
@@ -676,21 +738,24 @@ struct kvm_fpu {
__u8 xmm[16][16];
__u32 mxcsr;
__u32 pad2;
-};
+ };
4.23 KVM_SET_FPU
+----------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_fpu (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_fpu (in)
+:Returns: 0 on success, -1 on error
Writes the floating point state to the vcpu.
-/* for KVM_GET_FPU and KVM_SET_FPU */
-struct kvm_fpu {
+::
+
+ /* for KVM_GET_FPU and KVM_SET_FPU */
+ struct kvm_fpu {
__u8 fpr[8][16];
__u16 fcw;
__u16 fsw;
@@ -702,16 +767,17 @@ struct kvm_fpu {
__u8 xmm[16][16];
__u32 mxcsr;
__u32 pad2;
-};
+ };
4.24 KVM_CREATE_IRQCHIP
+-----------------------
-Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390)
-Architectures: x86, ARM, arm64, s390
-Type: vm ioctl
-Parameters: none
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390)
+:Architectures: x86, ARM, arm64, s390
+:Type: vm ioctl
+:Parameters: none
+:Returns: 0 on success, -1 on error
Creates an interrupt controller model in the kernel.
On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up
@@ -727,12 +793,13 @@ before KVM_CREATE_IRQCHIP can be used.
4.25 KVM_IRQ_LINE
+-----------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86, arm, arm64
-Type: vm ioctl
-Parameters: struct kvm_irq_level
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86, arm, arm64
+:Type: vm ioctl
+:Parameters: struct kvm_irq_level
+:Returns: 0 on success, -1 on error
Sets the level of a GSI input to the interrupt controller model in the kernel.
On some architectures it is required that an interrupt controller model has
@@ -756,16 +823,20 @@ of course).
ARM/arm64 can signal an interrupt either at the CPU level, or at the
in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to
use PPIs designated for specific cpus. The irq field is interpreted
-like this:
+like this::
bits: | 31 ... 28 | 27 ... 24 | 23 ... 16 | 15 ... 0 |
field: | vcpu2_index | irq_type | vcpu_index | irq_id |
The irq_type field has the following values:
-- irq_type[0]: out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ
-- irq_type[1]: in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.)
+
+- irq_type[0]:
+ out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ
+- irq_type[1]:
+ in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.)
(the vcpu_index field is ignored)
-- irq_type[2]: in-kernel GIC: PPI, irq_id between 16 and 31 (incl.)
+- irq_type[2]:
+ in-kernel GIC: PPI, irq_id between 16 and 31 (incl.)
(The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)
@@ -779,27 +850,32 @@ Note that on arm/arm64, the KVM_CAP_IRQCHIP capability only conditions
injection of interrupts for the in-kernel irqchip. KVM_IRQ_LINE can always
be used for a userspace interrupt controller.
-struct kvm_irq_level {
+::
+
+ struct kvm_irq_level {
union {
__u32 irq; /* GSI */
__s32 status; /* not used for KVM_IRQ_LEVEL */
};
__u32 level; /* 0 or 1 */
-};
+ };
4.26 KVM_GET_IRQCHIP
+--------------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_irqchip (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_irqchip (in/out)
+:Returns: 0 on success, -1 on error
Reads the state of a kernel interrupt controller created with
KVM_CREATE_IRQCHIP into a buffer provided by the caller.
-struct kvm_irqchip {
+::
+
+ struct kvm_irqchip {
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
__u32 pad;
union {
@@ -807,21 +883,24 @@ struct kvm_irqchip {
struct kvm_pic_state pic;
struct kvm_ioapic_state ioapic;
} chip;
-};
+ };
4.27 KVM_SET_IRQCHIP
+--------------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_irqchip (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_irqchip (in)
+:Returns: 0 on success, -1 on error
Sets the state of a kernel interrupt controller created with
KVM_CREATE_IRQCHIP from a buffer provided by the caller.
-struct kvm_irqchip {
+::
+
+ struct kvm_irqchip {
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
__u32 pad;
union {
@@ -829,16 +908,17 @@ struct kvm_irqchip {
struct kvm_pic_state pic;
struct kvm_ioapic_state ioapic;
} chip;
-};
+ };
4.28 KVM_XEN_HVM_CONFIG
+-----------------------
-Capability: KVM_CAP_XEN_HVM
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_xen_hvm_config (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XEN_HVM
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_xen_hvm_config (in)
+:Returns: 0 on success, -1 on error
Sets the MSR that the Xen HVM guest uses to initialize its hypercall
page, and provides the starting address and size of the hypercall
@@ -846,7 +926,9 @@ blobs in userspace. When the guest writes the MSR, kvm copies one
page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
memory.
-struct kvm_xen_hvm_config {
+::
+
+ struct kvm_xen_hvm_config {
__u32 flags;
__u32 msr;
__u64 blob_addr_32;
@@ -854,16 +936,17 @@ struct kvm_xen_hvm_config {
__u8 blob_size_32;
__u8 blob_size_64;
__u8 pad2[30];
-};
+ };
4.29 KVM_GET_CLOCK
+------------------
-Capability: KVM_CAP_ADJUST_CLOCK
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_clock_data (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_ADJUST_CLOCK
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_clock_data (out)
+:Returns: 0 on success, -1 on error
Gets the current timestamp of kvmclock as seen by the current guest. In
conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
@@ -880,47 +963,56 @@ with KVM_SET_CLOCK. KVM will try to make all VCPUs follow this clock,
but the exact value read by each VCPU could differ, because the host
TSC is not stable.
-struct kvm_clock_data {
+::
+
+ struct kvm_clock_data {
__u64 clock; /* kvmclock current value */
__u32 flags;
__u32 pad[9];
-};
+ };
4.30 KVM_SET_CLOCK
+------------------
-Capability: KVM_CAP_ADJUST_CLOCK
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_clock_data (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_ADJUST_CLOCK
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_clock_data (in)
+:Returns: 0 on success, -1 on error
Sets the current timestamp of kvmclock to the value specified in its parameter.
In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
such as migration.
-struct kvm_clock_data {
+::
+
+ struct kvm_clock_data {
__u64 clock; /* kvmclock current value */
__u32 flags;
__u32 pad[9];
-};
+ };
4.31 KVM_GET_VCPU_EVENTS
+------------------------
-Capability: KVM_CAP_VCPU_EVENTS
-Extended by: KVM_CAP_INTR_SHADOW
-Architectures: x86, arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_vcpu_event (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_VCPU_EVENTS
+:Extended by: KVM_CAP_INTR_SHADOW
+:Architectures: x86, arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_vcpu_event (out)
+:Returns: 0 on success, -1 on error
X86:
+^^^^
Gets currently pending exceptions, interrupts, and NMIs as well as related
states of the vcpu.
-struct kvm_vcpu_events {
+::
+
+ struct kvm_vcpu_events {
struct {
__u8 injected;
__u8 nr;
@@ -951,7 +1043,7 @@ struct kvm_vcpu_events {
__u8 reserved[27];
__u8 exception_has_payload;
__u64 exception_payload;
-};
+ };
The following bits are defined in the flags field:
@@ -967,6 +1059,7 @@ The following bits are defined in the flags field:
KVM_CAP_EXCEPTION_PAYLOAD is enabled.
ARM/ARM64:
+^^^^^^^^^^
If the guest accesses a device that is being emulated by the host kernel in
such a way that a real device would generate a physical SError, KVM may make
@@ -1006,8 +1099,9 @@ It is not possible to read back a pending external abort (injected via
KVM_SET_VCPU_EVENTS or otherwise) because such an exception is always delivered
directly to the virtual CPU).
+::
-struct kvm_vcpu_events {
+ struct kvm_vcpu_events {
struct {
__u8 serror_pending;
__u8 serror_has_esr;
@@ -1017,18 +1111,20 @@ struct kvm_vcpu_events {
__u64 serror_esr;
} exception;
__u32 reserved[12];
-};
+ };
4.32 KVM_SET_VCPU_EVENTS
+------------------------
-Capability: KVM_CAP_VCPU_EVENTS
-Extended by: KVM_CAP_INTR_SHADOW
-Architectures: x86, arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_vcpu_event (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_VCPU_EVENTS
+:Extended by: KVM_CAP_INTR_SHADOW
+:Architectures: x86, arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_vcpu_event (in)
+:Returns: 0 on success, -1 on error
X86:
+^^^^
Set pending exceptions, interrupts, and NMIs as well as related states of the
vcpu.
@@ -1040,9 +1136,11 @@ from the update. These fields are nmi.pending, sipi_vector, smi.smm,
smi.pending. Keep the corresponding bits in the flags field cleared to
suppress overwriting the current in-kernel state. The bits are:
-KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
-KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
-KVM_VCPUEVENT_VALID_SMM - transfer the smi sub-struct.
+=============================== ==================================
+KVM_VCPUEVENT_VALID_NMI_PENDING transfer nmi.pending to the kernel
+KVM_VCPUEVENT_VALID_SIPI_VECTOR transfer sipi_vector
+KVM_VCPUEVENT_VALID_SMM transfer the smi sub-struct.
+=============================== ==================================
If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
the flags field to signal that interrupt.shadow contains a valid state and
@@ -1056,6 +1154,7 @@ exception_has_payload, exception_payload, and exception.pending fields
contain a valid state and shall be written into the VCPU.
ARM/ARM64:
+^^^^^^^^^^
User space may need to inject several types of events to the guest.
@@ -1078,31 +1177,35 @@ See KVM_GET_VCPU_EVENTS for the data structure.
4.33 KVM_GET_DEBUGREGS
+----------------------
-Capability: KVM_CAP_DEBUGREGS
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_debugregs (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_DEBUGREGS
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_debugregs (out)
+:Returns: 0 on success, -1 on error
Reads debug registers from the vcpu.
-struct kvm_debugregs {
+::
+
+ struct kvm_debugregs {
__u64 db[4];
__u64 dr6;
__u64 dr7;
__u64 flags;
__u64 reserved[9];
-};
+ };
4.34 KVM_SET_DEBUGREGS
+----------------------
-Capability: KVM_CAP_DEBUGREGS
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_debugregs (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_DEBUGREGS
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_debugregs (in)
+:Returns: 0 on success, -1 on error
Writes debug registers into the vcpu.
@@ -1111,24 +1214,27 @@ yet and must be cleared on entry.
4.35 KVM_SET_USER_MEMORY_REGION
+-------------------------------
-Capability: KVM_CAP_USER_MEMORY
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_userspace_memory_region (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_USER_MEMORY
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_userspace_memory_region (in)
+:Returns: 0 on success, -1 on error
-struct kvm_userspace_memory_region {
+::
+
+ struct kvm_userspace_memory_region {
__u32 slot;
__u32 flags;
__u64 guest_phys_addr;
__u64 memory_size; /* bytes */
__u64 userspace_addr; /* start of the userspace allocated memory */
-};
+ };
-/* for kvm_memory_region::flags */
-#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0)
-#define KVM_MEM_READONLY (1UL << 1)
+ /* for kvm_memory_region::flags */
+ #define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0)
+ #define KVM_MEM_READONLY (1UL << 1)
This ioctl allows the user to create, modify or delete a guest physical
memory slot. Bits 0-15 of "slot" specify the slot id and this value
@@ -1174,12 +1280,13 @@ allocation and is deprecated.
4.36 KVM_SET_TSS_ADDR
+---------------------
-Capability: KVM_CAP_SET_TSS_ADDR
-Architectures: x86
-Type: vm ioctl
-Parameters: unsigned long tss_address (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_SET_TSS_ADDR
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: unsigned long tss_address (in)
+:Returns: 0 on success, -1 on error
This ioctl defines the physical address of a three-page region in the guest
physical address space. The region must be within the first 4GB of the
@@ -1193,21 +1300,24 @@ documentation when it pops into existence).
4.37 KVM_ENABLE_CAP
+-------------------
-Capability: KVM_CAP_ENABLE_CAP
-Architectures: mips, ppc, s390
-Type: vcpu ioctl
-Parameters: struct kvm_enable_cap (in)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_ENABLE_CAP
+:Architectures: mips, ppc, s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_enable_cap (in)
+:Returns: 0 on success; -1 on error
-Capability: KVM_CAP_ENABLE_CAP_VM
-Architectures: all
-Type: vcpu ioctl
-Parameters: struct kvm_enable_cap (in)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_ENABLE_CAP_VM
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: struct kvm_enable_cap (in)
+:Returns: 0 on success; -1 on error
-+Not all extensions are enabled by default. Using this ioctl the application
-can enable an extension, making it available to the guest.
+.. note::
+
+ Not all extensions are enabled by default. Using this ioctl the application
+ can enable an extension, making it available to the guest.
On systems that do not support this ioctl, it always fails. On systems that
do support it, it only works for extensions that are supported for enablement.
@@ -1215,76 +1325,91 @@ do support it, it only works for extensions that are supported for enablement.
To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
be used.
-struct kvm_enable_cap {
+::
+
+ struct kvm_enable_cap {
/* in */
__u32 cap;
The capability that is supposed to get enabled.
+::
+
__u32 flags;
A bitfield indicating future enhancements. Has to be 0 for now.
+::
+
__u64 args[4];
Arguments for enabling a feature. If a feature needs initial values to
function properly, this is the place to put them.
+::
+
__u8 pad[64];
-};
+ };
The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctl
for vm-wide capabilities.
4.38 KVM_GET_MP_STATE
+---------------------
-Capability: KVM_CAP_MP_STATE
-Architectures: x86, s390, arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_mp_state (out)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_MP_STATE
+:Architectures: x86, s390, arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_mp_state (out)
+:Returns: 0 on success; -1 on error
-struct kvm_mp_state {
+::
+
+ struct kvm_mp_state {
__u32 mp_state;
-};
+ };
Returns the vcpu's current "multiprocessing state" (though also valid on
uniprocessor guests).
Possible values are:
- - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86,arm/arm64]
- - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP)
+ ========================== ===============================================
+ KVM_MP_STATE_RUNNABLE the vcpu is currently running [x86,arm/arm64]
+ KVM_MP_STATE_UNINITIALIZED the vcpu is an application processor (AP)
which has not yet received an INIT signal [x86]
- - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is
+ KVM_MP_STATE_INIT_RECEIVED the vcpu has received an INIT signal, and is
now ready for a SIPI [x86]
- - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and
+ KVM_MP_STATE_HALTED the vcpu has executed a HLT instruction and
is waiting for an interrupt [x86]
- - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector
+ KVM_MP_STATE_SIPI_RECEIVED the vcpu has just received a SIPI (vector
accessible via KVM_GET_VCPU_EVENTS) [x86]
- - KVM_MP_STATE_STOPPED: the vcpu is stopped [s390,arm/arm64]
- - KVM_MP_STATE_CHECK_STOP: the vcpu is in a special error state [s390]
- - KVM_MP_STATE_OPERATING: the vcpu is operating (running or halted)
+ KVM_MP_STATE_STOPPED the vcpu is stopped [s390,arm/arm64]
+ KVM_MP_STATE_CHECK_STOP the vcpu is in a special error state [s390]
+ KVM_MP_STATE_OPERATING the vcpu is operating (running or halted)
[s390]
- - KVM_MP_STATE_LOAD: the vcpu is in a special load/startup state
+ KVM_MP_STATE_LOAD the vcpu is in a special load/startup state
[s390]
+ ========================== ===============================================
On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an
in-kernel irqchip, the multiprocessing state must be maintained by userspace on
these architectures.
For arm/arm64:
+^^^^^^^^^^^^^^
The only states that are valid are KVM_MP_STATE_STOPPED and
KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not.
4.39 KVM_SET_MP_STATE
+---------------------
-Capability: KVM_CAP_MP_STATE
-Architectures: x86, s390, arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_mp_state (in)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_MP_STATE
+:Architectures: x86, s390, arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_mp_state (in)
+:Returns: 0 on success; -1 on error
Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
arguments.
@@ -1294,17 +1419,19 @@ in-kernel irqchip, the multiprocessing state must be maintained by userspace on
these architectures.
For arm/arm64:
+^^^^^^^^^^^^^^
The only states that are valid are KVM_MP_STATE_STOPPED and
KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not.
4.40 KVM_SET_IDENTITY_MAP_ADDR
+------------------------------
-Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
-Architectures: x86
-Type: vm ioctl
-Parameters: unsigned long identity (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: unsigned long identity (in)
+:Returns: 0 on success, -1 on error
This ioctl defines the physical address of a one-page region in the guest
physical address space. The region must be within the first 4GB of the
@@ -1322,12 +1449,13 @@ documentation when it pops into existence).
Fails if any VCPU has already been created.
4.41 KVM_SET_BOOT_CPU_ID
+------------------------
-Capability: KVM_CAP_SET_BOOT_CPU_ID
-Architectures: x86
-Type: vm ioctl
-Parameters: unsigned long vcpu_id
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_SET_BOOT_CPU_ID
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: unsigned long vcpu_id
+:Returns: 0 on success, -1 on error
Define which vcpu is the Bootstrap Processor (BSP). Values are the same
as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
@@ -1335,102 +1463,119 @@ is vcpu 0.
4.42 KVM_GET_XSAVE
+------------------
-Capability: KVM_CAP_XSAVE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_xsave (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XSAVE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_xsave (out)
+:Returns: 0 on success, -1 on error
-struct kvm_xsave {
+
+::
+
+ struct kvm_xsave {
__u32 region[1024];
-};
+ };
This ioctl would copy current vcpu's xsave struct to the userspace.
4.43 KVM_SET_XSAVE
+------------------
-Capability: KVM_CAP_XSAVE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_xsave (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XSAVE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_xsave (in)
+:Returns: 0 on success, -1 on error
-struct kvm_xsave {
+::
+
+
+ struct kvm_xsave {
__u32 region[1024];
-};
+ };
This ioctl would copy userspace's xsave struct to the kernel.
4.44 KVM_GET_XCRS
+-----------------
-Capability: KVM_CAP_XCRS
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_xcrs (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XCRS
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_xcrs (out)
+:Returns: 0 on success, -1 on error
-struct kvm_xcr {
+::
+
+ struct kvm_xcr {
__u32 xcr;
__u32 reserved;
__u64 value;
-};
+ };
-struct kvm_xcrs {
+ struct kvm_xcrs {
__u32 nr_xcrs;
__u32 flags;
struct kvm_xcr xcrs[KVM_MAX_XCRS];
__u64 padding[16];
-};
+ };
This ioctl would copy current vcpu's xcrs to the userspace.
4.45 KVM_SET_XCRS
+-----------------
-Capability: KVM_CAP_XCRS
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_xcrs (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XCRS
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_xcrs (in)
+:Returns: 0 on success, -1 on error
-struct kvm_xcr {
+::
+
+ struct kvm_xcr {
__u32 xcr;
__u32 reserved;
__u64 value;
-};
+ };
-struct kvm_xcrs {
+ struct kvm_xcrs {
__u32 nr_xcrs;
__u32 flags;
struct kvm_xcr xcrs[KVM_MAX_XCRS];
__u64 padding[16];
-};
+ };
This ioctl would set vcpu's xcr to the value userspace specified.
4.46 KVM_GET_SUPPORTED_CPUID
+----------------------------
-Capability: KVM_CAP_EXT_CPUID
-Architectures: x86
-Type: system ioctl
-Parameters: struct kvm_cpuid2 (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_EXT_CPUID
+:Architectures: x86
+:Type: system ioctl
+:Parameters: struct kvm_cpuid2 (in/out)
+:Returns: 0 on success, -1 on error
-struct kvm_cpuid2 {
+::
+
+ struct kvm_cpuid2 {
__u32 nent;
__u32 padding;
struct kvm_cpuid_entry2 entries[0];
-};
+ };
-#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
-#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
-#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
+ #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
+ #define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
+ #define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
-struct kvm_cpuid_entry2 {
+ struct kvm_cpuid_entry2 {
__u32 function;
__u32 index;
__u32 flags;
@@ -1439,7 +1584,7 @@ struct kvm_cpuid_entry2 {
__u32 ecx;
__u32 edx;
__u32 padding[3];
-};
+ };
This ioctl returns x86 cpuid features which are supported by both the
hardware and kvm in its default configuration. Userspace can use the
@@ -1467,10 +1612,16 @@ with unknown or unsupported features masked out. Some features (for example,
x2apic), may not be present in the host cpu, but are exposed by kvm if it can
emulate them efficiently. The fields in each entry are defined as follows:
- function: the eax value used to obtain the entry
- index: the ecx value used to obtain the entry (for entries that are
+ function:
+ the eax value used to obtain the entry
+
+ index:
+ the ecx value used to obtain the entry (for entries that are
affected by ecx)
- flags: an OR of zero or more of the following:
+
+ flags:
+ an OR of zero or more of the following:
+
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
if the index field is valid
KVM_CPUID_FLAG_STATEFUL_FUNC:
@@ -1480,12 +1631,14 @@ emulate them efficiently. The fields in each entry are defined as follows:
KVM_CPUID_FLAG_STATE_READ_NEXT:
for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
the first entry to be read by a cpu
- eax, ebx, ecx, edx: the values returned by the cpuid instruction for
+
+ eax, ebx, ecx, edx:
+ the values returned by the cpuid instruction for
this function/index combination
The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returned
as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC
-support. Instead it is reported via
+support. Instead it is reported via::
ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER)
@@ -1494,18 +1647,21 @@ feature in userspace, then you can enable the feature for KVM_SET_CPUID2.
4.47 KVM_PPC_GET_PVINFO
+-----------------------
-Capability: KVM_CAP_PPC_GET_PVINFO
-Architectures: ppc
-Type: vm ioctl
-Parameters: struct kvm_ppc_pvinfo (out)
-Returns: 0 on success, !0 on error
+:Capability: KVM_CAP_PPC_GET_PVINFO
+:Architectures: ppc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_pvinfo (out)
+:Returns: 0 on success, !0 on error
-struct kvm_ppc_pvinfo {
+::
+
+ struct kvm_ppc_pvinfo {
__u32 flags;
__u32 hcall[4];
__u8 pad[108];
-};
+ };
This ioctl fetches PV specific information that need to be passed to the guest
using the device tree or other means from vm context.
@@ -1515,33 +1671,39 @@ The hcall array defines 4 instructions that make up a hypercall.
If any additional field gets added to this structure later on, a bit for that
additional piece of information will be set in the flags bitmap.
-The flags bitmap is defined as:
+The flags bitmap is defined as::
/* the host supports the ePAPR idle hcall
#define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0)
4.52 KVM_SET_GSI_ROUTING
+------------------------
-Capability: KVM_CAP_IRQ_ROUTING
-Architectures: x86 s390 arm arm64
-Type: vm ioctl
-Parameters: struct kvm_irq_routing (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQ_ROUTING
+:Architectures: x86 s390 arm arm64
+:Type: vm ioctl
+:Parameters: struct kvm_irq_routing (in)
+:Returns: 0 on success, -1 on error
Sets the GSI routing table entries, overwriting any previously set entries.
On arm/arm64, GSI routing has the following limitation:
+
- GSI routing does not apply to KVM_IRQ_LINE but only to KVM_IRQFD.
-struct kvm_irq_routing {
+::
+
+ struct kvm_irq_routing {
__u32 nr;
__u32 flags;
struct kvm_irq_routing_entry entries[0];
-};
+ };
No flags are specified so far, the corresponding field must be set to zero.
-struct kvm_irq_routing_entry {
+::
+
+ struct kvm_irq_routing_entry {
__u32 gsi;
__u32 type;
__u32 flags;
@@ -1553,15 +1715,16 @@ struct kvm_irq_routing_entry {
struct kvm_irq_routing_hv_sint hv_sint;
__u32 pad[8];
} u;
-};
+ };
-/* gsi routing entry types */
-#define KVM_IRQ_ROUTING_IRQCHIP 1
-#define KVM_IRQ_ROUTING_MSI 2
-#define KVM_IRQ_ROUTING_S390_ADAPTER 3
-#define KVM_IRQ_ROUTING_HV_SINT 4
+ /* gsi routing entry types */
+ #define KVM_IRQ_ROUTING_IRQCHIP 1
+ #define KVM_IRQ_ROUTING_MSI 2
+ #define KVM_IRQ_ROUTING_S390_ADAPTER 3
+ #define KVM_IRQ_ROUTING_HV_SINT 4
flags:
+
- KVM_MSI_VALID_DEVID: used along with KVM_IRQ_ROUTING_MSI routing entry
type, specifies that the devid field contains a valid value. The per-VM
KVM_CAP_MSI_DEVID capability advertises the requirement to provide
@@ -1569,12 +1732,14 @@ flags:
never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
- zero otherwise
-struct kvm_irq_routing_irqchip {
+::
+
+ struct kvm_irq_routing_irqchip {
__u32 irqchip;
__u32 pin;
-};
+ };
-struct kvm_irq_routing_msi {
+ struct kvm_irq_routing_msi {
__u32 address_lo;
__u32 address_hi;
__u32 data;
@@ -1582,7 +1747,7 @@ struct kvm_irq_routing_msi {
__u32 pad;
__u32 devid;
};
-};
+ };
If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier
for the device that wrote the MSI message. For PCI, this is usually a
@@ -1593,39 +1758,43 @@ feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,
address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of
address_hi must be zero.
-struct kvm_irq_routing_s390_adapter {
+::
+
+ struct kvm_irq_routing_s390_adapter {
__u64 ind_addr;
__u64 summary_addr;
__u64 ind_offset;
__u32 summary_offset;
__u32 adapter_id;
-};
+ };
-struct kvm_irq_routing_hv_sint {
+ struct kvm_irq_routing_hv_sint {
__u32 vcpu;
__u32 sint;
-};
+ };
4.55 KVM_SET_TSC_KHZ
+--------------------
-Capability: KVM_CAP_TSC_CONTROL
-Architectures: x86
-Type: vcpu ioctl
-Parameters: virtual tsc_khz
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_TSC_CONTROL
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: virtual tsc_khz
+:Returns: 0 on success, -1 on error
Specifies the tsc frequency for the virtual machine. The unit of the
frequency is KHz.
4.56 KVM_GET_TSC_KHZ
+--------------------
-Capability: KVM_CAP_GET_TSC_KHZ
-Architectures: x86
-Type: vcpu ioctl
-Parameters: none
-Returns: virtual tsc-khz on success, negative value on error
+:Capability: KVM_CAP_GET_TSC_KHZ
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: none
+:Returns: virtual tsc-khz on success, negative value on error
Returns the tsc frequency of the guest. The unit of the return value is
KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
@@ -1633,17 +1802,20 @@ error.
4.57 KVM_GET_LAPIC
+------------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_lapic_state (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_lapic_state (out)
+:Returns: 0 on success, -1 on error
-#define KVM_APIC_REG_SIZE 0x400
-struct kvm_lapic_state {
+::
+
+ #define KVM_APIC_REG_SIZE 0x400
+ struct kvm_lapic_state {
char regs[KVM_APIC_REG_SIZE];
-};
+ };
Reads the Local APIC registers and copies them into the input argument. The
data format and layout are the same as documented in the architecture manual.
@@ -1661,17 +1833,20 @@ always uses xAPIC format.
4.58 KVM_SET_LAPIC
+------------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_lapic_state (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_lapic_state (in)
+:Returns: 0 on success, -1 on error
-#define KVM_APIC_REG_SIZE 0x400
-struct kvm_lapic_state {
+::
+
+ #define KVM_APIC_REG_SIZE 0x400
+ struct kvm_lapic_state {
char regs[KVM_APIC_REG_SIZE];
-};
+ };
Copies the input argument into the Local APIC registers. The data format
and layout are the same as documented in the architecture manual.
@@ -1682,35 +1857,38 @@ See the note in KVM_GET_LAPIC.
4.59 KVM_IOEVENTFD
+------------------
-Capability: KVM_CAP_IOEVENTFD
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_ioeventfd (in)
-Returns: 0 on success, !0 on error
+:Capability: KVM_CAP_IOEVENTFD
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_ioeventfd (in)
+:Returns: 0 on success, !0 on error
This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
within the guest. A guest write in the registered address will signal the
provided event instead of triggering an exit.
-struct kvm_ioeventfd {
+::
+
+ struct kvm_ioeventfd {
__u64 datamatch;
__u64 addr; /* legal pio/mmio address */
__u32 len; /* 0, 1, 2, 4, or 8 bytes */
__s32 fd;
__u32 flags;
__u8 pad[36];
-};
+ };
For the special case of virtio-ccw devices on s390, the ioevent is matched
to a subchannel/virtqueue tuple instead.
-The following flags are defined:
+The following flags are defined::
-#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
-#define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio)
-#define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign)
-#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \
+ #define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
+ #define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio)
+ #define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign)
+ #define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \
(1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify)
If datamatch flag is set, the event will be signaled only if the written value
@@ -1725,17 +1903,20 @@ The speedup may only apply to specific architectures, but the ioeventfd will
work anyway.
4.60 KVM_DIRTY_TLB
+------------------
-Capability: KVM_CAP_SW_TLB
-Architectures: ppc
-Type: vcpu ioctl
-Parameters: struct kvm_dirty_tlb (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_SW_TLB
+:Architectures: ppc
+:Type: vcpu ioctl
+:Parameters: struct kvm_dirty_tlb (in)
+:Returns: 0 on success, -1 on error
-struct kvm_dirty_tlb {
+::
+
+ struct kvm_dirty_tlb {
__u64 bitmap;
__u32 num_dirty;
-};
+ };
This must be called whenever userspace has changed an entry in the shared
TLB, prior to calling KVM_RUN on the associated vcpu.
@@ -1758,23 +1939,26 @@ be set to the number of set bits in the bitmap.
4.62 KVM_CREATE_SPAPR_TCE
+-------------------------
-Capability: KVM_CAP_SPAPR_TCE
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_create_spapr_tce (in)
-Returns: file descriptor for manipulating the created TCE table
+:Capability: KVM_CAP_SPAPR_TCE
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_create_spapr_tce (in)
+:Returns: file descriptor for manipulating the created TCE table
This creates a virtual TCE (translation control entry) table, which
is an IOMMU for PAPR-style virtual I/O. It is used to translate
logical addresses used in virtual I/O into guest physical addresses,
and provides a scatter/gather capability for PAPR virtual I/O.
-/* for KVM_CAP_SPAPR_TCE */
-struct kvm_create_spapr_tce {
+::
+
+ /* for KVM_CAP_SPAPR_TCE */
+ struct kvm_create_spapr_tce {
__u64 liobn;
__u32 window_size;
-};
+ };
The liobn field gives the logical IO bus number for which to create a
TCE table. The window_size field specifies the size of the DMA window
@@ -1794,12 +1978,13 @@ circumstances.
4.63 KVM_ALLOCATE_RMA
+---------------------
-Capability: KVM_CAP_PPC_RMA
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_allocate_rma (out)
-Returns: file descriptor for mapping the allocated RMA
+:Capability: KVM_CAP_PPC_RMA
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_allocate_rma (out)
+:Returns: file descriptor for mapping the allocated RMA
This allocates a Real Mode Area (RMA) from the pool allocated at boot
time by the kernel. An RMA is a physically-contiguous, aligned region
@@ -1808,10 +1993,12 @@ will be accessed by real-mode (MMU off) accesses in a KVM guest.
POWER processors support a set of sizes for the RMA that usually
includes 64MB, 128MB, 256MB and some larger powers of two.
-/* for KVM_ALLOCATE_RMA */
-struct kvm_allocate_rma {
+::
+
+ /* for KVM_ALLOCATE_RMA */
+ struct kvm_allocate_rma {
__u64 rma_size;
-};
+ };
The return value is a file descriptor which can be passed to mmap(2)
to map the allocated RMA into userspace. The mapped area can then be
@@ -1827,12 +2014,13 @@ because it supports the Virtual RMA (VRMA) facility.
4.64 KVM_NMI
+------------
-Capability: KVM_CAP_USER_NMI
-Architectures: x86
-Type: vcpu ioctl
-Parameters: none
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_USER_NMI
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: none
+:Returns: 0 on success, -1 on error
Queues an NMI on the thread's vcpu. Note this is well defined only
when KVM_CREATE_IRQCHIP has not been called, since this is an interface
@@ -1853,14 +2041,16 @@ debugging.
4.65 KVM_S390_UCAS_MAP
+----------------------
-Capability: KVM_CAP_S390_UCONTROL
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_ucas_mapping (in)
-Returns: 0 in case of success
+:Capability: KVM_CAP_S390_UCONTROL
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_ucas_mapping (in)
+:Returns: 0 in case of success
+
+The parameter is defined like this::
-The parameter is defined like this:
struct kvm_s390_ucas_mapping {
__u64 user_addr;
__u64 vcpu_addr;
@@ -1873,14 +2063,16 @@ be aligned by 1 megabyte.
4.66 KVM_S390_UCAS_UNMAP
+------------------------
-Capability: KVM_CAP_S390_UCONTROL
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_ucas_mapping (in)
-Returns: 0 in case of success
+:Capability: KVM_CAP_S390_UCONTROL
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_ucas_mapping (in)
+:Returns: 0 in case of success
+
+The parameter is defined like this::
-The parameter is defined like this:
struct kvm_s390_ucas_mapping {
__u64 user_addr;
__u64 vcpu_addr;
@@ -1893,12 +2085,13 @@ All parameters need to be aligned by 1 megabyte.
4.67 KVM_S390_VCPU_FAULT
+------------------------
-Capability: KVM_CAP_S390_UCONTROL
-Architectures: s390
-Type: vcpu ioctl
-Parameters: vcpu absolute address (in)
-Returns: 0 in case of success
+:Capability: KVM_CAP_S390_UCONTROL
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: vcpu absolute address (in)
+:Returns: 0 in case of success
This call creates a page table entry on the virtual cpu's address space
(for user controlled virtual machines) or the virtual machine's address
@@ -1910,23 +2103,31 @@ prior to calling the KVM_RUN ioctl.
4.68 KVM_SET_ONE_REG
+--------------------
+
+:Capability: KVM_CAP_ONE_REG
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: struct kvm_one_reg (in)
+:Returns: 0 on success, negative value on failure
-Capability: KVM_CAP_ONE_REG
-Architectures: all
-Type: vcpu ioctl
-Parameters: struct kvm_one_reg (in)
-Returns: 0 on success, negative value on failure
Errors:
- ENOENT: no such register
- EINVAL: invalid register ID, or no such register
- EPERM: (arm64) register access not allowed before vcpu finalization
+
+ ====== ============================================================
+ ENOENT no such register
+ EINVAL invalid register ID, or no such register
+ EPERM (arm64) register access not allowed before vcpu finalization
+ ====== ============================================================
+
(These error codes are indicative only: do not rely on a specific error
code being returned in a specific situation.)
-struct kvm_one_reg {
+::
+
+ struct kvm_one_reg {
__u64 id;
__u64 addr;
-};
+ };
Using this ioctl, a single vcpu register can be set to a specific value
defined by user space with the passed in struct kvm_one_reg, where id
@@ -1936,217 +2137,226 @@ and architecture specific registers. Each have their own range of operation
and their own constants and width. To keep track of the implemented
registers, find a list below:
- Arch | Register | Width (bits)
- | |
- PPC | KVM_REG_PPC_HIOR | 64
- PPC | KVM_REG_PPC_IAC1 | 64
- PPC | KVM_REG_PPC_IAC2 | 64
- PPC | KVM_REG_PPC_IAC3 | 64
- PPC | KVM_REG_PPC_IAC4 | 64
- PPC | KVM_REG_PPC_DAC1 | 64
- PPC | KVM_REG_PPC_DAC2 | 64
- PPC | KVM_REG_PPC_DABR | 64
- PPC | KVM_REG_PPC_DSCR | 64
- PPC | KVM_REG_PPC_PURR | 64
- PPC | KVM_REG_PPC_SPURR | 64
- PPC | KVM_REG_PPC_DAR | 64
- PPC | KVM_REG_PPC_DSISR | 32
- PPC | KVM_REG_PPC_AMR | 64
- PPC | KVM_REG_PPC_UAMOR | 64
- PPC | KVM_REG_PPC_MMCR0 | 64
- PPC | KVM_REG_PPC_MMCR1 | 64
- PPC | KVM_REG_PPC_MMCRA | 64
- PPC | KVM_REG_PPC_MMCR2 | 64
- PPC | KVM_REG_PPC_MMCRS | 64
- PPC | KVM_REG_PPC_SIAR | 64
- PPC | KVM_REG_PPC_SDAR | 64
- PPC | KVM_REG_PPC_SIER | 64
- PPC | KVM_REG_PPC_PMC1 | 32
- PPC | KVM_REG_PPC_PMC2 | 32
- PPC | KVM_REG_PPC_PMC3 | 32
- PPC | KVM_REG_PPC_PMC4 | 32
- PPC | KVM_REG_PPC_PMC5 | 32
- PPC | KVM_REG_PPC_PMC6 | 32
- PPC | KVM_REG_PPC_PMC7 | 32
- PPC | KVM_REG_PPC_PMC8 | 32
- PPC | KVM_REG_PPC_FPR0 | 64
- ...
- PPC | KVM_REG_PPC_FPR31 | 64
- PPC | KVM_REG_PPC_VR0 | 128
- ...
- PPC | KVM_REG_PPC_VR31 | 128
- PPC | KVM_REG_PPC_VSR0 | 128
- ...
- PPC | KVM_REG_PPC_VSR31 | 128
- PPC | KVM_REG_PPC_FPSCR | 64
- PPC | KVM_REG_PPC_VSCR | 32
- PPC | KVM_REG_PPC_VPA_ADDR | 64
- PPC | KVM_REG_PPC_VPA_SLB | 128
- PPC | KVM_REG_PPC_VPA_DTL | 128
- PPC | KVM_REG_PPC_EPCR | 32
- PPC | KVM_REG_PPC_EPR | 32
- PPC | KVM_REG_PPC_TCR | 32
- PPC | KVM_REG_PPC_TSR | 32
- PPC | KVM_REG_PPC_OR_TSR | 32
- PPC | KVM_REG_PPC_CLEAR_TSR | 32
- PPC | KVM_REG_PPC_MAS0 | 32
- PPC | KVM_REG_PPC_MAS1 | 32
- PPC | KVM_REG_PPC_MAS2 | 64
- PPC | KVM_REG_PPC_MAS7_3 | 64
- PPC | KVM_REG_PPC_MAS4 | 32
- PPC | KVM_REG_PPC_MAS6 | 32
- PPC | KVM_REG_PPC_MMUCFG | 32
- PPC | KVM_REG_PPC_TLB0CFG | 32
- PPC | KVM_REG_PPC_TLB1CFG | 32
- PPC | KVM_REG_PPC_TLB2CFG | 32
- PPC | KVM_REG_PPC_TLB3CFG | 32
- PPC | KVM_REG_PPC_TLB0PS | 32
- PPC | KVM_REG_PPC_TLB1PS | 32
- PPC | KVM_REG_PPC_TLB2PS | 32
- PPC | KVM_REG_PPC_TLB3PS | 32
- PPC | KVM_REG_PPC_EPTCFG | 32
- PPC | KVM_REG_PPC_ICP_STATE | 64
- PPC | KVM_REG_PPC_VP_STATE | 128
- PPC | KVM_REG_PPC_TB_OFFSET | 64
- PPC | KVM_REG_PPC_SPMC1 | 32
- PPC | KVM_REG_PPC_SPMC2 | 32
- PPC | KVM_REG_PPC_IAMR | 64
- PPC | KVM_REG_PPC_TFHAR | 64
- PPC | KVM_REG_PPC_TFIAR | 64
- PPC | KVM_REG_PPC_TEXASR | 64
- PPC | KVM_REG_PPC_FSCR | 64
- PPC | KVM_REG_PPC_PSPB | 32
- PPC | KVM_REG_PPC_EBBHR | 64
- PPC | KVM_REG_PPC_EBBRR | 64
- PPC | KVM_REG_PPC_BESCR | 64
- PPC | KVM_REG_PPC_TAR | 64
- PPC | KVM_REG_PPC_DPDES | 64
- PPC | KVM_REG_PPC_DAWR | 64
- PPC | KVM_REG_PPC_DAWRX | 64
- PPC | KVM_REG_PPC_CIABR | 64
- PPC | KVM_REG_PPC_IC | 64
- PPC | KVM_REG_PPC_VTB | 64
- PPC | KVM_REG_PPC_CSIGR | 64
- PPC | KVM_REG_PPC_TACR | 64
- PPC | KVM_REG_PPC_TCSCR | 64
- PPC | KVM_REG_PPC_PID | 64
- PPC | KVM_REG_PPC_ACOP | 64
- PPC | KVM_REG_PPC_VRSAVE | 32
- PPC | KVM_REG_PPC_LPCR | 32
- PPC | KVM_REG_PPC_LPCR_64 | 64
- PPC | KVM_REG_PPC_PPR | 64
- PPC | KVM_REG_PPC_ARCH_COMPAT | 32
- PPC | KVM_REG_PPC_DABRX | 32
- PPC | KVM_REG_PPC_WORT | 64
- PPC | KVM_REG_PPC_SPRG9 | 64
- PPC | KVM_REG_PPC_DBSR | 32
- PPC | KVM_REG_PPC_TIDR | 64
- PPC | KVM_REG_PPC_PSSCR | 64
- PPC | KVM_REG_PPC_DEC_EXPIRY | 64
- PPC | KVM_REG_PPC_PTCR | 64
- PPC | KVM_REG_PPC_TM_GPR0 | 64
- ...
- PPC | KVM_REG_PPC_TM_GPR31 | 64
- PPC | KVM_REG_PPC_TM_VSR0 | 128
- ...
- PPC | KVM_REG_PPC_TM_VSR63 | 128
- PPC | KVM_REG_PPC_TM_CR | 64
- PPC | KVM_REG_PPC_TM_LR | 64
- PPC | KVM_REG_PPC_TM_CTR | 64
- PPC | KVM_REG_PPC_TM_FPSCR | 64
- PPC | KVM_REG_PPC_TM_AMR | 64
- PPC | KVM_REG_PPC_TM_PPR | 64
- PPC | KVM_REG_PPC_TM_VRSAVE | 64
- PPC | KVM_REG_PPC_TM_VSCR | 32
- PPC | KVM_REG_PPC_TM_DSCR | 64
- PPC | KVM_REG_PPC_TM_TAR | 64
- PPC | KVM_REG_PPC_TM_XER | 64
- | |
- MIPS | KVM_REG_MIPS_R0 | 64
- ...
- MIPS | KVM_REG_MIPS_R31 | 64
- MIPS | KVM_REG_MIPS_HI | 64
- MIPS | KVM_REG_MIPS_LO | 64
- MIPS | KVM_REG_MIPS_PC | 64
- MIPS | KVM_REG_MIPS_CP0_INDEX | 32
- MIPS | KVM_REG_MIPS_CP0_ENTRYLO0 | 64
- MIPS | KVM_REG_MIPS_CP0_ENTRYLO1 | 64
- MIPS | KVM_REG_MIPS_CP0_CONTEXT | 64
- MIPS | KVM_REG_MIPS_CP0_CONTEXTCONFIG| 32
- MIPS | KVM_REG_MIPS_CP0_USERLOCAL | 64
- MIPS | KVM_REG_MIPS_CP0_XCONTEXTCONFIG| 64
- MIPS | KVM_REG_MIPS_CP0_PAGEMASK | 32
- MIPS | KVM_REG_MIPS_CP0_PAGEGRAIN | 32
- MIPS | KVM_REG_MIPS_CP0_SEGCTL0 | 64
- MIPS | KVM_REG_MIPS_CP0_SEGCTL1 | 64
- MIPS | KVM_REG_MIPS_CP0_SEGCTL2 | 64
- MIPS | KVM_REG_MIPS_CP0_PWBASE | 64
- MIPS | KVM_REG_MIPS_CP0_PWFIELD | 64
- MIPS | KVM_REG_MIPS_CP0_PWSIZE | 64
- MIPS | KVM_REG_MIPS_CP0_WIRED | 32
- MIPS | KVM_REG_MIPS_CP0_PWCTL | 32
- MIPS | KVM_REG_MIPS_CP0_HWRENA | 32
- MIPS | KVM_REG_MIPS_CP0_BADVADDR | 64
- MIPS | KVM_REG_MIPS_CP0_BADINSTR | 32
- MIPS | KVM_REG_MIPS_CP0_BADINSTRP | 32
- MIPS | KVM_REG_MIPS_CP0_COUNT | 32
- MIPS | KVM_REG_MIPS_CP0_ENTRYHI | 64
- MIPS | KVM_REG_MIPS_CP0_COMPARE | 32
- MIPS | KVM_REG_MIPS_CP0_STATUS | 32
- MIPS | KVM_REG_MIPS_CP0_INTCTL | 32
- MIPS | KVM_REG_MIPS_CP0_CAUSE | 32
- MIPS | KVM_REG_MIPS_CP0_EPC | 64
- MIPS | KVM_REG_MIPS_CP0_PRID | 32
- MIPS | KVM_REG_MIPS_CP0_EBASE | 64
- MIPS | KVM_REG_MIPS_CP0_CONFIG | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG1 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG2 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG3 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG4 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG5 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG7 | 32
- MIPS | KVM_REG_MIPS_CP0_XCONTEXT | 64
- MIPS | KVM_REG_MIPS_CP0_ERROREPC | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH1 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH2 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH3 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH4 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH5 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH6 | 64
- MIPS | KVM_REG_MIPS_CP0_MAAR(0..63) | 64
- MIPS | KVM_REG_MIPS_COUNT_CTL | 64
- MIPS | KVM_REG_MIPS_COUNT_RESUME | 64
- MIPS | KVM_REG_MIPS_COUNT_HZ | 64
- MIPS | KVM_REG_MIPS_FPR_32(0..31) | 32
- MIPS | KVM_REG_MIPS_FPR_64(0..31) | 64
- MIPS | KVM_REG_MIPS_VEC_128(0..31) | 128
- MIPS | KVM_REG_MIPS_FCR_IR | 32
- MIPS | KVM_REG_MIPS_FCR_CSR | 32
- MIPS | KVM_REG_MIPS_MSA_IR | 32
- MIPS | KVM_REG_MIPS_MSA_CSR | 32
+ ======= =============================== ============
+ Arch Register Width (bits)
+ ======= =============================== ============
+ PPC KVM_REG_PPC_HIOR 64
+ PPC KVM_REG_PPC_IAC1 64
+ PPC KVM_REG_PPC_IAC2 64
+ PPC KVM_REG_PPC_IAC3 64
+ PPC KVM_REG_PPC_IAC4 64
+ PPC KVM_REG_PPC_DAC1 64
+ PPC KVM_REG_PPC_DAC2 64
+ PPC KVM_REG_PPC_DABR 64
+ PPC KVM_REG_PPC_DSCR 64
+ PPC KVM_REG_PPC_PURR 64
+ PPC KVM_REG_PPC_SPURR 64
+ PPC KVM_REG_PPC_DAR 64
+ PPC KVM_REG_PPC_DSISR 32
+ PPC KVM_REG_PPC_AMR 64
+ PPC KVM_REG_PPC_UAMOR 64
+ PPC KVM_REG_PPC_MMCR0 64
+ PPC KVM_REG_PPC_MMCR1 64
+ PPC KVM_REG_PPC_MMCRA 64
+ PPC KVM_REG_PPC_MMCR2 64
+ PPC KVM_REG_PPC_MMCRS 64
+ PPC KVM_REG_PPC_SIAR 64
+ PPC KVM_REG_PPC_SDAR 64
+ PPC KVM_REG_PPC_SIER 64
+ PPC KVM_REG_PPC_PMC1 32
+ PPC KVM_REG_PPC_PMC2 32
+ PPC KVM_REG_PPC_PMC3 32
+ PPC KVM_REG_PPC_PMC4 32
+ PPC KVM_REG_PPC_PMC5 32
+ PPC KVM_REG_PPC_PMC6 32
+ PPC KVM_REG_PPC_PMC7 32
+ PPC KVM_REG_PPC_PMC8 32
+ PPC KVM_REG_PPC_FPR0 64
+ ...
+ PPC KVM_REG_PPC_FPR31 64
+ PPC KVM_REG_PPC_VR0 128
+ ...
+ PPC KVM_REG_PPC_VR31 128
+ PPC KVM_REG_PPC_VSR0 128
+ ...
+ PPC KVM_REG_PPC_VSR31 128
+ PPC KVM_REG_PPC_FPSCR 64
+ PPC KVM_REG_PPC_VSCR 32
+ PPC KVM_REG_PPC_VPA_ADDR 64
+ PPC KVM_REG_PPC_VPA_SLB 128
+ PPC KVM_REG_PPC_VPA_DTL 128
+ PPC KVM_REG_PPC_EPCR 32
+ PPC KVM_REG_PPC_EPR 32
+ PPC KVM_REG_PPC_TCR 32
+ PPC KVM_REG_PPC_TSR 32
+ PPC KVM_REG_PPC_OR_TSR 32
+ PPC KVM_REG_PPC_CLEAR_TSR 32
+ PPC KVM_REG_PPC_MAS0 32
+ PPC KVM_REG_PPC_MAS1 32
+ PPC KVM_REG_PPC_MAS2 64
+ PPC KVM_REG_PPC_MAS7_3 64
+ PPC KVM_REG_PPC_MAS4 32
+ PPC KVM_REG_PPC_MAS6 32
+ PPC KVM_REG_PPC_MMUCFG 32
+ PPC KVM_REG_PPC_TLB0CFG 32
+ PPC KVM_REG_PPC_TLB1CFG 32
+ PPC KVM_REG_PPC_TLB2CFG 32
+ PPC KVM_REG_PPC_TLB3CFG 32
+ PPC KVM_REG_PPC_TLB0PS 32
+ PPC KVM_REG_PPC_TLB1PS 32
+ PPC KVM_REG_PPC_TLB2PS 32
+ PPC KVM_REG_PPC_TLB3PS 32
+ PPC KVM_REG_PPC_EPTCFG 32
+ PPC KVM_REG_PPC_ICP_STATE 64
+ PPC KVM_REG_PPC_VP_STATE 128
+ PPC KVM_REG_PPC_TB_OFFSET 64
+ PPC KVM_REG_PPC_SPMC1 32
+ PPC KVM_REG_PPC_SPMC2 32
+ PPC KVM_REG_PPC_IAMR 64
+ PPC KVM_REG_PPC_TFHAR 64
+ PPC KVM_REG_PPC_TFIAR 64
+ PPC KVM_REG_PPC_TEXASR 64
+ PPC KVM_REG_PPC_FSCR 64
+ PPC KVM_REG_PPC_PSPB 32
+ PPC KVM_REG_PPC_EBBHR 64
+ PPC KVM_REG_PPC_EBBRR 64
+ PPC KVM_REG_PPC_BESCR 64
+ PPC KVM_REG_PPC_TAR 64
+ PPC KVM_REG_PPC_DPDES 64
+ PPC KVM_REG_PPC_DAWR 64
+ PPC KVM_REG_PPC_DAWRX 64
+ PPC KVM_REG_PPC_CIABR 64
+ PPC KVM_REG_PPC_IC 64
+ PPC KVM_REG_PPC_VTB 64
+ PPC KVM_REG_PPC_CSIGR 64
+ PPC KVM_REG_PPC_TACR 64
+ PPC KVM_REG_PPC_TCSCR 64
+ PPC KVM_REG_PPC_PID 64
+ PPC KVM_REG_PPC_ACOP 64
+ PPC KVM_REG_PPC_VRSAVE 32
+ PPC KVM_REG_PPC_LPCR 32
+ PPC KVM_REG_PPC_LPCR_64 64
+ PPC KVM_REG_PPC_PPR 64
+ PPC KVM_REG_PPC_ARCH_COMPAT 32
+ PPC KVM_REG_PPC_DABRX 32
+ PPC KVM_REG_PPC_WORT 64
+ PPC KVM_REG_PPC_SPRG9 64
+ PPC KVM_REG_PPC_DBSR 32
+ PPC KVM_REG_PPC_TIDR 64
+ PPC KVM_REG_PPC_PSSCR 64
+ PPC KVM_REG_PPC_DEC_EXPIRY 64
+ PPC KVM_REG_PPC_PTCR 64
+ PPC KVM_REG_PPC_TM_GPR0 64
+ ...
+ PPC KVM_REG_PPC_TM_GPR31 64
+ PPC KVM_REG_PPC_TM_VSR0 128
+ ...
+ PPC KVM_REG_PPC_TM_VSR63 128
+ PPC KVM_REG_PPC_TM_CR 64
+ PPC KVM_REG_PPC_TM_LR 64
+ PPC KVM_REG_PPC_TM_CTR 64
+ PPC KVM_REG_PPC_TM_FPSCR 64
+ PPC KVM_REG_PPC_TM_AMR 64
+ PPC KVM_REG_PPC_TM_PPR 64
+ PPC KVM_REG_PPC_TM_VRSAVE 64
+ PPC KVM_REG_PPC_TM_VSCR 32
+ PPC KVM_REG_PPC_TM_DSCR 64
+ PPC KVM_REG_PPC_TM_TAR 64
+ PPC KVM_REG_PPC_TM_XER 64
+
+ MIPS KVM_REG_MIPS_R0 64
+ ...
+ MIPS KVM_REG_MIPS_R31 64
+ MIPS KVM_REG_MIPS_HI 64
+ MIPS KVM_REG_MIPS_LO 64
+ MIPS KVM_REG_MIPS_PC 64
+ MIPS KVM_REG_MIPS_CP0_INDEX 32
+ MIPS KVM_REG_MIPS_CP0_ENTRYLO0 64
+ MIPS KVM_REG_MIPS_CP0_ENTRYLO1 64
+ MIPS KVM_REG_MIPS_CP0_CONTEXT 64
+ MIPS KVM_REG_MIPS_CP0_CONTEXTCONFIG 32
+ MIPS KVM_REG_MIPS_CP0_USERLOCAL 64
+ MIPS KVM_REG_MIPS_CP0_XCONTEXTCONFIG 64
+ MIPS KVM_REG_MIPS_CP0_PAGEMASK 32
+ MIPS KVM_REG_MIPS_CP0_PAGEGRAIN 32
+ MIPS KVM_REG_MIPS_CP0_SEGCTL0 64
+ MIPS KVM_REG_MIPS_CP0_SEGCTL1 64
+ MIPS KVM_REG_MIPS_CP0_SEGCTL2 64
+ MIPS KVM_REG_MIPS_CP0_PWBASE 64
+ MIPS KVM_REG_MIPS_CP0_PWFIELD 64
+ MIPS KVM_REG_MIPS_CP0_PWSIZE 64
+ MIPS KVM_REG_MIPS_CP0_WIRED 32
+ MIPS KVM_REG_MIPS_CP0_PWCTL 32
+ MIPS KVM_REG_MIPS_CP0_HWRENA 32
+ MIPS KVM_REG_MIPS_CP0_BADVADDR 64
+ MIPS KVM_REG_MIPS_CP0_BADINSTR 32
+ MIPS KVM_REG_MIPS_CP0_BADINSTRP 32
+ MIPS KVM_REG_MIPS_CP0_COUNT 32
+ MIPS KVM_REG_MIPS_CP0_ENTRYHI 64
+ MIPS KVM_REG_MIPS_CP0_COMPARE 32
+ MIPS KVM_REG_MIPS_CP0_STATUS 32
+ MIPS KVM_REG_MIPS_CP0_INTCTL 32
+ MIPS KVM_REG_MIPS_CP0_CAUSE 32
+ MIPS KVM_REG_MIPS_CP0_EPC 64
+ MIPS KVM_REG_MIPS_CP0_PRID 32
+ MIPS KVM_REG_MIPS_CP0_EBASE 64
+ MIPS KVM_REG_MIPS_CP0_CONFIG 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG1 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG2 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG3 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG4 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG5 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG7 32
+ MIPS KVM_REG_MIPS_CP0_XCONTEXT 64
+ MIPS KVM_REG_MIPS_CP0_ERROREPC 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH1 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH2 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH3 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH4 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH5 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH6 64
+ MIPS KVM_REG_MIPS_CP0_MAAR(0..63) 64
+ MIPS KVM_REG_MIPS_COUNT_CTL 64
+ MIPS KVM_REG_MIPS_COUNT_RESUME 64
+ MIPS KVM_REG_MIPS_COUNT_HZ 64
+ MIPS KVM_REG_MIPS_FPR_32(0..31) 32
+ MIPS KVM_REG_MIPS_FPR_64(0..31) 64
+ MIPS KVM_REG_MIPS_VEC_128(0..31) 128
+ MIPS KVM_REG_MIPS_FCR_IR 32
+ MIPS KVM_REG_MIPS_FCR_CSR 32
+ MIPS KVM_REG_MIPS_MSA_IR 32
+ MIPS KVM_REG_MIPS_MSA_CSR 32
+ ======= =============================== ============
ARM registers are mapped using the lower 32 bits. The upper 16 of that
is the register group type, or coprocessor number:
-ARM core registers have the following id bit patterns:
+ARM core registers have the following id bit patterns::
+
0x4020 0000 0010 <index into the kvm_regs struct:16>
-ARM 32-bit CP15 registers have the following id bit patterns:
+ARM 32-bit CP15 registers have the following id bit patterns::
+
0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3>
-ARM 64-bit CP15 registers have the following id bit patterns:
+ARM 64-bit CP15 registers have the following id bit patterns::
+
0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3>
-ARM CCSIDR registers are demultiplexed by CSSELR value:
+ARM CCSIDR registers are demultiplexed by CSSELR value::
+
0x4020 0000 0011 00 <csselr:8>
-ARM 32-bit VFP control registers have the following id bit patterns:
+ARM 32-bit VFP control registers have the following id bit patterns::
+
0x4020 0000 0012 1 <regno:12>
-ARM 64-bit FP registers have the following id bit patterns:
+ARM 64-bit FP registers have the following id bit patterns::
+
0x4030 0000 0012 0 <regno:12>
-ARM firmware pseudo-registers have the following bit pattern:
+ARM firmware pseudo-registers have the following bit pattern::
+
0x4030 0000 0014 <regno:16>
@@ -2156,15 +2366,18 @@ that is the register group type, or coprocessor number:
arm64 core/FP-SIMD registers have the following id bit patterns. Note
that the size of the access is variable, as the kvm_regs structure
contains elements ranging from 32 to 128 bits. The index is a 32bit
-value in the kvm_regs structure seen as a 32bit array.
+value in the kvm_regs structure seen as a 32bit array::
+
0x60x0 0000 0010 <index into the kvm_regs struct:16>
Specifically:
+
+======================= ========= ===== =======================================
Encoding Register Bits kvm_regs member
-----------------------------------------------------------------
+======================= ========= ===== =======================================
0x6030 0000 0010 0000 X0 64 regs.regs[0]
0x6030 0000 0010 0002 X1 64 regs.regs[1]
- ...
+ ...
0x6030 0000 0010 003c X30 64 regs.regs[30]
0x6030 0000 0010 003e SP 64 regs.sp
0x6030 0000 0010 0040 PC 64 regs.pc
@@ -2176,30 +2389,35 @@ Specifically:
0x6030 0000 0010 004c SPSR_UND 64 spsr[KVM_SPSR_UND]
0x6030 0000 0010 004e SPSR_IRQ 64 spsr[KVM_SPSR_IRQ]
0x6060 0000 0010 0050 SPSR_FIQ 64 spsr[KVM_SPSR_FIQ]
- 0x6040 0000 0010 0054 V0 128 fp_regs.vregs[0] (*)
- 0x6040 0000 0010 0058 V1 128 fp_regs.vregs[1] (*)
- ...
- 0x6040 0000 0010 00d0 V31 128 fp_regs.vregs[31] (*)
+ 0x6040 0000 0010 0054 V0 128 fp_regs.vregs[0] [1]_
+ 0x6040 0000 0010 0058 V1 128 fp_regs.vregs[1] [1]_
+ ...
+ 0x6040 0000 0010 00d0 V31 128 fp_regs.vregs[31] [1]_
0x6020 0000 0010 00d4 FPSR 32 fp_regs.fpsr
0x6020 0000 0010 00d5 FPCR 32 fp_regs.fpcr
+======================= ========= ===== =======================================
-(*) These encodings are not accepted for SVE-enabled vcpus. See
- KVM_ARM_VCPU_INIT.
+.. [1] These encodings are not accepted for SVE-enabled vcpus. See
+ KVM_ARM_VCPU_INIT.
- The equivalent register content can be accessed via bits [127:0] of
- the corresponding SVE Zn registers instead for vcpus that have SVE
- enabled (see below).
+ The equivalent register content can be accessed via bits [127:0] of
+ the corresponding SVE Zn registers instead for vcpus that have SVE
+ enabled (see below).
+
+arm64 CCSIDR registers are demultiplexed by CSSELR value::
-arm64 CCSIDR registers are demultiplexed by CSSELR value:
0x6020 0000 0011 00 <csselr:8>
-arm64 system registers have the following id bit patterns:
+arm64 system registers have the following id bit patterns::
+
0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3>
-arm64 firmware pseudo-registers have the following bit pattern:
+arm64 firmware pseudo-registers have the following bit pattern::
+
0x6030 0000 0014 <regno:16>
-arm64 SVE registers have the following bit patterns:
+arm64 SVE registers have the following bit patterns::
+
0x6080 0000 0015 00 <n:5> <slice:5> Zn bits[2048*slice + 2047 : 2048*slice]
0x6050 0000 0015 04 <n:4> <slice:5> Pn bits[256*slice + 255 : 256*slice]
0x6050 0000 0015 060 <slice:5> FFR bits[256*slice + 255 : 256*slice]
@@ -2207,7 +2425,7 @@ arm64 SVE registers have the following bit patterns:
Access to register IDs where 2048 * slice >= 128 * max_vq will fail with
ENOENT. max_vq is the vcpu's maximum supported vector length in 128-bit
-quadwords: see (**) below.
+quadwords: see [2]_ below.
These registers are only accessible on vcpus for which SVE is enabled.
See KVM_ARM_VCPU_INIT for details.
@@ -2222,21 +2440,21 @@ lengths supported by the vcpu to be discovered and configured by
userspace. When transferred to or from user memory via KVM_GET_ONE_REG
or KVM_SET_ONE_REG, the value of this register is of type
__u64[KVM_ARM64_SVE_VLS_WORDS], and encodes the set of vector lengths as
-follows:
+follows::
-__u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS];
+ __u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS];
-if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX &&
- ((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >>
+ if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX &&
+ ((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >>
((vq - KVM_ARM64_SVE_VQ_MIN) % 64)) & 1))
/* Vector length vq * 16 bytes supported */
-else
+ else
/* Vector length vq * 16 bytes not supported */
-(**) The maximum value vq for which the above condition is true is
-max_vq. This is the maximum vector length available to the guest on
-this vcpu, and determines which register slices are visible through
-this ioctl interface.
+.. [2] The maximum value vq for which the above condition is true is
+ max_vq. This is the maximum vector length available to the guest on
+ this vcpu, and determines which register slices are visible through
+ this ioctl interface.
(See Documentation/arm64/sve.rst for an explanation of the "vq"
nomenclature.)
@@ -2261,11 +2479,13 @@ write this register will fail with EPERM.
MIPS registers are mapped using the lower 32 bits. The upper 16 of that is
the register group type:
-MIPS core registers (see above) have the following id bit patterns:
+MIPS core registers (see above) have the following id bit patterns::
+
0x7030 0000 0000 <reg:16>
MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bit
-patterns depending on whether they're 32-bit or 64-bit registers:
+patterns depending on whether they're 32-bit or 64-bit registers::
+
0x7020 0000 0001 00 <reg:5> <sel:3> (32-bit)
0x7030 0000 0001 00 <reg:5> <sel:3> (64-bit)
@@ -2276,10 +2496,12 @@ with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and
the PFNX field starting at bit 30.
MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bit
-patterns:
+patterns::
+
0x7030 0000 0001 01 <reg:8>
-MIPS KVM control registers (see above) have the following id bit patterns:
+MIPS KVM control registers (see above) have the following id bit patterns::
+
0x7030 0000 0002 <reg:16>
MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the following
@@ -2288,31 +2510,40 @@ always accessed according to the current guest FPU mode (Status.FR and
Config5.FRE), i.e. as the guest would see them, and they become unpredictable
if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector
registers (see KVM_REG_MIPS_VEC_128() above) have similar patterns as they
-overlap the FPU registers:
+overlap the FPU registers::
+
0x7020 0000 0003 00 <0:3> <reg:5> (32-bit FPU registers)
0x7030 0000 0003 00 <0:3> <reg:5> (64-bit FPU registers)
0x7040 0000 0003 00 <0:3> <reg:5> (128-bit MSA vector registers)
MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have the
-following id bit patterns:
+following id bit patterns::
+
0x7020 0000 0003 01 <0:3> <reg:5>
MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the
-following id bit patterns:
+following id bit patterns::
+
0x7020 0000 0003 02 <0:3> <reg:5>
4.69 KVM_GET_ONE_REG
+--------------------
+
+:Capability: KVM_CAP_ONE_REG
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: struct kvm_one_reg (in and out)
+:Returns: 0 on success, negative value on failure
-Capability: KVM_CAP_ONE_REG
-Architectures: all
-Type: vcpu ioctl
-Parameters: struct kvm_one_reg (in and out)
-Returns: 0 on success, negative value on failure
Errors include:
- ENOENT: no such register
- EINVAL: invalid register ID, or no such register
- EPERM: (arm64) register access not allowed before vcpu finalization
+
+ ======== ============================================================
+ ENOENT no such register
+ EINVAL invalid register ID, or no such register
+ EPERM (arm64) register access not allowed before vcpu finalization
+ ======== ============================================================
+
(These error codes are indicative only: do not rely on a specific error
code being returned in a specific situation.)
@@ -2326,12 +2557,13 @@ list in 4.68.
4.70 KVM_KVMCLOCK_CTRL
+----------------------
-Capability: KVM_CAP_KVMCLOCK_CTRL
-Architectures: Any that implement pvclocks (currently x86 only)
-Type: vcpu ioctl
-Parameters: None
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_KVMCLOCK_CTRL
+:Architectures: Any that implement pvclocks (currently x86 only)
+:Type: vcpu ioctl
+:Parameters: None
+:Returns: 0 on success, -1 on error
This signals to the host kernel that the specified guest is being paused by
userspace. The host will set a flag in the pvclock structure that is checked
@@ -2347,26 +2579,30 @@ after pausing the vcpu, but before it is resumed.
4.71 KVM_SIGNAL_MSI
+-------------------
-Capability: KVM_CAP_SIGNAL_MSI
-Architectures: x86 arm arm64
-Type: vm ioctl
-Parameters: struct kvm_msi (in)
-Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
+:Capability: KVM_CAP_SIGNAL_MSI
+:Architectures: x86 arm arm64
+:Type: vm ioctl
+:Parameters: struct kvm_msi (in)
+:Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
Directly inject a MSI message. Only valid with in-kernel irqchip that handles
MSI messages.
-struct kvm_msi {
+::
+
+ struct kvm_msi {
__u32 address_lo;
__u32 address_hi;
__u32 data;
__u32 flags;
__u32 devid;
__u8 pad[12];
-};
+ };
-flags: KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM
+flags:
+ KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM
KVM_CAP_MSI_DEVID capability advertises the requirement to provide
the device ID. If this capability is not available, userspace
should never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
@@ -2382,30 +2618,31 @@ address_hi must be zero.
4.71 KVM_CREATE_PIT2
+--------------------
-Capability: KVM_CAP_PIT2
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_pit_config (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PIT2
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_pit_config (in)
+:Returns: 0 on success, -1 on error
Creates an in-kernel device model for the i8254 PIT. This call is only valid
after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following
-parameters have to be passed:
+parameters have to be passed::
-struct kvm_pit_config {
+ struct kvm_pit_config {
__u32 flags;
__u32 pad[15];
-};
+ };
-Valid flags are:
+Valid flags are::
-#define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */
+ #define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */
PIT timer interrupts may use a per-VM kernel thread for injection. If it
-exists, this thread will have a name of the following pattern:
+exists, this thread will have a name of the following pattern::
-kvm-pit/<owner-process-pid>
+ kvm-pit/<owner-process-pid>
When running a guest with elevated priorities, the scheduling parameters of
this thread may have to be adjusted accordingly.
@@ -2414,37 +2651,39 @@ This IOCTL replaces the obsolete KVM_CREATE_PIT.
4.72 KVM_GET_PIT2
+-----------------
-Capability: KVM_CAP_PIT_STATE2
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_pit_state2 (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PIT_STATE2
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_pit_state2 (out)
+:Returns: 0 on success, -1 on error
Retrieves the state of the in-kernel PIT model. Only valid after
-KVM_CREATE_PIT2. The state is returned in the following structure:
+KVM_CREATE_PIT2. The state is returned in the following structure::
-struct kvm_pit_state2 {
+ struct kvm_pit_state2 {
struct kvm_pit_channel_state channels[3];
__u32 flags;
__u32 reserved[9];
-};
+ };
-Valid flags are:
+Valid flags are::
-/* disable PIT in HPET legacy mode */
-#define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001
+ /* disable PIT in HPET legacy mode */
+ #define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001
This IOCTL replaces the obsolete KVM_GET_PIT.
4.73 KVM_SET_PIT2
+-----------------
-Capability: KVM_CAP_PIT_STATE2
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_pit_state2 (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PIT_STATE2
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_pit_state2 (in)
+:Returns: 0 on success, -1 on error
Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
See KVM_GET_PIT2 for details on struct kvm_pit_state2.
@@ -2453,12 +2692,13 @@ This IOCTL replaces the obsolete KVM_SET_PIT.
4.74 KVM_PPC_GET_SMMU_INFO
+--------------------------
-Capability: KVM_CAP_PPC_GET_SMMU_INFO
-Architectures: powerpc
-Type: vm ioctl
-Parameters: None
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PPC_GET_SMMU_INFO
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: None
+:Returns: 0 on success, -1 on error
This populates and returns a structure describing the features of
the "Server" class MMU emulation supported by KVM.
@@ -2466,7 +2706,7 @@ This can in turn be used by userspace to generate the appropriate
device-tree properties for the guest operating system.
The structure contains some global information, followed by an
-array of supported segment page sizes:
+array of supported segment page sizes::
struct kvm_ppc_smmu_info {
__u64 flags;
@@ -2494,7 +2734,7 @@ The "slb_size" field indicates how many SLB entries are supported
The "sps" array contains 8 entries indicating the supported base
page sizes for a segment in increasing order. Each entry is defined
-as follow:
+as follow::
struct kvm_ppc_one_seg_page_size {
__u32 page_shift; /* Base page shift of segment (or 0) */
@@ -2515,7 +2755,7 @@ size provides the list of supported actual page sizes (which can be
only larger or equal to the base page size), along with the
corresponding encoding in the hash PTE. Similarly, the array is
8 entries sorted by increasing sizes and an entry with a "0" shift
-is an empty entry and a terminator:
+is an empty entry and a terminator::
struct kvm_ppc_one_page_size {
__u32 page_shift; /* Page shift (or 0) */
@@ -2527,12 +2767,13 @@ PTE's RPN field (ie, it needs to be shifted left by 12 to OR it
into the hash PTE second double word).
4.75 KVM_IRQFD
+--------------
-Capability: KVM_CAP_IRQFD
-Architectures: x86 s390 arm arm64
-Type: vm ioctl
-Parameters: struct kvm_irqfd (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQFD
+:Architectures: x86 s390 arm arm64
+:Type: vm ioctl
+:Parameters: struct kvm_irqfd (in)
+:Returns: 0 on success, -1 on error
Allows setting an eventfd to directly trigger a guest interrupt.
kvm_irqfd.fd specifies the file descriptor to use as the eventfd and
@@ -2556,6 +2797,7 @@ irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment
and need not be specified with KVM_IRQFD_FLAG_DEASSIGN.
On arm/arm64, gsi routing being supported, the following can happen:
+
- in case no routing entry is associated to this gsi, injection fails
- in case the gsi is associated to an irqchip routing entry,
irqchip.pin + 32 corresponds to the injected SPI ID.
@@ -2564,12 +2806,13 @@ On arm/arm64, gsi routing being supported, the following can happen:
to GICv3 ITS in-kernel emulation).
4.76 KVM_PPC_ALLOCATE_HTAB
+--------------------------
-Capability: KVM_CAP_PPC_ALLOC_HTAB
-Architectures: powerpc
-Type: vm ioctl
-Parameters: Pointer to u32 containing hash table order (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PPC_ALLOC_HTAB
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: Pointer to u32 containing hash table order (in/out)
+:Returns: 0 on success, -1 on error
This requests the host kernel to allocate an MMU hash table for a
guest using the PAPR paravirtualization interface. This only does
@@ -2600,75 +2843,88 @@ real-mode area (VRMA) facility, the kernel will re-create the VMRA
HPTEs on the next KVM_RUN of any vcpu.
4.77 KVM_S390_INTERRUPT
+-----------------------
-Capability: basic
-Architectures: s390
-Type: vm ioctl, vcpu ioctl
-Parameters: struct kvm_s390_interrupt (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: s390
+:Type: vm ioctl, vcpu ioctl
+:Parameters: struct kvm_s390_interrupt (in)
+:Returns: 0 on success, -1 on error
Allows to inject an interrupt to the guest. Interrupts can be floating
(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type.
-Interrupt parameters are passed via kvm_s390_interrupt:
+Interrupt parameters are passed via kvm_s390_interrupt::
-struct kvm_s390_interrupt {
+ struct kvm_s390_interrupt {
__u32 type;
__u32 parm;
__u64 parm64;
-};
+ };
type can be one of the following:
-KVM_S390_SIGP_STOP (vcpu) - sigp stop; optional flags in parm
-KVM_S390_PROGRAM_INT (vcpu) - program check; code in parm
-KVM_S390_SIGP_SET_PREFIX (vcpu) - sigp set prefix; prefix address in parm
-KVM_S390_RESTART (vcpu) - restart
-KVM_S390_INT_CLOCK_COMP (vcpu) - clock comparator interrupt
-KVM_S390_INT_CPU_TIMER (vcpu) - CPU timer interrupt
-KVM_S390_INT_VIRTIO (vm) - virtio external interrupt; external interrupt
- parameters in parm and parm64
-KVM_S390_INT_SERVICE (vm) - sclp external interrupt; sclp parameter in parm
-KVM_S390_INT_EMERGENCY (vcpu) - sigp emergency; source cpu in parm
-KVM_S390_INT_EXTERNAL_CALL (vcpu) - sigp external call; source cpu in parm
-KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm) - compound value to indicate an
- I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel);
- I/O interruption parameters in parm (subchannel) and parm64 (intparm,
- interruption subclass)
-KVM_S390_MCHK (vm, vcpu) - machine check interrupt; cr 14 bits in parm,
- machine check interrupt code in parm64 (note that
- machine checks needing further payload are not
- supported by this ioctl)
+KVM_S390_SIGP_STOP (vcpu)
+ - sigp stop; optional flags in parm
+KVM_S390_PROGRAM_INT (vcpu)
+ - program check; code in parm
+KVM_S390_SIGP_SET_PREFIX (vcpu)
+ - sigp set prefix; prefix address in parm
+KVM_S390_RESTART (vcpu)
+ - restart
+KVM_S390_INT_CLOCK_COMP (vcpu)
+ - clock comparator interrupt
+KVM_S390_INT_CPU_TIMER (vcpu)
+ - CPU timer interrupt
+KVM_S390_INT_VIRTIO (vm)
+ - virtio external interrupt; external interrupt
+ parameters in parm and parm64
+KVM_S390_INT_SERVICE (vm)
+ - sclp external interrupt; sclp parameter in parm
+KVM_S390_INT_EMERGENCY (vcpu)
+ - sigp emergency; source cpu in parm
+KVM_S390_INT_EXTERNAL_CALL (vcpu)
+ - sigp external call; source cpu in parm
+KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm)
+ - compound value to indicate an
+ I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel);
+ I/O interruption parameters in parm (subchannel) and parm64 (intparm,
+ interruption subclass)
+KVM_S390_MCHK (vm, vcpu)
+ - machine check interrupt; cr 14 bits in parm, machine check interrupt
+ code in parm64 (note that machine checks needing further payload are not
+ supported by this ioctl)
This is an asynchronous vcpu ioctl and can be invoked from any thread.
4.78 KVM_PPC_GET_HTAB_FD
+------------------------
-Capability: KVM_CAP_PPC_HTAB_FD
-Architectures: powerpc
-Type: vm ioctl
-Parameters: Pointer to struct kvm_get_htab_fd (in)
-Returns: file descriptor number (>= 0) on success, -1 on error
+:Capability: KVM_CAP_PPC_HTAB_FD
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: Pointer to struct kvm_get_htab_fd (in)
+:Returns: file descriptor number (>= 0) on success, -1 on error
This returns a file descriptor that can be used either to read out the
entries in the guest's hashed page table (HPT), or to write entries to
initialize the HPT. The returned fd can only be written to if the
KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
can only be read if that bit is clear. The argument struct looks like
-this:
+this::
-/* For KVM_PPC_GET_HTAB_FD */
-struct kvm_get_htab_fd {
+ /* For KVM_PPC_GET_HTAB_FD */
+ struct kvm_get_htab_fd {
__u64 flags;
__u64 start_index;
__u64 reserved[2];
-};
+ };
-/* Values for kvm_get_htab_fd.flags */
-#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1)
-#define KVM_GET_HTAB_WRITE ((__u64)0x2)
+ /* Values for kvm_get_htab_fd.flags */
+ #define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1)
+ #define KVM_GET_HTAB_WRITE ((__u64)0x2)
-The `start_index' field gives the index in the HPT of the entry at
+The 'start_index' field gives the index in the HPT of the entry at
which to start reading. It is ignored when writing.
Reads on the fd will initially supply information about all
@@ -2683,29 +2939,34 @@ Data read or written is structured as a header (8 bytes) followed by a
series of valid HPT entries (16 bytes) each. The header indicates how
many valid HPT entries there are and how many invalid entries follow
the valid entries. The invalid entries are not represented explicitly
-in the stream. The header format is:
+in the stream. The header format is::
-struct kvm_get_htab_header {
+ struct kvm_get_htab_header {
__u32 index;
__u16 n_valid;
__u16 n_invalid;
-};
+ };
Writes to the fd create HPT entries starting at the index given in the
-header; first `n_valid' valid entries with contents from the data
-written, then `n_invalid' invalid entries, invalidating any previously
+header; first 'n_valid' valid entries with contents from the data
+written, then 'n_invalid' invalid entries, invalidating any previously
valid entries found.
4.79 KVM_CREATE_DEVICE
+----------------------
+
+:Capability: KVM_CAP_DEVICE_CTRL
+:Type: vm ioctl
+:Parameters: struct kvm_create_device (in/out)
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_DEVICE_CTRL
-Type: vm ioctl
-Parameters: struct kvm_create_device (in/out)
-Returns: 0 on success, -1 on error
Errors:
- ENODEV: The device type is unknown or unsupported
- EEXIST: Device already created, and this type of device may not
+
+ ====== =======================================================
+ ENODEV The device type is unknown or unsupported
+ EEXIST Device already created, and this type of device may not
be instantiated multiple times
+ ====== =======================================================
Other error conditions may be defined by individual device types or
have their standard meanings.
@@ -2721,25 +2982,32 @@ Individual devices should not define flags. Attributes should be used
for specifying any behavior that is not implied by the device type
number.
-struct kvm_create_device {
+::
+
+ struct kvm_create_device {
__u32 type; /* in: KVM_DEV_TYPE_xxx */
__u32 fd; /* out: device handle */
__u32 flags; /* in: KVM_CREATE_DEVICE_xxx */
-};
+ };
4.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR
+--------------------------------------------
+
+:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
+ KVM_CAP_VCPU_ATTRIBUTES for vcpu device
+:Type: device ioctl, vm ioctl, vcpu ioctl
+:Parameters: struct kvm_device_attr
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
- KVM_CAP_VCPU_ATTRIBUTES for vcpu device
-Type: device ioctl, vm ioctl, vcpu ioctl
-Parameters: struct kvm_device_attr
-Returns: 0 on success, -1 on error
Errors:
- 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.
- EPERM: The attribute cannot (currently) be accessed this way
+ EPERM The attribute cannot (currently) be accessed this way
(e.g. read-only attribute, or attribute that only makes
sense when the device is in a different state)
+ ===== =============================================================
Other error conditions may be defined by individual device types.
@@ -2748,23 +3016,30 @@ semantics are device-specific. See individual device documentation in
the "devices" directory. As with ONE_REG, the size of the data
transferred is defined by the particular attribute.
-struct kvm_device_attr {
+::
+
+ struct kvm_device_attr {
__u32 flags; /* no flags currently defined */
__u32 group; /* device-defined */
__u64 attr; /* group-defined */
__u64 addr; /* userspace address of attr data */
-};
+ };
4.81 KVM_HAS_DEVICE_ATTR
+------------------------
+
+:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
+ KVM_CAP_VCPU_ATTRIBUTES for vcpu device
+:Type: device ioctl, vm ioctl, vcpu ioctl
+:Parameters: struct kvm_device_attr
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
- KVM_CAP_VCPU_ATTRIBUTES for vcpu device
-Type: device ioctl, vm ioctl, vcpu ioctl
-Parameters: struct kvm_device_attr
-Returns: 0 on success, -1 on error
Errors:
- 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.
+ ===== =============================================================
Tests whether a device supports a particular attribute. A successful
return indicates the attribute is implemented. It does not necessarily
@@ -2772,15 +3047,20 @@ indicate that the attribute can be read or written in the device's
current state. "addr" is ignored.
4.82 KVM_ARM_VCPU_INIT
+----------------------
+
+:Capability: basic
+:Architectures: arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_vcpu_init (in)
+:Returns: 0 on success; -1 on error
-Capability: basic
-Architectures: arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_vcpu_init (in)
-Returns: 0 on success; -1 on error
Errors:
- EINVAL: the target is unknown, or the combination of features is invalid.
- ENOENT: a features bit specified is unknown.
+
+ ====== =================================================================
+ EINVAL the target is unknown, or the combination of features is invalid.
+ ENOENT a features bit specified is unknown.
+ ====== =================================================================
This tells KVM what type of CPU to present to the guest, and what
optional features it should have. This will cause a reset of the cpu
@@ -2796,6 +3076,7 @@ state. All calls to this function after the initial call must use the same
target and same set of feature flags, otherwise EINVAL will be returned.
Possible features:
+
- KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state.
Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on
and execute guest code when KVM_RUN is called.
@@ -2852,14 +3133,19 @@ Possible features:
no longer be written using KVM_SET_ONE_REG.
4.83 KVM_ARM_PREFERRED_TARGET
+-----------------------------
+
+:Capability: basic
+:Architectures: arm, arm64
+:Type: vm ioctl
+:Parameters: struct struct kvm_vcpu_init (out)
+:Returns: 0 on success; -1 on error
-Capability: basic
-Architectures: arm, arm64
-Type: vm ioctl
-Parameters: struct struct kvm_vcpu_init (out)
-Returns: 0 on success; -1 on error
Errors:
- ENODEV: no preferred target available for the host
+
+ ====== ==========================================
+ ENODEV no preferred target available for the host
+ ====== ==========================================
This queries KVM for preferred CPU target type which can be emulated
by KVM on underlying host.
@@ -2876,43 +3162,57 @@ in VCPU matching underlying host.
4.84 KVM_GET_REG_LIST
+---------------------
+
+:Capability: basic
+:Architectures: arm, arm64, mips
+:Type: vcpu ioctl
+:Parameters: struct kvm_reg_list (in/out)
+:Returns: 0 on success; -1 on error
-Capability: basic
-Architectures: arm, arm64, mips
-Type: vcpu ioctl
-Parameters: struct kvm_reg_list (in/out)
-Returns: 0 on success; -1 on error
Errors:
- E2BIG: the reg index list is too big to fit in the array specified by
+
+ ===== ==============================================================
+ E2BIG the reg index list is too big to fit in the array specified by
the user (the number required will be written into n).
+ ===== ==============================================================
-struct kvm_reg_list {
+::
+
+ struct kvm_reg_list {
__u64 n; /* number of registers in reg[] */
__u64 reg[0];
-};
+ };
This ioctl returns the guest registers that are supported for the
KVM_GET_ONE_REG/KVM_SET_ONE_REG calls.
4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated)
+-----------------------------------------
+
+:Capability: KVM_CAP_ARM_SET_DEVICE_ADDR
+:Architectures: arm, arm64
+:Type: vm ioctl
+:Parameters: struct kvm_arm_device_address (in)
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_ARM_SET_DEVICE_ADDR
-Architectures: arm, arm64
-Type: vm ioctl
-Parameters: struct kvm_arm_device_address (in)
-Returns: 0 on success, -1 on error
Errors:
- ENODEV: The device id is unknown
- ENXIO: Device not supported on current system
- EEXIST: Address already set
- E2BIG: Address outside guest physical address space
- EBUSY: Address overlaps with other device range
-struct kvm_arm_device_addr {
+ ====== ============================================
+ ENODEV The device id is unknown
+ ENXIO Device not supported on current system
+ EEXIST Address already set
+ E2BIG Address outside guest physical address space
+ EBUSY Address overlaps with other device range
+ ====== ============================================
+
+::
+
+ struct kvm_arm_device_addr {
__u64 id;
__u64 addr;
-};
+ };
Specify a device address in the guest's physical address space where guests
can access emulated or directly exposed devices, which the host kernel needs
@@ -2920,7 +3220,7 @@ to know about. The id field is an architecture specific identifier for a
specific device.
ARM/arm64 divides the id field into two parts, a device id and an
-address type id specific to the individual device.
+address type id specific to the individual device::
bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 |
field: | 0x00000000 | device id | addr type id |
@@ -2938,12 +3238,13 @@ should be used instead.
4.86 KVM_PPC_RTAS_DEFINE_TOKEN
+------------------------------
-Capability: KVM_CAP_PPC_RTAS
-Architectures: ppc
-Type: vm ioctl
-Parameters: struct kvm_rtas_token_args
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PPC_RTAS
+:Architectures: ppc
+:Type: vm ioctl
+:Parameters: struct kvm_rtas_token_args
+:Returns: 0 on success, -1 on error
Defines a token value for a RTAS (Run Time Abstraction Services)
service in order to allow it to be handled in the kernel. The
@@ -2957,18 +3258,21 @@ calls by the guest for that service will be passed to userspace to be
handled.
4.87 KVM_SET_GUEST_DEBUG
+------------------------
-Capability: KVM_CAP_SET_GUEST_DEBUG
-Architectures: x86, s390, ppc, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_guest_debug (in)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_SET_GUEST_DEBUG
+:Architectures: x86, s390, ppc, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_guest_debug (in)
+:Returns: 0 on success; -1 on error
-struct kvm_guest_debug {
+::
+
+ struct kvm_guest_debug {
__u32 control;
__u32 pad;
struct kvm_guest_debug_arch arch;
-};
+ };
Set up the processor specific debug registers and configure vcpu for
handling guest debug events. There are two parts to the structure, the
@@ -3010,26 +3314,31 @@ KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run
structure containing architecture specific debug information.
4.88 KVM_GET_EMULATED_CPUID
+---------------------------
-Capability: KVM_CAP_EXT_EMUL_CPUID
-Architectures: x86
-Type: system ioctl
-Parameters: struct kvm_cpuid2 (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_EXT_EMUL_CPUID
+:Architectures: x86
+:Type: system ioctl
+:Parameters: struct kvm_cpuid2 (in/out)
+:Returns: 0 on success, -1 on error
-struct kvm_cpuid2 {
+::
+
+ struct kvm_cpuid2 {
__u32 nent;
__u32 flags;
struct kvm_cpuid_entry2 entries[0];
-};
+ };
The member 'flags' is used for passing flags from userspace.
-#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
-#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
-#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
+::
-struct kvm_cpuid_entry2 {
+ #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
+ #define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
+ #define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
+
+ struct kvm_cpuid_entry2 {
__u32 function;
__u32 index;
__u32 flags;
@@ -3038,7 +3347,7 @@ struct kvm_cpuid_entry2 {
__u32 ecx;
__u32 edx;
__u32 padding[3];
-};
+ };
This ioctl returns x86 cpuid features which are emulated by
kvm.Userspace can use the information returned by this ioctl to query
@@ -3063,10 +3372,14 @@ emulated efficiently and thus not included here.
The fields in each entry are defined as follows:
- function: the eax value used to obtain the entry
- index: the ecx value used to obtain the entry (for entries that are
+ function:
+ the eax value used to obtain the entry
+ index:
+ the ecx value used to obtain the entry (for entries that are
affected by ecx)
- flags: an OR of zero or more of the following:
+ flags:
+ an OR of zero or more of the following:
+
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
if the index field is valid
KVM_CPUID_FLAG_STATEFUL_FUNC:
@@ -3076,24 +3389,28 @@ The fields in each entry are defined as follows:
KVM_CPUID_FLAG_STATE_READ_NEXT:
for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
the first entry to be read by a cpu
- eax, ebx, ecx, edx: the values returned by the cpuid instruction for
+
+ eax, ebx, ecx, edx:
+
+ the values returned by the cpuid instruction for
this function/index combination
4.89 KVM_S390_MEM_OP
+--------------------
-Capability: KVM_CAP_S390_MEM_OP
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_mem_op (in)
-Returns: = 0 on success,
- < 0 on generic error (e.g. -EFAULT or -ENOMEM),
- > 0 if an exception occurred while walking the page tables
+:Capability: KVM_CAP_S390_MEM_OP
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_mem_op (in)
+:Returns: = 0 on success,
+ < 0 on generic error (e.g. -EFAULT or -ENOMEM),
+ > 0 if an exception occurred while walking the page tables
Read or write data from/to the logical (virtual) memory of a VCPU.
-Parameters are specified via the following structure:
+Parameters are specified via the following structure::
-struct kvm_s390_mem_op {
+ struct kvm_s390_mem_op {
__u64 gaddr; /* the guest address */
__u64 flags; /* flags */
__u32 size; /* amount of bytes */
@@ -3101,7 +3418,7 @@ struct kvm_s390_mem_op {
__u64 buf; /* buffer in userspace */
__u8 ar; /* the access register number */
__u8 reserved[31]; /* should be set to 0 */
-};
+ };
The type of operation is specified in the "op" field. It is either
KVM_S390_MEMOP_LOGICAL_READ for reading from logical memory space or
@@ -3128,24 +3445,25 @@ The "reserved" field is meant for future extensions. It is not used by
KVM with the currently defined set of flags.
4.90 KVM_S390_GET_SKEYS
+-----------------------
-Capability: KVM_CAP_S390_SKEYS
-Architectures: s390
-Type: vm ioctl
-Parameters: struct kvm_s390_skeys
-Returns: 0 on success, KVM_S390_GET_KEYS_NONE if guest is not using storage
- keys, negative value on error
+:Capability: KVM_CAP_S390_SKEYS
+:Architectures: s390
+:Type: vm ioctl
+:Parameters: struct kvm_s390_skeys
+:Returns: 0 on success, KVM_S390_GET_KEYS_NONE if guest is not using storage
+ keys, negative value on error
This ioctl is used to get guest storage key values on the s390
-architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
+architecture. The ioctl takes parameters via the kvm_s390_skeys struct::
-struct kvm_s390_skeys {
+ struct kvm_s390_skeys {
__u64 start_gfn;
__u64 count;
__u64 skeydata_addr;
__u32 flags;
__u32 reserved[9];
-};
+ };
The start_gfn field is the number of the first guest frame whose storage keys
you want to get.
@@ -3159,12 +3477,13 @@ The skeydata_addr field is the address to a buffer large enough to hold count
bytes. This buffer will be filled with storage key data by the ioctl.
4.91 KVM_S390_SET_SKEYS
+-----------------------
-Capability: KVM_CAP_S390_SKEYS
-Architectures: s390
-Type: vm ioctl
-Parameters: struct kvm_s390_skeys
-Returns: 0 on success, negative value on error
+:Capability: KVM_CAP_S390_SKEYS
+:Architectures: s390
+:Type: vm ioctl
+:Parameters: struct kvm_s390_skeys
+:Returns: 0 on success, negative value on error
This ioctl is used to set guest storage key values on the s390
architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
@@ -3186,21 +3505,27 @@ Note: If any architecturally invalid key value is found in the given data then
the ioctl will return -EINVAL.
4.92 KVM_S390_IRQ
+-----------------
+
+:Capability: KVM_CAP_S390_INJECT_IRQ
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_irq (in)
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_S390_INJECT_IRQ
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_irq (in)
-Returns: 0 on success, -1 on error
Errors:
- EINVAL: interrupt type is invalid
- type is KVM_S390_SIGP_STOP and flag parameter is invalid value
+
+
+ ====== =================================================================
+ EINVAL interrupt type is invalid
+ type is KVM_S390_SIGP_STOP and flag parameter is invalid value,
type is KVM_S390_INT_EXTERNAL_CALL and code is bigger
- than the maximum of VCPUs
- EBUSY: type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped
- type is KVM_S390_SIGP_STOP and a stop irq is already pending
+ than the maximum of VCPUs
+ EBUSY type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped,
+ type is KVM_S390_SIGP_STOP and a stop irq is already pending,
type is KVM_S390_INT_EXTERNAL_CALL and an external call interrupt
- is already pending
+ is already pending
+ ====== =================================================================
Allows to inject an interrupt to the guest.
@@ -3208,9 +3533,9 @@ Using struct kvm_s390_irq as a parameter allows
to inject additional payload which is not
possible via KVM_S390_INTERRUPT.
-Interrupt parameters are passed via kvm_s390_irq:
+Interrupt parameters are passed via kvm_s390_irq::
-struct kvm_s390_irq {
+ struct kvm_s390_irq {
__u64 type;
union {
struct kvm_s390_io_info io;
@@ -3223,44 +3548,45 @@ struct kvm_s390_irq {
struct kvm_s390_mchk_info mchk;
char reserved[64];
} u;
-};
+ };
type can be one of the following:
-KVM_S390_SIGP_STOP - sigp stop; parameter in .stop
-KVM_S390_PROGRAM_INT - program check; parameters in .pgm
-KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix
-KVM_S390_RESTART - restart; no parameters
-KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters
-KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters
-KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg
-KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall
-KVM_S390_MCHK - machine check interrupt; parameters in .mchk
+- KVM_S390_SIGP_STOP - sigp stop; parameter in .stop
+- KVM_S390_PROGRAM_INT - program check; parameters in .pgm
+- KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix
+- KVM_S390_RESTART - restart; no parameters
+- KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters
+- KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters
+- KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg
+- KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall
+- KVM_S390_MCHK - machine check interrupt; parameters in .mchk
This is an asynchronous vcpu ioctl and can be invoked from any thread.
4.94 KVM_S390_GET_IRQ_STATE
+---------------------------
-Capability: KVM_CAP_S390_IRQ_STATE
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_irq_state (out)
-Returns: >= number of bytes copied into buffer,
- -EINVAL if buffer size is 0,
- -ENOBUFS if buffer size is too small to fit all pending interrupts,
- -EFAULT if the buffer address was invalid
+:Capability: KVM_CAP_S390_IRQ_STATE
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_irq_state (out)
+:Returns: >= number of bytes copied into buffer,
+ -EINVAL if buffer size is 0,
+ -ENOBUFS if buffer size is too small to fit all pending interrupts,
+ -EFAULT if the buffer address was invalid
This ioctl allows userspace to retrieve the complete state of all currently
pending interrupts in a single buffer. Use cases include migration
and introspection. The parameter structure contains the address of a
-userspace buffer and its length:
+userspace buffer and its length::
-struct kvm_s390_irq_state {
+ struct kvm_s390_irq_state {
__u64 buf;
__u32 flags; /* will stay unused for compatibility reasons */
__u32 len;
__u32 reserved[4]; /* will stay unused for compatibility reasons */
-};
+ };
Userspace passes in the above struct and for each pending interrupt a
struct kvm_s390_irq is copied to the provided buffer.
@@ -3274,29 +3600,30 @@ If -ENOBUFS is returned the buffer provided was too small and userspace
may retry with a bigger buffer.
4.95 KVM_S390_SET_IRQ_STATE
+---------------------------
-Capability: KVM_CAP_S390_IRQ_STATE
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_irq_state (in)
-Returns: 0 on success,
- -EFAULT if the buffer address was invalid,
- -EINVAL for an invalid buffer length (see below),
- -EBUSY if there were already interrupts pending,
- errors occurring when actually injecting the
+:Capability: KVM_CAP_S390_IRQ_STATE
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_irq_state (in)
+:Returns: 0 on success,
+ -EFAULT if the buffer address was invalid,
+ -EINVAL for an invalid buffer length (see below),
+ -EBUSY if there were already interrupts pending,
+ errors occurring when actually injecting the
interrupt. See KVM_S390_IRQ.
This ioctl allows userspace to set the complete state of all cpu-local
interrupts currently pending for the vcpu. It is intended for restoring
interrupt state after a migration. The input parameter is a userspace buffer
-containing a struct kvm_s390_irq_state:
+containing a struct kvm_s390_irq_state::
-struct kvm_s390_irq_state {
+ struct kvm_s390_irq_state {
__u64 buf;
__u32 flags; /* will stay unused for compatibility reasons */
__u32 len;
__u32 reserved[4]; /* will stay unused for compatibility reasons */
-};
+ };
The restrictions for flags and reserved apply as well.
(see KVM_S390_GET_IRQ_STATE)
@@ -3311,20 +3638,22 @@ and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq),
which is the maximum number of possibly pending cpu-local interrupts.
4.96 KVM_SMI
+------------
-Capability: KVM_CAP_X86_SMM
-Architectures: x86
-Type: vcpu ioctl
-Parameters: none
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_X86_SMM
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: none
+:Returns: 0 on success, -1 on error
Queues an SMI on the thread's vcpu.
4.97 KVM_CAP_PPC_MULTITCE
+-------------------------
-Capability: KVM_CAP_PPC_MULTITCE
-Architectures: ppc
-Type: vm
+:Capability: KVM_CAP_PPC_MULTITCE
+:Architectures: ppc
+:Type: vm
This capability means the kernel is capable of handling hypercalls
H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user
@@ -3346,26 +3675,27 @@ an implementation for these despite the in kernel acceleration.
This capability is always enabled.
4.98 KVM_CREATE_SPAPR_TCE_64
+----------------------------
-Capability: KVM_CAP_SPAPR_TCE_64
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_create_spapr_tce_64 (in)
-Returns: file descriptor for manipulating the created TCE table
+:Capability: KVM_CAP_SPAPR_TCE_64
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_create_spapr_tce_64 (in)
+:Returns: file descriptor for manipulating the created TCE table
This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bit
windows, described in 4.62 KVM_CREATE_SPAPR_TCE
-This capability uses extended struct in ioctl interface:
+This capability uses extended struct in ioctl interface::
-/* for KVM_CAP_SPAPR_TCE_64 */
-struct kvm_create_spapr_tce_64 {
+ /* for KVM_CAP_SPAPR_TCE_64 */
+ struct kvm_create_spapr_tce_64 {
__u64 liobn;
__u32 page_shift;
__u32 flags;
__u64 offset; /* in pages */
__u64 size; /* in pages */
-};
+ };
The aim of extension is to support an additional bigger DMA window with
a variable page size.
@@ -3378,12 +3708,13 @@ of IOMMU pages.
The rest of functionality is identical to KVM_CREATE_SPAPR_TCE.
4.99 KVM_REINJECT_CONTROL
+-------------------------
-Capability: KVM_CAP_REINJECT_CONTROL
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_reinject_control (in)
-Returns: 0 on success,
+:Capability: KVM_CAP_REINJECT_CONTROL
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_reinject_control (in)
+:Returns: 0 on success,
-EFAULT if struct kvm_reinject_control cannot be read,
-ENXIO if KVM_CREATE_PIT or KVM_CREATE_PIT2 didn't succeed earlier.
@@ -3393,21 +3724,24 @@ vector(s) that i8254 injects. Reinject mode dequeues a tick and injects its
interrupt whenever there isn't a pending interrupt from i8254.
!reinject mode injects an interrupt as soon as a tick arrives.
-struct kvm_reinject_control {
+::
+
+ struct kvm_reinject_control {
__u8 pit_reinject;
__u8 reserved[31];
-};
+ };
pit_reinject = 0 (!reinject mode) is recommended, unless running an old
operating system that uses the PIT for timing (e.g. Linux 2.4.x).
4.100 KVM_PPC_CONFIGURE_V3_MMU
+------------------------------
-Capability: KVM_CAP_PPC_RADIX_MMU or KVM_CAP_PPC_HASH_MMU_V3
-Architectures: ppc
-Type: vm ioctl
-Parameters: struct kvm_ppc_mmuv3_cfg (in)
-Returns: 0 on success,
+:Capability: KVM_CAP_PPC_RADIX_MMU or KVM_CAP_PPC_HASH_MMU_V3
+:Architectures: ppc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_mmuv3_cfg (in)
+:Returns: 0 on success,
-EFAULT if struct kvm_ppc_mmuv3_cfg cannot be read,
-EINVAL if the configuration is invalid
@@ -3415,10 +3749,12 @@ This ioctl controls whether the guest will use radix or HPT (hashed
page table) translation, and sets the pointer to the process table for
the guest.
-struct kvm_ppc_mmuv3_cfg {
+::
+
+ struct kvm_ppc_mmuv3_cfg {
__u64 flags;
__u64 process_table;
-};
+ };
There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX and
KVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guest
@@ -3433,12 +3769,13 @@ as the second doubleword of the partition table entry, as defined in
the Power ISA V3.00, Book III section 5.7.6.1.
4.101 KVM_PPC_GET_RMMU_INFO
+---------------------------
-Capability: KVM_CAP_PPC_RADIX_MMU
-Architectures: ppc
-Type: vm ioctl
-Parameters: struct kvm_ppc_rmmu_info (out)
-Returns: 0 on success,
+:Capability: KVM_CAP_PPC_RADIX_MMU
+:Architectures: ppc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_rmmu_info (out)
+:Returns: 0 on success,
-EFAULT if struct kvm_ppc_rmmu_info cannot be written,
-EINVAL if no useful information can be returned
@@ -3447,14 +3784,52 @@ containing supported radix tree geometries, and (b) a list that maps
page sizes to put in the "AP" (actual page size) field for the tlbie
(TLB invalidate entry) instruction.
-struct kvm_ppc_rmmu_info {
+::
+
+ struct kvm_ppc_rmmu_info {
+ struct kvm_ppc_radix_geom {
+ __u8 page_shift;
+ __u8 level_bits[4];
+ __u8 pad[3];
+ } geometries[8];
+ __u32 ap_encodings[8];
+ };
+
+The geometries[] field gives up to 8 supported geometries for the
+radix page table, in terms of the log base 2 of the smallest page
+size, and the number of bits indexed at each level of the tree, from
+the PTE level up to the PGD level in that order. Any unused entries
+will have 0 in the page_shift field.
+
+The ap_encodings gives the supported page sizes and their AP field
+encodings, encoded with the AP value in the top 3 bits and the log
+base 2 of the page size in the bottom 6 bits.
+
+4.102 KVM_PPC_RESIZE_HPT_PREPARE
+--------------------------------
+
+:Capability: KVM_CAP_SPAPR_RESIZE_HPT
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_resize_hpt (in)
+:Returns: 0 on successful completion,
+ >0 if a new HPT is being prepared, the value is an estimated
+ number of milliseconds until preparation is complete,
+ -EFAULT if struct kvm_reinject_control cannot be read,
+ -EINVAL if the supplied shift or flags are invalid,
+ -ENOMEM if unable to allocate the new HPT,
+ -ENOSPC if there was a hash collision
+
+::
+
+ struct kvm_ppc_rmmu_info {
struct kvm_ppc_radix_geom {
__u8 page_shift;
__u8 level_bits[4];
__u8 pad[3];
} geometries[8];
__u32 ap_encodings[8];
-};
+ };
The geometries[] field gives up to 8 supported geometries for the
radix page table, in terms of the log base 2 of the smallest page
@@ -3467,19 +3842,18 @@ encodings, encoded with the AP value in the top 3 bits and the log
base 2 of the page size in the bottom 6 bits.
4.102 KVM_PPC_RESIZE_HPT_PREPARE
+--------------------------------
-Capability: KVM_CAP_SPAPR_RESIZE_HPT
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_ppc_resize_hpt (in)
-Returns: 0 on successful completion,
+:Capability: KVM_CAP_SPAPR_RESIZE_HPT
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_resize_hpt (in)
+:Returns: 0 on successful completion,
>0 if a new HPT is being prepared, the value is an estimated
- number of milliseconds until preparation is complete
+ number of milliseconds until preparation is complete,
-EFAULT if struct kvm_reinject_control cannot be read,
- -EINVAL if the supplied shift or flags are invalid
- -ENOMEM if unable to allocate the new HPT
- -ENOSPC if there was a hash collision when moving existing
- HPT entries to the new HPT
+ -EINVAL if the supplied shift or flags are invalid,when moving existing
+ HPT entries to the new HPT,
-EIO on other error conditions
Used to implement the PAPR extension for runtime resizing of a guest's
@@ -3497,6 +3871,7 @@ requested in the parameters, discards the existing pending HPT and
creates a new one as above.
If called when there is a pending HPT of the size requested, will:
+
* If preparation of the pending HPT is already complete, return 0
* If preparation of the pending HPT has failed, return an error
code, then discard the pending HPT.
@@ -3513,26 +3888,29 @@ Normally this will be called repeatedly with the same parameters until
it returns <= 0. The first call will initiate preparation, subsequent
ones will monitor preparation until it completes or fails.
-struct kvm_ppc_resize_hpt {
+::
+
+ struct kvm_ppc_resize_hpt {
__u64 flags;
__u32 shift;
__u32 pad;
-};
+ };
4.103 KVM_PPC_RESIZE_HPT_COMMIT
+-------------------------------
-Capability: KVM_CAP_SPAPR_RESIZE_HPT
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_ppc_resize_hpt (in)
-Returns: 0 on successful completion,
+:Capability: KVM_CAP_SPAPR_RESIZE_HPT
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_resize_hpt (in)
+:Returns: 0 on successful completion,
-EFAULT if struct kvm_reinject_control cannot be read,
- -EINVAL if the supplied shift or flags are invalid
+ -EINVAL if the supplied shift or flags are invalid,
-ENXIO is there is no pending HPT, or the pending HPT doesn't
- have the requested size
- -EBUSY if the pending HPT is not fully prepared
+ have the requested size,
+ -EBUSY if the pending HPT is not fully prepared,
-ENOSPC if there was a hash collision when moving existing
- HPT entries to the new HPT
+ HPT entries to the new HPT,
-EIO on other error conditions
Used to implement the PAPR extension for runtime resizing of a guest's
@@ -3555,31 +3933,35 @@ HPT and the previous HPT will be discarded.
On failure, the guest will still be operating on its previous HPT.
-struct kvm_ppc_resize_hpt {
+::
+
+ struct kvm_ppc_resize_hpt {
__u64 flags;
__u32 shift;
__u32 pad;
-};
+ };
4.104 KVM_X86_GET_MCE_CAP_SUPPORTED
+-----------------------------------
-Capability: KVM_CAP_MCE
-Architectures: x86
-Type: system ioctl
-Parameters: u64 mce_cap (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_MCE
+:Architectures: x86
+:Type: system ioctl
+:Parameters: u64 mce_cap (out)
+:Returns: 0 on success, -1 on error
Returns supported MCE capabilities. The u64 mce_cap parameter
has the same format as the MSR_IA32_MCG_CAP register. Supported
capabilities will have the corresponding bits set.
4.105 KVM_X86_SETUP_MCE
+-----------------------
-Capability: KVM_CAP_MCE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: u64 mcg_cap (in)
-Returns: 0 on success,
+:Capability: KVM_CAP_MCE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: u64 mcg_cap (in)
+:Returns: 0 on success,
-EFAULT if u64 mcg_cap cannot be read,
-EINVAL if the requested number of banks is invalid,
-EINVAL if requested MCE capability is not supported.
@@ -3592,20 +3974,21 @@ checking for KVM_CAP_MCE. The supported capabilities can be
retrieved with KVM_X86_GET_MCE_CAP_SUPPORTED.
4.106 KVM_X86_SET_MCE
+---------------------
-Capability: KVM_CAP_MCE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_x86_mce (in)
-Returns: 0 on success,
+:Capability: KVM_CAP_MCE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_x86_mce (in)
+:Returns: 0 on success,
-EFAULT if struct kvm_x86_mce cannot be read,
-EINVAL if the bank number is invalid,
-EINVAL if VAL bit is not set in status field.
Inject a machine check error (MCE) into the guest. The input
-parameter is:
+parameter is::
-struct kvm_x86_mce {
+ struct kvm_x86_mce {
__u64 status;
__u64 addr;
__u64 misc;
@@ -3613,7 +3996,7 @@ struct kvm_x86_mce {
__u8 bank;
__u8 pad1[7];
__u64 pad2[3];
-};
+ };
If the MCE being reported is an uncorrected error, KVM will
inject it as an MCE exception into the guest. If the guest
@@ -3625,15 +4008,17 @@ store it in the corresponding bank (provided this bank is
not holding a previously reported uncorrected error).
4.107 KVM_S390_GET_CMMA_BITS
+----------------------------
-Capability: KVM_CAP_S390_CMMA_MIGRATION
-Architectures: s390
-Type: vm ioctl
-Parameters: struct kvm_s390_cmma_log (in, out)
-Returns: 0 on success, a negative value on error
+:Capability: KVM_CAP_S390_CMMA_MIGRATION
+:Architectures: s390
+:Type: vm ioctl
+:Parameters: struct kvm_s390_cmma_log (in, out)
+:Returns: 0 on success, a negative value on error
This ioctl is used to get the values of the CMMA bits on the s390
architecture. It is meant to be used in two scenarios:
+
- During live migration to save the CMMA values. Live migration needs
to be enabled via the KVM_REQ_START_MIGRATION VM property.
- To non-destructively peek at the CMMA values, with the flag
@@ -3643,9 +4028,12 @@ The ioctl takes parameters via the kvm_s390_cmma_log struct. The desired
values are written to a buffer whose location is indicated via the "values"
member in the kvm_s390_cmma_log struct. The values in the input struct are
also updated as needed.
+
Each CMMA value takes up one byte.
-struct kvm_s390_cmma_log {
+::
+
+ struct kvm_s390_cmma_log {
__u64 start_gfn;
__u32 count;
__u32 flags;
@@ -3654,7 +4042,7 @@ struct kvm_s390_cmma_log {
__u64 mask;
};
__u64 values;
-};
+ };
start_gfn is the number of the first guest frame whose CMMA values are
to be retrieved,
@@ -3715,12 +4103,13 @@ KVM_S390_CMMA_PEEK is not set but migration mode was not enabled, with
present for the addresses (e.g. when using hugepages).
4.108 KVM_S390_SET_CMMA_BITS
+----------------------------
-Capability: KVM_CAP_S390_CMMA_MIGRATION
-Architectures: s390
-Type: vm ioctl
-Parameters: struct kvm_s390_cmma_log (in)
-Returns: 0 on success, a negative value on error
+:Capability: KVM_CAP_S390_CMMA_MIGRATION
+:Architectures: s390
+:Type: vm ioctl
+:Parameters: struct kvm_s390_cmma_log (in)
+:Returns: 0 on success, a negative value on error
This ioctl is used to set the values of the CMMA bits on the s390
architecture. It is meant to be used during live migration to restore
@@ -3728,16 +4117,18 @@ the CMMA values, but there are no restrictions on its use.
The ioctl takes parameters via the kvm_s390_cmma_values struct.
Each CMMA value takes up one byte.
-struct kvm_s390_cmma_log {
+::
+
+ struct kvm_s390_cmma_log {
__u64 start_gfn;
__u32 count;
__u32 flags;
union {
__u64 remaining;
__u64 mask;
- };
+ };
__u64 values;
-};
+ };
start_gfn indicates the starting guest frame number,
@@ -3760,26 +4151,27 @@ or if no page table is present for the addresses (e.g. when using
hugepages).
4.109 KVM_PPC_GET_CPU_CHAR
+--------------------------
-Capability: KVM_CAP_PPC_GET_CPU_CHAR
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_ppc_cpu_char (out)
-Returns: 0 on successful completion
+:Capability: KVM_CAP_PPC_GET_CPU_CHAR
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_cpu_char (out)
+:Returns: 0 on successful completion,
-EFAULT if struct kvm_ppc_cpu_char cannot be written
This ioctl gives userspace information about certain characteristics
of the CPU relating to speculative execution of instructions and
possible information leakage resulting from speculative execution (see
CVE-2017-5715, CVE-2017-5753 and CVE-2017-5754). The information is
-returned in struct kvm_ppc_cpu_char, which looks like this:
+returned in struct kvm_ppc_cpu_char, which looks like this::
-struct kvm_ppc_cpu_char {
+ struct kvm_ppc_cpu_char {
__u64 character; /* characteristics of the CPU */
__u64 behaviour; /* recommended software behaviour */
__u64 character_mask; /* valid bits in character */
__u64 behaviour_mask; /* valid bits in behaviour */
-};
+ };
For extensibility, the character_mask and behaviour_mask fields
indicate which bits of character and behaviour have been filled in by
@@ -3806,12 +4198,13 @@ These fields use the same bit definitions as the new
H_GET_CPU_CHARACTERISTICS hypercall.
4.110 KVM_MEMORY_ENCRYPT_OP
+---------------------------
-Capability: basic
-Architectures: x86
-Type: system
-Parameters: an opaque platform specific structure (in/out)
-Returns: 0 on success; -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: system
+:Parameters: an opaque platform specific structure (in/out)
+:Returns: 0 on success; -1 on error
If the platform supports creating encrypted VMs then this ioctl can be used
for issuing platform-specific memory encryption commands to manage those
@@ -3822,12 +4215,13 @@ Currently, this ioctl is used for issuing Secure Encrypted Virtualization
Documentation/virt/kvm/amd-memory-encryption.rst.
4.111 KVM_MEMORY_ENCRYPT_REG_REGION
+-----------------------------------
-Capability: basic
-Architectures: x86
-Type: system
-Parameters: struct kvm_enc_region (in)
-Returns: 0 on success; -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: system
+:Parameters: struct kvm_enc_region (in)
+:Returns: 0 on success; -1 on error
This ioctl can be used to register a guest memory region which may
contain encrypted data (e.g. guest RAM, SMRAM etc).
@@ -3845,60 +4239,71 @@ swap or migrate (move) ciphertext pages. Hence, for now we pin the guest
memory region registered with the ioctl.
4.112 KVM_MEMORY_ENCRYPT_UNREG_REGION
+-------------------------------------
-Capability: basic
-Architectures: x86
-Type: system
-Parameters: struct kvm_enc_region (in)
-Returns: 0 on success; -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: system
+:Parameters: struct kvm_enc_region (in)
+:Returns: 0 on success; -1 on error
This ioctl can be used to unregister the guest memory region registered
with KVM_MEMORY_ENCRYPT_REG_REGION ioctl above.
4.113 KVM_HYPERV_EVENTFD
+------------------------
-Capability: KVM_CAP_HYPERV_EVENTFD
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_hyperv_eventfd (in)
+:Capability: KVM_CAP_HYPERV_EVENTFD
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_hyperv_eventfd (in)
This ioctl (un)registers an eventfd to receive notifications from the guest on
the specified Hyper-V connection id through the SIGNAL_EVENT hypercall, without
causing a user exit. SIGNAL_EVENT hypercall with non-zero event flag number
(bits 24-31) still triggers a KVM_EXIT_HYPERV_HCALL user exit.
-struct kvm_hyperv_eventfd {
+::
+
+ struct kvm_hyperv_eventfd {
__u32 conn_id;
__s32 fd;
__u32 flags;
__u32 padding[3];
-};
+ };
-The conn_id field should fit within 24 bits:
+The conn_id field should fit within 24 bits::
-#define KVM_HYPERV_CONN_ID_MASK 0x00ffffff
+ #define KVM_HYPERV_CONN_ID_MASK 0x00ffffff
-The acceptable values for the flags field are:
+The acceptable values for the flags field are::
-#define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0)
+ #define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0)
-Returns: 0 on success,
- -EINVAL if conn_id or flags is outside the allowed range
- -ENOENT on deassign if the conn_id isn't registered
- -EEXIST on assign if the conn_id is already registered
+:Returns: 0 on success,
+ -EINVAL if conn_id or flags is outside the allowed range,
+ -ENOENT on deassign if the conn_id isn't registered,
+ -EEXIST on assign if the conn_id is already registered
4.114 KVM_GET_NESTED_STATE
+--------------------------
+
+:Capability: KVM_CAP_NESTED_STATE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_nested_state (in/out)
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_NESTED_STATE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_nested_state (in/out)
-Returns: 0 on success, -1 on error
Errors:
- E2BIG: the total state size exceeds the value of 'size' specified by
+
+ ===== =============================================================
+ E2BIG the total state size exceeds the value of 'size' specified by
the user; the size required will be written into size.
+ ===== =============================================================
-struct kvm_nested_state {
+::
+
+ struct kvm_nested_state {
__u16 flags;
__u16 format;
__u32 size;
@@ -3915,33 +4320,33 @@ struct kvm_nested_state {
struct kvm_vmx_nested_state_data vmx[0];
struct kvm_svm_nested_state_data svm[0];
} data;
-};
+ };
-#define KVM_STATE_NESTED_GUEST_MODE 0x00000001
-#define KVM_STATE_NESTED_RUN_PENDING 0x00000002
-#define KVM_STATE_NESTED_EVMCS 0x00000004
+ #define KVM_STATE_NESTED_GUEST_MODE 0x00000001
+ #define KVM_STATE_NESTED_RUN_PENDING 0x00000002
+ #define KVM_STATE_NESTED_EVMCS 0x00000004
-#define KVM_STATE_NESTED_FORMAT_VMX 0
-#define KVM_STATE_NESTED_FORMAT_SVM 1
+ #define KVM_STATE_NESTED_FORMAT_VMX 0
+ #define KVM_STATE_NESTED_FORMAT_SVM 1
-#define KVM_STATE_NESTED_VMX_VMCS_SIZE 0x1000
+ #define KVM_STATE_NESTED_VMX_VMCS_SIZE 0x1000
-#define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE 0x00000001
-#define KVM_STATE_NESTED_VMX_SMM_VMXON 0x00000002
+ #define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE 0x00000001
+ #define KVM_STATE_NESTED_VMX_SMM_VMXON 0x00000002
-struct kvm_vmx_nested_state_hdr {
+ struct kvm_vmx_nested_state_hdr {
__u64 vmxon_pa;
__u64 vmcs12_pa;
struct {
__u16 flags;
} smm;
-};
+ };
-struct kvm_vmx_nested_state_data {
+ struct kvm_vmx_nested_state_data {
__u8 vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];
__u8 shadow_vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];
-};
+ };
This ioctl copies the vcpu's nested virtualization state from the kernel to
userspace.
@@ -3950,24 +4355,26 @@ The maximum size of the state can be retrieved by passing KVM_CAP_NESTED_STATE
to the KVM_CHECK_EXTENSION ioctl().
4.115 KVM_SET_NESTED_STATE
+--------------------------
-Capability: KVM_CAP_NESTED_STATE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_nested_state (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_NESTED_STATE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_nested_state (in)
+:Returns: 0 on success, -1 on error
This copies the vcpu's kvm_nested_state struct from userspace to the kernel.
For the definition of struct kvm_nested_state, see KVM_GET_NESTED_STATE.
4.116 KVM_(UN)REGISTER_COALESCED_MMIO
+-------------------------------------
-Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio)
- KVM_CAP_COALESCED_PIO (for coalesced pio)
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_coalesced_mmio_zone
-Returns: 0 on success, < 0 on error
+:Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio)
+ KVM_CAP_COALESCED_PIO (for coalesced pio)
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_coalesced_mmio_zone
+:Returns: 0 on success, < 0 on error
Coalesced I/O is a performance optimization that defers hardware
register write emulation so that userspace exits are avoided. It is
@@ -3989,15 +4396,18 @@ between coalesced mmio and pio except that coalesced pio records accesses
to I/O ports.
4.117 KVM_CLEAR_DIRTY_LOG (vm ioctl)
+------------------------------------
-Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
-Architectures: x86, arm, arm64, mips
-Type: vm ioctl
-Parameters: struct kvm_dirty_log (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
+:Architectures: x86, arm, arm64, mips
+:Type: vm ioctl
+:Parameters: struct kvm_dirty_log (in)
+:Returns: 0 on success, -1 on error
-/* for KVM_CLEAR_DIRTY_LOG */
-struct kvm_clear_dirty_log {
+::
+
+ /* for KVM_CLEAR_DIRTY_LOG */
+ struct kvm_clear_dirty_log {
__u32 slot;
__u32 num_pages;
__u64 first_page;
@@ -4005,7 +4415,7 @@ struct kvm_clear_dirty_log {
void __user *dirty_bitmap; /* one bit per page */
__u64 padding;
};
-};
+ };
The ioctl clears the dirty status of pages in a memory slot, according to
the bitmap that is passed in struct kvm_clear_dirty_log's dirty_bitmap
@@ -4029,20 +4439,23 @@ However, it can always be used as long as KVM_CHECK_EXTENSION confirms
that KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is present.
4.118 KVM_GET_SUPPORTED_HV_CPUID
+--------------------------------
-Capability: KVM_CAP_HYPERV_CPUID
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_cpuid2 (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_HYPERV_CPUID
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_cpuid2 (in/out)
+:Returns: 0 on success, -1 on error
-struct kvm_cpuid2 {
+::
+
+ struct kvm_cpuid2 {
__u32 nent;
__u32 padding;
struct kvm_cpuid_entry2 entries[0];
-};
+ };
-struct kvm_cpuid_entry2 {
+ struct kvm_cpuid_entry2 {
__u32 function;
__u32 index;
__u32 flags;
@@ -4051,7 +4464,7 @@ struct kvm_cpuid_entry2 {
__u32 ecx;
__u32 edx;
__u32 padding[3];
-};
+ };
This ioctl returns x86 cpuid features leaves related to Hyper-V emulation in
KVM. Userspace can use the information returned by this ioctl to construct
@@ -4064,13 +4477,13 @@ KVM_GET_SUPPORTED_CPUID ioctl because some of them intersect with KVM feature
leaves (0x40000000, 0x40000001).
Currently, the following list of CPUID leaves are returned:
- HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS
- HYPERV_CPUID_INTERFACE
- HYPERV_CPUID_VERSION
- HYPERV_CPUID_FEATURES
- HYPERV_CPUID_ENLIGHTMENT_INFO
- HYPERV_CPUID_IMPLEMENT_LIMITS
- HYPERV_CPUID_NESTED_FEATURES
+ - HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS
+ - HYPERV_CPUID_INTERFACE
+ - HYPERV_CPUID_VERSION
+ - HYPERV_CPUID_FEATURES
+ - HYPERV_CPUID_ENLIGHTMENT_INFO
+ - HYPERV_CPUID_IMPLEMENT_LIMITS
+ - HYPERV_CPUID_NESTED_FEATURES
HYPERV_CPUID_NESTED_FEATURES leaf is only exposed when Enlightened VMCS was
enabled on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS).
@@ -4086,17 +4499,25 @@ number of valid entries in the 'entries' array, which is then filled.
userspace should not expect to get any particular value there.
4.119 KVM_ARM_VCPU_FINALIZE
+---------------------------
+
+:Architectures: arm, arm64
+:Type: vcpu ioctl
+:Parameters: int feature (in)
+:Returns: 0 on success, -1 on error
-Architectures: arm, arm64
-Type: vcpu ioctl
-Parameters: int feature (in)
-Returns: 0 on success, -1 on error
Errors:
- EPERM: feature not enabled, needs configuration, or already finalized
- EINVAL: feature unknown or not present
+
+ ====== ==============================================================
+ EPERM feature not enabled, needs configuration, or already finalized
+ EINVAL feature unknown or not present
+ ====== ==============================================================
Recognised values for feature:
+
+ ===== ===========================================
arm64 KVM_ARM_VCPU_SVE (requires KVM_CAP_ARM_SVE)
+ ===== ===========================================
Finalizes the configuration of the specified vcpu feature.
@@ -4120,21 +4541,24 @@ See KVM_ARM_VCPU_INIT for details of vcpu features that require finalization
using this ioctl.
4.120 KVM_SET_PMU_EVENT_FILTER
+------------------------------
-Capability: KVM_CAP_PMU_EVENT_FILTER
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_pmu_event_filter (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PMU_EVENT_FILTER
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_pmu_event_filter (in)
+:Returns: 0 on success, -1 on error
-struct kvm_pmu_event_filter {
+::
+
+ struct kvm_pmu_event_filter {
__u32 action;
__u32 nevents;
__u32 fixed_counter_bitmap;
__u32 flags;
__u32 pad[4];
__u64 events[0];
-};
+ };
This ioctl restricts the set of PMU events that the guest can program.
The argument holds a list of events which will be allowed or denied.
@@ -4145,20 +4569,26 @@ counters are controlled by the fixed_counter_bitmap.
No flags are defined yet, the field must be zero.
-Valid values for 'action':
-#define KVM_PMU_EVENT_ALLOW 0
-#define KVM_PMU_EVENT_DENY 1
+Valid values for 'action'::
+
+ #define KVM_PMU_EVENT_ALLOW 0
+ #define KVM_PMU_EVENT_DENY 1
4.121 KVM_PPC_SVM_OFF
+---------------------
+
+:Capability: basic
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: none
+:Returns: 0 on successful completion,
-Capability: basic
-Architectures: powerpc
-Type: vm ioctl
-Parameters: none
-Returns: 0 on successful completion,
Errors:
- EINVAL: if ultravisor failed to terminate the secure guest
- ENOMEM: if hypervisor failed to allocate new radix page tables for guest
+
+ ====== ================================================================
+ EINVAL if ultravisor failed to terminate the secure guest
+ ENOMEM if hypervisor failed to allocate new radix page tables for guest
+ ====== ================================================================
This ioctl is used to turn off the secure mode of the guest or transition
the guest from secure mode to normal mode. This is invoked when the guest
@@ -4169,7 +4599,7 @@ unpins the VPA pages and releases all the device pages that are used to
track the secure pages by hypervisor.
5. The kvm_run structure
-------------------------
+========================
Application code obtains a pointer to the kvm_run structure by
mmap()ing a vcpu fd. From that point, application code can control
@@ -4177,13 +4607,17 @@ execution by changing fields in kvm_run prior to calling the KVM_RUN
ioctl, and obtain information about the reason KVM_RUN returned by
looking up structure members.
-struct kvm_run {
+::
+
+ struct kvm_run {
/* in */
__u8 request_interrupt_window;
Request that KVM_RUN return when it becomes possible to inject external
interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
+::
+
__u8 immediate_exit;
This field is polled once when KVM_RUN starts; if non-zero, KVM_RUN
@@ -4195,6 +4629,8 @@ a signal handler that sets run->immediate_exit to a non-zero value.
This field is ignored if KVM_CAP_IMMEDIATE_EXIT is not available.
+::
+
__u8 padding1[6];
/* out */
@@ -4204,16 +4640,22 @@ When KVM_RUN has returned successfully (return value 0), this informs
application code why KVM_RUN has returned. Allowable values for this
field are detailed below.
+::
+
__u8 ready_for_interrupt_injection;
If request_interrupt_window has been specified, this field indicates
an interrupt can be injected now with KVM_INTERRUPT.
+::
+
__u8 if_flag;
The value of the current interrupt flag. Only valid if in-kernel
local APIC is not used.
+::
+
__u16 flags;
More architecture-specific flags detailing state of the VCPU that may
@@ -4221,17 +4663,23 @@ affect the device's behavior. The only currently defined flag is
KVM_RUN_X86_SMM, which is valid on x86 machines and is set if the
VCPU is in system management mode.
+::
+
/* in (pre_kvm_run), out (post_kvm_run) */
__u64 cr8;
The value of the cr8 register. Only valid if in-kernel local APIC is
not used. Both input and output.
+::
+
__u64 apic_base;
The value of the APIC BASE msr. Only valid if in-kernel local
APIC is not used. Both input and output.
+::
+
union {
/* KVM_EXIT_UNKNOWN */
struct {
@@ -4242,6 +4690,8 @@ If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
reasons. Further architecture-specific information is available in
hardware_exit_reason.
+::
+
/* KVM_EXIT_FAIL_ENTRY */
struct {
__u64 hardware_entry_failure_reason;
@@ -4251,6 +4701,8 @@ If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
to unknown reasons. Further architecture-specific information is
available in hardware_entry_failure_reason.
+::
+
/* KVM_EXIT_EXCEPTION */
struct {
__u32 exception;
@@ -4259,10 +4711,12 @@ available in hardware_entry_failure_reason.
Unused.
+::
+
/* KVM_EXIT_IO */
struct {
-#define KVM_EXIT_IO_IN 0
-#define KVM_EXIT_IO_OUT 1
+ #define KVM_EXIT_IO_IN 0
+ #define KVM_EXIT_IO_OUT 1
__u8 direction;
__u8 size; /* bytes */
__u16 port;
@@ -4276,6 +4730,8 @@ data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
where kvm expects application code to place the data for the next
KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
+::
+
/* KVM_EXIT_DEBUG */
struct {
struct kvm_debug_exit_arch arch;
@@ -4284,6 +4740,8 @@ KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
If the exit_reason is KVM_EXIT_DEBUG, then a vcpu is processing a debug event
for which architecture specific information is returned.
+::
+
/* KVM_EXIT_MMIO */
struct {
__u64 phys_addr;
@@ -4301,14 +4759,19 @@ The 'data' member contains, in its first 'len' bytes, the value as it would
appear if the VCPU performed a load or store of the appropriate width directly
to the byte array.
-NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR and
+.. note::
+
+ For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR and
KVM_EXIT_EPR the corresponding
+
operations are complete (and guest state is consistent) only after userspace
has re-entered the kernel with KVM_RUN. The kernel side will first finish
incomplete operations and then check for pending signals. Userspace
can re-enter the guest with an unmasked signal pending to complete
pending operations.
+::
+
/* KVM_EXIT_HYPERCALL */
struct {
__u64 nr;
@@ -4320,7 +4783,10 @@ pending operations.
Unused. This was once used for 'hypercall to userspace'. To implement
such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
-Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
+
+.. note:: KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
+
+::
/* KVM_EXIT_TPR_ACCESS */
struct {
@@ -4331,6 +4797,8 @@ Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
To be documented (KVM_TPR_ACCESS_REPORTING).
+::
+
/* KVM_EXIT_S390_SIEIC */
struct {
__u8 icptcode;
@@ -4342,16 +4810,20 @@ To be documented (KVM_TPR_ACCESS_REPORTING).
s390 specific.
+::
+
/* KVM_EXIT_S390_RESET */
-#define KVM_S390_RESET_POR 1
-#define KVM_S390_RESET_CLEAR 2
-#define KVM_S390_RESET_SUBSYSTEM 4
-#define KVM_S390_RESET_CPU_INIT 8
-#define KVM_S390_RESET_IPL 16
+ #define KVM_S390_RESET_POR 1
+ #define KVM_S390_RESET_CLEAR 2
+ #define KVM_S390_RESET_SUBSYSTEM 4
+ #define KVM_S390_RESET_CPU_INIT 8
+ #define KVM_S390_RESET_IPL 16
__u64 s390_reset_flags;
s390 specific.
+::
+
/* KVM_EXIT_S390_UCONTROL */
struct {
__u64 trans_exc_code;
@@ -4366,6 +4838,8 @@ in the cpu's lowcore are presented here as defined by the z Architecture
Principles of Operation Book in the Chapter for Dynamic Address Translation
(DAT)
+::
+
/* KVM_EXIT_DCR */
struct {
__u32 dcrn;
@@ -4375,6 +4849,8 @@ Principles of Operation Book in the Chapter for Dynamic Address Translation
Deprecated - was used for 440 KVM.
+::
+
/* KVM_EXIT_OSI */
struct {
__u64 gprs[32];
@@ -4388,6 +4864,8 @@ Userspace can now handle the hypercall and when it's done modify the gprs as
necessary. Upon guest entry all guest GPRs will then be replaced by the values
in this struct.
+::
+
/* KVM_EXIT_PAPR_HCALL */
struct {
__u64 nr;
@@ -4405,6 +4883,8 @@ The possible hypercalls are defined in the Power Architecture Platform
Requirements (PAPR) document available from www.power.org (free
developer registration required to access it).
+::
+
/* KVM_EXIT_S390_TSCH */
struct {
__u16 subchannel_id;
@@ -4421,6 +4901,8 @@ interrupt for the target subchannel has been dequeued and subchannel_id,
subchannel_nr, io_int_parm and io_int_word contain the parameters for that
interrupt. ipb is needed for instruction parameter decoding.
+::
+
/* KVM_EXIT_EPR */
struct {
__u32 epr;
@@ -4440,11 +4922,13 @@ It gets triggered whenever both KVM_CAP_PPC_EPR are enabled and an
external interrupt has just been delivered into the guest. User space
should put the acknowledged interrupt vector into the 'epr' field.
+::
+
/* KVM_EXIT_SYSTEM_EVENT */
struct {
-#define KVM_SYSTEM_EVENT_SHUTDOWN 1
-#define KVM_SYSTEM_EVENT_RESET 2
-#define KVM_SYSTEM_EVENT_CRASH 3
+ #define KVM_SYSTEM_EVENT_SHUTDOWN 1
+ #define KVM_SYSTEM_EVENT_RESET 2
+ #define KVM_SYSTEM_EVENT_CRASH 3
__u32 type;
__u64 flags;
} system_event;
@@ -4457,18 +4941,21 @@ the system-level event type. The 'flags' field describes architecture
specific flags for the system-level event.
Valid values for 'type' are:
- KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the
+
+ - KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the
VM. Userspace is not obliged to honour this, and if it does honour
this does not need to destroy the VM synchronously (ie it may call
KVM_RUN again before shutdown finally occurs).
- KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM.
+ - KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM.
As with SHUTDOWN, userspace can choose to ignore the request, or
to schedule the reset to occur in the future and may call KVM_RUN again.
- KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest
+ - KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest
has requested a crash condition maintenance. Userspace can choose
to ignore the request, or to gather VM memory core dump and/or
reset/shutdown of the VM.
+::
+
/* KVM_EXIT_IOAPIC_EOI */
struct {
__u8 vector;
@@ -4481,9 +4968,11 @@ the userspace IOAPIC should process the EOI and retrigger the interrupt if
it is still asserted. Vector is the LAPIC interrupt vector for which the
EOI was received.
+::
+
struct kvm_hyperv_exit {
-#define KVM_EXIT_HYPERV_SYNIC 1
-#define KVM_EXIT_HYPERV_HCALL 2
+ #define KVM_EXIT_HYPERV_SYNIC 1
+ #define KVM_EXIT_HYPERV_HCALL 2
__u32 type;
union {
struct {
@@ -4501,14 +4990,20 @@ EOI was received.
};
/* KVM_EXIT_HYPERV */
struct kvm_hyperv_exit hyperv;
+
Indicates that the VCPU exits into userspace to process some tasks
related to Hyper-V emulation.
+
Valid values for 'type' are:
- KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about
+
+ - KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about
+
Hyper-V SynIC state change. Notification is used to remap SynIC
event/message pages and to enable/disable SynIC messages/events processing
in userspace.
+::
+
/* KVM_EXIT_ARM_NISV */
struct {
__u64 esr_iss;
@@ -4542,6 +5037,8 @@ Note that KVM does not skip the faulting instruction as it does for
KVM_EXIT_MMIO, but userspace has to emulate any change to the processing state
if it decides to decode and emulate the instruction.
+::
+
/* Fix the size of the union. */
char padding[256];
};
@@ -4566,18 +5063,20 @@ avoid some system call overhead if userspace has to handle the exit.
Userspace can query the validity of the structure by checking
kvm_valid_regs for specific bits. These bits are architecture specific
and usually define the validity of a groups of registers. (e.g. one bit
- for general purpose registers)
+for general purpose registers)
Please note that the kernel is allowed to use the kvm_run structure as the
primary storage for certain register types. Therefore, the kernel may use the
values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set.
-};
+::
+
+ };
6. Capabilities that can be enabled on vCPUs
---------------------------------------------
+============================================
There are certain capabilities that change the behavior of the virtual CPU or
the virtual machine when enabled. To enable them, please see section 4.37.
@@ -4586,23 +5085,28 @@ the virtual machine is when enabling them.
The following information is provided along with the description:
- Architectures: which instruction set architectures provide this ioctl.
+ Architectures:
+ which instruction set architectures provide this ioctl.
x86 includes both i386 and x86_64.
- Target: whether this is a per-vcpu or per-vm capability.
+ Target:
+ whether this is a per-vcpu or per-vm capability.
- Parameters: what parameters are accepted by the capability.
+ Parameters:
+ what parameters are accepted by the capability.
- Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
+ Returns:
+ the return value. General error numbers (EBADF, ENOMEM, EINVAL)
are not detailed, but errors with specific meanings are.
6.1 KVM_CAP_PPC_OSI
+-------------------
-Architectures: ppc
-Target: vcpu
-Parameters: none
-Returns: 0 on success; -1 on error
+:Architectures: ppc
+:Target: vcpu
+:Parameters: none
+:Returns: 0 on success; -1 on error
This capability enables interception of OSI hypercalls that otherwise would
be treated as normal system calls to be injected into the guest. OSI hypercalls
@@ -4613,11 +5117,12 @@ When this capability is enabled, KVM_EXIT_OSI can occur.
6.2 KVM_CAP_PPC_PAPR
+--------------------
-Architectures: ppc
-Target: vcpu
-Parameters: none
-Returns: 0 on success; -1 on error
+:Architectures: ppc
+:Target: vcpu
+:Parameters: none
+:Returns: 0 on success; -1 on error
This capability enables interception of PAPR hypercalls. PAPR hypercalls are
done using the hypercall instruction "sc 1".
@@ -4633,18 +5138,21 @@ When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.
6.3 KVM_CAP_SW_TLB
+------------------
-Architectures: ppc
-Target: vcpu
-Parameters: args[0] is the address of a struct kvm_config_tlb
-Returns: 0 on success; -1 on error
+:Architectures: ppc
+:Target: vcpu
+:Parameters: args[0] is the address of a struct kvm_config_tlb
+:Returns: 0 on success; -1 on error
-struct kvm_config_tlb {
+::
+
+ struct kvm_config_tlb {
__u64 params;
__u64 array;
__u32 mmu_type;
__u32 array_len;
-};
+ };
Configures the virtual CPU's TLB array, establishing a shared memory area
between userspace and KVM. The "params" and "array" fields are userspace
@@ -4663,6 +5171,7 @@ to tell KVM which entries have been changed, prior to calling KVM_RUN again
on this vcpu.
For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:
+
- The "params" field is of type "struct kvm_book3e_206_tlb_params".
- The "array" field points to an array of type "struct
kvm_book3e_206_tlb_entry".
@@ -4676,11 +5185,12 @@ For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:
hardware ignores this value for TLB0.
6.4 KVM_CAP_S390_CSS_SUPPORT
+----------------------------
-Architectures: s390
-Target: vcpu
-Parameters: none
-Returns: 0 on success; -1 on error
+:Architectures: s390
+:Target: vcpu
+:Parameters: none
+:Returns: 0 on success; -1 on error
This capability enables support for handling of channel I/O instructions.
@@ -4694,11 +5204,12 @@ Note that even though this capability is enabled per-vcpu, the complete
virtual machine is affected.
6.5 KVM_CAP_PPC_EPR
+-------------------
-Architectures: ppc
-Target: vcpu
-Parameters: args[0] defines whether the proxy facility is active
-Returns: 0 on success; -1 on error
+:Architectures: ppc
+:Target: vcpu
+:Parameters: args[0] defines whether the proxy facility is active
+:Returns: 0 on success; -1 on error
This capability enables or disables the delivery of interrupts through the
external proxy facility.
@@ -4712,62 +5223,70 @@ When disabled (args[0] == 0), behavior is as if this facility is unsupported.
When this capability is enabled, KVM_EXIT_EPR can occur.
6.6 KVM_CAP_IRQ_MPIC
+--------------------
-Architectures: ppc
-Parameters: args[0] is the MPIC device fd
- args[1] is the MPIC CPU number for this vcpu
+:Architectures: ppc
+:Parameters: args[0] is the MPIC device fd;
+ args[1] is the MPIC CPU number for this vcpu
This capability connects the vcpu to an in-kernel MPIC device.
6.7 KVM_CAP_IRQ_XICS
+--------------------
-Architectures: ppc
-Target: vcpu
-Parameters: args[0] is the XICS device fd
- args[1] is the XICS CPU number (server ID) for this vcpu
+:Architectures: ppc
+:Target: vcpu
+:Parameters: args[0] is the XICS device fd;
+ args[1] is the XICS CPU number (server ID) for this vcpu
This capability connects the vcpu to an in-kernel XICS device.
6.8 KVM_CAP_S390_IRQCHIP
+------------------------
-Architectures: s390
-Target: vm
-Parameters: none
+:Architectures: s390
+:Target: vm
+:Parameters: none
This capability enables the in-kernel irqchip for s390. Please refer to
"4.24 KVM_CREATE_IRQCHIP" for details.
6.9 KVM_CAP_MIPS_FPU
+--------------------
-Architectures: mips
-Target: vcpu
-Parameters: args[0] is reserved for future use (should be 0).
+:Architectures: mips
+:Target: vcpu
+:Parameters: args[0] is reserved for future use (should be 0).
This capability allows the use of the host Floating Point Unit by the guest. It
allows the Config1.FP bit to be set to enable the FPU in the guest. Once this is
-done the KVM_REG_MIPS_FPR_* and KVM_REG_MIPS_FCR_* registers can be accessed
-(depending on the current guest FPU register mode), and the Status.FR,
+done the ``KVM_REG_MIPS_FPR_*`` and ``KVM_REG_MIPS_FCR_*`` registers can be
+accessed (depending on the current guest FPU register mode), and the Status.FR,
Config5.FRE bits are accessible via the KVM API and also from the guest,
depending on them being supported by the FPU.
6.10 KVM_CAP_MIPS_MSA
+---------------------
-Architectures: mips
-Target: vcpu
-Parameters: args[0] is reserved for future use (should be 0).
+:Architectures: mips
+:Target: vcpu
+:Parameters: args[0] is reserved for future use (should be 0).
This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest.
It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest.
-Once this is done the KVM_REG_MIPS_VEC_* and KVM_REG_MIPS_MSA_* registers can be
-accessed, and the Config5.MSAEn bit is accessible via the KVM API and also from
-the guest.
+Once this is done the ``KVM_REG_MIPS_VEC_*`` and ``KVM_REG_MIPS_MSA_*``
+registers can be accessed, and the Config5.MSAEn bit is accessible via the
+KVM API and also from the guest.
6.74 KVM_CAP_SYNC_REGS
-Architectures: s390, x86
-Target: s390: always enabled, x86: vcpu
-Parameters: none
-Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register
-sets are supported (bitfields defined in arch/x86/include/uapi/asm/kvm.h).
+----------------------
+
+:Architectures: s390, x86
+:Target: s390: always enabled, x86: vcpu
+:Parameters: none
+:Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register
+ sets are supported
+ (bitfields defined in arch/x86/include/uapi/asm/kvm.h).
As described above in the kvm_sync_regs struct info in section 5 (kvm_run):
KVM_CAP_SYNC_REGS "allow[s] userspace to access certain guest registers
@@ -4780,6 +5299,7 @@ userspace.
For s390 specifics, please refer to the source code.
For x86:
+
- the register sets to be copied out to kvm_run are selectable
by userspace (rather that all sets being copied out for every exit).
- vcpu_events are available in addition to regs and sregs.
@@ -4796,23 +5316,26 @@ into the vCPU even if they've been modified.
Unused bitfields in the bitarrays must be set to zero.
-struct kvm_sync_regs {
+::
+
+ struct kvm_sync_regs {
struct kvm_regs regs;
struct kvm_sregs sregs;
struct kvm_vcpu_events events;
-};
+ };
6.75 KVM_CAP_PPC_IRQ_XIVE
+-------------------------
-Architectures: ppc
-Target: vcpu
-Parameters: args[0] is the XIVE device fd
- args[1] is the XIVE CPU number (server ID) for this vcpu
+:Architectures: ppc
+:Target: vcpu
+:Parameters: args[0] is the XIVE device fd;
+ args[1] is the XIVE CPU number (server ID) for this vcpu
This capability connects the vcpu to an in-kernel XIVE device.
7. Capabilities that can be enabled on VMs
-------------------------------------------
+==========================================
There are certain capabilities that change the behavior of the virtual
machine when enabled. To enable them, please see section 4.37. Below
@@ -4821,20 +5344,24 @@ is when enabling them.
The following information is provided along with the description:
- Architectures: which instruction set architectures provide this ioctl.
+ Architectures:
+ which instruction set architectures provide this ioctl.
x86 includes both i386 and x86_64.
- Parameters: what parameters are accepted by the capability.
+ Parameters:
+ what parameters are accepted by the capability.
- Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
+ Returns:
+ the return value. General error numbers (EBADF, ENOMEM, EINVAL)
are not detailed, but errors with specific meanings are.
7.1 KVM_CAP_PPC_ENABLE_HCALL
+----------------------------
-Architectures: ppc
-Parameters: args[0] is the sPAPR hcall number
- args[1] is 0 to disable, 1 to enable in-kernel handling
+:Architectures: ppc
+:Parameters: args[0] is the sPAPR hcall number;
+ args[1] is 0 to disable, 1 to enable in-kernel handling
This capability controls whether individual sPAPR hypercalls (hcalls)
get handled by the kernel or not. Enabling or disabling in-kernel
@@ -4852,13 +5379,15 @@ implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL
error.
7.2 KVM_CAP_S390_USER_SIGP
+--------------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
This capability controls which SIGP orders will be handled completely in user
space. With this capability enabled, all fast orders will be handled completely
in the kernel:
+
- SENSE
- SENSE RUNNING
- EXTERNAL CALL
@@ -4872,48 +5401,52 @@ in the hardware prior to interception). If this capability is not enabled, the
old way of handling SIGP orders is used (partially in kernel and user space).
7.3 KVM_CAP_S390_VECTOR_REGISTERS
+---------------------------------
-Architectures: s390
-Parameters: none
-Returns: 0 on success, negative value on error
+:Architectures: s390
+:Parameters: none
+:Returns: 0 on success, negative value on error
Allows use of the vector registers introduced with z13 processor, and
provides for the synchronization between host and user space. Will
return -EINVAL if the machine does not support vectors.
7.4 KVM_CAP_S390_USER_STSI
+--------------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
This capability allows post-handlers for the STSI instruction. After
initial handling in the kernel, KVM exits to user space with
KVM_EXIT_S390_STSI to allow user space to insert further data.
Before exiting to userspace, kvm handlers should fill in s390_stsi field of
-vcpu->run:
-struct {
+vcpu->run::
+
+ struct {
__u64 addr;
__u8 ar;
__u8 reserved;
__u8 fc;
__u8 sel1;
__u16 sel2;
-} s390_stsi;
+ } s390_stsi;
-@addr - guest address of STSI SYSIB
-@fc - function code
-@sel1 - selector 1
-@sel2 - selector 2
-@ar - access register number
+ @addr - guest address of STSI SYSIB
+ @fc - function code
+ @sel1 - selector 1
+ @sel2 - selector 2
+ @ar - access register number
KVM handlers should exit to userspace with rc = -EREMOTE.
7.5 KVM_CAP_SPLIT_IRQCHIP
+-------------------------
-Architectures: x86
-Parameters: args[0] - number of routes reserved for userspace IOAPICs
-Returns: 0 on success, -1 on error
+:Architectures: x86
+:Parameters: args[0] - number of routes reserved for userspace IOAPICs
+:Returns: 0 on success, -1 on error
Create a local apic for each processor in the kernel. This can be used
instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the
@@ -4930,24 +5463,26 @@ Fails if VCPU has already been created, or if the irqchip is already in the
kernel (i.e. KVM_CREATE_IRQCHIP has already been called).
7.6 KVM_CAP_S390_RI
+-------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
Allows use of runtime-instrumentation introduced with zEC12 processor.
Will return -EINVAL if the machine does not support runtime-instrumentation.
Will return -EBUSY if a VCPU has already been created.
7.7 KVM_CAP_X2APIC_API
+----------------------
-Architectures: x86
-Parameters: args[0] - features that should be enabled
-Returns: 0 on success, -EINVAL when args[0] contains invalid features
+:Architectures: x86
+:Parameters: args[0] - features that should be enabled
+:Returns: 0 on success, -EINVAL when args[0] contains invalid features
-Valid feature flags in args[0] are
+Valid feature flags in args[0] are::
-#define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0)
-#define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1)
+ #define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0)
+ #define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1)
Enabling KVM_X2APIC_API_USE_32BIT_IDS changes the behavior of
KVM_SET_GSI_ROUTING, KVM_SIGNAL_MSI, KVM_SET_LAPIC, and KVM_GET_LAPIC,
@@ -4961,9 +5496,10 @@ without interrupt remapping. This is undesirable in logical mode,
where 0xff represents CPUs 0-7 in cluster 0.
7.8 KVM_CAP_S390_USER_INSTR0
+----------------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
With this capability enabled, all illegal instructions 0x0000 (2 bytes) will
be intercepted and forwarded to user space. User space can use this
@@ -4975,26 +5511,29 @@ This capability can be enabled dynamically even if VCPUs were already
created and are running.
7.9 KVM_CAP_S390_GS
+-------------------
-Architectures: s390
-Parameters: none
-Returns: 0 on success; -EINVAL if the machine does not support
- guarded storage; -EBUSY if a VCPU has already been created.
+:Architectures: s390
+:Parameters: none
+:Returns: 0 on success; -EINVAL if the machine does not support
+ guarded storage; -EBUSY if a VCPU has already been created.
Allows use of guarded storage for the KVM guest.
7.10 KVM_CAP_S390_AIS
+---------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
Allow use of adapter-interruption suppression.
-Returns: 0 on success; -EBUSY if a VCPU has already been created.
+:Returns: 0 on success; -EBUSY if a VCPU has already been created.
7.11 KVM_CAP_PPC_SMT
+--------------------
-Architectures: ppc
-Parameters: vsmt_mode, flags
+:Architectures: ppc
+:Parameters: vsmt_mode, flags
Enabling this capability on a VM provides userspace with a way to set
the desired virtual SMT mode (i.e. the number of virtual CPUs per
@@ -5009,9 +5548,10 @@ The KVM_CAP_PPC_SMT_POSSIBLE capability indicates which virtual SMT
modes are available.
7.12 KVM_CAP_PPC_FWNMI
+----------------------
-Architectures: ppc
-Parameters: none
+:Architectures: ppc
+:Parameters: none
With this capability a machine check exception in the guest address
space will cause KVM to exit the guest with NMI exit reason. This
@@ -5020,17 +5560,18 @@ machine check handling routine. Without this capability KVM will
branch to guests' 0x200 interrupt vector.
7.13 KVM_CAP_X86_DISABLE_EXITS
+------------------------------
-Architectures: x86
-Parameters: args[0] defines which exits are disabled
-Returns: 0 on success, -EINVAL when args[0] contains invalid exits
+:Architectures: x86
+:Parameters: args[0] defines which exits are disabled
+:Returns: 0 on success, -EINVAL when args[0] contains invalid exits
-Valid bits in args[0] are
+Valid bits in args[0] are::
-#define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0)
-#define KVM_X86_DISABLE_EXITS_HLT (1 << 1)
-#define KVM_X86_DISABLE_EXITS_PAUSE (1 << 2)
-#define KVM_X86_DISABLE_EXITS_CSTATE (1 << 3)
+ #define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0)
+ #define KVM_X86_DISABLE_EXITS_HLT (1 << 1)
+ #define KVM_X86_DISABLE_EXITS_PAUSE (1 << 2)
+ #define KVM_X86_DISABLE_EXITS_CSTATE (1 << 3)
Enabling this capability on a VM provides userspace with a way to no
longer intercept some instructions for improved latency in some
@@ -5042,12 +5583,13 @@ all such vmexits.
Do not enable KVM_FEATURE_PV_UNHALT if you disable HLT exits.
7.14 KVM_CAP_S390_HPAGE_1M
+--------------------------
-Architectures: s390
-Parameters: none
-Returns: 0 on success, -EINVAL if hpage module parameter was not set
- or cmma is enabled, or the VM has the KVM_VM_S390_UCONTROL
- flag set
+:Architectures: s390
+:Parameters: none
+:Returns: 0 on success, -EINVAL if hpage module parameter was not set
+ or cmma is enabled, or the VM has the KVM_VM_S390_UCONTROL
+ flag set
With this capability the KVM support for memory backing with 1m pages
through hugetlbfs can be enabled for a VM. After the capability is
@@ -5059,20 +5601,22 @@ While it is generally possible to create a huge page backed VM without
this capability, the VM will not be able to run.
7.15 KVM_CAP_MSR_PLATFORM_INFO
+------------------------------
-Architectures: x86
-Parameters: args[0] whether feature should be enabled or not
+:Architectures: x86
+:Parameters: args[0] whether feature should be enabled or not
With this capability, a guest may read the MSR_PLATFORM_INFO MSR. Otherwise,
a #GP would be raised when the guest tries to access. Currently, this
capability does not enable write permissions of this MSR for the guest.
7.16 KVM_CAP_PPC_NESTED_HV
+--------------------------
-Architectures: ppc
-Parameters: none
-Returns: 0 on success, -EINVAL when the implementation doesn't support
- nested-HV virtualization.
+:Architectures: ppc
+:Parameters: none
+:Returns: 0 on success, -EINVAL when the implementation doesn't support
+ nested-HV virtualization.
HV-KVM on POWER9 and later systems allows for "nested-HV"
virtualization, which provides a way for a guest VM to run guests that
@@ -5082,9 +5626,10 @@ the necessary functionality and on the facility being enabled with a
kvm-hv module parameter.
7.17 KVM_CAP_EXCEPTION_PAYLOAD
+------------------------------
-Architectures: x86
-Parameters: args[0] whether feature should be enabled or not
+:Architectures: x86
+:Parameters: args[0] whether feature should be enabled or not
With this capability enabled, CR2 will not be modified prior to the
emulated VM-exit when L1 intercepts a #PF exception that occurs in
@@ -5095,21 +5640,21 @@ L2. As a result, when KVM_GET_VCPU_EVENTS reports a pending #PF (or
faulting address (or the new DR6 bits*) will be reported in the
exception_payload field. Similarly, when userspace injects a #PF (or
#DB) into L2 using KVM_SET_VCPU_EVENTS, it is expected to set
-exception.has_payload and to put the faulting address (or the new DR6
-bits*) in the exception_payload field.
+exception.has_payload and to put the faulting address - or the new DR6
+bits\ [#]_ - in the exception_payload field.
This capability also enables exception.pending in struct
kvm_vcpu_events, which allows userspace to distinguish between pending
and injected exceptions.
-* For the new DR6 bits, note that bit 16 is set iff the #DB exception
- will clear DR6.RTM.
+.. [#] For the new DR6 bits, note that bit 16 is set iff the #DB exception
+ will clear DR6.RTM.
7.18 KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
-Architectures: x86, arm, arm64, mips
-Parameters: args[0] whether feature should be enabled or not
+:Architectures: x86, arm, arm64, mips
+:Parameters: args[0] whether feature should be enabled or not
With this capability enabled, KVM_GET_DIRTY_LOG will not automatically
clear and write-protect all pages that are returned as dirty.
@@ -5136,14 +5681,15 @@ KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 signals that those bugs are fixed.
Userspace should not try to use KVM_CAP_MANUAL_DIRTY_LOG_PROTECT.
8. Other capabilities.
-----------------------
+======================
This section lists capabilities that give information about other
features of the KVM implementation.
8.1 KVM_CAP_PPC_HWRNG
+---------------------
-Architectures: ppc
+:Architectures: ppc
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that that the kernel has an implementation of the
@@ -5152,8 +5698,10 @@ If present, the kernel H_RANDOM handler can be enabled for guest use
with the KVM_CAP_PPC_ENABLE_HCALL capability.
8.2 KVM_CAP_HYPERV_SYNIC
+------------------------
+
+:Architectures: x86
-Architectures: x86
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that that the kernel has an implementation of the
Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is
@@ -5165,8 +5713,9 @@ will disable the use of APIC hardware virtualization even if supported
by the CPU, as it's incompatible with SynIC auto-EOI behavior.
8.3 KVM_CAP_PPC_RADIX_MMU
+-------------------------
-Architectures: ppc
+:Architectures: ppc
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that that the kernel can support guests using the
@@ -5174,8 +5723,9 @@ radix MMU defined in Power ISA V3.00 (as implemented in the POWER9
processor).
8.4 KVM_CAP_PPC_HASH_MMU_V3
+---------------------------
-Architectures: ppc
+:Architectures: ppc
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that that the kernel can support guests using the
@@ -5183,8 +5733,9 @@ hashed page table MMU defined in Power ISA V3.00 (as implemented in
the POWER9 processor), including in-memory segment tables.
8.5 KVM_CAP_MIPS_VZ
+-------------------
-Architectures: mips
+:Architectures: mips
This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that
it is available, means that full hardware assisted virtualization capabilities
@@ -5202,16 +5753,19 @@ values (see below). All other values are reserved. This is to allow for the
possibility of other hardware assisted virtualization implementations which
may be incompatible with the MIPS VZ ASE.
- 0: The trap & emulate implementation is in use to run guest code in user
+== ==========================================================================
+ 0 The trap & emulate implementation is in use to run guest code in user
mode. Guest virtual memory segments are rearranged to fit the guest in the
user mode address space.
- 1: The MIPS VZ ASE is in use, providing full hardware assisted
+ 1 The MIPS VZ ASE is in use, providing full hardware assisted
virtualization, including standard guest virtual memory segments.
+== ==========================================================================
8.6 KVM_CAP_MIPS_TE
+-------------------
-Architectures: mips
+:Architectures: mips
This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that
it is available, means that the trap & emulate implementation is available to
@@ -5223,8 +5777,9 @@ If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is
available, it means that the VM is using trap & emulate.
8.7 KVM_CAP_MIPS_64BIT
+----------------------
-Architectures: mips
+:Architectures: mips
This capability indicates the supported architecture type of the guest, i.e. the
supported register and address width.
@@ -5234,22 +5789,26 @@ kvm VM handle correspond roughly to the CP0_Config.AT register field, and should
be checked specifically against known values (see below). All other values are
reserved.
- 0: MIPS32 or microMIPS32.
+== ========================================================================
+ 0 MIPS32 or microMIPS32.
Both registers and addresses are 32-bits wide.
It will only be possible to run 32-bit guest code.
- 1: MIPS64 or microMIPS64 with access only to 32-bit compatibility segments.
+ 1 MIPS64 or microMIPS64 with access only to 32-bit compatibility segments.
Registers are 64-bits wide, but addresses are 32-bits wide.
64-bit guest code may run but cannot access MIPS64 memory segments.
It will also be possible to run 32-bit guest code.
- 2: MIPS64 or microMIPS64 with access to all address segments.
+ 2 MIPS64 or microMIPS64 with access to all address segments.
Both registers and addresses are 64-bits wide.
It will be possible to run 64-bit or 32-bit guest code.
+== ========================================================================
8.9 KVM_CAP_ARM_USER_IRQ
+------------------------
+
+:Architectures: arm, arm64
-Architectures: arm, arm64
This capability, if KVM_CHECK_EXTENSION indicates that it is available, means
that if userspace creates a VM without an in-kernel interrupt controller, it
will be notified of changes to the output level of in-kernel emulated devices,
@@ -5276,7 +5835,7 @@ If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a
number larger than 0 indicating the version of this capability is implemented
and thereby which bits in in run->s.regs.device_irq_level can signal values.
-Currently the following bits are defined for the device_irq_level bitmap:
+Currently the following bits are defined for the device_irq_level bitmap::
KVM_CAP_ARM_USER_IRQ >= 1:
@@ -5289,8 +5848,9 @@ indicated by returning a higher number from KVM_CHECK_EXTENSION and will be
listed above.
8.10 KVM_CAP_PPC_SMT_POSSIBLE
+-----------------------------
-Architectures: ppc
+:Architectures: ppc
Querying this capability returns a bitmap indicating the possible
virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N
@@ -5298,8 +5858,9 @@ virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N
available.
8.11 KVM_CAP_HYPERV_SYNIC2
+--------------------------
-Architectures: x86
+:Architectures: x86
This capability enables a newer version of Hyper-V Synthetic interrupt
controller (SynIC). The only difference with KVM_CAP_HYPERV_SYNIC is that KVM
@@ -5307,8 +5868,9 @@ doesn't clear SynIC message and event flags pages when they are enabled by
writing to the respective MSRs.
8.12 KVM_CAP_HYPERV_VP_INDEX
+----------------------------
-Architectures: x86
+:Architectures: x86
This capability indicates that userspace can load HV_X64_MSR_VP_INDEX msr. Its
value is used to denote the target vcpu for a SynIC interrupt. For
@@ -5316,47 +5878,53 @@ compatibilty, KVM initializes this msr to KVM's internal vcpu index. When this
capability is absent, userspace can still query this msr's value.
8.13 KVM_CAP_S390_AIS_MIGRATION
+-------------------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
This capability indicates if the flic device will be able to get/set the
AIS states for migration via the KVM_DEV_FLIC_AISM_ALL attribute and allows
to discover this without having to create a flic device.
8.14 KVM_CAP_S390_PSW
+---------------------
-Architectures: s390
+:Architectures: s390
This capability indicates that the PSW is exposed via the kvm_run structure.
8.15 KVM_CAP_S390_GMAP
+----------------------
-Architectures: s390
+:Architectures: s390
This capability indicates that the user space memory used as guest mapping can
be anywhere in the user memory address space, as long as the memory slots are
aligned and sized to a segment (1MB) boundary.
8.16 KVM_CAP_S390_COW
+---------------------
-Architectures: s390
+:Architectures: s390
This capability indicates that the user space memory used as guest mapping can
use copy-on-write semantics as well as dirty pages tracking via read-only page
tables.
8.17 KVM_CAP_S390_BPB
+---------------------
-Architectures: s390
+:Architectures: s390
This capability indicates that kvm will implement the interfaces to handle
reset, migration and nested KVM for branch prediction blocking. The stfle
facility 82 should not be provided to the guest without this capability.
8.18 KVM_CAP_HYPERV_TLBFLUSH
+----------------------------
-Architectures: x86
+:Architectures: x86
This capability indicates that KVM supports paravirtualized Hyper-V TLB Flush
hypercalls:
@@ -5364,8 +5932,9 @@ HvFlushVirtualAddressSpace, HvFlushVirtualAddressSpaceEx,
HvFlushVirtualAddressList, HvFlushVirtualAddressListEx.
8.19 KVM_CAP_ARM_INJECT_SERROR_ESR
+----------------------------------
-Architectures: arm, arm64
+:Architectures: arm, arm64
This capability indicates that userspace can specify (via the
KVM_SET_VCPU_EVENTS ioctl) the syndrome value reported to the guest when it
@@ -5376,16 +5945,20 @@ CPU when the exception is taken. If this virtual SError is taken to EL1 using
AArch64, this value will be reported in the ISS field of ESR_ELx.
See KVM_CAP_VCPU_EVENTS for more details.
+
8.20 KVM_CAP_HYPERV_SEND_IPI
+----------------------------
-Architectures: x86
+:Architectures: x86
This capability indicates that KVM supports paravirtualized Hyper-V IPI send
hypercalls:
HvCallSendSyntheticClusterIpi, HvCallSendSyntheticClusterIpiEx.
+
8.21 KVM_CAP_HYPERV_DIRECT_TLBFLUSH
+-----------------------------------
-Architecture: x86
+:Architecture: x86
This capability indicates that KVM running on top of Hyper-V hypervisor
enables Direct TLB flush for its guests meaning that TLB flush
diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst
index 24d1076ec680..6fe79185b9bc 100644
--- a/Documentation/virt/kvm/index.rst
+++ b/Documentation/virt/kvm/index.rst
@@ -7,6 +7,7 @@ KVM
.. toctree::
:maxdepth: 2
+ api
amd-memory-encryption
cpuid
halt-polling
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 17/27] docs: kvm: Convert api.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
convert api.txt document to ReST format while trying to keep
its format as close as possible with the authors intent, and
avoid adding uneeded markups.
- 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 <mchehab+huawei@kernel.org>
---
Documentation/virt/kvm/{api.txt => api.rst} | 3343 +++++++++++--------
Documentation/virt/kvm/index.rst | 1 +
2 files changed, 1959 insertions(+), 1385 deletions(-)
rename Documentation/virt/kvm/{api.txt => api.rst} (71%)
diff --git a/Documentation/virt/kvm/api.txt b/Documentation/virt/kvm/api.rst
similarity index 71%
rename from Documentation/virt/kvm/api.txt
rename to Documentation/virt/kvm/api.rst
index ebb37b34dcfc..c6e1bb3ae0c6 100644
--- a/Documentation/virt/kvm/api.txt
+++ b/Documentation/virt/kvm/api.rst
@@ -1,8 +1,9 @@
+===================================================================
The Definitive KVM (Kernel-based Virtual Machine) API Documentation
===================================================================
1. General description
-----------------------
+======================
The kvm API is a set of ioctls that are issued to control various aspects
of a virtual machine. The ioctls belong to the following classes:
@@ -33,7 +34,7 @@ of a virtual machine. The ioctls belong to the following classes:
was used to create the VM.
2. File descriptors
--------------------
+===================
The kvm API is centered around file descriptors. An initial
open("/dev/kvm") obtains a handle to the kvm subsystem; this handle
@@ -70,7 +71,7 @@ the VM is shut down.
3. Extensions
--------------
+=============
As of Linux 2.6.22, the KVM ABI has been stabilized: no backward
incompatible change are allowed. However, there is an extension
@@ -84,13 +85,14 @@ set of ioctls is available for application use.
4. API description
-------------------
+==================
This section describes ioctls that can be used to control kvm guests.
For each ioctl, the following information is provided along with a
description:
- Capability: which KVM extension provides this ioctl. Can be 'basic',
+ Capability:
+ which KVM extension provides this ioctl. Can be 'basic',
which means that is will be provided by any kernel that supports
API version 12 (see section 4.1), a KVM_CAP_xyz constant, which
means availability needs to be checked with KVM_CHECK_EXTENSION
@@ -99,24 +101,29 @@ description:
availability: for kernels that don't support the ioctl,
the ioctl returns -ENOTTY.
- Architectures: which instruction set architectures provide this ioctl.
+ Architectures:
+ which instruction set architectures provide this ioctl.
x86 includes both i386 and x86_64.
- Type: system, vm, or vcpu.
+ Type:
+ system, vm, or vcpu.
- Parameters: what parameters are accepted by the ioctl.
+ Parameters:
+ what parameters are accepted by the ioctl.
- Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
+ Returns:
+ the return value. General error numbers (EBADF, ENOMEM, EINVAL)
are not detailed, but errors with specific meanings are.
4.1 KVM_GET_API_VERSION
+-----------------------
-Capability: basic
-Architectures: all
-Type: system ioctl
-Parameters: none
-Returns: the constant KVM_API_VERSION (=12)
+:Capability: basic
+:Architectures: all
+:Type: system ioctl
+:Parameters: none
+:Returns: the constant KVM_API_VERSION (=12)
This identifies the API version as the stable kvm API. It is not
expected that this number will change. However, Linux 2.6.20 and
@@ -127,12 +134,13 @@ described as 'basic' will be available.
4.2 KVM_CREATE_VM
+-----------------
-Capability: basic
-Architectures: all
-Type: system ioctl
-Parameters: machine type identifier (KVM_VM_*)
-Returns: a VM fd that can be used to control the new virtual machine.
+:Capability: basic
+:Architectures: all
+:Type: system ioctl
+:Parameters: machine type identifier (KVM_VM_*)
+:Returns: a VM fd that can be used to control the new virtual machine.
The new VM has no virtual cpus and no memory.
You probably want to use 0 as machine type.
@@ -155,17 +163,17 @@ identifier, where IPA_Bits is the maximum width of any physical
address used by the VM. The IPA_Bits is encoded in bits[7-0] of the
machine type identifier.
-e.g, to configure a guest to use 48bit physical address size :
+e.g, to configure a guest to use 48bit physical address size::
vm_fd = ioctl(dev_fd, KVM_CREATE_VM, KVM_VM_TYPE_ARM_IPA_SIZE(48));
-The requested size (IPA_Bits) must be :
- 0 - Implies default size, 40bits (for backward compatibility)
+The requested size (IPA_Bits) must be:
- or
-
- N - Implies N bits, where N is a positive integer such that,
+ == =========================================================
+ 0 Implies default size, 40bits (for backward compatibility)
+ N Implies N bits, where N is a positive integer such that,
32 <= N <= Host_IPA_Limit
+ == =========================================================
Host_IPA_Limit is the maximum possible value for IPA_Bits on the host and
is dependent on the CPU capability and the kernel configuration. The limit can
@@ -179,21 +187,28 @@ host physical address translations).
4.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST
+----------------------------------------------------------
+
+:Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST
+:Architectures: x86
+:Type: system ioctl
+:Parameters: struct kvm_msr_list (in/out)
+:Returns: 0 on success; -1 on error
-Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST
-Architectures: x86
-Type: system ioctl
-Parameters: struct kvm_msr_list (in/out)
-Returns: 0 on success; -1 on error
Errors:
- EFAULT: the msr index list cannot be read from or written to
- E2BIG: the msr index list is to be to fit in the array specified by
+
+ ====== ============================================================
+ EFAULT the msr index list cannot be read from or written to
+ E2BIG the msr index list is to be to fit in the array specified by
the user.
+ ====== ============================================================
-struct kvm_msr_list {
+::
+
+ struct kvm_msr_list {
__u32 nmsrs; /* number of msrs in entries */
__u32 indices[0];
-};
+ };
The user fills in the size of the indices array in nmsrs, and in return
kvm adjusts nmsrs to reflect the actual number of msrs and fills in the
@@ -214,12 +229,13 @@ otherwise.
4.4 KVM_CHECK_EXTENSION
+-----------------------
-Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl
-Architectures: all
-Type: system ioctl, vm ioctl
-Parameters: extension identifier (KVM_CAP_*)
-Returns: 0 if unsupported; 1 (or some other positive integer) if supported
+:Capability: basic, KVM_CAP_CHECK_EXTENSION_VM for vm ioctl
+:Architectures: all
+:Type: system ioctl, vm ioctl
+:Parameters: extension identifier (KVM_CAP_*)
+:Returns: 0 if unsupported; 1 (or some other positive integer) if supported
The API allows the application to query about extensions to the core
kvm API. Userspace passes an extension identifier (an integer) and
@@ -232,12 +248,13 @@ It is thus encouraged to use the vm ioctl to query for capabilities (available
with KVM_CAP_CHECK_EXTENSION_VM on the vm fd)
4.5 KVM_GET_VCPU_MMAP_SIZE
+--------------------------
-Capability: basic
-Architectures: all
-Type: system ioctl
-Parameters: none
-Returns: size of vcpu mmap area, in bytes
+:Capability: basic
+:Architectures: all
+:Type: system ioctl
+:Parameters: none
+:Returns: size of vcpu mmap area, in bytes
The KVM_RUN ioctl (cf.) communicates with userspace via a shared
memory region. This ioctl returns the size of that region. See the
@@ -245,23 +262,25 @@ KVM_RUN documentation for details.
4.6 KVM_SET_MEMORY_REGION
+-------------------------
-Capability: basic
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_memory_region (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_memory_region (in)
+:Returns: 0 on success, -1 on error
This ioctl is obsolete and has been removed.
4.7 KVM_CREATE_VCPU
+-------------------
-Capability: basic
-Architectures: all
-Type: vm ioctl
-Parameters: vcpu id (apic id on x86)
-Returns: vcpu fd on success, -1 on error
+:Capability: basic
+:Architectures: all
+:Type: vm ioctl
+:Parameters: vcpu id (apic id on x86)
+:Returns: vcpu fd on success, -1 on error
This API adds a vcpu to a virtual machine. No more than max_vcpus may be added.
The vcpu id is an integer in the range [0, max_vcpu_id).
@@ -302,22 +321,25 @@ cpu's hardware control block.
4.8 KVM_GET_DIRTY_LOG (vm ioctl)
+--------------------------------
-Capability: basic
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_dirty_log (in/out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_dirty_log (in/out)
+:Returns: 0 on success, -1 on error
-/* for KVM_GET_DIRTY_LOG */
-struct kvm_dirty_log {
+::
+
+ /* for KVM_GET_DIRTY_LOG */
+ struct kvm_dirty_log {
__u32 slot;
__u32 padding;
union {
void __user *dirty_bitmap; /* one bit per page */
__u64 padding;
};
-};
+ };
Given a memory slot, return a bitmap containing any pages dirtied
since the last call to this ioctl. Bit 0 is the first page in the
@@ -334,25 +356,31 @@ KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is enabled. For more information,
see the description of the capability.
4.9 KVM_SET_MEMORY_ALIAS
+------------------------
-Capability: basic
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_memory_alias (in)
-Returns: 0 (success), -1 (error)
+:Capability: basic
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_memory_alias (in)
+:Returns: 0 (success), -1 (error)
This ioctl is obsolete and has been removed.
4.10 KVM_RUN
+------------
+
+:Capability: basic
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: none
+:Returns: 0 on success, -1 on error
-Capability: basic
-Architectures: all
-Type: vcpu ioctl
-Parameters: none
-Returns: 0 on success, -1 on error
Errors:
- EINTR: an unmasked signal is pending
+
+ ===== =============================
+ EINTR an unmasked signal is pending
+ ===== =============================
This ioctl is used to run a guest virtual cpu. While there are no
explicit parameters, there is an implicit parameter block that can be
@@ -362,42 +390,46 @@ kvm_run' (see below).
4.11 KVM_GET_REGS
+-----------------
-Capability: basic
-Architectures: all except ARM, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_regs (out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all except ARM, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_regs (out)
+:Returns: 0 on success, -1 on error
Reads the general purpose registers from the vcpu.
-/* x86 */
-struct kvm_regs {
+::
+
+ /* x86 */
+ struct kvm_regs {
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
__u64 rax, rbx, rcx, rdx;
__u64 rsi, rdi, rsp, rbp;
__u64 r8, r9, r10, r11;
__u64 r12, r13, r14, r15;
__u64 rip, rflags;
-};
+ };
-/* mips */
-struct kvm_regs {
+ /* mips */
+ struct kvm_regs {
/* out (KVM_GET_REGS) / in (KVM_SET_REGS) */
__u64 gpr[32];
__u64 hi;
__u64 lo;
__u64 pc;
-};
+ };
4.12 KVM_SET_REGS
+-----------------
-Capability: basic
-Architectures: all except ARM, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_regs (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all except ARM, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_regs (in)
+:Returns: 0 on success, -1 on error
Writes the general purpose registers into the vcpu.
@@ -405,17 +437,20 @@ See KVM_GET_REGS for the data structure.
4.13 KVM_GET_SREGS
+------------------
-Capability: basic
-Architectures: x86, ppc
-Type: vcpu ioctl
-Parameters: struct kvm_sregs (out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86, ppc
+:Type: vcpu ioctl
+:Parameters: struct kvm_sregs (out)
+:Returns: 0 on success, -1 on error
Reads special registers from the vcpu.
-/* x86 */
-struct kvm_sregs {
+::
+
+ /* x86 */
+ struct kvm_sregs {
struct kvm_segment cs, ds, es, fs, gs, ss;
struct kvm_segment tr, ldt;
struct kvm_dtable gdt, idt;
@@ -423,9 +458,9 @@ struct kvm_sregs {
__u64 efer;
__u64 apic_base;
__u64 interrupt_bitmap[(KVM_NR_INTERRUPTS + 63) / 64];
-};
+ };
-/* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */
+ /* ppc -- see arch/powerpc/include/uapi/asm/kvm.h */
interrupt_bitmap is a bitmap of pending external interrupts. At most
one bit may be set. This interrupt has been acknowledged by the APIC
@@ -433,29 +468,33 @@ but not yet injected into the cpu core.
4.14 KVM_SET_SREGS
+------------------
-Capability: basic
-Architectures: x86, ppc
-Type: vcpu ioctl
-Parameters: struct kvm_sregs (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86, ppc
+:Type: vcpu ioctl
+:Parameters: struct kvm_sregs (in)
+:Returns: 0 on success, -1 on error
Writes special registers into the vcpu. See KVM_GET_SREGS for the
data structures.
4.15 KVM_TRANSLATE
+------------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_translation (in/out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_translation (in/out)
+:Returns: 0 on success, -1 on error
Translates a virtual address according to the vcpu's current address
translation mode.
-struct kvm_translation {
+::
+
+ struct kvm_translation {
/* in */
__u64 linear_address;
@@ -465,59 +504,68 @@ struct kvm_translation {
__u8 writeable;
__u8 usermode;
__u8 pad[5];
-};
+ };
4.16 KVM_INTERRUPT
+------------------
-Capability: basic
-Architectures: x86, ppc, mips
-Type: vcpu ioctl
-Parameters: struct kvm_interrupt (in)
-Returns: 0 on success, negative on failure.
+:Capability: basic
+:Architectures: x86, ppc, mips
+:Type: vcpu ioctl
+:Parameters: struct kvm_interrupt (in)
+:Returns: 0 on success, negative on failure.
Queues a hardware interrupt vector to be injected.
-/* for KVM_INTERRUPT */
-struct kvm_interrupt {
+::
+
+ /* for KVM_INTERRUPT */
+ struct kvm_interrupt {
/* in */
__u32 irq;
-};
+ };
X86:
+^^^^
-Returns: 0 on success,
- -EEXIST if an interrupt is already enqueued
- -EINVAL the the irq number is invalid
- -ENXIO if the PIC is in the kernel
- -EFAULT if the pointer is invalid
+:Returns:
+
+ ========= ===================================
+ 0 on success,
+ -EEXIST if an interrupt is already enqueued
+ -EINVAL the the irq number is invalid
+ -ENXIO if the PIC is in the kernel
+ -EFAULT if the pointer is invalid
+ ========= ===================================
Note 'irq' is an interrupt vector, not an interrupt pin or line. This
ioctl is useful if the in-kernel PIC is not used.
PPC:
+^^^^
Queues an external interrupt to be injected. This ioctl is overleaded
with 3 different irq values:
a) KVM_INTERRUPT_SET
- This injects an edge type external interrupt into the guest once it's ready
- to receive interrupts. When injected, the interrupt is done.
+ This injects an edge type external interrupt into the guest once it's ready
+ to receive interrupts. When injected, the interrupt is done.
b) KVM_INTERRUPT_UNSET
- This unsets any pending interrupt.
+ This unsets any pending interrupt.
- Only available with KVM_CAP_PPC_UNSET_IRQ.
+ Only available with KVM_CAP_PPC_UNSET_IRQ.
c) KVM_INTERRUPT_SET_LEVEL
- This injects a level type external interrupt into the guest context. The
- interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
- is triggered.
+ This injects a level type external interrupt into the guest context. The
+ interrupt stays pending until a specific ioctl with KVM_INTERRUPT_UNSET
+ is triggered.
- Only available with KVM_CAP_PPC_IRQ_LEVEL.
+ Only available with KVM_CAP_PPC_IRQ_LEVEL.
Note that any value for 'irq' other than the ones stated above is invalid
and incurs unexpected behavior.
@@ -525,6 +573,7 @@ and incurs unexpected behavior.
This is an asynchronous vcpu ioctl and can be invoked from any thread.
MIPS:
+^^^^^
Queues an external interrupt to be injected into the virtual CPU. A negative
interrupt number dequeues the interrupt.
@@ -533,24 +582,26 @@ This is an asynchronous vcpu ioctl and can be invoked from any thread.
4.17 KVM_DEBUG_GUEST
+--------------------
-Capability: basic
-Architectures: none
-Type: vcpu ioctl
-Parameters: none)
-Returns: -1 on error
+:Capability: basic
+:Architectures: none
+:Type: vcpu ioctl
+:Parameters: none)
+:Returns: -1 on error
Support for this has been removed. Use KVM_SET_GUEST_DEBUG instead.
4.18 KVM_GET_MSRS
+-----------------
-Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system)
-Architectures: x86
-Type: system ioctl, vcpu ioctl
-Parameters: struct kvm_msrs (in/out)
-Returns: number of msrs successfully returned;
- -1 on error
+:Capability: basic (vcpu), KVM_CAP_GET_MSR_FEATURES (system)
+:Architectures: x86
+:Type: system ioctl, vcpu ioctl
+:Parameters: struct kvm_msrs (in/out)
+:Returns: number of msrs successfully returned;
+ -1 on error
When used as a system ioctl:
Reads the values of MSR-based features that are available for the VM. This
@@ -562,18 +613,20 @@ When used as a vcpu ioctl:
Reads model-specific registers from the vcpu. Supported msr indices can
be obtained using KVM_GET_MSR_INDEX_LIST in a system ioctl.
-struct kvm_msrs {
+::
+
+ struct kvm_msrs {
__u32 nmsrs; /* number of msrs in entries */
__u32 pad;
struct kvm_msr_entry entries[0];
-};
+ };
-struct kvm_msr_entry {
+ struct kvm_msr_entry {
__u32 index;
__u32 reserved;
__u64 data;
-};
+ };
Application code should set the 'nmsrs' member (which indicates the
size of the entries array) and the 'index' member of each array entry.
@@ -581,12 +634,13 @@ kvm will fill in the 'data' member.
4.19 KVM_SET_MSRS
+-----------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_msrs (in)
-Returns: number of msrs successfully set (see below), -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_msrs (in)
+:Returns: number of msrs successfully set (see below), -1 on error
Writes model-specific registers to the vcpu. See KVM_GET_MSRS for the
data structures.
@@ -602,41 +656,44 @@ MSRs that have been set successfully.
4.20 KVM_SET_CPUID
+------------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_cpuid (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_cpuid (in)
+:Returns: 0 on success, -1 on error
Defines the vcpu responses to the cpuid instruction. Applications
should use the KVM_SET_CPUID2 ioctl if available.
+::
-struct kvm_cpuid_entry {
+ struct kvm_cpuid_entry {
__u32 function;
__u32 eax;
__u32 ebx;
__u32 ecx;
__u32 edx;
__u32 padding;
-};
+ };
-/* for KVM_SET_CPUID */
-struct kvm_cpuid {
+ /* for KVM_SET_CPUID */
+ struct kvm_cpuid {
__u32 nent;
__u32 padding;
struct kvm_cpuid_entry entries[0];
-};
+ };
4.21 KVM_SET_SIGNAL_MASK
+------------------------
-Capability: basic
-Architectures: all
-Type: vcpu ioctl
-Parameters: struct kvm_signal_mask (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: struct kvm_signal_mask (in)
+:Returns: 0 on success, -1 on error
Defines which signals are blocked during execution of KVM_RUN. This
signal mask temporarily overrides the threads signal mask. Any
@@ -646,25 +703,30 @@ their traditional behaviour) will cause KVM_RUN to return with -EINTR.
Note the signal will only be delivered if not blocked by the original
signal mask.
-/* for KVM_SET_SIGNAL_MASK */
-struct kvm_signal_mask {
+::
+
+ /* for KVM_SET_SIGNAL_MASK */
+ struct kvm_signal_mask {
__u32 len;
__u8 sigset[0];
-};
+ };
4.22 KVM_GET_FPU
+----------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_fpu (out)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_fpu (out)
+:Returns: 0 on success, -1 on error
Reads the floating point state from the vcpu.
-/* for KVM_GET_FPU and KVM_SET_FPU */
-struct kvm_fpu {
+::
+
+ /* for KVM_GET_FPU and KVM_SET_FPU */
+ struct kvm_fpu {
__u8 fpr[8][16];
__u16 fcw;
__u16 fsw;
@@ -676,21 +738,24 @@ struct kvm_fpu {
__u8 xmm[16][16];
__u32 mxcsr;
__u32 pad2;
-};
+ };
4.23 KVM_SET_FPU
+----------------
-Capability: basic
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_fpu (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_fpu (in)
+:Returns: 0 on success, -1 on error
Writes the floating point state to the vcpu.
-/* for KVM_GET_FPU and KVM_SET_FPU */
-struct kvm_fpu {
+::
+
+ /* for KVM_GET_FPU and KVM_SET_FPU */
+ struct kvm_fpu {
__u8 fpr[8][16];
__u16 fcw;
__u16 fsw;
@@ -702,16 +767,17 @@ struct kvm_fpu {
__u8 xmm[16][16];
__u32 mxcsr;
__u32 pad2;
-};
+ };
4.24 KVM_CREATE_IRQCHIP
+-----------------------
-Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390)
-Architectures: x86, ARM, arm64, s390
-Type: vm ioctl
-Parameters: none
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP, KVM_CAP_S390_IRQCHIP (s390)
+:Architectures: x86, ARM, arm64, s390
+:Type: vm ioctl
+:Parameters: none
+:Returns: 0 on success, -1 on error
Creates an interrupt controller model in the kernel.
On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up
@@ -727,12 +793,13 @@ before KVM_CREATE_IRQCHIP can be used.
4.25 KVM_IRQ_LINE
+-----------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86, arm, arm64
-Type: vm ioctl
-Parameters: struct kvm_irq_level
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86, arm, arm64
+:Type: vm ioctl
+:Parameters: struct kvm_irq_level
+:Returns: 0 on success, -1 on error
Sets the level of a GSI input to the interrupt controller model in the kernel.
On some architectures it is required that an interrupt controller model has
@@ -756,16 +823,20 @@ of course).
ARM/arm64 can signal an interrupt either at the CPU level, or at the
in-kernel irqchip (GIC), and for in-kernel irqchip can tell the GIC to
use PPIs designated for specific cpus. The irq field is interpreted
-like this:
+like this::
bits: | 31 ... 28 | 27 ... 24 | 23 ... 16 | 15 ... 0 |
field: | vcpu2_index | irq_type | vcpu_index | irq_id |
The irq_type field has the following values:
-- irq_type[0]: out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ
-- irq_type[1]: in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.)
+
+- irq_type[0]:
+ out-of-kernel GIC: irq_id 0 is IRQ, irq_id 1 is FIQ
+- irq_type[1]:
+ in-kernel GIC: SPI, irq_id between 32 and 1019 (incl.)
(the vcpu_index field is ignored)
-- irq_type[2]: in-kernel GIC: PPI, irq_id between 16 and 31 (incl.)
+- irq_type[2]:
+ in-kernel GIC: PPI, irq_id between 16 and 31 (incl.)
(The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)
@@ -779,27 +850,32 @@ Note that on arm/arm64, the KVM_CAP_IRQCHIP capability only conditions
injection of interrupts for the in-kernel irqchip. KVM_IRQ_LINE can always
be used for a userspace interrupt controller.
-struct kvm_irq_level {
+::
+
+ struct kvm_irq_level {
union {
__u32 irq; /* GSI */
__s32 status; /* not used for KVM_IRQ_LEVEL */
};
__u32 level; /* 0 or 1 */
-};
+ };
4.26 KVM_GET_IRQCHIP
+--------------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_irqchip (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_irqchip (in/out)
+:Returns: 0 on success, -1 on error
Reads the state of a kernel interrupt controller created with
KVM_CREATE_IRQCHIP into a buffer provided by the caller.
-struct kvm_irqchip {
+::
+
+ struct kvm_irqchip {
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
__u32 pad;
union {
@@ -807,21 +883,24 @@ struct kvm_irqchip {
struct kvm_pic_state pic;
struct kvm_ioapic_state ioapic;
} chip;
-};
+ };
4.27 KVM_SET_IRQCHIP
+--------------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_irqchip (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_irqchip (in)
+:Returns: 0 on success, -1 on error
Sets the state of a kernel interrupt controller created with
KVM_CREATE_IRQCHIP from a buffer provided by the caller.
-struct kvm_irqchip {
+::
+
+ struct kvm_irqchip {
__u32 chip_id; /* 0 = PIC1, 1 = PIC2, 2 = IOAPIC */
__u32 pad;
union {
@@ -829,16 +908,17 @@ struct kvm_irqchip {
struct kvm_pic_state pic;
struct kvm_ioapic_state ioapic;
} chip;
-};
+ };
4.28 KVM_XEN_HVM_CONFIG
+-----------------------
-Capability: KVM_CAP_XEN_HVM
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_xen_hvm_config (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XEN_HVM
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_xen_hvm_config (in)
+:Returns: 0 on success, -1 on error
Sets the MSR that the Xen HVM guest uses to initialize its hypercall
page, and provides the starting address and size of the hypercall
@@ -846,7 +926,9 @@ blobs in userspace. When the guest writes the MSR, kvm copies one
page of a blob (32- or 64-bit, depending on the vcpu mode) to guest
memory.
-struct kvm_xen_hvm_config {
+::
+
+ struct kvm_xen_hvm_config {
__u32 flags;
__u32 msr;
__u64 blob_addr_32;
@@ -854,16 +936,17 @@ struct kvm_xen_hvm_config {
__u8 blob_size_32;
__u8 blob_size_64;
__u8 pad2[30];
-};
+ };
4.29 KVM_GET_CLOCK
+------------------
-Capability: KVM_CAP_ADJUST_CLOCK
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_clock_data (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_ADJUST_CLOCK
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_clock_data (out)
+:Returns: 0 on success, -1 on error
Gets the current timestamp of kvmclock as seen by the current guest. In
conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios
@@ -880,47 +963,56 @@ with KVM_SET_CLOCK. KVM will try to make all VCPUs follow this clock,
but the exact value read by each VCPU could differ, because the host
TSC is not stable.
-struct kvm_clock_data {
+::
+
+ struct kvm_clock_data {
__u64 clock; /* kvmclock current value */
__u32 flags;
__u32 pad[9];
-};
+ };
4.30 KVM_SET_CLOCK
+------------------
-Capability: KVM_CAP_ADJUST_CLOCK
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_clock_data (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_ADJUST_CLOCK
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_clock_data (in)
+:Returns: 0 on success, -1 on error
Sets the current timestamp of kvmclock to the value specified in its parameter.
In conjunction with KVM_GET_CLOCK, it is used to ensure monotonicity on scenarios
such as migration.
-struct kvm_clock_data {
+::
+
+ struct kvm_clock_data {
__u64 clock; /* kvmclock current value */
__u32 flags;
__u32 pad[9];
-};
+ };
4.31 KVM_GET_VCPU_EVENTS
+------------------------
-Capability: KVM_CAP_VCPU_EVENTS
-Extended by: KVM_CAP_INTR_SHADOW
-Architectures: x86, arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_vcpu_event (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_VCPU_EVENTS
+:Extended by: KVM_CAP_INTR_SHADOW
+:Architectures: x86, arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_vcpu_event (out)
+:Returns: 0 on success, -1 on error
X86:
+^^^^
Gets currently pending exceptions, interrupts, and NMIs as well as related
states of the vcpu.
-struct kvm_vcpu_events {
+::
+
+ struct kvm_vcpu_events {
struct {
__u8 injected;
__u8 nr;
@@ -951,7 +1043,7 @@ struct kvm_vcpu_events {
__u8 reserved[27];
__u8 exception_has_payload;
__u64 exception_payload;
-};
+ };
The following bits are defined in the flags field:
@@ -967,6 +1059,7 @@ The following bits are defined in the flags field:
KVM_CAP_EXCEPTION_PAYLOAD is enabled.
ARM/ARM64:
+^^^^^^^^^^
If the guest accesses a device that is being emulated by the host kernel in
such a way that a real device would generate a physical SError, KVM may make
@@ -1006,8 +1099,9 @@ It is not possible to read back a pending external abort (injected via
KVM_SET_VCPU_EVENTS or otherwise) because such an exception is always delivered
directly to the virtual CPU).
+::
-struct kvm_vcpu_events {
+ struct kvm_vcpu_events {
struct {
__u8 serror_pending;
__u8 serror_has_esr;
@@ -1017,18 +1111,20 @@ struct kvm_vcpu_events {
__u64 serror_esr;
} exception;
__u32 reserved[12];
-};
+ };
4.32 KVM_SET_VCPU_EVENTS
+------------------------
-Capability: KVM_CAP_VCPU_EVENTS
-Extended by: KVM_CAP_INTR_SHADOW
-Architectures: x86, arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_vcpu_event (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_VCPU_EVENTS
+:Extended by: KVM_CAP_INTR_SHADOW
+:Architectures: x86, arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_vcpu_event (in)
+:Returns: 0 on success, -1 on error
X86:
+^^^^
Set pending exceptions, interrupts, and NMIs as well as related states of the
vcpu.
@@ -1040,9 +1136,11 @@ from the update. These fields are nmi.pending, sipi_vector, smi.smm,
smi.pending. Keep the corresponding bits in the flags field cleared to
suppress overwriting the current in-kernel state. The bits are:
-KVM_VCPUEVENT_VALID_NMI_PENDING - transfer nmi.pending to the kernel
-KVM_VCPUEVENT_VALID_SIPI_VECTOR - transfer sipi_vector
-KVM_VCPUEVENT_VALID_SMM - transfer the smi sub-struct.
+=============================== ==================================
+KVM_VCPUEVENT_VALID_NMI_PENDING transfer nmi.pending to the kernel
+KVM_VCPUEVENT_VALID_SIPI_VECTOR transfer sipi_vector
+KVM_VCPUEVENT_VALID_SMM transfer the smi sub-struct.
+=============================== ==================================
If KVM_CAP_INTR_SHADOW is available, KVM_VCPUEVENT_VALID_SHADOW can be set in
the flags field to signal that interrupt.shadow contains a valid state and
@@ -1056,6 +1154,7 @@ exception_has_payload, exception_payload, and exception.pending fields
contain a valid state and shall be written into the VCPU.
ARM/ARM64:
+^^^^^^^^^^
User space may need to inject several types of events to the guest.
@@ -1078,31 +1177,35 @@ See KVM_GET_VCPU_EVENTS for the data structure.
4.33 KVM_GET_DEBUGREGS
+----------------------
-Capability: KVM_CAP_DEBUGREGS
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_debugregs (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_DEBUGREGS
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_debugregs (out)
+:Returns: 0 on success, -1 on error
Reads debug registers from the vcpu.
-struct kvm_debugregs {
+::
+
+ struct kvm_debugregs {
__u64 db[4];
__u64 dr6;
__u64 dr7;
__u64 flags;
__u64 reserved[9];
-};
+ };
4.34 KVM_SET_DEBUGREGS
+----------------------
-Capability: KVM_CAP_DEBUGREGS
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_debugregs (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_DEBUGREGS
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_debugregs (in)
+:Returns: 0 on success, -1 on error
Writes debug registers into the vcpu.
@@ -1111,24 +1214,27 @@ yet and must be cleared on entry.
4.35 KVM_SET_USER_MEMORY_REGION
+-------------------------------
-Capability: KVM_CAP_USER_MEMORY
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_userspace_memory_region (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_USER_MEMORY
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_userspace_memory_region (in)
+:Returns: 0 on success, -1 on error
-struct kvm_userspace_memory_region {
+::
+
+ struct kvm_userspace_memory_region {
__u32 slot;
__u32 flags;
__u64 guest_phys_addr;
__u64 memory_size; /* bytes */
__u64 userspace_addr; /* start of the userspace allocated memory */
-};
+ };
-/* for kvm_memory_region::flags */
-#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0)
-#define KVM_MEM_READONLY (1UL << 1)
+ /* for kvm_memory_region::flags */
+ #define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0)
+ #define KVM_MEM_READONLY (1UL << 1)
This ioctl allows the user to create, modify or delete a guest physical
memory slot. Bits 0-15 of "slot" specify the slot id and this value
@@ -1174,12 +1280,13 @@ allocation and is deprecated.
4.36 KVM_SET_TSS_ADDR
+---------------------
-Capability: KVM_CAP_SET_TSS_ADDR
-Architectures: x86
-Type: vm ioctl
-Parameters: unsigned long tss_address (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_SET_TSS_ADDR
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: unsigned long tss_address (in)
+:Returns: 0 on success, -1 on error
This ioctl defines the physical address of a three-page region in the guest
physical address space. The region must be within the first 4GB of the
@@ -1193,21 +1300,24 @@ documentation when it pops into existence).
4.37 KVM_ENABLE_CAP
+-------------------
-Capability: KVM_CAP_ENABLE_CAP
-Architectures: mips, ppc, s390
-Type: vcpu ioctl
-Parameters: struct kvm_enable_cap (in)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_ENABLE_CAP
+:Architectures: mips, ppc, s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_enable_cap (in)
+:Returns: 0 on success; -1 on error
-Capability: KVM_CAP_ENABLE_CAP_VM
-Architectures: all
-Type: vcpu ioctl
-Parameters: struct kvm_enable_cap (in)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_ENABLE_CAP_VM
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: struct kvm_enable_cap (in)
+:Returns: 0 on success; -1 on error
-+Not all extensions are enabled by default. Using this ioctl the application
-can enable an extension, making it available to the guest.
+.. note::
+
+ Not all extensions are enabled by default. Using this ioctl the application
+ can enable an extension, making it available to the guest.
On systems that do not support this ioctl, it always fails. On systems that
do support it, it only works for extensions that are supported for enablement.
@@ -1215,76 +1325,91 @@ do support it, it only works for extensions that are supported for enablement.
To check if a capability can be enabled, the KVM_CHECK_EXTENSION ioctl should
be used.
-struct kvm_enable_cap {
+::
+
+ struct kvm_enable_cap {
/* in */
__u32 cap;
The capability that is supposed to get enabled.
+::
+
__u32 flags;
A bitfield indicating future enhancements. Has to be 0 for now.
+::
+
__u64 args[4];
Arguments for enabling a feature. If a feature needs initial values to
function properly, this is the place to put them.
+::
+
__u8 pad[64];
-};
+ };
The vcpu ioctl should be used for vcpu-specific capabilities, the vm ioctl
for vm-wide capabilities.
4.38 KVM_GET_MP_STATE
+---------------------
-Capability: KVM_CAP_MP_STATE
-Architectures: x86, s390, arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_mp_state (out)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_MP_STATE
+:Architectures: x86, s390, arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_mp_state (out)
+:Returns: 0 on success; -1 on error
-struct kvm_mp_state {
+::
+
+ struct kvm_mp_state {
__u32 mp_state;
-};
+ };
Returns the vcpu's current "multiprocessing state" (though also valid on
uniprocessor guests).
Possible values are:
- - KVM_MP_STATE_RUNNABLE: the vcpu is currently running [x86,arm/arm64]
- - KVM_MP_STATE_UNINITIALIZED: the vcpu is an application processor (AP)
+ ========================== ===============================================
+ KVM_MP_STATE_RUNNABLE the vcpu is currently running [x86,arm/arm64]
+ KVM_MP_STATE_UNINITIALIZED the vcpu is an application processor (AP)
which has not yet received an INIT signal [x86]
- - KVM_MP_STATE_INIT_RECEIVED: the vcpu has received an INIT signal, and is
+ KVM_MP_STATE_INIT_RECEIVED the vcpu has received an INIT signal, and is
now ready for a SIPI [x86]
- - KVM_MP_STATE_HALTED: the vcpu has executed a HLT instruction and
+ KVM_MP_STATE_HALTED the vcpu has executed a HLT instruction and
is waiting for an interrupt [x86]
- - KVM_MP_STATE_SIPI_RECEIVED: the vcpu has just received a SIPI (vector
+ KVM_MP_STATE_SIPI_RECEIVED the vcpu has just received a SIPI (vector
accessible via KVM_GET_VCPU_EVENTS) [x86]
- - KVM_MP_STATE_STOPPED: the vcpu is stopped [s390,arm/arm64]
- - KVM_MP_STATE_CHECK_STOP: the vcpu is in a special error state [s390]
- - KVM_MP_STATE_OPERATING: the vcpu is operating (running or halted)
+ KVM_MP_STATE_STOPPED the vcpu is stopped [s390,arm/arm64]
+ KVM_MP_STATE_CHECK_STOP the vcpu is in a special error state [s390]
+ KVM_MP_STATE_OPERATING the vcpu is operating (running or halted)
[s390]
- - KVM_MP_STATE_LOAD: the vcpu is in a special load/startup state
+ KVM_MP_STATE_LOAD the vcpu is in a special load/startup state
[s390]
+ ========================== ===============================================
On x86, this ioctl is only useful after KVM_CREATE_IRQCHIP. Without an
in-kernel irqchip, the multiprocessing state must be maintained by userspace on
these architectures.
For arm/arm64:
+^^^^^^^^^^^^^^
The only states that are valid are KVM_MP_STATE_STOPPED and
KVM_MP_STATE_RUNNABLE which reflect if the vcpu is paused or not.
4.39 KVM_SET_MP_STATE
+---------------------
-Capability: KVM_CAP_MP_STATE
-Architectures: x86, s390, arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_mp_state (in)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_MP_STATE
+:Architectures: x86, s390, arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_mp_state (in)
+:Returns: 0 on success; -1 on error
Sets the vcpu's current "multiprocessing state"; see KVM_GET_MP_STATE for
arguments.
@@ -1294,17 +1419,19 @@ in-kernel irqchip, the multiprocessing state must be maintained by userspace on
these architectures.
For arm/arm64:
+^^^^^^^^^^^^^^
The only states that are valid are KVM_MP_STATE_STOPPED and
KVM_MP_STATE_RUNNABLE which reflect if the vcpu should be paused or not.
4.40 KVM_SET_IDENTITY_MAP_ADDR
+------------------------------
-Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
-Architectures: x86
-Type: vm ioctl
-Parameters: unsigned long identity (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_SET_IDENTITY_MAP_ADDR
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: unsigned long identity (in)
+:Returns: 0 on success, -1 on error
This ioctl defines the physical address of a one-page region in the guest
physical address space. The region must be within the first 4GB of the
@@ -1322,12 +1449,13 @@ documentation when it pops into existence).
Fails if any VCPU has already been created.
4.41 KVM_SET_BOOT_CPU_ID
+------------------------
-Capability: KVM_CAP_SET_BOOT_CPU_ID
-Architectures: x86
-Type: vm ioctl
-Parameters: unsigned long vcpu_id
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_SET_BOOT_CPU_ID
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: unsigned long vcpu_id
+:Returns: 0 on success, -1 on error
Define which vcpu is the Bootstrap Processor (BSP). Values are the same
as the vcpu id in KVM_CREATE_VCPU. If this ioctl is not called, the default
@@ -1335,102 +1463,119 @@ is vcpu 0.
4.42 KVM_GET_XSAVE
+------------------
-Capability: KVM_CAP_XSAVE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_xsave (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XSAVE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_xsave (out)
+:Returns: 0 on success, -1 on error
-struct kvm_xsave {
+
+::
+
+ struct kvm_xsave {
__u32 region[1024];
-};
+ };
This ioctl would copy current vcpu's xsave struct to the userspace.
4.43 KVM_SET_XSAVE
+------------------
-Capability: KVM_CAP_XSAVE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_xsave (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XSAVE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_xsave (in)
+:Returns: 0 on success, -1 on error
-struct kvm_xsave {
+::
+
+
+ struct kvm_xsave {
__u32 region[1024];
-};
+ };
This ioctl would copy userspace's xsave struct to the kernel.
4.44 KVM_GET_XCRS
+-----------------
-Capability: KVM_CAP_XCRS
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_xcrs (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XCRS
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_xcrs (out)
+:Returns: 0 on success, -1 on error
-struct kvm_xcr {
+::
+
+ struct kvm_xcr {
__u32 xcr;
__u32 reserved;
__u64 value;
-};
+ };
-struct kvm_xcrs {
+ struct kvm_xcrs {
__u32 nr_xcrs;
__u32 flags;
struct kvm_xcr xcrs[KVM_MAX_XCRS];
__u64 padding[16];
-};
+ };
This ioctl would copy current vcpu's xcrs to the userspace.
4.45 KVM_SET_XCRS
+-----------------
-Capability: KVM_CAP_XCRS
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_xcrs (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_XCRS
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_xcrs (in)
+:Returns: 0 on success, -1 on error
-struct kvm_xcr {
+::
+
+ struct kvm_xcr {
__u32 xcr;
__u32 reserved;
__u64 value;
-};
+ };
-struct kvm_xcrs {
+ struct kvm_xcrs {
__u32 nr_xcrs;
__u32 flags;
struct kvm_xcr xcrs[KVM_MAX_XCRS];
__u64 padding[16];
-};
+ };
This ioctl would set vcpu's xcr to the value userspace specified.
4.46 KVM_GET_SUPPORTED_CPUID
+----------------------------
-Capability: KVM_CAP_EXT_CPUID
-Architectures: x86
-Type: system ioctl
-Parameters: struct kvm_cpuid2 (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_EXT_CPUID
+:Architectures: x86
+:Type: system ioctl
+:Parameters: struct kvm_cpuid2 (in/out)
+:Returns: 0 on success, -1 on error
-struct kvm_cpuid2 {
+::
+
+ struct kvm_cpuid2 {
__u32 nent;
__u32 padding;
struct kvm_cpuid_entry2 entries[0];
-};
+ };
-#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
-#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
-#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
+ #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
+ #define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
+ #define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
-struct kvm_cpuid_entry2 {
+ struct kvm_cpuid_entry2 {
__u32 function;
__u32 index;
__u32 flags;
@@ -1439,7 +1584,7 @@ struct kvm_cpuid_entry2 {
__u32 ecx;
__u32 edx;
__u32 padding[3];
-};
+ };
This ioctl returns x86 cpuid features which are supported by both the
hardware and kvm in its default configuration. Userspace can use the
@@ -1467,10 +1612,16 @@ with unknown or unsupported features masked out. Some features (for example,
x2apic), may not be present in the host cpu, but are exposed by kvm if it can
emulate them efficiently. The fields in each entry are defined as follows:
- function: the eax value used to obtain the entry
- index: the ecx value used to obtain the entry (for entries that are
+ function:
+ the eax value used to obtain the entry
+
+ index:
+ the ecx value used to obtain the entry (for entries that are
affected by ecx)
- flags: an OR of zero or more of the following:
+
+ flags:
+ an OR of zero or more of the following:
+
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
if the index field is valid
KVM_CPUID_FLAG_STATEFUL_FUNC:
@@ -1480,12 +1631,14 @@ emulate them efficiently. The fields in each entry are defined as follows:
KVM_CPUID_FLAG_STATE_READ_NEXT:
for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
the first entry to be read by a cpu
- eax, ebx, ecx, edx: the values returned by the cpuid instruction for
+
+ eax, ebx, ecx, edx:
+ the values returned by the cpuid instruction for
this function/index combination
The TSC deadline timer feature (CPUID leaf 1, ecx[24]) is always returned
as false, since the feature depends on KVM_CREATE_IRQCHIP for local APIC
-support. Instead it is reported via
+support. Instead it is reported via::
ioctl(KVM_CHECK_EXTENSION, KVM_CAP_TSC_DEADLINE_TIMER)
@@ -1494,18 +1647,21 @@ feature in userspace, then you can enable the feature for KVM_SET_CPUID2.
4.47 KVM_PPC_GET_PVINFO
+-----------------------
-Capability: KVM_CAP_PPC_GET_PVINFO
-Architectures: ppc
-Type: vm ioctl
-Parameters: struct kvm_ppc_pvinfo (out)
-Returns: 0 on success, !0 on error
+:Capability: KVM_CAP_PPC_GET_PVINFO
+:Architectures: ppc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_pvinfo (out)
+:Returns: 0 on success, !0 on error
-struct kvm_ppc_pvinfo {
+::
+
+ struct kvm_ppc_pvinfo {
__u32 flags;
__u32 hcall[4];
__u8 pad[108];
-};
+ };
This ioctl fetches PV specific information that need to be passed to the guest
using the device tree or other means from vm context.
@@ -1515,33 +1671,39 @@ The hcall array defines 4 instructions that make up a hypercall.
If any additional field gets added to this structure later on, a bit for that
additional piece of information will be set in the flags bitmap.
-The flags bitmap is defined as:
+The flags bitmap is defined as::
/* the host supports the ePAPR idle hcall
#define KVM_PPC_PVINFO_FLAGS_EV_IDLE (1<<0)
4.52 KVM_SET_GSI_ROUTING
+------------------------
-Capability: KVM_CAP_IRQ_ROUTING
-Architectures: x86 s390 arm arm64
-Type: vm ioctl
-Parameters: struct kvm_irq_routing (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQ_ROUTING
+:Architectures: x86 s390 arm arm64
+:Type: vm ioctl
+:Parameters: struct kvm_irq_routing (in)
+:Returns: 0 on success, -1 on error
Sets the GSI routing table entries, overwriting any previously set entries.
On arm/arm64, GSI routing has the following limitation:
+
- GSI routing does not apply to KVM_IRQ_LINE but only to KVM_IRQFD.
-struct kvm_irq_routing {
+::
+
+ struct kvm_irq_routing {
__u32 nr;
__u32 flags;
struct kvm_irq_routing_entry entries[0];
-};
+ };
No flags are specified so far, the corresponding field must be set to zero.
-struct kvm_irq_routing_entry {
+::
+
+ struct kvm_irq_routing_entry {
__u32 gsi;
__u32 type;
__u32 flags;
@@ -1553,15 +1715,16 @@ struct kvm_irq_routing_entry {
struct kvm_irq_routing_hv_sint hv_sint;
__u32 pad[8];
} u;
-};
+ };
-/* gsi routing entry types */
-#define KVM_IRQ_ROUTING_IRQCHIP 1
-#define KVM_IRQ_ROUTING_MSI 2
-#define KVM_IRQ_ROUTING_S390_ADAPTER 3
-#define KVM_IRQ_ROUTING_HV_SINT 4
+ /* gsi routing entry types */
+ #define KVM_IRQ_ROUTING_IRQCHIP 1
+ #define KVM_IRQ_ROUTING_MSI 2
+ #define KVM_IRQ_ROUTING_S390_ADAPTER 3
+ #define KVM_IRQ_ROUTING_HV_SINT 4
flags:
+
- KVM_MSI_VALID_DEVID: used along with KVM_IRQ_ROUTING_MSI routing entry
type, specifies that the devid field contains a valid value. The per-VM
KVM_CAP_MSI_DEVID capability advertises the requirement to provide
@@ -1569,12 +1732,14 @@ flags:
never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
- zero otherwise
-struct kvm_irq_routing_irqchip {
+::
+
+ struct kvm_irq_routing_irqchip {
__u32 irqchip;
__u32 pin;
-};
+ };
-struct kvm_irq_routing_msi {
+ struct kvm_irq_routing_msi {
__u32 address_lo;
__u32 address_hi;
__u32 data;
@@ -1582,7 +1747,7 @@ struct kvm_irq_routing_msi {
__u32 pad;
__u32 devid;
};
-};
+ };
If KVM_MSI_VALID_DEVID is set, devid contains a unique device identifier
for the device that wrote the MSI message. For PCI, this is usually a
@@ -1593,39 +1758,43 @@ feature of KVM_CAP_X2APIC_API capability is enabled. If it is enabled,
address_hi bits 31-8 provide bits 31-8 of the destination id. Bits 7-0 of
address_hi must be zero.
-struct kvm_irq_routing_s390_adapter {
+::
+
+ struct kvm_irq_routing_s390_adapter {
__u64 ind_addr;
__u64 summary_addr;
__u64 ind_offset;
__u32 summary_offset;
__u32 adapter_id;
-};
+ };
-struct kvm_irq_routing_hv_sint {
+ struct kvm_irq_routing_hv_sint {
__u32 vcpu;
__u32 sint;
-};
+ };
4.55 KVM_SET_TSC_KHZ
+--------------------
-Capability: KVM_CAP_TSC_CONTROL
-Architectures: x86
-Type: vcpu ioctl
-Parameters: virtual tsc_khz
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_TSC_CONTROL
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: virtual tsc_khz
+:Returns: 0 on success, -1 on error
Specifies the tsc frequency for the virtual machine. The unit of the
frequency is KHz.
4.56 KVM_GET_TSC_KHZ
+--------------------
-Capability: KVM_CAP_GET_TSC_KHZ
-Architectures: x86
-Type: vcpu ioctl
-Parameters: none
-Returns: virtual tsc-khz on success, negative value on error
+:Capability: KVM_CAP_GET_TSC_KHZ
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: none
+:Returns: virtual tsc-khz on success, negative value on error
Returns the tsc frequency of the guest. The unit of the return value is
KHz. If the host has unstable tsc this ioctl returns -EIO instead as an
@@ -1633,17 +1802,20 @@ error.
4.57 KVM_GET_LAPIC
+------------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_lapic_state (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_lapic_state (out)
+:Returns: 0 on success, -1 on error
-#define KVM_APIC_REG_SIZE 0x400
-struct kvm_lapic_state {
+::
+
+ #define KVM_APIC_REG_SIZE 0x400
+ struct kvm_lapic_state {
char regs[KVM_APIC_REG_SIZE];
-};
+ };
Reads the Local APIC registers and copies them into the input argument. The
data format and layout are the same as documented in the architecture manual.
@@ -1661,17 +1833,20 @@ always uses xAPIC format.
4.58 KVM_SET_LAPIC
+------------------
-Capability: KVM_CAP_IRQCHIP
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_lapic_state (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQCHIP
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_lapic_state (in)
+:Returns: 0 on success, -1 on error
-#define KVM_APIC_REG_SIZE 0x400
-struct kvm_lapic_state {
+::
+
+ #define KVM_APIC_REG_SIZE 0x400
+ struct kvm_lapic_state {
char regs[KVM_APIC_REG_SIZE];
-};
+ };
Copies the input argument into the Local APIC registers. The data format
and layout are the same as documented in the architecture manual.
@@ -1682,35 +1857,38 @@ See the note in KVM_GET_LAPIC.
4.59 KVM_IOEVENTFD
+------------------
-Capability: KVM_CAP_IOEVENTFD
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_ioeventfd (in)
-Returns: 0 on success, !0 on error
+:Capability: KVM_CAP_IOEVENTFD
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_ioeventfd (in)
+:Returns: 0 on success, !0 on error
This ioctl attaches or detaches an ioeventfd to a legal pio/mmio address
within the guest. A guest write in the registered address will signal the
provided event instead of triggering an exit.
-struct kvm_ioeventfd {
+::
+
+ struct kvm_ioeventfd {
__u64 datamatch;
__u64 addr; /* legal pio/mmio address */
__u32 len; /* 0, 1, 2, 4, or 8 bytes */
__s32 fd;
__u32 flags;
__u8 pad[36];
-};
+ };
For the special case of virtio-ccw devices on s390, the ioevent is matched
to a subchannel/virtqueue tuple instead.
-The following flags are defined:
+The following flags are defined::
-#define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
-#define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio)
-#define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign)
-#define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \
+ #define KVM_IOEVENTFD_FLAG_DATAMATCH (1 << kvm_ioeventfd_flag_nr_datamatch)
+ #define KVM_IOEVENTFD_FLAG_PIO (1 << kvm_ioeventfd_flag_nr_pio)
+ #define KVM_IOEVENTFD_FLAG_DEASSIGN (1 << kvm_ioeventfd_flag_nr_deassign)
+ #define KVM_IOEVENTFD_FLAG_VIRTIO_CCW_NOTIFY \
(1 << kvm_ioeventfd_flag_nr_virtio_ccw_notify)
If datamatch flag is set, the event will be signaled only if the written value
@@ -1725,17 +1903,20 @@ The speedup may only apply to specific architectures, but the ioeventfd will
work anyway.
4.60 KVM_DIRTY_TLB
+------------------
-Capability: KVM_CAP_SW_TLB
-Architectures: ppc
-Type: vcpu ioctl
-Parameters: struct kvm_dirty_tlb (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_SW_TLB
+:Architectures: ppc
+:Type: vcpu ioctl
+:Parameters: struct kvm_dirty_tlb (in)
+:Returns: 0 on success, -1 on error
-struct kvm_dirty_tlb {
+::
+
+ struct kvm_dirty_tlb {
__u64 bitmap;
__u32 num_dirty;
-};
+ };
This must be called whenever userspace has changed an entry in the shared
TLB, prior to calling KVM_RUN on the associated vcpu.
@@ -1758,23 +1939,26 @@ be set to the number of set bits in the bitmap.
4.62 KVM_CREATE_SPAPR_TCE
+-------------------------
-Capability: KVM_CAP_SPAPR_TCE
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_create_spapr_tce (in)
-Returns: file descriptor for manipulating the created TCE table
+:Capability: KVM_CAP_SPAPR_TCE
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_create_spapr_tce (in)
+:Returns: file descriptor for manipulating the created TCE table
This creates a virtual TCE (translation control entry) table, which
is an IOMMU for PAPR-style virtual I/O. It is used to translate
logical addresses used in virtual I/O into guest physical addresses,
and provides a scatter/gather capability for PAPR virtual I/O.
-/* for KVM_CAP_SPAPR_TCE */
-struct kvm_create_spapr_tce {
+::
+
+ /* for KVM_CAP_SPAPR_TCE */
+ struct kvm_create_spapr_tce {
__u64 liobn;
__u32 window_size;
-};
+ };
The liobn field gives the logical IO bus number for which to create a
TCE table. The window_size field specifies the size of the DMA window
@@ -1794,12 +1978,13 @@ circumstances.
4.63 KVM_ALLOCATE_RMA
+---------------------
-Capability: KVM_CAP_PPC_RMA
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_allocate_rma (out)
-Returns: file descriptor for mapping the allocated RMA
+:Capability: KVM_CAP_PPC_RMA
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_allocate_rma (out)
+:Returns: file descriptor for mapping the allocated RMA
This allocates a Real Mode Area (RMA) from the pool allocated at boot
time by the kernel. An RMA is a physically-contiguous, aligned region
@@ -1808,10 +1993,12 @@ will be accessed by real-mode (MMU off) accesses in a KVM guest.
POWER processors support a set of sizes for the RMA that usually
includes 64MB, 128MB, 256MB and some larger powers of two.
-/* for KVM_ALLOCATE_RMA */
-struct kvm_allocate_rma {
+::
+
+ /* for KVM_ALLOCATE_RMA */
+ struct kvm_allocate_rma {
__u64 rma_size;
-};
+ };
The return value is a file descriptor which can be passed to mmap(2)
to map the allocated RMA into userspace. The mapped area can then be
@@ -1827,12 +2014,13 @@ because it supports the Virtual RMA (VRMA) facility.
4.64 KVM_NMI
+------------
-Capability: KVM_CAP_USER_NMI
-Architectures: x86
-Type: vcpu ioctl
-Parameters: none
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_USER_NMI
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: none
+:Returns: 0 on success, -1 on error
Queues an NMI on the thread's vcpu. Note this is well defined only
when KVM_CREATE_IRQCHIP has not been called, since this is an interface
@@ -1853,14 +2041,16 @@ debugging.
4.65 KVM_S390_UCAS_MAP
+----------------------
-Capability: KVM_CAP_S390_UCONTROL
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_ucas_mapping (in)
-Returns: 0 in case of success
+:Capability: KVM_CAP_S390_UCONTROL
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_ucas_mapping (in)
+:Returns: 0 in case of success
+
+The parameter is defined like this::
-The parameter is defined like this:
struct kvm_s390_ucas_mapping {
__u64 user_addr;
__u64 vcpu_addr;
@@ -1873,14 +2063,16 @@ be aligned by 1 megabyte.
4.66 KVM_S390_UCAS_UNMAP
+------------------------
-Capability: KVM_CAP_S390_UCONTROL
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_ucas_mapping (in)
-Returns: 0 in case of success
+:Capability: KVM_CAP_S390_UCONTROL
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_ucas_mapping (in)
+:Returns: 0 in case of success
+
+The parameter is defined like this::
-The parameter is defined like this:
struct kvm_s390_ucas_mapping {
__u64 user_addr;
__u64 vcpu_addr;
@@ -1893,12 +2085,13 @@ All parameters need to be aligned by 1 megabyte.
4.67 KVM_S390_VCPU_FAULT
+------------------------
-Capability: KVM_CAP_S390_UCONTROL
-Architectures: s390
-Type: vcpu ioctl
-Parameters: vcpu absolute address (in)
-Returns: 0 in case of success
+:Capability: KVM_CAP_S390_UCONTROL
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: vcpu absolute address (in)
+:Returns: 0 in case of success
This call creates a page table entry on the virtual cpu's address space
(for user controlled virtual machines) or the virtual machine's address
@@ -1910,23 +2103,31 @@ prior to calling the KVM_RUN ioctl.
4.68 KVM_SET_ONE_REG
+--------------------
+
+:Capability: KVM_CAP_ONE_REG
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: struct kvm_one_reg (in)
+:Returns: 0 on success, negative value on failure
-Capability: KVM_CAP_ONE_REG
-Architectures: all
-Type: vcpu ioctl
-Parameters: struct kvm_one_reg (in)
-Returns: 0 on success, negative value on failure
Errors:
- ENOENT: no such register
- EINVAL: invalid register ID, or no such register
- EPERM: (arm64) register access not allowed before vcpu finalization
+
+ ====== ============================================================
+ ENOENT no such register
+ EINVAL invalid register ID, or no such register
+ EPERM (arm64) register access not allowed before vcpu finalization
+ ====== ============================================================
+
(These error codes are indicative only: do not rely on a specific error
code being returned in a specific situation.)
-struct kvm_one_reg {
+::
+
+ struct kvm_one_reg {
__u64 id;
__u64 addr;
-};
+ };
Using this ioctl, a single vcpu register can be set to a specific value
defined by user space with the passed in struct kvm_one_reg, where id
@@ -1936,217 +2137,226 @@ and architecture specific registers. Each have their own range of operation
and their own constants and width. To keep track of the implemented
registers, find a list below:
- Arch | Register | Width (bits)
- | |
- PPC | KVM_REG_PPC_HIOR | 64
- PPC | KVM_REG_PPC_IAC1 | 64
- PPC | KVM_REG_PPC_IAC2 | 64
- PPC | KVM_REG_PPC_IAC3 | 64
- PPC | KVM_REG_PPC_IAC4 | 64
- PPC | KVM_REG_PPC_DAC1 | 64
- PPC | KVM_REG_PPC_DAC2 | 64
- PPC | KVM_REG_PPC_DABR | 64
- PPC | KVM_REG_PPC_DSCR | 64
- PPC | KVM_REG_PPC_PURR | 64
- PPC | KVM_REG_PPC_SPURR | 64
- PPC | KVM_REG_PPC_DAR | 64
- PPC | KVM_REG_PPC_DSISR | 32
- PPC | KVM_REG_PPC_AMR | 64
- PPC | KVM_REG_PPC_UAMOR | 64
- PPC | KVM_REG_PPC_MMCR0 | 64
- PPC | KVM_REG_PPC_MMCR1 | 64
- PPC | KVM_REG_PPC_MMCRA | 64
- PPC | KVM_REG_PPC_MMCR2 | 64
- PPC | KVM_REG_PPC_MMCRS | 64
- PPC | KVM_REG_PPC_SIAR | 64
- PPC | KVM_REG_PPC_SDAR | 64
- PPC | KVM_REG_PPC_SIER | 64
- PPC | KVM_REG_PPC_PMC1 | 32
- PPC | KVM_REG_PPC_PMC2 | 32
- PPC | KVM_REG_PPC_PMC3 | 32
- PPC | KVM_REG_PPC_PMC4 | 32
- PPC | KVM_REG_PPC_PMC5 | 32
- PPC | KVM_REG_PPC_PMC6 | 32
- PPC | KVM_REG_PPC_PMC7 | 32
- PPC | KVM_REG_PPC_PMC8 | 32
- PPC | KVM_REG_PPC_FPR0 | 64
- ...
- PPC | KVM_REG_PPC_FPR31 | 64
- PPC | KVM_REG_PPC_VR0 | 128
- ...
- PPC | KVM_REG_PPC_VR31 | 128
- PPC | KVM_REG_PPC_VSR0 | 128
- ...
- PPC | KVM_REG_PPC_VSR31 | 128
- PPC | KVM_REG_PPC_FPSCR | 64
- PPC | KVM_REG_PPC_VSCR | 32
- PPC | KVM_REG_PPC_VPA_ADDR | 64
- PPC | KVM_REG_PPC_VPA_SLB | 128
- PPC | KVM_REG_PPC_VPA_DTL | 128
- PPC | KVM_REG_PPC_EPCR | 32
- PPC | KVM_REG_PPC_EPR | 32
- PPC | KVM_REG_PPC_TCR | 32
- PPC | KVM_REG_PPC_TSR | 32
- PPC | KVM_REG_PPC_OR_TSR | 32
- PPC | KVM_REG_PPC_CLEAR_TSR | 32
- PPC | KVM_REG_PPC_MAS0 | 32
- PPC | KVM_REG_PPC_MAS1 | 32
- PPC | KVM_REG_PPC_MAS2 | 64
- PPC | KVM_REG_PPC_MAS7_3 | 64
- PPC | KVM_REG_PPC_MAS4 | 32
- PPC | KVM_REG_PPC_MAS6 | 32
- PPC | KVM_REG_PPC_MMUCFG | 32
- PPC | KVM_REG_PPC_TLB0CFG | 32
- PPC | KVM_REG_PPC_TLB1CFG | 32
- PPC | KVM_REG_PPC_TLB2CFG | 32
- PPC | KVM_REG_PPC_TLB3CFG | 32
- PPC | KVM_REG_PPC_TLB0PS | 32
- PPC | KVM_REG_PPC_TLB1PS | 32
- PPC | KVM_REG_PPC_TLB2PS | 32
- PPC | KVM_REG_PPC_TLB3PS | 32
- PPC | KVM_REG_PPC_EPTCFG | 32
- PPC | KVM_REG_PPC_ICP_STATE | 64
- PPC | KVM_REG_PPC_VP_STATE | 128
- PPC | KVM_REG_PPC_TB_OFFSET | 64
- PPC | KVM_REG_PPC_SPMC1 | 32
- PPC | KVM_REG_PPC_SPMC2 | 32
- PPC | KVM_REG_PPC_IAMR | 64
- PPC | KVM_REG_PPC_TFHAR | 64
- PPC | KVM_REG_PPC_TFIAR | 64
- PPC | KVM_REG_PPC_TEXASR | 64
- PPC | KVM_REG_PPC_FSCR | 64
- PPC | KVM_REG_PPC_PSPB | 32
- PPC | KVM_REG_PPC_EBBHR | 64
- PPC | KVM_REG_PPC_EBBRR | 64
- PPC | KVM_REG_PPC_BESCR | 64
- PPC | KVM_REG_PPC_TAR | 64
- PPC | KVM_REG_PPC_DPDES | 64
- PPC | KVM_REG_PPC_DAWR | 64
- PPC | KVM_REG_PPC_DAWRX | 64
- PPC | KVM_REG_PPC_CIABR | 64
- PPC | KVM_REG_PPC_IC | 64
- PPC | KVM_REG_PPC_VTB | 64
- PPC | KVM_REG_PPC_CSIGR | 64
- PPC | KVM_REG_PPC_TACR | 64
- PPC | KVM_REG_PPC_TCSCR | 64
- PPC | KVM_REG_PPC_PID | 64
- PPC | KVM_REG_PPC_ACOP | 64
- PPC | KVM_REG_PPC_VRSAVE | 32
- PPC | KVM_REG_PPC_LPCR | 32
- PPC | KVM_REG_PPC_LPCR_64 | 64
- PPC | KVM_REG_PPC_PPR | 64
- PPC | KVM_REG_PPC_ARCH_COMPAT | 32
- PPC | KVM_REG_PPC_DABRX | 32
- PPC | KVM_REG_PPC_WORT | 64
- PPC | KVM_REG_PPC_SPRG9 | 64
- PPC | KVM_REG_PPC_DBSR | 32
- PPC | KVM_REG_PPC_TIDR | 64
- PPC | KVM_REG_PPC_PSSCR | 64
- PPC | KVM_REG_PPC_DEC_EXPIRY | 64
- PPC | KVM_REG_PPC_PTCR | 64
- PPC | KVM_REG_PPC_TM_GPR0 | 64
- ...
- PPC | KVM_REG_PPC_TM_GPR31 | 64
- PPC | KVM_REG_PPC_TM_VSR0 | 128
- ...
- PPC | KVM_REG_PPC_TM_VSR63 | 128
- PPC | KVM_REG_PPC_TM_CR | 64
- PPC | KVM_REG_PPC_TM_LR | 64
- PPC | KVM_REG_PPC_TM_CTR | 64
- PPC | KVM_REG_PPC_TM_FPSCR | 64
- PPC | KVM_REG_PPC_TM_AMR | 64
- PPC | KVM_REG_PPC_TM_PPR | 64
- PPC | KVM_REG_PPC_TM_VRSAVE | 64
- PPC | KVM_REG_PPC_TM_VSCR | 32
- PPC | KVM_REG_PPC_TM_DSCR | 64
- PPC | KVM_REG_PPC_TM_TAR | 64
- PPC | KVM_REG_PPC_TM_XER | 64
- | |
- MIPS | KVM_REG_MIPS_R0 | 64
- ...
- MIPS | KVM_REG_MIPS_R31 | 64
- MIPS | KVM_REG_MIPS_HI | 64
- MIPS | KVM_REG_MIPS_LO | 64
- MIPS | KVM_REG_MIPS_PC | 64
- MIPS | KVM_REG_MIPS_CP0_INDEX | 32
- MIPS | KVM_REG_MIPS_CP0_ENTRYLO0 | 64
- MIPS | KVM_REG_MIPS_CP0_ENTRYLO1 | 64
- MIPS | KVM_REG_MIPS_CP0_CONTEXT | 64
- MIPS | KVM_REG_MIPS_CP0_CONTEXTCONFIG| 32
- MIPS | KVM_REG_MIPS_CP0_USERLOCAL | 64
- MIPS | KVM_REG_MIPS_CP0_XCONTEXTCONFIG| 64
- MIPS | KVM_REG_MIPS_CP0_PAGEMASK | 32
- MIPS | KVM_REG_MIPS_CP0_PAGEGRAIN | 32
- MIPS | KVM_REG_MIPS_CP0_SEGCTL0 | 64
- MIPS | KVM_REG_MIPS_CP0_SEGCTL1 | 64
- MIPS | KVM_REG_MIPS_CP0_SEGCTL2 | 64
- MIPS | KVM_REG_MIPS_CP0_PWBASE | 64
- MIPS | KVM_REG_MIPS_CP0_PWFIELD | 64
- MIPS | KVM_REG_MIPS_CP0_PWSIZE | 64
- MIPS | KVM_REG_MIPS_CP0_WIRED | 32
- MIPS | KVM_REG_MIPS_CP0_PWCTL | 32
- MIPS | KVM_REG_MIPS_CP0_HWRENA | 32
- MIPS | KVM_REG_MIPS_CP0_BADVADDR | 64
- MIPS | KVM_REG_MIPS_CP0_BADINSTR | 32
- MIPS | KVM_REG_MIPS_CP0_BADINSTRP | 32
- MIPS | KVM_REG_MIPS_CP0_COUNT | 32
- MIPS | KVM_REG_MIPS_CP0_ENTRYHI | 64
- MIPS | KVM_REG_MIPS_CP0_COMPARE | 32
- MIPS | KVM_REG_MIPS_CP0_STATUS | 32
- MIPS | KVM_REG_MIPS_CP0_INTCTL | 32
- MIPS | KVM_REG_MIPS_CP0_CAUSE | 32
- MIPS | KVM_REG_MIPS_CP0_EPC | 64
- MIPS | KVM_REG_MIPS_CP0_PRID | 32
- MIPS | KVM_REG_MIPS_CP0_EBASE | 64
- MIPS | KVM_REG_MIPS_CP0_CONFIG | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG1 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG2 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG3 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG4 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG5 | 32
- MIPS | KVM_REG_MIPS_CP0_CONFIG7 | 32
- MIPS | KVM_REG_MIPS_CP0_XCONTEXT | 64
- MIPS | KVM_REG_MIPS_CP0_ERROREPC | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH1 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH2 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH3 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH4 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH5 | 64
- MIPS | KVM_REG_MIPS_CP0_KSCRATCH6 | 64
- MIPS | KVM_REG_MIPS_CP0_MAAR(0..63) | 64
- MIPS | KVM_REG_MIPS_COUNT_CTL | 64
- MIPS | KVM_REG_MIPS_COUNT_RESUME | 64
- MIPS | KVM_REG_MIPS_COUNT_HZ | 64
- MIPS | KVM_REG_MIPS_FPR_32(0..31) | 32
- MIPS | KVM_REG_MIPS_FPR_64(0..31) | 64
- MIPS | KVM_REG_MIPS_VEC_128(0..31) | 128
- MIPS | KVM_REG_MIPS_FCR_IR | 32
- MIPS | KVM_REG_MIPS_FCR_CSR | 32
- MIPS | KVM_REG_MIPS_MSA_IR | 32
- MIPS | KVM_REG_MIPS_MSA_CSR | 32
+ ======= =============================== ============
+ Arch Register Width (bits)
+ ======= =============================== ============
+ PPC KVM_REG_PPC_HIOR 64
+ PPC KVM_REG_PPC_IAC1 64
+ PPC KVM_REG_PPC_IAC2 64
+ PPC KVM_REG_PPC_IAC3 64
+ PPC KVM_REG_PPC_IAC4 64
+ PPC KVM_REG_PPC_DAC1 64
+ PPC KVM_REG_PPC_DAC2 64
+ PPC KVM_REG_PPC_DABR 64
+ PPC KVM_REG_PPC_DSCR 64
+ PPC KVM_REG_PPC_PURR 64
+ PPC KVM_REG_PPC_SPURR 64
+ PPC KVM_REG_PPC_DAR 64
+ PPC KVM_REG_PPC_DSISR 32
+ PPC KVM_REG_PPC_AMR 64
+ PPC KVM_REG_PPC_UAMOR 64
+ PPC KVM_REG_PPC_MMCR0 64
+ PPC KVM_REG_PPC_MMCR1 64
+ PPC KVM_REG_PPC_MMCRA 64
+ PPC KVM_REG_PPC_MMCR2 64
+ PPC KVM_REG_PPC_MMCRS 64
+ PPC KVM_REG_PPC_SIAR 64
+ PPC KVM_REG_PPC_SDAR 64
+ PPC KVM_REG_PPC_SIER 64
+ PPC KVM_REG_PPC_PMC1 32
+ PPC KVM_REG_PPC_PMC2 32
+ PPC KVM_REG_PPC_PMC3 32
+ PPC KVM_REG_PPC_PMC4 32
+ PPC KVM_REG_PPC_PMC5 32
+ PPC KVM_REG_PPC_PMC6 32
+ PPC KVM_REG_PPC_PMC7 32
+ PPC KVM_REG_PPC_PMC8 32
+ PPC KVM_REG_PPC_FPR0 64
+ ...
+ PPC KVM_REG_PPC_FPR31 64
+ PPC KVM_REG_PPC_VR0 128
+ ...
+ PPC KVM_REG_PPC_VR31 128
+ PPC KVM_REG_PPC_VSR0 128
+ ...
+ PPC KVM_REG_PPC_VSR31 128
+ PPC KVM_REG_PPC_FPSCR 64
+ PPC KVM_REG_PPC_VSCR 32
+ PPC KVM_REG_PPC_VPA_ADDR 64
+ PPC KVM_REG_PPC_VPA_SLB 128
+ PPC KVM_REG_PPC_VPA_DTL 128
+ PPC KVM_REG_PPC_EPCR 32
+ PPC KVM_REG_PPC_EPR 32
+ PPC KVM_REG_PPC_TCR 32
+ PPC KVM_REG_PPC_TSR 32
+ PPC KVM_REG_PPC_OR_TSR 32
+ PPC KVM_REG_PPC_CLEAR_TSR 32
+ PPC KVM_REG_PPC_MAS0 32
+ PPC KVM_REG_PPC_MAS1 32
+ PPC KVM_REG_PPC_MAS2 64
+ PPC KVM_REG_PPC_MAS7_3 64
+ PPC KVM_REG_PPC_MAS4 32
+ PPC KVM_REG_PPC_MAS6 32
+ PPC KVM_REG_PPC_MMUCFG 32
+ PPC KVM_REG_PPC_TLB0CFG 32
+ PPC KVM_REG_PPC_TLB1CFG 32
+ PPC KVM_REG_PPC_TLB2CFG 32
+ PPC KVM_REG_PPC_TLB3CFG 32
+ PPC KVM_REG_PPC_TLB0PS 32
+ PPC KVM_REG_PPC_TLB1PS 32
+ PPC KVM_REG_PPC_TLB2PS 32
+ PPC KVM_REG_PPC_TLB3PS 32
+ PPC KVM_REG_PPC_EPTCFG 32
+ PPC KVM_REG_PPC_ICP_STATE 64
+ PPC KVM_REG_PPC_VP_STATE 128
+ PPC KVM_REG_PPC_TB_OFFSET 64
+ PPC KVM_REG_PPC_SPMC1 32
+ PPC KVM_REG_PPC_SPMC2 32
+ PPC KVM_REG_PPC_IAMR 64
+ PPC KVM_REG_PPC_TFHAR 64
+ PPC KVM_REG_PPC_TFIAR 64
+ PPC KVM_REG_PPC_TEXASR 64
+ PPC KVM_REG_PPC_FSCR 64
+ PPC KVM_REG_PPC_PSPB 32
+ PPC KVM_REG_PPC_EBBHR 64
+ PPC KVM_REG_PPC_EBBRR 64
+ PPC KVM_REG_PPC_BESCR 64
+ PPC KVM_REG_PPC_TAR 64
+ PPC KVM_REG_PPC_DPDES 64
+ PPC KVM_REG_PPC_DAWR 64
+ PPC KVM_REG_PPC_DAWRX 64
+ PPC KVM_REG_PPC_CIABR 64
+ PPC KVM_REG_PPC_IC 64
+ PPC KVM_REG_PPC_VTB 64
+ PPC KVM_REG_PPC_CSIGR 64
+ PPC KVM_REG_PPC_TACR 64
+ PPC KVM_REG_PPC_TCSCR 64
+ PPC KVM_REG_PPC_PID 64
+ PPC KVM_REG_PPC_ACOP 64
+ PPC KVM_REG_PPC_VRSAVE 32
+ PPC KVM_REG_PPC_LPCR 32
+ PPC KVM_REG_PPC_LPCR_64 64
+ PPC KVM_REG_PPC_PPR 64
+ PPC KVM_REG_PPC_ARCH_COMPAT 32
+ PPC KVM_REG_PPC_DABRX 32
+ PPC KVM_REG_PPC_WORT 64
+ PPC KVM_REG_PPC_SPRG9 64
+ PPC KVM_REG_PPC_DBSR 32
+ PPC KVM_REG_PPC_TIDR 64
+ PPC KVM_REG_PPC_PSSCR 64
+ PPC KVM_REG_PPC_DEC_EXPIRY 64
+ PPC KVM_REG_PPC_PTCR 64
+ PPC KVM_REG_PPC_TM_GPR0 64
+ ...
+ PPC KVM_REG_PPC_TM_GPR31 64
+ PPC KVM_REG_PPC_TM_VSR0 128
+ ...
+ PPC KVM_REG_PPC_TM_VSR63 128
+ PPC KVM_REG_PPC_TM_CR 64
+ PPC KVM_REG_PPC_TM_LR 64
+ PPC KVM_REG_PPC_TM_CTR 64
+ PPC KVM_REG_PPC_TM_FPSCR 64
+ PPC KVM_REG_PPC_TM_AMR 64
+ PPC KVM_REG_PPC_TM_PPR 64
+ PPC KVM_REG_PPC_TM_VRSAVE 64
+ PPC KVM_REG_PPC_TM_VSCR 32
+ PPC KVM_REG_PPC_TM_DSCR 64
+ PPC KVM_REG_PPC_TM_TAR 64
+ PPC KVM_REG_PPC_TM_XER 64
+
+ MIPS KVM_REG_MIPS_R0 64
+ ...
+ MIPS KVM_REG_MIPS_R31 64
+ MIPS KVM_REG_MIPS_HI 64
+ MIPS KVM_REG_MIPS_LO 64
+ MIPS KVM_REG_MIPS_PC 64
+ MIPS KVM_REG_MIPS_CP0_INDEX 32
+ MIPS KVM_REG_MIPS_CP0_ENTRYLO0 64
+ MIPS KVM_REG_MIPS_CP0_ENTRYLO1 64
+ MIPS KVM_REG_MIPS_CP0_CONTEXT 64
+ MIPS KVM_REG_MIPS_CP0_CONTEXTCONFIG 32
+ MIPS KVM_REG_MIPS_CP0_USERLOCAL 64
+ MIPS KVM_REG_MIPS_CP0_XCONTEXTCONFIG 64
+ MIPS KVM_REG_MIPS_CP0_PAGEMASK 32
+ MIPS KVM_REG_MIPS_CP0_PAGEGRAIN 32
+ MIPS KVM_REG_MIPS_CP0_SEGCTL0 64
+ MIPS KVM_REG_MIPS_CP0_SEGCTL1 64
+ MIPS KVM_REG_MIPS_CP0_SEGCTL2 64
+ MIPS KVM_REG_MIPS_CP0_PWBASE 64
+ MIPS KVM_REG_MIPS_CP0_PWFIELD 64
+ MIPS KVM_REG_MIPS_CP0_PWSIZE 64
+ MIPS KVM_REG_MIPS_CP0_WIRED 32
+ MIPS KVM_REG_MIPS_CP0_PWCTL 32
+ MIPS KVM_REG_MIPS_CP0_HWRENA 32
+ MIPS KVM_REG_MIPS_CP0_BADVADDR 64
+ MIPS KVM_REG_MIPS_CP0_BADINSTR 32
+ MIPS KVM_REG_MIPS_CP0_BADINSTRP 32
+ MIPS KVM_REG_MIPS_CP0_COUNT 32
+ MIPS KVM_REG_MIPS_CP0_ENTRYHI 64
+ MIPS KVM_REG_MIPS_CP0_COMPARE 32
+ MIPS KVM_REG_MIPS_CP0_STATUS 32
+ MIPS KVM_REG_MIPS_CP0_INTCTL 32
+ MIPS KVM_REG_MIPS_CP0_CAUSE 32
+ MIPS KVM_REG_MIPS_CP0_EPC 64
+ MIPS KVM_REG_MIPS_CP0_PRID 32
+ MIPS KVM_REG_MIPS_CP0_EBASE 64
+ MIPS KVM_REG_MIPS_CP0_CONFIG 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG1 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG2 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG3 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG4 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG5 32
+ MIPS KVM_REG_MIPS_CP0_CONFIG7 32
+ MIPS KVM_REG_MIPS_CP0_XCONTEXT 64
+ MIPS KVM_REG_MIPS_CP0_ERROREPC 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH1 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH2 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH3 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH4 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH5 64
+ MIPS KVM_REG_MIPS_CP0_KSCRATCH6 64
+ MIPS KVM_REG_MIPS_CP0_MAAR(0..63) 64
+ MIPS KVM_REG_MIPS_COUNT_CTL 64
+ MIPS KVM_REG_MIPS_COUNT_RESUME 64
+ MIPS KVM_REG_MIPS_COUNT_HZ 64
+ MIPS KVM_REG_MIPS_FPR_32(0..31) 32
+ MIPS KVM_REG_MIPS_FPR_64(0..31) 64
+ MIPS KVM_REG_MIPS_VEC_128(0..31) 128
+ MIPS KVM_REG_MIPS_FCR_IR 32
+ MIPS KVM_REG_MIPS_FCR_CSR 32
+ MIPS KVM_REG_MIPS_MSA_IR 32
+ MIPS KVM_REG_MIPS_MSA_CSR 32
+ ======= =============================== ============
ARM registers are mapped using the lower 32 bits. The upper 16 of that
is the register group type, or coprocessor number:
-ARM core registers have the following id bit patterns:
+ARM core registers have the following id bit patterns::
+
0x4020 0000 0010 <index into the kvm_regs struct:16>
-ARM 32-bit CP15 registers have the following id bit patterns:
+ARM 32-bit CP15 registers have the following id bit patterns::
+
0x4020 0000 000F <zero:1> <crn:4> <crm:4> <opc1:4> <opc2:3>
-ARM 64-bit CP15 registers have the following id bit patterns:
+ARM 64-bit CP15 registers have the following id bit patterns::
+
0x4030 0000 000F <zero:1> <zero:4> <crm:4> <opc1:4> <zero:3>
-ARM CCSIDR registers are demultiplexed by CSSELR value:
+ARM CCSIDR registers are demultiplexed by CSSELR value::
+
0x4020 0000 0011 00 <csselr:8>
-ARM 32-bit VFP control registers have the following id bit patterns:
+ARM 32-bit VFP control registers have the following id bit patterns::
+
0x4020 0000 0012 1 <regno:12>
-ARM 64-bit FP registers have the following id bit patterns:
+ARM 64-bit FP registers have the following id bit patterns::
+
0x4030 0000 0012 0 <regno:12>
-ARM firmware pseudo-registers have the following bit pattern:
+ARM firmware pseudo-registers have the following bit pattern::
+
0x4030 0000 0014 <regno:16>
@@ -2156,15 +2366,18 @@ that is the register group type, or coprocessor number:
arm64 core/FP-SIMD registers have the following id bit patterns. Note
that the size of the access is variable, as the kvm_regs structure
contains elements ranging from 32 to 128 bits. The index is a 32bit
-value in the kvm_regs structure seen as a 32bit array.
+value in the kvm_regs structure seen as a 32bit array::
+
0x60x0 0000 0010 <index into the kvm_regs struct:16>
Specifically:
+
+======================= ========= ===== =======================================
Encoding Register Bits kvm_regs member
-----------------------------------------------------------------
+======================= ========= ===== =======================================
0x6030 0000 0010 0000 X0 64 regs.regs[0]
0x6030 0000 0010 0002 X1 64 regs.regs[1]
- ...
+ ...
0x6030 0000 0010 003c X30 64 regs.regs[30]
0x6030 0000 0010 003e SP 64 regs.sp
0x6030 0000 0010 0040 PC 64 regs.pc
@@ -2176,30 +2389,35 @@ Specifically:
0x6030 0000 0010 004c SPSR_UND 64 spsr[KVM_SPSR_UND]
0x6030 0000 0010 004e SPSR_IRQ 64 spsr[KVM_SPSR_IRQ]
0x6060 0000 0010 0050 SPSR_FIQ 64 spsr[KVM_SPSR_FIQ]
- 0x6040 0000 0010 0054 V0 128 fp_regs.vregs[0] (*)
- 0x6040 0000 0010 0058 V1 128 fp_regs.vregs[1] (*)
- ...
- 0x6040 0000 0010 00d0 V31 128 fp_regs.vregs[31] (*)
+ 0x6040 0000 0010 0054 V0 128 fp_regs.vregs[0] [1]_
+ 0x6040 0000 0010 0058 V1 128 fp_regs.vregs[1] [1]_
+ ...
+ 0x6040 0000 0010 00d0 V31 128 fp_regs.vregs[31] [1]_
0x6020 0000 0010 00d4 FPSR 32 fp_regs.fpsr
0x6020 0000 0010 00d5 FPCR 32 fp_regs.fpcr
+======================= ========= ===== =======================================
-(*) These encodings are not accepted for SVE-enabled vcpus. See
- KVM_ARM_VCPU_INIT.
+.. [1] These encodings are not accepted for SVE-enabled vcpus. See
+ KVM_ARM_VCPU_INIT.
- The equivalent register content can be accessed via bits [127:0] of
- the corresponding SVE Zn registers instead for vcpus that have SVE
- enabled (see below).
+ The equivalent register content can be accessed via bits [127:0] of
+ the corresponding SVE Zn registers instead for vcpus that have SVE
+ enabled (see below).
+
+arm64 CCSIDR registers are demultiplexed by CSSELR value::
-arm64 CCSIDR registers are demultiplexed by CSSELR value:
0x6020 0000 0011 00 <csselr:8>
-arm64 system registers have the following id bit patterns:
+arm64 system registers have the following id bit patterns::
+
0x6030 0000 0013 <op0:2> <op1:3> <crn:4> <crm:4> <op2:3>
-arm64 firmware pseudo-registers have the following bit pattern:
+arm64 firmware pseudo-registers have the following bit pattern::
+
0x6030 0000 0014 <regno:16>
-arm64 SVE registers have the following bit patterns:
+arm64 SVE registers have the following bit patterns::
+
0x6080 0000 0015 00 <n:5> <slice:5> Zn bits[2048*slice + 2047 : 2048*slice]
0x6050 0000 0015 04 <n:4> <slice:5> Pn bits[256*slice + 255 : 256*slice]
0x6050 0000 0015 060 <slice:5> FFR bits[256*slice + 255 : 256*slice]
@@ -2207,7 +2425,7 @@ arm64 SVE registers have the following bit patterns:
Access to register IDs where 2048 * slice >= 128 * max_vq will fail with
ENOENT. max_vq is the vcpu's maximum supported vector length in 128-bit
-quadwords: see (**) below.
+quadwords: see [2]_ below.
These registers are only accessible on vcpus for which SVE is enabled.
See KVM_ARM_VCPU_INIT for details.
@@ -2222,21 +2440,21 @@ lengths supported by the vcpu to be discovered and configured by
userspace. When transferred to or from user memory via KVM_GET_ONE_REG
or KVM_SET_ONE_REG, the value of this register is of type
__u64[KVM_ARM64_SVE_VLS_WORDS], and encodes the set of vector lengths as
-follows:
+follows::
-__u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS];
+ __u64 vector_lengths[KVM_ARM64_SVE_VLS_WORDS];
-if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX &&
- ((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >>
+ if (vq >= SVE_VQ_MIN && vq <= SVE_VQ_MAX &&
+ ((vector_lengths[(vq - KVM_ARM64_SVE_VQ_MIN) / 64] >>
((vq - KVM_ARM64_SVE_VQ_MIN) % 64)) & 1))
/* Vector length vq * 16 bytes supported */
-else
+ else
/* Vector length vq * 16 bytes not supported */
-(**) The maximum value vq for which the above condition is true is
-max_vq. This is the maximum vector length available to the guest on
-this vcpu, and determines which register slices are visible through
-this ioctl interface.
+.. [2] The maximum value vq for which the above condition is true is
+ max_vq. This is the maximum vector length available to the guest on
+ this vcpu, and determines which register slices are visible through
+ this ioctl interface.
(See Documentation/arm64/sve.rst for an explanation of the "vq"
nomenclature.)
@@ -2261,11 +2479,13 @@ write this register will fail with EPERM.
MIPS registers are mapped using the lower 32 bits. The upper 16 of that is
the register group type:
-MIPS core registers (see above) have the following id bit patterns:
+MIPS core registers (see above) have the following id bit patterns::
+
0x7030 0000 0000 <reg:16>
MIPS CP0 registers (see KVM_REG_MIPS_CP0_* above) have the following id bit
-patterns depending on whether they're 32-bit or 64-bit registers:
+patterns depending on whether they're 32-bit or 64-bit registers::
+
0x7020 0000 0001 00 <reg:5> <sel:3> (32-bit)
0x7030 0000 0001 00 <reg:5> <sel:3> (64-bit)
@@ -2276,10 +2496,12 @@ with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and
the PFNX field starting at bit 30.
MIPS MAARs (see KVM_REG_MIPS_CP0_MAAR(*) above) have the following id bit
-patterns:
+patterns::
+
0x7030 0000 0001 01 <reg:8>
-MIPS KVM control registers (see above) have the following id bit patterns:
+MIPS KVM control registers (see above) have the following id bit patterns::
+
0x7030 0000 0002 <reg:16>
MIPS FPU registers (see KVM_REG_MIPS_FPR_{32,64}() above) have the following
@@ -2288,31 +2510,40 @@ always accessed according to the current guest FPU mode (Status.FR and
Config5.FRE), i.e. as the guest would see them, and they become unpredictable
if the guest FPU mode is changed. MIPS SIMD Architecture (MSA) vector
registers (see KVM_REG_MIPS_VEC_128() above) have similar patterns as they
-overlap the FPU registers:
+overlap the FPU registers::
+
0x7020 0000 0003 00 <0:3> <reg:5> (32-bit FPU registers)
0x7030 0000 0003 00 <0:3> <reg:5> (64-bit FPU registers)
0x7040 0000 0003 00 <0:3> <reg:5> (128-bit MSA vector registers)
MIPS FPU control registers (see KVM_REG_MIPS_FCR_{IR,CSR} above) have the
-following id bit patterns:
+following id bit patterns::
+
0x7020 0000 0003 01 <0:3> <reg:5>
MIPS MSA control registers (see KVM_REG_MIPS_MSA_{IR,CSR} above) have the
-following id bit patterns:
+following id bit patterns::
+
0x7020 0000 0003 02 <0:3> <reg:5>
4.69 KVM_GET_ONE_REG
+--------------------
+
+:Capability: KVM_CAP_ONE_REG
+:Architectures: all
+:Type: vcpu ioctl
+:Parameters: struct kvm_one_reg (in and out)
+:Returns: 0 on success, negative value on failure
-Capability: KVM_CAP_ONE_REG
-Architectures: all
-Type: vcpu ioctl
-Parameters: struct kvm_one_reg (in and out)
-Returns: 0 on success, negative value on failure
Errors include:
- ENOENT: no such register
- EINVAL: invalid register ID, or no such register
- EPERM: (arm64) register access not allowed before vcpu finalization
+
+ ======== ============================================================
+ ENOENT no such register
+ EINVAL invalid register ID, or no such register
+ EPERM (arm64) register access not allowed before vcpu finalization
+ ======== ============================================================
+
(These error codes are indicative only: do not rely on a specific error
code being returned in a specific situation.)
@@ -2326,12 +2557,13 @@ list in 4.68.
4.70 KVM_KVMCLOCK_CTRL
+----------------------
-Capability: KVM_CAP_KVMCLOCK_CTRL
-Architectures: Any that implement pvclocks (currently x86 only)
-Type: vcpu ioctl
-Parameters: None
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_KVMCLOCK_CTRL
+:Architectures: Any that implement pvclocks (currently x86 only)
+:Type: vcpu ioctl
+:Parameters: None
+:Returns: 0 on success, -1 on error
This signals to the host kernel that the specified guest is being paused by
userspace. The host will set a flag in the pvclock structure that is checked
@@ -2347,26 +2579,30 @@ after pausing the vcpu, but before it is resumed.
4.71 KVM_SIGNAL_MSI
+-------------------
-Capability: KVM_CAP_SIGNAL_MSI
-Architectures: x86 arm arm64
-Type: vm ioctl
-Parameters: struct kvm_msi (in)
-Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
+:Capability: KVM_CAP_SIGNAL_MSI
+:Architectures: x86 arm arm64
+:Type: vm ioctl
+:Parameters: struct kvm_msi (in)
+:Returns: >0 on delivery, 0 if guest blocked the MSI, and -1 on error
Directly inject a MSI message. Only valid with in-kernel irqchip that handles
MSI messages.
-struct kvm_msi {
+::
+
+ struct kvm_msi {
__u32 address_lo;
__u32 address_hi;
__u32 data;
__u32 flags;
__u32 devid;
__u8 pad[12];
-};
+ };
-flags: KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM
+flags:
+ KVM_MSI_VALID_DEVID: devid contains a valid value. The per-VM
KVM_CAP_MSI_DEVID capability advertises the requirement to provide
the device ID. If this capability is not available, userspace
should never set the KVM_MSI_VALID_DEVID flag as the ioctl might fail.
@@ -2382,30 +2618,31 @@ address_hi must be zero.
4.71 KVM_CREATE_PIT2
+--------------------
-Capability: KVM_CAP_PIT2
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_pit_config (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PIT2
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_pit_config (in)
+:Returns: 0 on success, -1 on error
Creates an in-kernel device model for the i8254 PIT. This call is only valid
after enabling in-kernel irqchip support via KVM_CREATE_IRQCHIP. The following
-parameters have to be passed:
+parameters have to be passed::
-struct kvm_pit_config {
+ struct kvm_pit_config {
__u32 flags;
__u32 pad[15];
-};
+ };
-Valid flags are:
+Valid flags are::
-#define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */
+ #define KVM_PIT_SPEAKER_DUMMY 1 /* emulate speaker port stub */
PIT timer interrupts may use a per-VM kernel thread for injection. If it
-exists, this thread will have a name of the following pattern:
+exists, this thread will have a name of the following pattern::
-kvm-pit/<owner-process-pid>
+ kvm-pit/<owner-process-pid>
When running a guest with elevated priorities, the scheduling parameters of
this thread may have to be adjusted accordingly.
@@ -2414,37 +2651,39 @@ This IOCTL replaces the obsolete KVM_CREATE_PIT.
4.72 KVM_GET_PIT2
+-----------------
-Capability: KVM_CAP_PIT_STATE2
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_pit_state2 (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PIT_STATE2
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_pit_state2 (out)
+:Returns: 0 on success, -1 on error
Retrieves the state of the in-kernel PIT model. Only valid after
-KVM_CREATE_PIT2. The state is returned in the following structure:
+KVM_CREATE_PIT2. The state is returned in the following structure::
-struct kvm_pit_state2 {
+ struct kvm_pit_state2 {
struct kvm_pit_channel_state channels[3];
__u32 flags;
__u32 reserved[9];
-};
+ };
-Valid flags are:
+Valid flags are::
-/* disable PIT in HPET legacy mode */
-#define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001
+ /* disable PIT in HPET legacy mode */
+ #define KVM_PIT_FLAGS_HPET_LEGACY 0x00000001
This IOCTL replaces the obsolete KVM_GET_PIT.
4.73 KVM_SET_PIT2
+-----------------
-Capability: KVM_CAP_PIT_STATE2
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_pit_state2 (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PIT_STATE2
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_pit_state2 (in)
+:Returns: 0 on success, -1 on error
Sets the state of the in-kernel PIT model. Only valid after KVM_CREATE_PIT2.
See KVM_GET_PIT2 for details on struct kvm_pit_state2.
@@ -2453,12 +2692,13 @@ This IOCTL replaces the obsolete KVM_SET_PIT.
4.74 KVM_PPC_GET_SMMU_INFO
+--------------------------
-Capability: KVM_CAP_PPC_GET_SMMU_INFO
-Architectures: powerpc
-Type: vm ioctl
-Parameters: None
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PPC_GET_SMMU_INFO
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: None
+:Returns: 0 on success, -1 on error
This populates and returns a structure describing the features of
the "Server" class MMU emulation supported by KVM.
@@ -2466,7 +2706,7 @@ This can in turn be used by userspace to generate the appropriate
device-tree properties for the guest operating system.
The structure contains some global information, followed by an
-array of supported segment page sizes:
+array of supported segment page sizes::
struct kvm_ppc_smmu_info {
__u64 flags;
@@ -2494,7 +2734,7 @@ The "slb_size" field indicates how many SLB entries are supported
The "sps" array contains 8 entries indicating the supported base
page sizes for a segment in increasing order. Each entry is defined
-as follow:
+as follow::
struct kvm_ppc_one_seg_page_size {
__u32 page_shift; /* Base page shift of segment (or 0) */
@@ -2515,7 +2755,7 @@ size provides the list of supported actual page sizes (which can be
only larger or equal to the base page size), along with the
corresponding encoding in the hash PTE. Similarly, the array is
8 entries sorted by increasing sizes and an entry with a "0" shift
-is an empty entry and a terminator:
+is an empty entry and a terminator::
struct kvm_ppc_one_page_size {
__u32 page_shift; /* Page shift (or 0) */
@@ -2527,12 +2767,13 @@ PTE's RPN field (ie, it needs to be shifted left by 12 to OR it
into the hash PTE second double word).
4.75 KVM_IRQFD
+--------------
-Capability: KVM_CAP_IRQFD
-Architectures: x86 s390 arm arm64
-Type: vm ioctl
-Parameters: struct kvm_irqfd (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_IRQFD
+:Architectures: x86 s390 arm arm64
+:Type: vm ioctl
+:Parameters: struct kvm_irqfd (in)
+:Returns: 0 on success, -1 on error
Allows setting an eventfd to directly trigger a guest interrupt.
kvm_irqfd.fd specifies the file descriptor to use as the eventfd and
@@ -2556,6 +2797,7 @@ irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment
and need not be specified with KVM_IRQFD_FLAG_DEASSIGN.
On arm/arm64, gsi routing being supported, the following can happen:
+
- in case no routing entry is associated to this gsi, injection fails
- in case the gsi is associated to an irqchip routing entry,
irqchip.pin + 32 corresponds to the injected SPI ID.
@@ -2564,12 +2806,13 @@ On arm/arm64, gsi routing being supported, the following can happen:
to GICv3 ITS in-kernel emulation).
4.76 KVM_PPC_ALLOCATE_HTAB
+--------------------------
-Capability: KVM_CAP_PPC_ALLOC_HTAB
-Architectures: powerpc
-Type: vm ioctl
-Parameters: Pointer to u32 containing hash table order (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PPC_ALLOC_HTAB
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: Pointer to u32 containing hash table order (in/out)
+:Returns: 0 on success, -1 on error
This requests the host kernel to allocate an MMU hash table for a
guest using the PAPR paravirtualization interface. This only does
@@ -2600,75 +2843,88 @@ real-mode area (VRMA) facility, the kernel will re-create the VMRA
HPTEs on the next KVM_RUN of any vcpu.
4.77 KVM_S390_INTERRUPT
+-----------------------
-Capability: basic
-Architectures: s390
-Type: vm ioctl, vcpu ioctl
-Parameters: struct kvm_s390_interrupt (in)
-Returns: 0 on success, -1 on error
+:Capability: basic
+:Architectures: s390
+:Type: vm ioctl, vcpu ioctl
+:Parameters: struct kvm_s390_interrupt (in)
+:Returns: 0 on success, -1 on error
Allows to inject an interrupt to the guest. Interrupts can be floating
(vm ioctl) or per cpu (vcpu ioctl), depending on the interrupt type.
-Interrupt parameters are passed via kvm_s390_interrupt:
+Interrupt parameters are passed via kvm_s390_interrupt::
-struct kvm_s390_interrupt {
+ struct kvm_s390_interrupt {
__u32 type;
__u32 parm;
__u64 parm64;
-};
+ };
type can be one of the following:
-KVM_S390_SIGP_STOP (vcpu) - sigp stop; optional flags in parm
-KVM_S390_PROGRAM_INT (vcpu) - program check; code in parm
-KVM_S390_SIGP_SET_PREFIX (vcpu) - sigp set prefix; prefix address in parm
-KVM_S390_RESTART (vcpu) - restart
-KVM_S390_INT_CLOCK_COMP (vcpu) - clock comparator interrupt
-KVM_S390_INT_CPU_TIMER (vcpu) - CPU timer interrupt
-KVM_S390_INT_VIRTIO (vm) - virtio external interrupt; external interrupt
- parameters in parm and parm64
-KVM_S390_INT_SERVICE (vm) - sclp external interrupt; sclp parameter in parm
-KVM_S390_INT_EMERGENCY (vcpu) - sigp emergency; source cpu in parm
-KVM_S390_INT_EXTERNAL_CALL (vcpu) - sigp external call; source cpu in parm
-KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm) - compound value to indicate an
- I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel);
- I/O interruption parameters in parm (subchannel) and parm64 (intparm,
- interruption subclass)
-KVM_S390_MCHK (vm, vcpu) - machine check interrupt; cr 14 bits in parm,
- machine check interrupt code in parm64 (note that
- machine checks needing further payload are not
- supported by this ioctl)
+KVM_S390_SIGP_STOP (vcpu)
+ - sigp stop; optional flags in parm
+KVM_S390_PROGRAM_INT (vcpu)
+ - program check; code in parm
+KVM_S390_SIGP_SET_PREFIX (vcpu)
+ - sigp set prefix; prefix address in parm
+KVM_S390_RESTART (vcpu)
+ - restart
+KVM_S390_INT_CLOCK_COMP (vcpu)
+ - clock comparator interrupt
+KVM_S390_INT_CPU_TIMER (vcpu)
+ - CPU timer interrupt
+KVM_S390_INT_VIRTIO (vm)
+ - virtio external interrupt; external interrupt
+ parameters in parm and parm64
+KVM_S390_INT_SERVICE (vm)
+ - sclp external interrupt; sclp parameter in parm
+KVM_S390_INT_EMERGENCY (vcpu)
+ - sigp emergency; source cpu in parm
+KVM_S390_INT_EXTERNAL_CALL (vcpu)
+ - sigp external call; source cpu in parm
+KVM_S390_INT_IO(ai,cssid,ssid,schid) (vm)
+ - compound value to indicate an
+ I/O interrupt (ai - adapter interrupt; cssid,ssid,schid - subchannel);
+ I/O interruption parameters in parm (subchannel) and parm64 (intparm,
+ interruption subclass)
+KVM_S390_MCHK (vm, vcpu)
+ - machine check interrupt; cr 14 bits in parm, machine check interrupt
+ code in parm64 (note that machine checks needing further payload are not
+ supported by this ioctl)
This is an asynchronous vcpu ioctl and can be invoked from any thread.
4.78 KVM_PPC_GET_HTAB_FD
+------------------------
-Capability: KVM_CAP_PPC_HTAB_FD
-Architectures: powerpc
-Type: vm ioctl
-Parameters: Pointer to struct kvm_get_htab_fd (in)
-Returns: file descriptor number (>= 0) on success, -1 on error
+:Capability: KVM_CAP_PPC_HTAB_FD
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: Pointer to struct kvm_get_htab_fd (in)
+:Returns: file descriptor number (>= 0) on success, -1 on error
This returns a file descriptor that can be used either to read out the
entries in the guest's hashed page table (HPT), or to write entries to
initialize the HPT. The returned fd can only be written to if the
KVM_GET_HTAB_WRITE bit is set in the flags field of the argument, and
can only be read if that bit is clear. The argument struct looks like
-this:
+this::
-/* For KVM_PPC_GET_HTAB_FD */
-struct kvm_get_htab_fd {
+ /* For KVM_PPC_GET_HTAB_FD */
+ struct kvm_get_htab_fd {
__u64 flags;
__u64 start_index;
__u64 reserved[2];
-};
+ };
-/* Values for kvm_get_htab_fd.flags */
-#define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1)
-#define KVM_GET_HTAB_WRITE ((__u64)0x2)
+ /* Values for kvm_get_htab_fd.flags */
+ #define KVM_GET_HTAB_BOLTED_ONLY ((__u64)0x1)
+ #define KVM_GET_HTAB_WRITE ((__u64)0x2)
-The `start_index' field gives the index in the HPT of the entry at
+The 'start_index' field gives the index in the HPT of the entry at
which to start reading. It is ignored when writing.
Reads on the fd will initially supply information about all
@@ -2683,29 +2939,34 @@ Data read or written is structured as a header (8 bytes) followed by a
series of valid HPT entries (16 bytes) each. The header indicates how
many valid HPT entries there are and how many invalid entries follow
the valid entries. The invalid entries are not represented explicitly
-in the stream. The header format is:
+in the stream. The header format is::
-struct kvm_get_htab_header {
+ struct kvm_get_htab_header {
__u32 index;
__u16 n_valid;
__u16 n_invalid;
-};
+ };
Writes to the fd create HPT entries starting at the index given in the
-header; first `n_valid' valid entries with contents from the data
-written, then `n_invalid' invalid entries, invalidating any previously
+header; first 'n_valid' valid entries with contents from the data
+written, then 'n_invalid' invalid entries, invalidating any previously
valid entries found.
4.79 KVM_CREATE_DEVICE
+----------------------
+
+:Capability: KVM_CAP_DEVICE_CTRL
+:Type: vm ioctl
+:Parameters: struct kvm_create_device (in/out)
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_DEVICE_CTRL
-Type: vm ioctl
-Parameters: struct kvm_create_device (in/out)
-Returns: 0 on success, -1 on error
Errors:
- ENODEV: The device type is unknown or unsupported
- EEXIST: Device already created, and this type of device may not
+
+ ====== =======================================================
+ ENODEV The device type is unknown or unsupported
+ EEXIST Device already created, and this type of device may not
be instantiated multiple times
+ ====== =======================================================
Other error conditions may be defined by individual device types or
have their standard meanings.
@@ -2721,25 +2982,32 @@ Individual devices should not define flags. Attributes should be used
for specifying any behavior that is not implied by the device type
number.
-struct kvm_create_device {
+::
+
+ struct kvm_create_device {
__u32 type; /* in: KVM_DEV_TYPE_xxx */
__u32 fd; /* out: device handle */
__u32 flags; /* in: KVM_CREATE_DEVICE_xxx */
-};
+ };
4.80 KVM_SET_DEVICE_ATTR/KVM_GET_DEVICE_ATTR
+--------------------------------------------
+
+:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
+ KVM_CAP_VCPU_ATTRIBUTES for vcpu device
+:Type: device ioctl, vm ioctl, vcpu ioctl
+:Parameters: struct kvm_device_attr
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
- KVM_CAP_VCPU_ATTRIBUTES for vcpu device
-Type: device ioctl, vm ioctl, vcpu ioctl
-Parameters: struct kvm_device_attr
-Returns: 0 on success, -1 on error
Errors:
- 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.
- EPERM: The attribute cannot (currently) be accessed this way
+ EPERM The attribute cannot (currently) be accessed this way
(e.g. read-only attribute, or attribute that only makes
sense when the device is in a different state)
+ ===== =============================================================
Other error conditions may be defined by individual device types.
@@ -2748,23 +3016,30 @@ semantics are device-specific. See individual device documentation in
the "devices" directory. As with ONE_REG, the size of the data
transferred is defined by the particular attribute.
-struct kvm_device_attr {
+::
+
+ struct kvm_device_attr {
__u32 flags; /* no flags currently defined */
__u32 group; /* device-defined */
__u64 attr; /* group-defined */
__u64 addr; /* userspace address of attr data */
-};
+ };
4.81 KVM_HAS_DEVICE_ATTR
+------------------------
+
+:Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
+ KVM_CAP_VCPU_ATTRIBUTES for vcpu device
+:Type: device ioctl, vm ioctl, vcpu ioctl
+:Parameters: struct kvm_device_attr
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_DEVICE_CTRL, KVM_CAP_VM_ATTRIBUTES for vm device,
- KVM_CAP_VCPU_ATTRIBUTES for vcpu device
-Type: device ioctl, vm ioctl, vcpu ioctl
-Parameters: struct kvm_device_attr
-Returns: 0 on success, -1 on error
Errors:
- 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.
+ ===== =============================================================
Tests whether a device supports a particular attribute. A successful
return indicates the attribute is implemented. It does not necessarily
@@ -2772,15 +3047,20 @@ indicate that the attribute can be read or written in the device's
current state. "addr" is ignored.
4.82 KVM_ARM_VCPU_INIT
+----------------------
+
+:Capability: basic
+:Architectures: arm, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_vcpu_init (in)
+:Returns: 0 on success; -1 on error
-Capability: basic
-Architectures: arm, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_vcpu_init (in)
-Returns: 0 on success; -1 on error
Errors:
- EINVAL: the target is unknown, or the combination of features is invalid.
- ENOENT: a features bit specified is unknown.
+
+ ====== =================================================================
+ EINVAL the target is unknown, or the combination of features is invalid.
+ ENOENT a features bit specified is unknown.
+ ====== =================================================================
This tells KVM what type of CPU to present to the guest, and what
optional features it should have. This will cause a reset of the cpu
@@ -2796,6 +3076,7 @@ state. All calls to this function after the initial call must use the same
target and same set of feature flags, otherwise EINVAL will be returned.
Possible features:
+
- KVM_ARM_VCPU_POWER_OFF: Starts the CPU in a power-off state.
Depends on KVM_CAP_ARM_PSCI. If not set, the CPU will be powered on
and execute guest code when KVM_RUN is called.
@@ -2852,14 +3133,19 @@ Possible features:
no longer be written using KVM_SET_ONE_REG.
4.83 KVM_ARM_PREFERRED_TARGET
+-----------------------------
+
+:Capability: basic
+:Architectures: arm, arm64
+:Type: vm ioctl
+:Parameters: struct struct kvm_vcpu_init (out)
+:Returns: 0 on success; -1 on error
-Capability: basic
-Architectures: arm, arm64
-Type: vm ioctl
-Parameters: struct struct kvm_vcpu_init (out)
-Returns: 0 on success; -1 on error
Errors:
- ENODEV: no preferred target available for the host
+
+ ====== ==========================================
+ ENODEV no preferred target available for the host
+ ====== ==========================================
This queries KVM for preferred CPU target type which can be emulated
by KVM on underlying host.
@@ -2876,43 +3162,57 @@ in VCPU matching underlying host.
4.84 KVM_GET_REG_LIST
+---------------------
+
+:Capability: basic
+:Architectures: arm, arm64, mips
+:Type: vcpu ioctl
+:Parameters: struct kvm_reg_list (in/out)
+:Returns: 0 on success; -1 on error
-Capability: basic
-Architectures: arm, arm64, mips
-Type: vcpu ioctl
-Parameters: struct kvm_reg_list (in/out)
-Returns: 0 on success; -1 on error
Errors:
- E2BIG: the reg index list is too big to fit in the array specified by
+
+ ===== ==============================================================
+ E2BIG the reg index list is too big to fit in the array specified by
the user (the number required will be written into n).
+ ===== ==============================================================
-struct kvm_reg_list {
+::
+
+ struct kvm_reg_list {
__u64 n; /* number of registers in reg[] */
__u64 reg[0];
-};
+ };
This ioctl returns the guest registers that are supported for the
KVM_GET_ONE_REG/KVM_SET_ONE_REG calls.
4.85 KVM_ARM_SET_DEVICE_ADDR (deprecated)
+-----------------------------------------
+
+:Capability: KVM_CAP_ARM_SET_DEVICE_ADDR
+:Architectures: arm, arm64
+:Type: vm ioctl
+:Parameters: struct kvm_arm_device_address (in)
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_ARM_SET_DEVICE_ADDR
-Architectures: arm, arm64
-Type: vm ioctl
-Parameters: struct kvm_arm_device_address (in)
-Returns: 0 on success, -1 on error
Errors:
- ENODEV: The device id is unknown
- ENXIO: Device not supported on current system
- EEXIST: Address already set
- E2BIG: Address outside guest physical address space
- EBUSY: Address overlaps with other device range
-struct kvm_arm_device_addr {
+ ====== ============================================
+ ENODEV The device id is unknown
+ ENXIO Device not supported on current system
+ EEXIST Address already set
+ E2BIG Address outside guest physical address space
+ EBUSY Address overlaps with other device range
+ ====== ============================================
+
+::
+
+ struct kvm_arm_device_addr {
__u64 id;
__u64 addr;
-};
+ };
Specify a device address in the guest's physical address space where guests
can access emulated or directly exposed devices, which the host kernel needs
@@ -2920,7 +3220,7 @@ to know about. The id field is an architecture specific identifier for a
specific device.
ARM/arm64 divides the id field into two parts, a device id and an
-address type id specific to the individual device.
+address type id specific to the individual device::
bits: | 63 ... 32 | 31 ... 16 | 15 ... 0 |
field: | 0x00000000 | device id | addr type id |
@@ -2938,12 +3238,13 @@ should be used instead.
4.86 KVM_PPC_RTAS_DEFINE_TOKEN
+------------------------------
-Capability: KVM_CAP_PPC_RTAS
-Architectures: ppc
-Type: vm ioctl
-Parameters: struct kvm_rtas_token_args
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PPC_RTAS
+:Architectures: ppc
+:Type: vm ioctl
+:Parameters: struct kvm_rtas_token_args
+:Returns: 0 on success, -1 on error
Defines a token value for a RTAS (Run Time Abstraction Services)
service in order to allow it to be handled in the kernel. The
@@ -2957,18 +3258,21 @@ calls by the guest for that service will be passed to userspace to be
handled.
4.87 KVM_SET_GUEST_DEBUG
+------------------------
-Capability: KVM_CAP_SET_GUEST_DEBUG
-Architectures: x86, s390, ppc, arm64
-Type: vcpu ioctl
-Parameters: struct kvm_guest_debug (in)
-Returns: 0 on success; -1 on error
+:Capability: KVM_CAP_SET_GUEST_DEBUG
+:Architectures: x86, s390, ppc, arm64
+:Type: vcpu ioctl
+:Parameters: struct kvm_guest_debug (in)
+:Returns: 0 on success; -1 on error
-struct kvm_guest_debug {
+::
+
+ struct kvm_guest_debug {
__u32 control;
__u32 pad;
struct kvm_guest_debug_arch arch;
-};
+ };
Set up the processor specific debug registers and configure vcpu for
handling guest debug events. There are two parts to the structure, the
@@ -3010,26 +3314,31 @@ KVM_EXIT_DEBUG with the kvm_debug_exit_arch part of the kvm_run
structure containing architecture specific debug information.
4.88 KVM_GET_EMULATED_CPUID
+---------------------------
-Capability: KVM_CAP_EXT_EMUL_CPUID
-Architectures: x86
-Type: system ioctl
-Parameters: struct kvm_cpuid2 (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_EXT_EMUL_CPUID
+:Architectures: x86
+:Type: system ioctl
+:Parameters: struct kvm_cpuid2 (in/out)
+:Returns: 0 on success, -1 on error
-struct kvm_cpuid2 {
+::
+
+ struct kvm_cpuid2 {
__u32 nent;
__u32 flags;
struct kvm_cpuid_entry2 entries[0];
-};
+ };
The member 'flags' is used for passing flags from userspace.
-#define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
-#define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
-#define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
+::
-struct kvm_cpuid_entry2 {
+ #define KVM_CPUID_FLAG_SIGNIFCANT_INDEX BIT(0)
+ #define KVM_CPUID_FLAG_STATEFUL_FUNC BIT(1)
+ #define KVM_CPUID_FLAG_STATE_READ_NEXT BIT(2)
+
+ struct kvm_cpuid_entry2 {
__u32 function;
__u32 index;
__u32 flags;
@@ -3038,7 +3347,7 @@ struct kvm_cpuid_entry2 {
__u32 ecx;
__u32 edx;
__u32 padding[3];
-};
+ };
This ioctl returns x86 cpuid features which are emulated by
kvm.Userspace can use the information returned by this ioctl to query
@@ -3063,10 +3372,14 @@ emulated efficiently and thus not included here.
The fields in each entry are defined as follows:
- function: the eax value used to obtain the entry
- index: the ecx value used to obtain the entry (for entries that are
+ function:
+ the eax value used to obtain the entry
+ index:
+ the ecx value used to obtain the entry (for entries that are
affected by ecx)
- flags: an OR of zero or more of the following:
+ flags:
+ an OR of zero or more of the following:
+
KVM_CPUID_FLAG_SIGNIFCANT_INDEX:
if the index field is valid
KVM_CPUID_FLAG_STATEFUL_FUNC:
@@ -3076,24 +3389,28 @@ The fields in each entry are defined as follows:
KVM_CPUID_FLAG_STATE_READ_NEXT:
for KVM_CPUID_FLAG_STATEFUL_FUNC entries, set if this entry is
the first entry to be read by a cpu
- eax, ebx, ecx, edx: the values returned by the cpuid instruction for
+
+ eax, ebx, ecx, edx:
+
+ the values returned by the cpuid instruction for
this function/index combination
4.89 KVM_S390_MEM_OP
+--------------------
-Capability: KVM_CAP_S390_MEM_OP
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_mem_op (in)
-Returns: = 0 on success,
- < 0 on generic error (e.g. -EFAULT or -ENOMEM),
- > 0 if an exception occurred while walking the page tables
+:Capability: KVM_CAP_S390_MEM_OP
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_mem_op (in)
+:Returns: = 0 on success,
+ < 0 on generic error (e.g. -EFAULT or -ENOMEM),
+ > 0 if an exception occurred while walking the page tables
Read or write data from/to the logical (virtual) memory of a VCPU.
-Parameters are specified via the following structure:
+Parameters are specified via the following structure::
-struct kvm_s390_mem_op {
+ struct kvm_s390_mem_op {
__u64 gaddr; /* the guest address */
__u64 flags; /* flags */
__u32 size; /* amount of bytes */
@@ -3101,7 +3418,7 @@ struct kvm_s390_mem_op {
__u64 buf; /* buffer in userspace */
__u8 ar; /* the access register number */
__u8 reserved[31]; /* should be set to 0 */
-};
+ };
The type of operation is specified in the "op" field. It is either
KVM_S390_MEMOP_LOGICAL_READ for reading from logical memory space or
@@ -3128,24 +3445,25 @@ The "reserved" field is meant for future extensions. It is not used by
KVM with the currently defined set of flags.
4.90 KVM_S390_GET_SKEYS
+-----------------------
-Capability: KVM_CAP_S390_SKEYS
-Architectures: s390
-Type: vm ioctl
-Parameters: struct kvm_s390_skeys
-Returns: 0 on success, KVM_S390_GET_KEYS_NONE if guest is not using storage
- keys, negative value on error
+:Capability: KVM_CAP_S390_SKEYS
+:Architectures: s390
+:Type: vm ioctl
+:Parameters: struct kvm_s390_skeys
+:Returns: 0 on success, KVM_S390_GET_KEYS_NONE if guest is not using storage
+ keys, negative value on error
This ioctl is used to get guest storage key values on the s390
-architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
+architecture. The ioctl takes parameters via the kvm_s390_skeys struct::
-struct kvm_s390_skeys {
+ struct kvm_s390_skeys {
__u64 start_gfn;
__u64 count;
__u64 skeydata_addr;
__u32 flags;
__u32 reserved[9];
-};
+ };
The start_gfn field is the number of the first guest frame whose storage keys
you want to get.
@@ -3159,12 +3477,13 @@ The skeydata_addr field is the address to a buffer large enough to hold count
bytes. This buffer will be filled with storage key data by the ioctl.
4.91 KVM_S390_SET_SKEYS
+-----------------------
-Capability: KVM_CAP_S390_SKEYS
-Architectures: s390
-Type: vm ioctl
-Parameters: struct kvm_s390_skeys
-Returns: 0 on success, negative value on error
+:Capability: KVM_CAP_S390_SKEYS
+:Architectures: s390
+:Type: vm ioctl
+:Parameters: struct kvm_s390_skeys
+:Returns: 0 on success, negative value on error
This ioctl is used to set guest storage key values on the s390
architecture. The ioctl takes parameters via the kvm_s390_skeys struct.
@@ -3186,21 +3505,27 @@ Note: If any architecturally invalid key value is found in the given data then
the ioctl will return -EINVAL.
4.92 KVM_S390_IRQ
+-----------------
+
+:Capability: KVM_CAP_S390_INJECT_IRQ
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_irq (in)
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_S390_INJECT_IRQ
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_irq (in)
-Returns: 0 on success, -1 on error
Errors:
- EINVAL: interrupt type is invalid
- type is KVM_S390_SIGP_STOP and flag parameter is invalid value
+
+
+ ====== =================================================================
+ EINVAL interrupt type is invalid
+ type is KVM_S390_SIGP_STOP and flag parameter is invalid value,
type is KVM_S390_INT_EXTERNAL_CALL and code is bigger
- than the maximum of VCPUs
- EBUSY: type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped
- type is KVM_S390_SIGP_STOP and a stop irq is already pending
+ than the maximum of VCPUs
+ EBUSY type is KVM_S390_SIGP_SET_PREFIX and vcpu is not stopped,
+ type is KVM_S390_SIGP_STOP and a stop irq is already pending,
type is KVM_S390_INT_EXTERNAL_CALL and an external call interrupt
- is already pending
+ is already pending
+ ====== =================================================================
Allows to inject an interrupt to the guest.
@@ -3208,9 +3533,9 @@ Using struct kvm_s390_irq as a parameter allows
to inject additional payload which is not
possible via KVM_S390_INTERRUPT.
-Interrupt parameters are passed via kvm_s390_irq:
+Interrupt parameters are passed via kvm_s390_irq::
-struct kvm_s390_irq {
+ struct kvm_s390_irq {
__u64 type;
union {
struct kvm_s390_io_info io;
@@ -3223,44 +3548,45 @@ struct kvm_s390_irq {
struct kvm_s390_mchk_info mchk;
char reserved[64];
} u;
-};
+ };
type can be one of the following:
-KVM_S390_SIGP_STOP - sigp stop; parameter in .stop
-KVM_S390_PROGRAM_INT - program check; parameters in .pgm
-KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix
-KVM_S390_RESTART - restart; no parameters
-KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters
-KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters
-KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg
-KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall
-KVM_S390_MCHK - machine check interrupt; parameters in .mchk
+- KVM_S390_SIGP_STOP - sigp stop; parameter in .stop
+- KVM_S390_PROGRAM_INT - program check; parameters in .pgm
+- KVM_S390_SIGP_SET_PREFIX - sigp set prefix; parameters in .prefix
+- KVM_S390_RESTART - restart; no parameters
+- KVM_S390_INT_CLOCK_COMP - clock comparator interrupt; no parameters
+- KVM_S390_INT_CPU_TIMER - CPU timer interrupt; no parameters
+- KVM_S390_INT_EMERGENCY - sigp emergency; parameters in .emerg
+- KVM_S390_INT_EXTERNAL_CALL - sigp external call; parameters in .extcall
+- KVM_S390_MCHK - machine check interrupt; parameters in .mchk
This is an asynchronous vcpu ioctl and can be invoked from any thread.
4.94 KVM_S390_GET_IRQ_STATE
+---------------------------
-Capability: KVM_CAP_S390_IRQ_STATE
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_irq_state (out)
-Returns: >= number of bytes copied into buffer,
- -EINVAL if buffer size is 0,
- -ENOBUFS if buffer size is too small to fit all pending interrupts,
- -EFAULT if the buffer address was invalid
+:Capability: KVM_CAP_S390_IRQ_STATE
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_irq_state (out)
+:Returns: >= number of bytes copied into buffer,
+ -EINVAL if buffer size is 0,
+ -ENOBUFS if buffer size is too small to fit all pending interrupts,
+ -EFAULT if the buffer address was invalid
This ioctl allows userspace to retrieve the complete state of all currently
pending interrupts in a single buffer. Use cases include migration
and introspection. The parameter structure contains the address of a
-userspace buffer and its length:
+userspace buffer and its length::
-struct kvm_s390_irq_state {
+ struct kvm_s390_irq_state {
__u64 buf;
__u32 flags; /* will stay unused for compatibility reasons */
__u32 len;
__u32 reserved[4]; /* will stay unused for compatibility reasons */
-};
+ };
Userspace passes in the above struct and for each pending interrupt a
struct kvm_s390_irq is copied to the provided buffer.
@@ -3274,29 +3600,30 @@ If -ENOBUFS is returned the buffer provided was too small and userspace
may retry with a bigger buffer.
4.95 KVM_S390_SET_IRQ_STATE
+---------------------------
-Capability: KVM_CAP_S390_IRQ_STATE
-Architectures: s390
-Type: vcpu ioctl
-Parameters: struct kvm_s390_irq_state (in)
-Returns: 0 on success,
- -EFAULT if the buffer address was invalid,
- -EINVAL for an invalid buffer length (see below),
- -EBUSY if there were already interrupts pending,
- errors occurring when actually injecting the
+:Capability: KVM_CAP_S390_IRQ_STATE
+:Architectures: s390
+:Type: vcpu ioctl
+:Parameters: struct kvm_s390_irq_state (in)
+:Returns: 0 on success,
+ -EFAULT if the buffer address was invalid,
+ -EINVAL for an invalid buffer length (see below),
+ -EBUSY if there were already interrupts pending,
+ errors occurring when actually injecting the
interrupt. See KVM_S390_IRQ.
This ioctl allows userspace to set the complete state of all cpu-local
interrupts currently pending for the vcpu. It is intended for restoring
interrupt state after a migration. The input parameter is a userspace buffer
-containing a struct kvm_s390_irq_state:
+containing a struct kvm_s390_irq_state::
-struct kvm_s390_irq_state {
+ struct kvm_s390_irq_state {
__u64 buf;
__u32 flags; /* will stay unused for compatibility reasons */
__u32 len;
__u32 reserved[4]; /* will stay unused for compatibility reasons */
-};
+ };
The restrictions for flags and reserved apply as well.
(see KVM_S390_GET_IRQ_STATE)
@@ -3311,20 +3638,22 @@ and it must not exceed (max_vcpus + 32) * sizeof(struct kvm_s390_irq),
which is the maximum number of possibly pending cpu-local interrupts.
4.96 KVM_SMI
+------------
-Capability: KVM_CAP_X86_SMM
-Architectures: x86
-Type: vcpu ioctl
-Parameters: none
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_X86_SMM
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: none
+:Returns: 0 on success, -1 on error
Queues an SMI on the thread's vcpu.
4.97 KVM_CAP_PPC_MULTITCE
+-------------------------
-Capability: KVM_CAP_PPC_MULTITCE
-Architectures: ppc
-Type: vm
+:Capability: KVM_CAP_PPC_MULTITCE
+:Architectures: ppc
+:Type: vm
This capability means the kernel is capable of handling hypercalls
H_PUT_TCE_INDIRECT and H_STUFF_TCE without passing those into the user
@@ -3346,26 +3675,27 @@ an implementation for these despite the in kernel acceleration.
This capability is always enabled.
4.98 KVM_CREATE_SPAPR_TCE_64
+----------------------------
-Capability: KVM_CAP_SPAPR_TCE_64
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_create_spapr_tce_64 (in)
-Returns: file descriptor for manipulating the created TCE table
+:Capability: KVM_CAP_SPAPR_TCE_64
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_create_spapr_tce_64 (in)
+:Returns: file descriptor for manipulating the created TCE table
This is an extension for KVM_CAP_SPAPR_TCE which only supports 32bit
windows, described in 4.62 KVM_CREATE_SPAPR_TCE
-This capability uses extended struct in ioctl interface:
+This capability uses extended struct in ioctl interface::
-/* for KVM_CAP_SPAPR_TCE_64 */
-struct kvm_create_spapr_tce_64 {
+ /* for KVM_CAP_SPAPR_TCE_64 */
+ struct kvm_create_spapr_tce_64 {
__u64 liobn;
__u32 page_shift;
__u32 flags;
__u64 offset; /* in pages */
__u64 size; /* in pages */
-};
+ };
The aim of extension is to support an additional bigger DMA window with
a variable page size.
@@ -3378,12 +3708,13 @@ of IOMMU pages.
The rest of functionality is identical to KVM_CREATE_SPAPR_TCE.
4.99 KVM_REINJECT_CONTROL
+-------------------------
-Capability: KVM_CAP_REINJECT_CONTROL
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_reinject_control (in)
-Returns: 0 on success,
+:Capability: KVM_CAP_REINJECT_CONTROL
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_reinject_control (in)
+:Returns: 0 on success,
-EFAULT if struct kvm_reinject_control cannot be read,
-ENXIO if KVM_CREATE_PIT or KVM_CREATE_PIT2 didn't succeed earlier.
@@ -3393,21 +3724,24 @@ vector(s) that i8254 injects. Reinject mode dequeues a tick and injects its
interrupt whenever there isn't a pending interrupt from i8254.
!reinject mode injects an interrupt as soon as a tick arrives.
-struct kvm_reinject_control {
+::
+
+ struct kvm_reinject_control {
__u8 pit_reinject;
__u8 reserved[31];
-};
+ };
pit_reinject = 0 (!reinject mode) is recommended, unless running an old
operating system that uses the PIT for timing (e.g. Linux 2.4.x).
4.100 KVM_PPC_CONFIGURE_V3_MMU
+------------------------------
-Capability: KVM_CAP_PPC_RADIX_MMU or KVM_CAP_PPC_HASH_MMU_V3
-Architectures: ppc
-Type: vm ioctl
-Parameters: struct kvm_ppc_mmuv3_cfg (in)
-Returns: 0 on success,
+:Capability: KVM_CAP_PPC_RADIX_MMU or KVM_CAP_PPC_HASH_MMU_V3
+:Architectures: ppc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_mmuv3_cfg (in)
+:Returns: 0 on success,
-EFAULT if struct kvm_ppc_mmuv3_cfg cannot be read,
-EINVAL if the configuration is invalid
@@ -3415,10 +3749,12 @@ This ioctl controls whether the guest will use radix or HPT (hashed
page table) translation, and sets the pointer to the process table for
the guest.
-struct kvm_ppc_mmuv3_cfg {
+::
+
+ struct kvm_ppc_mmuv3_cfg {
__u64 flags;
__u64 process_table;
-};
+ };
There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX and
KVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guest
@@ -3433,12 +3769,13 @@ as the second doubleword of the partition table entry, as defined in
the Power ISA V3.00, Book III section 5.7.6.1.
4.101 KVM_PPC_GET_RMMU_INFO
+---------------------------
-Capability: KVM_CAP_PPC_RADIX_MMU
-Architectures: ppc
-Type: vm ioctl
-Parameters: struct kvm_ppc_rmmu_info (out)
-Returns: 0 on success,
+:Capability: KVM_CAP_PPC_RADIX_MMU
+:Architectures: ppc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_rmmu_info (out)
+:Returns: 0 on success,
-EFAULT if struct kvm_ppc_rmmu_info cannot be written,
-EINVAL if no useful information can be returned
@@ -3447,14 +3784,52 @@ containing supported radix tree geometries, and (b) a list that maps
page sizes to put in the "AP" (actual page size) field for the tlbie
(TLB invalidate entry) instruction.
-struct kvm_ppc_rmmu_info {
+::
+
+ struct kvm_ppc_rmmu_info {
+ struct kvm_ppc_radix_geom {
+ __u8 page_shift;
+ __u8 level_bits[4];
+ __u8 pad[3];
+ } geometries[8];
+ __u32 ap_encodings[8];
+ };
+
+The geometries[] field gives up to 8 supported geometries for the
+radix page table, in terms of the log base 2 of the smallest page
+size, and the number of bits indexed at each level of the tree, from
+the PTE level up to the PGD level in that order. Any unused entries
+will have 0 in the page_shift field.
+
+The ap_encodings gives the supported page sizes and their AP field
+encodings, encoded with the AP value in the top 3 bits and the log
+base 2 of the page size in the bottom 6 bits.
+
+4.102 KVM_PPC_RESIZE_HPT_PREPARE
+--------------------------------
+
+:Capability: KVM_CAP_SPAPR_RESIZE_HPT
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_resize_hpt (in)
+:Returns: 0 on successful completion,
+ >0 if a new HPT is being prepared, the value is an estimated
+ number of milliseconds until preparation is complete,
+ -EFAULT if struct kvm_reinject_control cannot be read,
+ -EINVAL if the supplied shift or flags are invalid,
+ -ENOMEM if unable to allocate the new HPT,
+ -ENOSPC if there was a hash collision
+
+::
+
+ struct kvm_ppc_rmmu_info {
struct kvm_ppc_radix_geom {
__u8 page_shift;
__u8 level_bits[4];
__u8 pad[3];
} geometries[8];
__u32 ap_encodings[8];
-};
+ };
The geometries[] field gives up to 8 supported geometries for the
radix page table, in terms of the log base 2 of the smallest page
@@ -3467,19 +3842,18 @@ encodings, encoded with the AP value in the top 3 bits and the log
base 2 of the page size in the bottom 6 bits.
4.102 KVM_PPC_RESIZE_HPT_PREPARE
+--------------------------------
-Capability: KVM_CAP_SPAPR_RESIZE_HPT
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_ppc_resize_hpt (in)
-Returns: 0 on successful completion,
+:Capability: KVM_CAP_SPAPR_RESIZE_HPT
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_resize_hpt (in)
+:Returns: 0 on successful completion,
>0 if a new HPT is being prepared, the value is an estimated
- number of milliseconds until preparation is complete
+ number of milliseconds until preparation is complete,
-EFAULT if struct kvm_reinject_control cannot be read,
- -EINVAL if the supplied shift or flags are invalid
- -ENOMEM if unable to allocate the new HPT
- -ENOSPC if there was a hash collision when moving existing
- HPT entries to the new HPT
+ -EINVAL if the supplied shift or flags are invalid,when moving existing
+ HPT entries to the new HPT,
-EIO on other error conditions
Used to implement the PAPR extension for runtime resizing of a guest's
@@ -3497,6 +3871,7 @@ requested in the parameters, discards the existing pending HPT and
creates a new one as above.
If called when there is a pending HPT of the size requested, will:
+
* If preparation of the pending HPT is already complete, return 0
* If preparation of the pending HPT has failed, return an error
code, then discard the pending HPT.
@@ -3513,26 +3888,29 @@ Normally this will be called repeatedly with the same parameters until
it returns <= 0. The first call will initiate preparation, subsequent
ones will monitor preparation until it completes or fails.
-struct kvm_ppc_resize_hpt {
+::
+
+ struct kvm_ppc_resize_hpt {
__u64 flags;
__u32 shift;
__u32 pad;
-};
+ };
4.103 KVM_PPC_RESIZE_HPT_COMMIT
+-------------------------------
-Capability: KVM_CAP_SPAPR_RESIZE_HPT
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_ppc_resize_hpt (in)
-Returns: 0 on successful completion,
+:Capability: KVM_CAP_SPAPR_RESIZE_HPT
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_resize_hpt (in)
+:Returns: 0 on successful completion,
-EFAULT if struct kvm_reinject_control cannot be read,
- -EINVAL if the supplied shift or flags are invalid
+ -EINVAL if the supplied shift or flags are invalid,
-ENXIO is there is no pending HPT, or the pending HPT doesn't
- have the requested size
- -EBUSY if the pending HPT is not fully prepared
+ have the requested size,
+ -EBUSY if the pending HPT is not fully prepared,
-ENOSPC if there was a hash collision when moving existing
- HPT entries to the new HPT
+ HPT entries to the new HPT,
-EIO on other error conditions
Used to implement the PAPR extension for runtime resizing of a guest's
@@ -3555,31 +3933,35 @@ HPT and the previous HPT will be discarded.
On failure, the guest will still be operating on its previous HPT.
-struct kvm_ppc_resize_hpt {
+::
+
+ struct kvm_ppc_resize_hpt {
__u64 flags;
__u32 shift;
__u32 pad;
-};
+ };
4.104 KVM_X86_GET_MCE_CAP_SUPPORTED
+-----------------------------------
-Capability: KVM_CAP_MCE
-Architectures: x86
-Type: system ioctl
-Parameters: u64 mce_cap (out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_MCE
+:Architectures: x86
+:Type: system ioctl
+:Parameters: u64 mce_cap (out)
+:Returns: 0 on success, -1 on error
Returns supported MCE capabilities. The u64 mce_cap parameter
has the same format as the MSR_IA32_MCG_CAP register. Supported
capabilities will have the corresponding bits set.
4.105 KVM_X86_SETUP_MCE
+-----------------------
-Capability: KVM_CAP_MCE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: u64 mcg_cap (in)
-Returns: 0 on success,
+:Capability: KVM_CAP_MCE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: u64 mcg_cap (in)
+:Returns: 0 on success,
-EFAULT if u64 mcg_cap cannot be read,
-EINVAL if the requested number of banks is invalid,
-EINVAL if requested MCE capability is not supported.
@@ -3592,20 +3974,21 @@ checking for KVM_CAP_MCE. The supported capabilities can be
retrieved with KVM_X86_GET_MCE_CAP_SUPPORTED.
4.106 KVM_X86_SET_MCE
+---------------------
-Capability: KVM_CAP_MCE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_x86_mce (in)
-Returns: 0 on success,
+:Capability: KVM_CAP_MCE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_x86_mce (in)
+:Returns: 0 on success,
-EFAULT if struct kvm_x86_mce cannot be read,
-EINVAL if the bank number is invalid,
-EINVAL if VAL bit is not set in status field.
Inject a machine check error (MCE) into the guest. The input
-parameter is:
+parameter is::
-struct kvm_x86_mce {
+ struct kvm_x86_mce {
__u64 status;
__u64 addr;
__u64 misc;
@@ -3613,7 +3996,7 @@ struct kvm_x86_mce {
__u8 bank;
__u8 pad1[7];
__u64 pad2[3];
-};
+ };
If the MCE being reported is an uncorrected error, KVM will
inject it as an MCE exception into the guest. If the guest
@@ -3625,15 +4008,17 @@ store it in the corresponding bank (provided this bank is
not holding a previously reported uncorrected error).
4.107 KVM_S390_GET_CMMA_BITS
+----------------------------
-Capability: KVM_CAP_S390_CMMA_MIGRATION
-Architectures: s390
-Type: vm ioctl
-Parameters: struct kvm_s390_cmma_log (in, out)
-Returns: 0 on success, a negative value on error
+:Capability: KVM_CAP_S390_CMMA_MIGRATION
+:Architectures: s390
+:Type: vm ioctl
+:Parameters: struct kvm_s390_cmma_log (in, out)
+:Returns: 0 on success, a negative value on error
This ioctl is used to get the values of the CMMA bits on the s390
architecture. It is meant to be used in two scenarios:
+
- During live migration to save the CMMA values. Live migration needs
to be enabled via the KVM_REQ_START_MIGRATION VM property.
- To non-destructively peek at the CMMA values, with the flag
@@ -3643,9 +4028,12 @@ The ioctl takes parameters via the kvm_s390_cmma_log struct. The desired
values are written to a buffer whose location is indicated via the "values"
member in the kvm_s390_cmma_log struct. The values in the input struct are
also updated as needed.
+
Each CMMA value takes up one byte.
-struct kvm_s390_cmma_log {
+::
+
+ struct kvm_s390_cmma_log {
__u64 start_gfn;
__u32 count;
__u32 flags;
@@ -3654,7 +4042,7 @@ struct kvm_s390_cmma_log {
__u64 mask;
};
__u64 values;
-};
+ };
start_gfn is the number of the first guest frame whose CMMA values are
to be retrieved,
@@ -3715,12 +4103,13 @@ KVM_S390_CMMA_PEEK is not set but migration mode was not enabled, with
present for the addresses (e.g. when using hugepages).
4.108 KVM_S390_SET_CMMA_BITS
+----------------------------
-Capability: KVM_CAP_S390_CMMA_MIGRATION
-Architectures: s390
-Type: vm ioctl
-Parameters: struct kvm_s390_cmma_log (in)
-Returns: 0 on success, a negative value on error
+:Capability: KVM_CAP_S390_CMMA_MIGRATION
+:Architectures: s390
+:Type: vm ioctl
+:Parameters: struct kvm_s390_cmma_log (in)
+:Returns: 0 on success, a negative value on error
This ioctl is used to set the values of the CMMA bits on the s390
architecture. It is meant to be used during live migration to restore
@@ -3728,16 +4117,18 @@ the CMMA values, but there are no restrictions on its use.
The ioctl takes parameters via the kvm_s390_cmma_values struct.
Each CMMA value takes up one byte.
-struct kvm_s390_cmma_log {
+::
+
+ struct kvm_s390_cmma_log {
__u64 start_gfn;
__u32 count;
__u32 flags;
union {
__u64 remaining;
__u64 mask;
- };
+ };
__u64 values;
-};
+ };
start_gfn indicates the starting guest frame number,
@@ -3760,26 +4151,27 @@ or if no page table is present for the addresses (e.g. when using
hugepages).
4.109 KVM_PPC_GET_CPU_CHAR
+--------------------------
-Capability: KVM_CAP_PPC_GET_CPU_CHAR
-Architectures: powerpc
-Type: vm ioctl
-Parameters: struct kvm_ppc_cpu_char (out)
-Returns: 0 on successful completion
+:Capability: KVM_CAP_PPC_GET_CPU_CHAR
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_cpu_char (out)
+:Returns: 0 on successful completion,
-EFAULT if struct kvm_ppc_cpu_char cannot be written
This ioctl gives userspace information about certain characteristics
of the CPU relating to speculative execution of instructions and
possible information leakage resulting from speculative execution (see
CVE-2017-5715, CVE-2017-5753 and CVE-2017-5754). The information is
-returned in struct kvm_ppc_cpu_char, which looks like this:
+returned in struct kvm_ppc_cpu_char, which looks like this::
-struct kvm_ppc_cpu_char {
+ struct kvm_ppc_cpu_char {
__u64 character; /* characteristics of the CPU */
__u64 behaviour; /* recommended software behaviour */
__u64 character_mask; /* valid bits in character */
__u64 behaviour_mask; /* valid bits in behaviour */
-};
+ };
For extensibility, the character_mask and behaviour_mask fields
indicate which bits of character and behaviour have been filled in by
@@ -3806,12 +4198,13 @@ These fields use the same bit definitions as the new
H_GET_CPU_CHARACTERISTICS hypercall.
4.110 KVM_MEMORY_ENCRYPT_OP
+---------------------------
-Capability: basic
-Architectures: x86
-Type: system
-Parameters: an opaque platform specific structure (in/out)
-Returns: 0 on success; -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: system
+:Parameters: an opaque platform specific structure (in/out)
+:Returns: 0 on success; -1 on error
If the platform supports creating encrypted VMs then this ioctl can be used
for issuing platform-specific memory encryption commands to manage those
@@ -3822,12 +4215,13 @@ Currently, this ioctl is used for issuing Secure Encrypted Virtualization
Documentation/virt/kvm/amd-memory-encryption.rst.
4.111 KVM_MEMORY_ENCRYPT_REG_REGION
+-----------------------------------
-Capability: basic
-Architectures: x86
-Type: system
-Parameters: struct kvm_enc_region (in)
-Returns: 0 on success; -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: system
+:Parameters: struct kvm_enc_region (in)
+:Returns: 0 on success; -1 on error
This ioctl can be used to register a guest memory region which may
contain encrypted data (e.g. guest RAM, SMRAM etc).
@@ -3845,60 +4239,71 @@ swap or migrate (move) ciphertext pages. Hence, for now we pin the guest
memory region registered with the ioctl.
4.112 KVM_MEMORY_ENCRYPT_UNREG_REGION
+-------------------------------------
-Capability: basic
-Architectures: x86
-Type: system
-Parameters: struct kvm_enc_region (in)
-Returns: 0 on success; -1 on error
+:Capability: basic
+:Architectures: x86
+:Type: system
+:Parameters: struct kvm_enc_region (in)
+:Returns: 0 on success; -1 on error
This ioctl can be used to unregister the guest memory region registered
with KVM_MEMORY_ENCRYPT_REG_REGION ioctl above.
4.113 KVM_HYPERV_EVENTFD
+------------------------
-Capability: KVM_CAP_HYPERV_EVENTFD
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_hyperv_eventfd (in)
+:Capability: KVM_CAP_HYPERV_EVENTFD
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_hyperv_eventfd (in)
This ioctl (un)registers an eventfd to receive notifications from the guest on
the specified Hyper-V connection id through the SIGNAL_EVENT hypercall, without
causing a user exit. SIGNAL_EVENT hypercall with non-zero event flag number
(bits 24-31) still triggers a KVM_EXIT_HYPERV_HCALL user exit.
-struct kvm_hyperv_eventfd {
+::
+
+ struct kvm_hyperv_eventfd {
__u32 conn_id;
__s32 fd;
__u32 flags;
__u32 padding[3];
-};
+ };
-The conn_id field should fit within 24 bits:
+The conn_id field should fit within 24 bits::
-#define KVM_HYPERV_CONN_ID_MASK 0x00ffffff
+ #define KVM_HYPERV_CONN_ID_MASK 0x00ffffff
-The acceptable values for the flags field are:
+The acceptable values for the flags field are::
-#define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0)
+ #define KVM_HYPERV_EVENTFD_DEASSIGN (1 << 0)
-Returns: 0 on success,
- -EINVAL if conn_id or flags is outside the allowed range
- -ENOENT on deassign if the conn_id isn't registered
- -EEXIST on assign if the conn_id is already registered
+:Returns: 0 on success,
+ -EINVAL if conn_id or flags is outside the allowed range,
+ -ENOENT on deassign if the conn_id isn't registered,
+ -EEXIST on assign if the conn_id is already registered
4.114 KVM_GET_NESTED_STATE
+--------------------------
+
+:Capability: KVM_CAP_NESTED_STATE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_nested_state (in/out)
+:Returns: 0 on success, -1 on error
-Capability: KVM_CAP_NESTED_STATE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_nested_state (in/out)
-Returns: 0 on success, -1 on error
Errors:
- E2BIG: the total state size exceeds the value of 'size' specified by
+
+ ===== =============================================================
+ E2BIG the total state size exceeds the value of 'size' specified by
the user; the size required will be written into size.
+ ===== =============================================================
-struct kvm_nested_state {
+::
+
+ struct kvm_nested_state {
__u16 flags;
__u16 format;
__u32 size;
@@ -3915,33 +4320,33 @@ struct kvm_nested_state {
struct kvm_vmx_nested_state_data vmx[0];
struct kvm_svm_nested_state_data svm[0];
} data;
-};
+ };
-#define KVM_STATE_NESTED_GUEST_MODE 0x00000001
-#define KVM_STATE_NESTED_RUN_PENDING 0x00000002
-#define KVM_STATE_NESTED_EVMCS 0x00000004
+ #define KVM_STATE_NESTED_GUEST_MODE 0x00000001
+ #define KVM_STATE_NESTED_RUN_PENDING 0x00000002
+ #define KVM_STATE_NESTED_EVMCS 0x00000004
-#define KVM_STATE_NESTED_FORMAT_VMX 0
-#define KVM_STATE_NESTED_FORMAT_SVM 1
+ #define KVM_STATE_NESTED_FORMAT_VMX 0
+ #define KVM_STATE_NESTED_FORMAT_SVM 1
-#define KVM_STATE_NESTED_VMX_VMCS_SIZE 0x1000
+ #define KVM_STATE_NESTED_VMX_VMCS_SIZE 0x1000
-#define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE 0x00000001
-#define KVM_STATE_NESTED_VMX_SMM_VMXON 0x00000002
+ #define KVM_STATE_NESTED_VMX_SMM_GUEST_MODE 0x00000001
+ #define KVM_STATE_NESTED_VMX_SMM_VMXON 0x00000002
-struct kvm_vmx_nested_state_hdr {
+ struct kvm_vmx_nested_state_hdr {
__u64 vmxon_pa;
__u64 vmcs12_pa;
struct {
__u16 flags;
} smm;
-};
+ };
-struct kvm_vmx_nested_state_data {
+ struct kvm_vmx_nested_state_data {
__u8 vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];
__u8 shadow_vmcs12[KVM_STATE_NESTED_VMX_VMCS_SIZE];
-};
+ };
This ioctl copies the vcpu's nested virtualization state from the kernel to
userspace.
@@ -3950,24 +4355,26 @@ The maximum size of the state can be retrieved by passing KVM_CAP_NESTED_STATE
to the KVM_CHECK_EXTENSION ioctl().
4.115 KVM_SET_NESTED_STATE
+--------------------------
-Capability: KVM_CAP_NESTED_STATE
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_nested_state (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_NESTED_STATE
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_nested_state (in)
+:Returns: 0 on success, -1 on error
This copies the vcpu's kvm_nested_state struct from userspace to the kernel.
For the definition of struct kvm_nested_state, see KVM_GET_NESTED_STATE.
4.116 KVM_(UN)REGISTER_COALESCED_MMIO
+-------------------------------------
-Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio)
- KVM_CAP_COALESCED_PIO (for coalesced pio)
-Architectures: all
-Type: vm ioctl
-Parameters: struct kvm_coalesced_mmio_zone
-Returns: 0 on success, < 0 on error
+:Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio)
+ KVM_CAP_COALESCED_PIO (for coalesced pio)
+:Architectures: all
+:Type: vm ioctl
+:Parameters: struct kvm_coalesced_mmio_zone
+:Returns: 0 on success, < 0 on error
Coalesced I/O is a performance optimization that defers hardware
register write emulation so that userspace exits are avoided. It is
@@ -3989,15 +4396,18 @@ between coalesced mmio and pio except that coalesced pio records accesses
to I/O ports.
4.117 KVM_CLEAR_DIRTY_LOG (vm ioctl)
+------------------------------------
-Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
-Architectures: x86, arm, arm64, mips
-Type: vm ioctl
-Parameters: struct kvm_dirty_log (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
+:Architectures: x86, arm, arm64, mips
+:Type: vm ioctl
+:Parameters: struct kvm_dirty_log (in)
+:Returns: 0 on success, -1 on error
-/* for KVM_CLEAR_DIRTY_LOG */
-struct kvm_clear_dirty_log {
+::
+
+ /* for KVM_CLEAR_DIRTY_LOG */
+ struct kvm_clear_dirty_log {
__u32 slot;
__u32 num_pages;
__u64 first_page;
@@ -4005,7 +4415,7 @@ struct kvm_clear_dirty_log {
void __user *dirty_bitmap; /* one bit per page */
__u64 padding;
};
-};
+ };
The ioctl clears the dirty status of pages in a memory slot, according to
the bitmap that is passed in struct kvm_clear_dirty_log's dirty_bitmap
@@ -4029,20 +4439,23 @@ However, it can always be used as long as KVM_CHECK_EXTENSION confirms
that KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 is present.
4.118 KVM_GET_SUPPORTED_HV_CPUID
+--------------------------------
-Capability: KVM_CAP_HYPERV_CPUID
-Architectures: x86
-Type: vcpu ioctl
-Parameters: struct kvm_cpuid2 (in/out)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_HYPERV_CPUID
+:Architectures: x86
+:Type: vcpu ioctl
+:Parameters: struct kvm_cpuid2 (in/out)
+:Returns: 0 on success, -1 on error
-struct kvm_cpuid2 {
+::
+
+ struct kvm_cpuid2 {
__u32 nent;
__u32 padding;
struct kvm_cpuid_entry2 entries[0];
-};
+ };
-struct kvm_cpuid_entry2 {
+ struct kvm_cpuid_entry2 {
__u32 function;
__u32 index;
__u32 flags;
@@ -4051,7 +4464,7 @@ struct kvm_cpuid_entry2 {
__u32 ecx;
__u32 edx;
__u32 padding[3];
-};
+ };
This ioctl returns x86 cpuid features leaves related to Hyper-V emulation in
KVM. Userspace can use the information returned by this ioctl to construct
@@ -4064,13 +4477,13 @@ KVM_GET_SUPPORTED_CPUID ioctl because some of them intersect with KVM feature
leaves (0x40000000, 0x40000001).
Currently, the following list of CPUID leaves are returned:
- HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS
- HYPERV_CPUID_INTERFACE
- HYPERV_CPUID_VERSION
- HYPERV_CPUID_FEATURES
- HYPERV_CPUID_ENLIGHTMENT_INFO
- HYPERV_CPUID_IMPLEMENT_LIMITS
- HYPERV_CPUID_NESTED_FEATURES
+ - HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS
+ - HYPERV_CPUID_INTERFACE
+ - HYPERV_CPUID_VERSION
+ - HYPERV_CPUID_FEATURES
+ - HYPERV_CPUID_ENLIGHTMENT_INFO
+ - HYPERV_CPUID_IMPLEMENT_LIMITS
+ - HYPERV_CPUID_NESTED_FEATURES
HYPERV_CPUID_NESTED_FEATURES leaf is only exposed when Enlightened VMCS was
enabled on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS).
@@ -4086,17 +4499,25 @@ number of valid entries in the 'entries' array, which is then filled.
userspace should not expect to get any particular value there.
4.119 KVM_ARM_VCPU_FINALIZE
+---------------------------
+
+:Architectures: arm, arm64
+:Type: vcpu ioctl
+:Parameters: int feature (in)
+:Returns: 0 on success, -1 on error
-Architectures: arm, arm64
-Type: vcpu ioctl
-Parameters: int feature (in)
-Returns: 0 on success, -1 on error
Errors:
- EPERM: feature not enabled, needs configuration, or already finalized
- EINVAL: feature unknown or not present
+
+ ====== ==============================================================
+ EPERM feature not enabled, needs configuration, or already finalized
+ EINVAL feature unknown or not present
+ ====== ==============================================================
Recognised values for feature:
+
+ ===== ===========================================
arm64 KVM_ARM_VCPU_SVE (requires KVM_CAP_ARM_SVE)
+ ===== ===========================================
Finalizes the configuration of the specified vcpu feature.
@@ -4120,21 +4541,24 @@ See KVM_ARM_VCPU_INIT for details of vcpu features that require finalization
using this ioctl.
4.120 KVM_SET_PMU_EVENT_FILTER
+------------------------------
-Capability: KVM_CAP_PMU_EVENT_FILTER
-Architectures: x86
-Type: vm ioctl
-Parameters: struct kvm_pmu_event_filter (in)
-Returns: 0 on success, -1 on error
+:Capability: KVM_CAP_PMU_EVENT_FILTER
+:Architectures: x86
+:Type: vm ioctl
+:Parameters: struct kvm_pmu_event_filter (in)
+:Returns: 0 on success, -1 on error
-struct kvm_pmu_event_filter {
+::
+
+ struct kvm_pmu_event_filter {
__u32 action;
__u32 nevents;
__u32 fixed_counter_bitmap;
__u32 flags;
__u32 pad[4];
__u64 events[0];
-};
+ };
This ioctl restricts the set of PMU events that the guest can program.
The argument holds a list of events which will be allowed or denied.
@@ -4145,20 +4569,26 @@ counters are controlled by the fixed_counter_bitmap.
No flags are defined yet, the field must be zero.
-Valid values for 'action':
-#define KVM_PMU_EVENT_ALLOW 0
-#define KVM_PMU_EVENT_DENY 1
+Valid values for 'action'::
+
+ #define KVM_PMU_EVENT_ALLOW 0
+ #define KVM_PMU_EVENT_DENY 1
4.121 KVM_PPC_SVM_OFF
+---------------------
+
+:Capability: basic
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: none
+:Returns: 0 on successful completion,
-Capability: basic
-Architectures: powerpc
-Type: vm ioctl
-Parameters: none
-Returns: 0 on successful completion,
Errors:
- EINVAL: if ultravisor failed to terminate the secure guest
- ENOMEM: if hypervisor failed to allocate new radix page tables for guest
+
+ ====== ================================================================
+ EINVAL if ultravisor failed to terminate the secure guest
+ ENOMEM if hypervisor failed to allocate new radix page tables for guest
+ ====== ================================================================
This ioctl is used to turn off the secure mode of the guest or transition
the guest from secure mode to normal mode. This is invoked when the guest
@@ -4169,7 +4599,7 @@ unpins the VPA pages and releases all the device pages that are used to
track the secure pages by hypervisor.
5. The kvm_run structure
-------------------------
+========================
Application code obtains a pointer to the kvm_run structure by
mmap()ing a vcpu fd. From that point, application code can control
@@ -4177,13 +4607,17 @@ execution by changing fields in kvm_run prior to calling the KVM_RUN
ioctl, and obtain information about the reason KVM_RUN returned by
looking up structure members.
-struct kvm_run {
+::
+
+ struct kvm_run {
/* in */
__u8 request_interrupt_window;
Request that KVM_RUN return when it becomes possible to inject external
interrupts into the guest. Useful in conjunction with KVM_INTERRUPT.
+::
+
__u8 immediate_exit;
This field is polled once when KVM_RUN starts; if non-zero, KVM_RUN
@@ -4195,6 +4629,8 @@ a signal handler that sets run->immediate_exit to a non-zero value.
This field is ignored if KVM_CAP_IMMEDIATE_EXIT is not available.
+::
+
__u8 padding1[6];
/* out */
@@ -4204,16 +4640,22 @@ When KVM_RUN has returned successfully (return value 0), this informs
application code why KVM_RUN has returned. Allowable values for this
field are detailed below.
+::
+
__u8 ready_for_interrupt_injection;
If request_interrupt_window has been specified, this field indicates
an interrupt can be injected now with KVM_INTERRUPT.
+::
+
__u8 if_flag;
The value of the current interrupt flag. Only valid if in-kernel
local APIC is not used.
+::
+
__u16 flags;
More architecture-specific flags detailing state of the VCPU that may
@@ -4221,17 +4663,23 @@ affect the device's behavior. The only currently defined flag is
KVM_RUN_X86_SMM, which is valid on x86 machines and is set if the
VCPU is in system management mode.
+::
+
/* in (pre_kvm_run), out (post_kvm_run) */
__u64 cr8;
The value of the cr8 register. Only valid if in-kernel local APIC is
not used. Both input and output.
+::
+
__u64 apic_base;
The value of the APIC BASE msr. Only valid if in-kernel local
APIC is not used. Both input and output.
+::
+
union {
/* KVM_EXIT_UNKNOWN */
struct {
@@ -4242,6 +4690,8 @@ If exit_reason is KVM_EXIT_UNKNOWN, the vcpu has exited due to unknown
reasons. Further architecture-specific information is available in
hardware_exit_reason.
+::
+
/* KVM_EXIT_FAIL_ENTRY */
struct {
__u64 hardware_entry_failure_reason;
@@ -4251,6 +4701,8 @@ If exit_reason is KVM_EXIT_FAIL_ENTRY, the vcpu could not be run due
to unknown reasons. Further architecture-specific information is
available in hardware_entry_failure_reason.
+::
+
/* KVM_EXIT_EXCEPTION */
struct {
__u32 exception;
@@ -4259,10 +4711,12 @@ available in hardware_entry_failure_reason.
Unused.
+::
+
/* KVM_EXIT_IO */
struct {
-#define KVM_EXIT_IO_IN 0
-#define KVM_EXIT_IO_OUT 1
+ #define KVM_EXIT_IO_IN 0
+ #define KVM_EXIT_IO_OUT 1
__u8 direction;
__u8 size; /* bytes */
__u16 port;
@@ -4276,6 +4730,8 @@ data_offset describes where the data is located (KVM_EXIT_IO_OUT) or
where kvm expects application code to place the data for the next
KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
+::
+
/* KVM_EXIT_DEBUG */
struct {
struct kvm_debug_exit_arch arch;
@@ -4284,6 +4740,8 @@ KVM_RUN invocation (KVM_EXIT_IO_IN). Data format is a packed array.
If the exit_reason is KVM_EXIT_DEBUG, then a vcpu is processing a debug event
for which architecture specific information is returned.
+::
+
/* KVM_EXIT_MMIO */
struct {
__u64 phys_addr;
@@ -4301,14 +4759,19 @@ The 'data' member contains, in its first 'len' bytes, the value as it would
appear if the VCPU performed a load or store of the appropriate width directly
to the byte array.
-NOTE: For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR and
+.. note::
+
+ For KVM_EXIT_IO, KVM_EXIT_MMIO, KVM_EXIT_OSI, KVM_EXIT_PAPR and
KVM_EXIT_EPR the corresponding
+
operations are complete (and guest state is consistent) only after userspace
has re-entered the kernel with KVM_RUN. The kernel side will first finish
incomplete operations and then check for pending signals. Userspace
can re-enter the guest with an unmasked signal pending to complete
pending operations.
+::
+
/* KVM_EXIT_HYPERCALL */
struct {
__u64 nr;
@@ -4320,7 +4783,10 @@ pending operations.
Unused. This was once used for 'hypercall to userspace'. To implement
such functionality, use KVM_EXIT_IO (x86) or KVM_EXIT_MMIO (all except s390).
-Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
+
+.. note:: KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
+
+::
/* KVM_EXIT_TPR_ACCESS */
struct {
@@ -4331,6 +4797,8 @@ Note KVM_EXIT_IO is significantly faster than KVM_EXIT_MMIO.
To be documented (KVM_TPR_ACCESS_REPORTING).
+::
+
/* KVM_EXIT_S390_SIEIC */
struct {
__u8 icptcode;
@@ -4342,16 +4810,20 @@ To be documented (KVM_TPR_ACCESS_REPORTING).
s390 specific.
+::
+
/* KVM_EXIT_S390_RESET */
-#define KVM_S390_RESET_POR 1
-#define KVM_S390_RESET_CLEAR 2
-#define KVM_S390_RESET_SUBSYSTEM 4
-#define KVM_S390_RESET_CPU_INIT 8
-#define KVM_S390_RESET_IPL 16
+ #define KVM_S390_RESET_POR 1
+ #define KVM_S390_RESET_CLEAR 2
+ #define KVM_S390_RESET_SUBSYSTEM 4
+ #define KVM_S390_RESET_CPU_INIT 8
+ #define KVM_S390_RESET_IPL 16
__u64 s390_reset_flags;
s390 specific.
+::
+
/* KVM_EXIT_S390_UCONTROL */
struct {
__u64 trans_exc_code;
@@ -4366,6 +4838,8 @@ in the cpu's lowcore are presented here as defined by the z Architecture
Principles of Operation Book in the Chapter for Dynamic Address Translation
(DAT)
+::
+
/* KVM_EXIT_DCR */
struct {
__u32 dcrn;
@@ -4375,6 +4849,8 @@ Principles of Operation Book in the Chapter for Dynamic Address Translation
Deprecated - was used for 440 KVM.
+::
+
/* KVM_EXIT_OSI */
struct {
__u64 gprs[32];
@@ -4388,6 +4864,8 @@ Userspace can now handle the hypercall and when it's done modify the gprs as
necessary. Upon guest entry all guest GPRs will then be replaced by the values
in this struct.
+::
+
/* KVM_EXIT_PAPR_HCALL */
struct {
__u64 nr;
@@ -4405,6 +4883,8 @@ The possible hypercalls are defined in the Power Architecture Platform
Requirements (PAPR) document available from www.power.org (free
developer registration required to access it).
+::
+
/* KVM_EXIT_S390_TSCH */
struct {
__u16 subchannel_id;
@@ -4421,6 +4901,8 @@ interrupt for the target subchannel has been dequeued and subchannel_id,
subchannel_nr, io_int_parm and io_int_word contain the parameters for that
interrupt. ipb is needed for instruction parameter decoding.
+::
+
/* KVM_EXIT_EPR */
struct {
__u32 epr;
@@ -4440,11 +4922,13 @@ It gets triggered whenever both KVM_CAP_PPC_EPR are enabled and an
external interrupt has just been delivered into the guest. User space
should put the acknowledged interrupt vector into the 'epr' field.
+::
+
/* KVM_EXIT_SYSTEM_EVENT */
struct {
-#define KVM_SYSTEM_EVENT_SHUTDOWN 1
-#define KVM_SYSTEM_EVENT_RESET 2
-#define KVM_SYSTEM_EVENT_CRASH 3
+ #define KVM_SYSTEM_EVENT_SHUTDOWN 1
+ #define KVM_SYSTEM_EVENT_RESET 2
+ #define KVM_SYSTEM_EVENT_CRASH 3
__u32 type;
__u64 flags;
} system_event;
@@ -4457,18 +4941,21 @@ the system-level event type. The 'flags' field describes architecture
specific flags for the system-level event.
Valid values for 'type' are:
- KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the
+
+ - KVM_SYSTEM_EVENT_SHUTDOWN -- the guest has requested a shutdown of the
VM. Userspace is not obliged to honour this, and if it does honour
this does not need to destroy the VM synchronously (ie it may call
KVM_RUN again before shutdown finally occurs).
- KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM.
+ - KVM_SYSTEM_EVENT_RESET -- the guest has requested a reset of the VM.
As with SHUTDOWN, userspace can choose to ignore the request, or
to schedule the reset to occur in the future and may call KVM_RUN again.
- KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest
+ - KVM_SYSTEM_EVENT_CRASH -- the guest crash occurred and the guest
has requested a crash condition maintenance. Userspace can choose
to ignore the request, or to gather VM memory core dump and/or
reset/shutdown of the VM.
+::
+
/* KVM_EXIT_IOAPIC_EOI */
struct {
__u8 vector;
@@ -4481,9 +4968,11 @@ the userspace IOAPIC should process the EOI and retrigger the interrupt if
it is still asserted. Vector is the LAPIC interrupt vector for which the
EOI was received.
+::
+
struct kvm_hyperv_exit {
-#define KVM_EXIT_HYPERV_SYNIC 1
-#define KVM_EXIT_HYPERV_HCALL 2
+ #define KVM_EXIT_HYPERV_SYNIC 1
+ #define KVM_EXIT_HYPERV_HCALL 2
__u32 type;
union {
struct {
@@ -4501,14 +4990,20 @@ EOI was received.
};
/* KVM_EXIT_HYPERV */
struct kvm_hyperv_exit hyperv;
+
Indicates that the VCPU exits into userspace to process some tasks
related to Hyper-V emulation.
+
Valid values for 'type' are:
- KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about
+
+ - KVM_EXIT_HYPERV_SYNIC -- synchronously notify user-space about
+
Hyper-V SynIC state change. Notification is used to remap SynIC
event/message pages and to enable/disable SynIC messages/events processing
in userspace.
+::
+
/* KVM_EXIT_ARM_NISV */
struct {
__u64 esr_iss;
@@ -4542,6 +5037,8 @@ Note that KVM does not skip the faulting instruction as it does for
KVM_EXIT_MMIO, but userspace has to emulate any change to the processing state
if it decides to decode and emulate the instruction.
+::
+
/* Fix the size of the union. */
char padding[256];
};
@@ -4566,18 +5063,20 @@ avoid some system call overhead if userspace has to handle the exit.
Userspace can query the validity of the structure by checking
kvm_valid_regs for specific bits. These bits are architecture specific
and usually define the validity of a groups of registers. (e.g. one bit
- for general purpose registers)
+for general purpose registers)
Please note that the kernel is allowed to use the kvm_run structure as the
primary storage for certain register types. Therefore, the kernel may use the
values in kvm_run even if the corresponding bit in kvm_dirty_regs is not set.
-};
+::
+
+ };
6. Capabilities that can be enabled on vCPUs
---------------------------------------------
+============================================
There are certain capabilities that change the behavior of the virtual CPU or
the virtual machine when enabled. To enable them, please see section 4.37.
@@ -4586,23 +5085,28 @@ the virtual machine is when enabling them.
The following information is provided along with the description:
- Architectures: which instruction set architectures provide this ioctl.
+ Architectures:
+ which instruction set architectures provide this ioctl.
x86 includes both i386 and x86_64.
- Target: whether this is a per-vcpu or per-vm capability.
+ Target:
+ whether this is a per-vcpu or per-vm capability.
- Parameters: what parameters are accepted by the capability.
+ Parameters:
+ what parameters are accepted by the capability.
- Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
+ Returns:
+ the return value. General error numbers (EBADF, ENOMEM, EINVAL)
are not detailed, but errors with specific meanings are.
6.1 KVM_CAP_PPC_OSI
+-------------------
-Architectures: ppc
-Target: vcpu
-Parameters: none
-Returns: 0 on success; -1 on error
+:Architectures: ppc
+:Target: vcpu
+:Parameters: none
+:Returns: 0 on success; -1 on error
This capability enables interception of OSI hypercalls that otherwise would
be treated as normal system calls to be injected into the guest. OSI hypercalls
@@ -4613,11 +5117,12 @@ When this capability is enabled, KVM_EXIT_OSI can occur.
6.2 KVM_CAP_PPC_PAPR
+--------------------
-Architectures: ppc
-Target: vcpu
-Parameters: none
-Returns: 0 on success; -1 on error
+:Architectures: ppc
+:Target: vcpu
+:Parameters: none
+:Returns: 0 on success; -1 on error
This capability enables interception of PAPR hypercalls. PAPR hypercalls are
done using the hypercall instruction "sc 1".
@@ -4633,18 +5138,21 @@ When this capability is enabled, KVM_EXIT_PAPR_HCALL can occur.
6.3 KVM_CAP_SW_TLB
+------------------
-Architectures: ppc
-Target: vcpu
-Parameters: args[0] is the address of a struct kvm_config_tlb
-Returns: 0 on success; -1 on error
+:Architectures: ppc
+:Target: vcpu
+:Parameters: args[0] is the address of a struct kvm_config_tlb
+:Returns: 0 on success; -1 on error
-struct kvm_config_tlb {
+::
+
+ struct kvm_config_tlb {
__u64 params;
__u64 array;
__u32 mmu_type;
__u32 array_len;
-};
+ };
Configures the virtual CPU's TLB array, establishing a shared memory area
between userspace and KVM. The "params" and "array" fields are userspace
@@ -4663,6 +5171,7 @@ to tell KVM which entries have been changed, prior to calling KVM_RUN again
on this vcpu.
For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:
+
- The "params" field is of type "struct kvm_book3e_206_tlb_params".
- The "array" field points to an array of type "struct
kvm_book3e_206_tlb_entry".
@@ -4676,11 +5185,12 @@ For mmu types KVM_MMU_FSL_BOOKE_NOHV and KVM_MMU_FSL_BOOKE_HV:
hardware ignores this value for TLB0.
6.4 KVM_CAP_S390_CSS_SUPPORT
+----------------------------
-Architectures: s390
-Target: vcpu
-Parameters: none
-Returns: 0 on success; -1 on error
+:Architectures: s390
+:Target: vcpu
+:Parameters: none
+:Returns: 0 on success; -1 on error
This capability enables support for handling of channel I/O instructions.
@@ -4694,11 +5204,12 @@ Note that even though this capability is enabled per-vcpu, the complete
virtual machine is affected.
6.5 KVM_CAP_PPC_EPR
+-------------------
-Architectures: ppc
-Target: vcpu
-Parameters: args[0] defines whether the proxy facility is active
-Returns: 0 on success; -1 on error
+:Architectures: ppc
+:Target: vcpu
+:Parameters: args[0] defines whether the proxy facility is active
+:Returns: 0 on success; -1 on error
This capability enables or disables the delivery of interrupts through the
external proxy facility.
@@ -4712,62 +5223,70 @@ When disabled (args[0] == 0), behavior is as if this facility is unsupported.
When this capability is enabled, KVM_EXIT_EPR can occur.
6.6 KVM_CAP_IRQ_MPIC
+--------------------
-Architectures: ppc
-Parameters: args[0] is the MPIC device fd
- args[1] is the MPIC CPU number for this vcpu
+:Architectures: ppc
+:Parameters: args[0] is the MPIC device fd;
+ args[1] is the MPIC CPU number for this vcpu
This capability connects the vcpu to an in-kernel MPIC device.
6.7 KVM_CAP_IRQ_XICS
+--------------------
-Architectures: ppc
-Target: vcpu
-Parameters: args[0] is the XICS device fd
- args[1] is the XICS CPU number (server ID) for this vcpu
+:Architectures: ppc
+:Target: vcpu
+:Parameters: args[0] is the XICS device fd;
+ args[1] is the XICS CPU number (server ID) for this vcpu
This capability connects the vcpu to an in-kernel XICS device.
6.8 KVM_CAP_S390_IRQCHIP
+------------------------
-Architectures: s390
-Target: vm
-Parameters: none
+:Architectures: s390
+:Target: vm
+:Parameters: none
This capability enables the in-kernel irqchip for s390. Please refer to
"4.24 KVM_CREATE_IRQCHIP" for details.
6.9 KVM_CAP_MIPS_FPU
+--------------------
-Architectures: mips
-Target: vcpu
-Parameters: args[0] is reserved for future use (should be 0).
+:Architectures: mips
+:Target: vcpu
+:Parameters: args[0] is reserved for future use (should be 0).
This capability allows the use of the host Floating Point Unit by the guest. It
allows the Config1.FP bit to be set to enable the FPU in the guest. Once this is
-done the KVM_REG_MIPS_FPR_* and KVM_REG_MIPS_FCR_* registers can be accessed
-(depending on the current guest FPU register mode), and the Status.FR,
+done the ``KVM_REG_MIPS_FPR_*`` and ``KVM_REG_MIPS_FCR_*`` registers can be
+accessed (depending on the current guest FPU register mode), and the Status.FR,
Config5.FRE bits are accessible via the KVM API and also from the guest,
depending on them being supported by the FPU.
6.10 KVM_CAP_MIPS_MSA
+---------------------
-Architectures: mips
-Target: vcpu
-Parameters: args[0] is reserved for future use (should be 0).
+:Architectures: mips
+:Target: vcpu
+:Parameters: args[0] is reserved for future use (should be 0).
This capability allows the use of the MIPS SIMD Architecture (MSA) by the guest.
It allows the Config3.MSAP bit to be set to enable the use of MSA by the guest.
-Once this is done the KVM_REG_MIPS_VEC_* and KVM_REG_MIPS_MSA_* registers can be
-accessed, and the Config5.MSAEn bit is accessible via the KVM API and also from
-the guest.
+Once this is done the ``KVM_REG_MIPS_VEC_*`` and ``KVM_REG_MIPS_MSA_*``
+registers can be accessed, and the Config5.MSAEn bit is accessible via the
+KVM API and also from the guest.
6.74 KVM_CAP_SYNC_REGS
-Architectures: s390, x86
-Target: s390: always enabled, x86: vcpu
-Parameters: none
-Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register
-sets are supported (bitfields defined in arch/x86/include/uapi/asm/kvm.h).
+----------------------
+
+:Architectures: s390, x86
+:Target: s390: always enabled, x86: vcpu
+:Parameters: none
+:Returns: x86: KVM_CHECK_EXTENSION returns a bit-array indicating which register
+ sets are supported
+ (bitfields defined in arch/x86/include/uapi/asm/kvm.h).
As described above in the kvm_sync_regs struct info in section 5 (kvm_run):
KVM_CAP_SYNC_REGS "allow[s] userspace to access certain guest registers
@@ -4780,6 +5299,7 @@ userspace.
For s390 specifics, please refer to the source code.
For x86:
+
- the register sets to be copied out to kvm_run are selectable
by userspace (rather that all sets being copied out for every exit).
- vcpu_events are available in addition to regs and sregs.
@@ -4796,23 +5316,26 @@ into the vCPU even if they've been modified.
Unused bitfields in the bitarrays must be set to zero.
-struct kvm_sync_regs {
+::
+
+ struct kvm_sync_regs {
struct kvm_regs regs;
struct kvm_sregs sregs;
struct kvm_vcpu_events events;
-};
+ };
6.75 KVM_CAP_PPC_IRQ_XIVE
+-------------------------
-Architectures: ppc
-Target: vcpu
-Parameters: args[0] is the XIVE device fd
- args[1] is the XIVE CPU number (server ID) for this vcpu
+:Architectures: ppc
+:Target: vcpu
+:Parameters: args[0] is the XIVE device fd;
+ args[1] is the XIVE CPU number (server ID) for this vcpu
This capability connects the vcpu to an in-kernel XIVE device.
7. Capabilities that can be enabled on VMs
-------------------------------------------
+==========================================
There are certain capabilities that change the behavior of the virtual
machine when enabled. To enable them, please see section 4.37. Below
@@ -4821,20 +5344,24 @@ is when enabling them.
The following information is provided along with the description:
- Architectures: which instruction set architectures provide this ioctl.
+ Architectures:
+ which instruction set architectures provide this ioctl.
x86 includes both i386 and x86_64.
- Parameters: what parameters are accepted by the capability.
+ Parameters:
+ what parameters are accepted by the capability.
- Returns: the return value. General error numbers (EBADF, ENOMEM, EINVAL)
+ Returns:
+ the return value. General error numbers (EBADF, ENOMEM, EINVAL)
are not detailed, but errors with specific meanings are.
7.1 KVM_CAP_PPC_ENABLE_HCALL
+----------------------------
-Architectures: ppc
-Parameters: args[0] is the sPAPR hcall number
- args[1] is 0 to disable, 1 to enable in-kernel handling
+:Architectures: ppc
+:Parameters: args[0] is the sPAPR hcall number;
+ args[1] is 0 to disable, 1 to enable in-kernel handling
This capability controls whether individual sPAPR hypercalls (hcalls)
get handled by the kernel or not. Enabling or disabling in-kernel
@@ -4852,13 +5379,15 @@ implementation, the KVM_ENABLE_CAP ioctl will fail with an EINVAL
error.
7.2 KVM_CAP_S390_USER_SIGP
+--------------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
This capability controls which SIGP orders will be handled completely in user
space. With this capability enabled, all fast orders will be handled completely
in the kernel:
+
- SENSE
- SENSE RUNNING
- EXTERNAL CALL
@@ -4872,48 +5401,52 @@ in the hardware prior to interception). If this capability is not enabled, the
old way of handling SIGP orders is used (partially in kernel and user space).
7.3 KVM_CAP_S390_VECTOR_REGISTERS
+---------------------------------
-Architectures: s390
-Parameters: none
-Returns: 0 on success, negative value on error
+:Architectures: s390
+:Parameters: none
+:Returns: 0 on success, negative value on error
Allows use of the vector registers introduced with z13 processor, and
provides for the synchronization between host and user space. Will
return -EINVAL if the machine does not support vectors.
7.4 KVM_CAP_S390_USER_STSI
+--------------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
This capability allows post-handlers for the STSI instruction. After
initial handling in the kernel, KVM exits to user space with
KVM_EXIT_S390_STSI to allow user space to insert further data.
Before exiting to userspace, kvm handlers should fill in s390_stsi field of
-vcpu->run:
-struct {
+vcpu->run::
+
+ struct {
__u64 addr;
__u8 ar;
__u8 reserved;
__u8 fc;
__u8 sel1;
__u16 sel2;
-} s390_stsi;
+ } s390_stsi;
-@addr - guest address of STSI SYSIB
-@fc - function code
-@sel1 - selector 1
-@sel2 - selector 2
-@ar - access register number
+ @addr - guest address of STSI SYSIB
+ @fc - function code
+ @sel1 - selector 1
+ @sel2 - selector 2
+ @ar - access register number
KVM handlers should exit to userspace with rc = -EREMOTE.
7.5 KVM_CAP_SPLIT_IRQCHIP
+-------------------------
-Architectures: x86
-Parameters: args[0] - number of routes reserved for userspace IOAPICs
-Returns: 0 on success, -1 on error
+:Architectures: x86
+:Parameters: args[0] - number of routes reserved for userspace IOAPICs
+:Returns: 0 on success, -1 on error
Create a local apic for each processor in the kernel. This can be used
instead of KVM_CREATE_IRQCHIP if the userspace VMM wishes to emulate the
@@ -4930,24 +5463,26 @@ Fails if VCPU has already been created, or if the irqchip is already in the
kernel (i.e. KVM_CREATE_IRQCHIP has already been called).
7.6 KVM_CAP_S390_RI
+-------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
Allows use of runtime-instrumentation introduced with zEC12 processor.
Will return -EINVAL if the machine does not support runtime-instrumentation.
Will return -EBUSY if a VCPU has already been created.
7.7 KVM_CAP_X2APIC_API
+----------------------
-Architectures: x86
-Parameters: args[0] - features that should be enabled
-Returns: 0 on success, -EINVAL when args[0] contains invalid features
+:Architectures: x86
+:Parameters: args[0] - features that should be enabled
+:Returns: 0 on success, -EINVAL when args[0] contains invalid features
-Valid feature flags in args[0] are
+Valid feature flags in args[0] are::
-#define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0)
-#define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1)
+ #define KVM_X2APIC_API_USE_32BIT_IDS (1ULL << 0)
+ #define KVM_X2APIC_API_DISABLE_BROADCAST_QUIRK (1ULL << 1)
Enabling KVM_X2APIC_API_USE_32BIT_IDS changes the behavior of
KVM_SET_GSI_ROUTING, KVM_SIGNAL_MSI, KVM_SET_LAPIC, and KVM_GET_LAPIC,
@@ -4961,9 +5496,10 @@ without interrupt remapping. This is undesirable in logical mode,
where 0xff represents CPUs 0-7 in cluster 0.
7.8 KVM_CAP_S390_USER_INSTR0
+----------------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
With this capability enabled, all illegal instructions 0x0000 (2 bytes) will
be intercepted and forwarded to user space. User space can use this
@@ -4975,26 +5511,29 @@ This capability can be enabled dynamically even if VCPUs were already
created and are running.
7.9 KVM_CAP_S390_GS
+-------------------
-Architectures: s390
-Parameters: none
-Returns: 0 on success; -EINVAL if the machine does not support
- guarded storage; -EBUSY if a VCPU has already been created.
+:Architectures: s390
+:Parameters: none
+:Returns: 0 on success; -EINVAL if the machine does not support
+ guarded storage; -EBUSY if a VCPU has already been created.
Allows use of guarded storage for the KVM guest.
7.10 KVM_CAP_S390_AIS
+---------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
Allow use of adapter-interruption suppression.
-Returns: 0 on success; -EBUSY if a VCPU has already been created.
+:Returns: 0 on success; -EBUSY if a VCPU has already been created.
7.11 KVM_CAP_PPC_SMT
+--------------------
-Architectures: ppc
-Parameters: vsmt_mode, flags
+:Architectures: ppc
+:Parameters: vsmt_mode, flags
Enabling this capability on a VM provides userspace with a way to set
the desired virtual SMT mode (i.e. the number of virtual CPUs per
@@ -5009,9 +5548,10 @@ The KVM_CAP_PPC_SMT_POSSIBLE capability indicates which virtual SMT
modes are available.
7.12 KVM_CAP_PPC_FWNMI
+----------------------
-Architectures: ppc
-Parameters: none
+:Architectures: ppc
+:Parameters: none
With this capability a machine check exception in the guest address
space will cause KVM to exit the guest with NMI exit reason. This
@@ -5020,17 +5560,18 @@ machine check handling routine. Without this capability KVM will
branch to guests' 0x200 interrupt vector.
7.13 KVM_CAP_X86_DISABLE_EXITS
+------------------------------
-Architectures: x86
-Parameters: args[0] defines which exits are disabled
-Returns: 0 on success, -EINVAL when args[0] contains invalid exits
+:Architectures: x86
+:Parameters: args[0] defines which exits are disabled
+:Returns: 0 on success, -EINVAL when args[0] contains invalid exits
-Valid bits in args[0] are
+Valid bits in args[0] are::
-#define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0)
-#define KVM_X86_DISABLE_EXITS_HLT (1 << 1)
-#define KVM_X86_DISABLE_EXITS_PAUSE (1 << 2)
-#define KVM_X86_DISABLE_EXITS_CSTATE (1 << 3)
+ #define KVM_X86_DISABLE_EXITS_MWAIT (1 << 0)
+ #define KVM_X86_DISABLE_EXITS_HLT (1 << 1)
+ #define KVM_X86_DISABLE_EXITS_PAUSE (1 << 2)
+ #define KVM_X86_DISABLE_EXITS_CSTATE (1 << 3)
Enabling this capability on a VM provides userspace with a way to no
longer intercept some instructions for improved latency in some
@@ -5042,12 +5583,13 @@ all such vmexits.
Do not enable KVM_FEATURE_PV_UNHALT if you disable HLT exits.
7.14 KVM_CAP_S390_HPAGE_1M
+--------------------------
-Architectures: s390
-Parameters: none
-Returns: 0 on success, -EINVAL if hpage module parameter was not set
- or cmma is enabled, or the VM has the KVM_VM_S390_UCONTROL
- flag set
+:Architectures: s390
+:Parameters: none
+:Returns: 0 on success, -EINVAL if hpage module parameter was not set
+ or cmma is enabled, or the VM has the KVM_VM_S390_UCONTROL
+ flag set
With this capability the KVM support for memory backing with 1m pages
through hugetlbfs can be enabled for a VM. After the capability is
@@ -5059,20 +5601,22 @@ While it is generally possible to create a huge page backed VM without
this capability, the VM will not be able to run.
7.15 KVM_CAP_MSR_PLATFORM_INFO
+------------------------------
-Architectures: x86
-Parameters: args[0] whether feature should be enabled or not
+:Architectures: x86
+:Parameters: args[0] whether feature should be enabled or not
With this capability, a guest may read the MSR_PLATFORM_INFO MSR. Otherwise,
a #GP would be raised when the guest tries to access. Currently, this
capability does not enable write permissions of this MSR for the guest.
7.16 KVM_CAP_PPC_NESTED_HV
+--------------------------
-Architectures: ppc
-Parameters: none
-Returns: 0 on success, -EINVAL when the implementation doesn't support
- nested-HV virtualization.
+:Architectures: ppc
+:Parameters: none
+:Returns: 0 on success, -EINVAL when the implementation doesn't support
+ nested-HV virtualization.
HV-KVM on POWER9 and later systems allows for "nested-HV"
virtualization, which provides a way for a guest VM to run guests that
@@ -5082,9 +5626,10 @@ the necessary functionality and on the facility being enabled with a
kvm-hv module parameter.
7.17 KVM_CAP_EXCEPTION_PAYLOAD
+------------------------------
-Architectures: x86
-Parameters: args[0] whether feature should be enabled or not
+:Architectures: x86
+:Parameters: args[0] whether feature should be enabled or not
With this capability enabled, CR2 will not be modified prior to the
emulated VM-exit when L1 intercepts a #PF exception that occurs in
@@ -5095,21 +5640,21 @@ L2. As a result, when KVM_GET_VCPU_EVENTS reports a pending #PF (or
faulting address (or the new DR6 bits*) will be reported in the
exception_payload field. Similarly, when userspace injects a #PF (or
#DB) into L2 using KVM_SET_VCPU_EVENTS, it is expected to set
-exception.has_payload and to put the faulting address (or the new DR6
-bits*) in the exception_payload field.
+exception.has_payload and to put the faulting address - or the new DR6
+bits\ [#]_ - in the exception_payload field.
This capability also enables exception.pending in struct
kvm_vcpu_events, which allows userspace to distinguish between pending
and injected exceptions.
-* For the new DR6 bits, note that bit 16 is set iff the #DB exception
- will clear DR6.RTM.
+.. [#] For the new DR6 bits, note that bit 16 is set iff the #DB exception
+ will clear DR6.RTM.
7.18 KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2
-Architectures: x86, arm, arm64, mips
-Parameters: args[0] whether feature should be enabled or not
+:Architectures: x86, arm, arm64, mips
+:Parameters: args[0] whether feature should be enabled or not
With this capability enabled, KVM_GET_DIRTY_LOG will not automatically
clear and write-protect all pages that are returned as dirty.
@@ -5136,14 +5681,15 @@ KVM_CAP_MANUAL_DIRTY_LOG_PROTECT2 signals that those bugs are fixed.
Userspace should not try to use KVM_CAP_MANUAL_DIRTY_LOG_PROTECT.
8. Other capabilities.
-----------------------
+======================
This section lists capabilities that give information about other
features of the KVM implementation.
8.1 KVM_CAP_PPC_HWRNG
+---------------------
-Architectures: ppc
+:Architectures: ppc
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that that the kernel has an implementation of the
@@ -5152,8 +5698,10 @@ If present, the kernel H_RANDOM handler can be enabled for guest use
with the KVM_CAP_PPC_ENABLE_HCALL capability.
8.2 KVM_CAP_HYPERV_SYNIC
+------------------------
+
+:Architectures: x86
-Architectures: x86
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that that the kernel has an implementation of the
Hyper-V Synthetic interrupt controller(SynIC). Hyper-V SynIC is
@@ -5165,8 +5713,9 @@ will disable the use of APIC hardware virtualization even if supported
by the CPU, as it's incompatible with SynIC auto-EOI behavior.
8.3 KVM_CAP_PPC_RADIX_MMU
+-------------------------
-Architectures: ppc
+:Architectures: ppc
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that that the kernel can support guests using the
@@ -5174,8 +5723,9 @@ radix MMU defined in Power ISA V3.00 (as implemented in the POWER9
processor).
8.4 KVM_CAP_PPC_HASH_MMU_V3
+---------------------------
-Architectures: ppc
+:Architectures: ppc
This capability, if KVM_CHECK_EXTENSION indicates that it is
available, means that that the kernel can support guests using the
@@ -5183,8 +5733,9 @@ hashed page table MMU defined in Power ISA V3.00 (as implemented in
the POWER9 processor), including in-memory segment tables.
8.5 KVM_CAP_MIPS_VZ
+-------------------
-Architectures: mips
+:Architectures: mips
This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that
it is available, means that full hardware assisted virtualization capabilities
@@ -5202,16 +5753,19 @@ values (see below). All other values are reserved. This is to allow for the
possibility of other hardware assisted virtualization implementations which
may be incompatible with the MIPS VZ ASE.
- 0: The trap & emulate implementation is in use to run guest code in user
+== ==========================================================================
+ 0 The trap & emulate implementation is in use to run guest code in user
mode. Guest virtual memory segments are rearranged to fit the guest in the
user mode address space.
- 1: The MIPS VZ ASE is in use, providing full hardware assisted
+ 1 The MIPS VZ ASE is in use, providing full hardware assisted
virtualization, including standard guest virtual memory segments.
+== ==========================================================================
8.6 KVM_CAP_MIPS_TE
+-------------------
-Architectures: mips
+:Architectures: mips
This capability, if KVM_CHECK_EXTENSION on the main kvm handle indicates that
it is available, means that the trap & emulate implementation is available to
@@ -5223,8 +5777,9 @@ If KVM_CHECK_EXTENSION on a kvm VM handle indicates that this capability is
available, it means that the VM is using trap & emulate.
8.7 KVM_CAP_MIPS_64BIT
+----------------------
-Architectures: mips
+:Architectures: mips
This capability indicates the supported architecture type of the guest, i.e. the
supported register and address width.
@@ -5234,22 +5789,26 @@ kvm VM handle correspond roughly to the CP0_Config.AT register field, and should
be checked specifically against known values (see below). All other values are
reserved.
- 0: MIPS32 or microMIPS32.
+== ========================================================================
+ 0 MIPS32 or microMIPS32.
Both registers and addresses are 32-bits wide.
It will only be possible to run 32-bit guest code.
- 1: MIPS64 or microMIPS64 with access only to 32-bit compatibility segments.
+ 1 MIPS64 or microMIPS64 with access only to 32-bit compatibility segments.
Registers are 64-bits wide, but addresses are 32-bits wide.
64-bit guest code may run but cannot access MIPS64 memory segments.
It will also be possible to run 32-bit guest code.
- 2: MIPS64 or microMIPS64 with access to all address segments.
+ 2 MIPS64 or microMIPS64 with access to all address segments.
Both registers and addresses are 64-bits wide.
It will be possible to run 64-bit or 32-bit guest code.
+== ========================================================================
8.9 KVM_CAP_ARM_USER_IRQ
+------------------------
+
+:Architectures: arm, arm64
-Architectures: arm, arm64
This capability, if KVM_CHECK_EXTENSION indicates that it is available, means
that if userspace creates a VM without an in-kernel interrupt controller, it
will be notified of changes to the output level of in-kernel emulated devices,
@@ -5276,7 +5835,7 @@ If KVM_CAP_ARM_USER_IRQ is supported, the KVM_CHECK_EXTENSION ioctl returns a
number larger than 0 indicating the version of this capability is implemented
and thereby which bits in in run->s.regs.device_irq_level can signal values.
-Currently the following bits are defined for the device_irq_level bitmap:
+Currently the following bits are defined for the device_irq_level bitmap::
KVM_CAP_ARM_USER_IRQ >= 1:
@@ -5289,8 +5848,9 @@ indicated by returning a higher number from KVM_CHECK_EXTENSION and will be
listed above.
8.10 KVM_CAP_PPC_SMT_POSSIBLE
+-----------------------------
-Architectures: ppc
+:Architectures: ppc
Querying this capability returns a bitmap indicating the possible
virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N
@@ -5298,8 +5858,9 @@ virtual SMT modes that can be set using KVM_CAP_PPC_SMT. If bit N
available.
8.11 KVM_CAP_HYPERV_SYNIC2
+--------------------------
-Architectures: x86
+:Architectures: x86
This capability enables a newer version of Hyper-V Synthetic interrupt
controller (SynIC). The only difference with KVM_CAP_HYPERV_SYNIC is that KVM
@@ -5307,8 +5868,9 @@ doesn't clear SynIC message and event flags pages when they are enabled by
writing to the respective MSRs.
8.12 KVM_CAP_HYPERV_VP_INDEX
+----------------------------
-Architectures: x86
+:Architectures: x86
This capability indicates that userspace can load HV_X64_MSR_VP_INDEX msr. Its
value is used to denote the target vcpu for a SynIC interrupt. For
@@ -5316,47 +5878,53 @@ compatibilty, KVM initializes this msr to KVM's internal vcpu index. When this
capability is absent, userspace can still query this msr's value.
8.13 KVM_CAP_S390_AIS_MIGRATION
+-------------------------------
-Architectures: s390
-Parameters: none
+:Architectures: s390
+:Parameters: none
This capability indicates if the flic device will be able to get/set the
AIS states for migration via the KVM_DEV_FLIC_AISM_ALL attribute and allows
to discover this without having to create a flic device.
8.14 KVM_CAP_S390_PSW
+---------------------
-Architectures: s390
+:Architectures: s390
This capability indicates that the PSW is exposed via the kvm_run structure.
8.15 KVM_CAP_S390_GMAP
+----------------------
-Architectures: s390
+:Architectures: s390
This capability indicates that the user space memory used as guest mapping can
be anywhere in the user memory address space, as long as the memory slots are
aligned and sized to a segment (1MB) boundary.
8.16 KVM_CAP_S390_COW
+---------------------
-Architectures: s390
+:Architectures: s390
This capability indicates that the user space memory used as guest mapping can
use copy-on-write semantics as well as dirty pages tracking via read-only page
tables.
8.17 KVM_CAP_S390_BPB
+---------------------
-Architectures: s390
+:Architectures: s390
This capability indicates that kvm will implement the interfaces to handle
reset, migration and nested KVM for branch prediction blocking. The stfle
facility 82 should not be provided to the guest without this capability.
8.18 KVM_CAP_HYPERV_TLBFLUSH
+----------------------------
-Architectures: x86
+:Architectures: x86
This capability indicates that KVM supports paravirtualized Hyper-V TLB Flush
hypercalls:
@@ -5364,8 +5932,9 @@ HvFlushVirtualAddressSpace, HvFlushVirtualAddressSpaceEx,
HvFlushVirtualAddressList, HvFlushVirtualAddressListEx.
8.19 KVM_CAP_ARM_INJECT_SERROR_ESR
+----------------------------------
-Architectures: arm, arm64
+:Architectures: arm, arm64
This capability indicates that userspace can specify (via the
KVM_SET_VCPU_EVENTS ioctl) the syndrome value reported to the guest when it
@@ -5376,16 +5945,20 @@ CPU when the exception is taken. If this virtual SError is taken to EL1 using
AArch64, this value will be reported in the ISS field of ESR_ELx.
See KVM_CAP_VCPU_EVENTS for more details.
+
8.20 KVM_CAP_HYPERV_SEND_IPI
+----------------------------
-Architectures: x86
+:Architectures: x86
This capability indicates that KVM supports paravirtualized Hyper-V IPI send
hypercalls:
HvCallSendSyntheticClusterIpi, HvCallSendSyntheticClusterIpiEx.
+
8.21 KVM_CAP_HYPERV_DIRECT_TLBFLUSH
+-----------------------------------
-Architecture: x86
+:Architecture: x86
This capability indicates that KVM running on top of Hyper-V hypervisor
enables Direct TLB flush for its guests meaning that TLB flush
diff --git a/Documentation/virt/kvm/index.rst b/Documentation/virt/kvm/index.rst
index 24d1076ec680..6fe79185b9bc 100644
--- a/Documentation/virt/kvm/index.rst
+++ b/Documentation/virt/kvm/index.rst
@@ -7,6 +7,7 @@ KVM
.. toctree::
:maxdepth: 2
+ api
amd-memory-encryption
cpuid
halt-polling
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 18/27] docs: kvm: convert arm/hyp-abi.txt to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 18/27] docs: kvm: convert arm/hyp-abi.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 18/27] docs: kvm: convert arm/hyp-abi.txt to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 19/27] docs: kvm: arm/psci.txt: convert to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Add a title for the document;
- Adjust whitespaces for it to be properly formatted after
parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 19/27] docs: kvm: arm/psci.txt: convert to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Add a title for the document;
- Adjust whitespaces for it to be properly formatted after
parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 19/27] docs: kvm: arm/psci.txt: convert to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- Add a title for the document;
- Adjust whitespaces for it to be properly formatted after
parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 20/27] docs: kvm: Convert hypercalls.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 20/27] docs: kvm: Convert hypercalls.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 20/27] docs: kvm: Convert hypercalls.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
.../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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 21/27] docs: kvm: Convert locking.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 21/27] docs: kvm: Convert locking.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 21/27] docs: kvm: Convert locking.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 22/27] docs: kvm: Convert mmu.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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
-
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 22/27] docs: kvm: Convert mmu.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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
-
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 22/27] docs: kvm: Convert mmu.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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
-
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 23/27] docs: kvm: Convert nested-vmx.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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 <at> il.ibm.com
- Nadav Har'El, nyh <at> il.ibm.com
- Orit Wasserman, oritw <at> il.ibm.com
- Ben-Ami Yassor, benami <at> il.ibm.com
- Muli Ben-Yehuda, muli <at> il.ibm.com
+ - Abel Gordon, abelg <at> il.ibm.com
+ - Nadav Har'El, nyh <at> il.ibm.com
+ - Orit Wasserman, oritw <at> il.ibm.com
+ - Ben-Ami Yassor, benami <at> il.ibm.com
+ - Muli Ben-Yehuda, muli <at> il.ibm.com
With contributions by:
- Anthony Liguori, aliguori <at> us.ibm.com
- Mike Day, mdday <at> us.ibm.com
- Michael Factor, factor <at> il.ibm.com
- Zvi Dubitzky, dubi <at> il.ibm.com
+ - Anthony Liguori, aliguori <at> us.ibm.com
+ - Mike Day, mdday <at> us.ibm.com
+ - Michael Factor, factor <at> il.ibm.com
+ - Zvi Dubitzky, dubi <at> il.ibm.com
And valuable reviews by:
- Avi Kivity, avi <at> redhat.com
- Gleb Natapov, gleb <at> redhat.com
- Marcelo Tosatti, mtosatti <at> redhat.com
- Kevin Tian, kevin.tian <at> intel.com
- and others.
+ - Avi Kivity, avi <at> redhat.com
+ - Gleb Natapov, gleb <at> redhat.com
+ - Marcelo Tosatti, mtosatti <at> redhat.com
+ - Kevin Tian, kevin.tian <at> intel.com
+ - and others.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 23/27] docs: kvm: Convert nested-vmx.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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 <at> il.ibm.com
- Nadav Har'El, nyh <at> il.ibm.com
- Orit Wasserman, oritw <at> il.ibm.com
- Ben-Ami Yassor, benami <at> il.ibm.com
- Muli Ben-Yehuda, muli <at> il.ibm.com
+ - Abel Gordon, abelg <at> il.ibm.com
+ - Nadav Har'El, nyh <at> il.ibm.com
+ - Orit Wasserman, oritw <at> il.ibm.com
+ - Ben-Ami Yassor, benami <at> il.ibm.com
+ - Muli Ben-Yehuda, muli <at> il.ibm.com
With contributions by:
- Anthony Liguori, aliguori <at> us.ibm.com
- Mike Day, mdday <at> us.ibm.com
- Michael Factor, factor <at> il.ibm.com
- Zvi Dubitzky, dubi <at> il.ibm.com
+ - Anthony Liguori, aliguori <at> us.ibm.com
+ - Mike Day, mdday <at> us.ibm.com
+ - Michael Factor, factor <at> il.ibm.com
+ - Zvi Dubitzky, dubi <at> il.ibm.com
And valuable reviews by:
- Avi Kivity, avi <at> redhat.com
- Gleb Natapov, gleb <at> redhat.com
- Marcelo Tosatti, mtosatti <at> redhat.com
- Kevin Tian, kevin.tian <at> intel.com
- and others.
+ - Avi Kivity, avi <at> redhat.com
+ - Gleb Natapov, gleb <at> redhat.com
+ - Marcelo Tosatti, mtosatti <at> redhat.com
+ - Kevin Tian, kevin.tian <at> intel.com
+ - and others.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 23/27] docs: kvm: Convert nested-vmx.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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 <at> il.ibm.com
- Nadav Har'El, nyh <at> il.ibm.com
- Orit Wasserman, oritw <at> il.ibm.com
- Ben-Ami Yassor, benami <at> il.ibm.com
- Muli Ben-Yehuda, muli <at> il.ibm.com
+ - Abel Gordon, abelg <at> il.ibm.com
+ - Nadav Har'El, nyh <at> il.ibm.com
+ - Orit Wasserman, oritw <at> il.ibm.com
+ - Ben-Ami Yassor, benami <at> il.ibm.com
+ - Muli Ben-Yehuda, muli <at> il.ibm.com
With contributions by:
- Anthony Liguori, aliguori <at> us.ibm.com
- Mike Day, mdday <at> us.ibm.com
- Michael Factor, factor <at> il.ibm.com
- Zvi Dubitzky, dubi <at> il.ibm.com
+ - Anthony Liguori, aliguori <at> us.ibm.com
+ - Mike Day, mdday <at> us.ibm.com
+ - Michael Factor, factor <at> il.ibm.com
+ - Zvi Dubitzky, dubi <at> il.ibm.com
And valuable reviews by:
- Avi Kivity, avi <at> redhat.com
- Gleb Natapov, gleb <at> redhat.com
- Marcelo Tosatti, mtosatti <at> redhat.com
- Kevin Tian, kevin.tian <at> intel.com
- and others.
+ - Avi Kivity, avi <at> redhat.com
+ - Gleb Natapov, gleb <at> redhat.com
+ - Marcelo Tosatti, mtosatti <at> redhat.com
+ - Kevin Tian, kevin.tian <at> intel.com
+ - and others.
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 24/27] docs: kvm: Convert ppc-pv.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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 <special mtsrin section>
[BookE only]
wrteei [0|1] b <special wrteei section>
-
+======================= ================================
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 24/27] docs: kvm: Convert ppc-pv.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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 <special mtsrin section>
[BookE only]
wrteei [0|1] b <special wrteei section>
-
+======================= ================================
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 24/27] docs: kvm: Convert ppc-pv.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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 <special mtsrin section>
[BookE only]
wrteei [0|1] b <special wrteei section>
-
+======================= ================================
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 25/27] docs: kvm: Convert s390-diag.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 25/27] docs: kvm: Convert s390-diag.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 25/27] docs: kvm: Convert s390-diag.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* Re: [PATCH 25/27] docs: kvm: Convert s390-diag.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
(?)
@ 2020-01-28 18:15 ` Cornelia Huck
-1 siblings, 0 replies; 64+ messages in thread
From: Cornelia Huck @ 2020-01-28 18:15 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
On Tue, 28 Jan 2020 14:58:21 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 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 <mchehab+huawei@kernel.org>
> ---
> 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%)
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
^ permalink raw reply [flat|nested] 64+ messages in thread
* [PATCH 26/27] docs: kvm: Convert timekeeping.txt to ReST format
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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 <zamsden@redhat.com>
+:Copyright: (c) 2010, Red Hat. All rights reserved.
- Zachary Amsden <zamsden@redhat.com>
- 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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 26/27] docs: kvm: Convert timekeeping.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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 <zamsden@redhat.com>
+:Copyright: (c) 2010, Red Hat. All rights reserved.
- Zachary Amsden <zamsden@redhat.com>
- 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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 26/27] docs: kvm: Convert timekeeping.txt to ReST format
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
- 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 <mchehab+huawei@kernel.org>
---
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 <zamsden@redhat.com>
+:Copyright: (c) 2010, Red Hat. All rights reserved.
- Zachary Amsden <zamsden@redhat.com>
- 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
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
* [PATCH 27/27] docs: kvm: review-checklist.txt: rename to ReST
2020-01-28 14:00 ` Mauro Carvalho Chehab
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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
================================
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 27/27] docs: kvm: review-checklist.txt: rename to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 13:58 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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
================================
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread* [PATCH 27/27] docs: kvm: review-checklist.txt: rename to ReST
@ 2020-01-28 14:00 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 64+ messages in thread
From: Mauro Carvalho Chehab @ 2020-01-28 14:00 UTC (permalink / raw)
To: Linux Media Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, Paolo Bonzini,
Jonathan Corbet, kvm, linux-doc
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 <mchehab+huawei@kernel.org>
---
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
================================
--
2.24.1
^ permalink raw reply related [flat|nested] 64+ messages in thread
